diff --git a/.env.example b/.env.example
index 06d43070c..66010b1f5 100644
--- a/.env.example
+++ b/.env.example
@@ -5,16 +5,18 @@
 # ANTHROPIC_API_KEY=sk-ant-xxx
 # OPENAI_API_KEY=sk-xxx
 # GEMINI_API_KEY=xxx
-# CEREBRAS_API_KEY=xxx
-
+# MODELSCOPE_API_KEY=xxx
+# CLAUDE_CODE_OAUTH=xxx
 # ── Chat Channel ──────────────────────────
 # TELEGRAM_BOT_TOKEN=123456:ABC...
 # DISCORD_BOT_TOKEN=xxx
-# LINE_CHANNEL_SECRET=xxx
-# LINE_CHANNEL_ACCESS_TOKEN=xxx
+# Feishu (飞书)
+# PICOCLAW_CHANNELS_FEISHU_APP_ID=cli_xxx
+# PICOCLAW_CHANNELS_FEISHU_APP_SECRET=xxx
+# PICOCLAW_CHANNELS_FEISHU_RANDOM_REACTION_EMOJI=Typing,OneSecond
 
 # ── Web Search (optional) ────────────────
 # BRAVE_SEARCH_API_KEY=BSA...
 
 # ── Timezone ──────────────────────────────
-TZ=Asia/Tokyo
+TZ=Asia/Shanghai
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 000000000..559a2249e
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,27 @@
+version: 2
+
+updates:
+
+  # Go dependencies (entire repo)
+  - package-ecosystem: "gomod"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "go"
+
+  # Frontend dependencies
+  - package-ecosystem: "npm"
+    directory: "/web/frontend"
+    schedule:
+      interval: "weekly"
+    labels:
+      - "dependencies"
+      - "frontend"
+
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
\ No newline at end of file
diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml
index dadbed212..784c404a6 100644
--- a/.github/workflows/docker-build.yml
+++ b/.github/workflows/docker-build.yml
@@ -31,11 +31,11 @@ jobs:
 
       # ── Docker Buildx ─────────────────────────
       - name: 🔧 Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       # ── Login to GHCR ─────────────────────────
       - name: 🔑 Login to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ${{ env.GHCR_REGISTRY }}
           username: ${{ github.actor }}
@@ -43,7 +43,7 @@ jobs:
 
       # ── Login to Docker Hub ────────────────────
       - name: 🔑 Login to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: ${{ env.DOCKERHUB_REGISTRY }}
           username: ${{ secrets.DOCKERHUB_USERNAME }}
@@ -62,7 +62,7 @@ jobs:
 
       # ── Build & Push ──────────────────────────
       - name: 🚀 Build and push Docker image
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@v7
         with:
           context: .
           push: true
diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml
new file mode 100644
index 000000000..a5002fec5
--- /dev/null
+++ b/.github/workflows/nightly.yml
@@ -0,0 +1,138 @@
+name: Nightly Build
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  nightly:
+    name: Nightly Build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Compute version
+        id: version
+        run: |
+          DATE=$(date -u +%Y%m%d)
+          SHA=$(git rev-parse --short=8 HEAD)
+          BASE_VERSION=$(git describe --tags --match "v*" --exclude "*nightly*" --abbrev=0 2>/dev/null || true)
+          if [ -z "$BASE_VERSION" ] || [ "$BASE_VERSION" = "v0.0.0" ]; then
+            VERSION="v0.0.0-nightly.${DATE}.${SHA}"
+          else
+            VERSION="${BASE_VERSION}-nightly.${DATE}.${SHA}"
+          fi
+
+          COMPARE_URL="https://github.com/${{ github.repository }}/commits/main"
+          if [ -n "$BASE_VERSION" ] && [ "$BASE_VERSION" != "v0.0.0" ]; then
+            COMPARE_URL="https://github.com/${{ github.repository }}/compare/${BASE_VERSION}...main"
+          fi
+
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          echo "changelog=**Full Changelog**: $COMPARE_URL" >> "$GITHUB_OUTPUT"
+
+      - name: Setup Go from go.mod
+        id: setup-go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      - name: Setup pnpm
+        run: corepack enable && corepack prepare pnpm@latest --activate
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Login to Docker Hub
+        uses: docker/login-action@v4
+        with:
+          registry: docker.io
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Create local tag for GoReleaser
+        run: git tag "${{ steps.version.outputs.version }}"
+
+      - name: Run GoReleaser
+        uses: goreleaser/goreleaser-action@v7
+        with:
+          distribution: goreleaser
+          version: ~> v2
+          args: release --clean
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
+          DOCKERHUB_IMAGE_NAME: ${{ vars.DOCKERHUB_REPOSITORY }}
+          GOVERSION: ${{ steps.setup-go.outputs.go-version }}
+          GORELEASER_CURRENT_TAG: ${{ steps.version.outputs.version }}
+          NIGHTLY_BUILD: "true"
+          MACOS_SIGN_P12: ${{ secrets.MACOS_SIGN_P12 }}
+          MACOS_SIGN_PASSWORD: ${{ secrets.MACOS_SIGN_PASSWORD }}
+          MACOS_NOTARY_ISSUER_ID: ${{ secrets.MACOS_NOTARY_ISSUER_ID }}
+          MACOS_NOTARY_KEY_ID: ${{ secrets.MACOS_NOTARY_KEY_ID }}
+          MACOS_NOTARY_KEY: ${{ secrets.MACOS_NOTARY_KEY }}
+
+      - name: Update nightly release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          CHANGELOG='${{ steps.version.outputs.changelog }}'
+          NOTES=$(cat <<EOF
+          Nightly build for **${VERSION}**
+
+          This is an automated build and may be unstable. Use with caution.
+
+          ${CHANGELOG}
+          EOF
+          )
+
+          # Delete existing nightly release and tag
+          gh release delete nightly --cleanup-tag -y 2>/dev/null || true
+
+          # Force-update nightly tag to current HEAD
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -fa nightly -m "Nightly build ${VERSION}"
+          git push origin nightly
+
+          # Collect release artifacts from goreleaser dist/
+          ASSETS=()
+          for f in dist/*.tar.gz dist/*.zip dist/*.deb dist/*.rpm dist/checksums.txt; do
+            [ -f "$f" ] && ASSETS+=("$f")
+          done
+
+          # Create nightly release (prerelease, NOT latest)
+          gh release create nightly \
+            --title "Nightly Build" \
+            --notes "$NOTES" \
+            --target "${{ github.sha }}" \
+            --prerelease \
+            --latest=false \
+            "${ASSETS[@]}"
+
diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml
index be1c10c52..2d544d4f0 100644
--- a/.github/workflows/pr.yml
+++ b/.github/workflows/pr.yml
@@ -23,6 +23,28 @@ jobs:
         uses: golangci/golangci-lint-action@v9
         with:
           version: v2.10.1
+          args: --build-tags=goolm,stdjson
+
+  vuln_check:
+    name: Security Check
+    runs-on: ubuntu-latest
+    env:
+      GOFLAGS: -tags=goolm,stdjson
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+
+      - name: Run Govulncheck
+        uses: golang/govulncheck-action@v1
+        with:
+          go-package: ./...
 
   test:
     name: Tests
@@ -40,4 +62,4 @@ jobs:
         run: go generate ./...
 
       - name: Run go test
-        run: go test ./...
+        run: go test -tags goolm,stdjson ./...
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 786c893ef..2ce341770 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -17,6 +17,11 @@ on:
         required: false
         type: boolean
         default: false
+      upload_tos:
+        description: "Upload to Volcengine TOS"
+        required: false
+        type: boolean
+        default: true
 
 jobs:
   create-tag:
@@ -60,28 +65,36 @@ jobs:
         with:
           go-version-file: go.mod
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      - name: Setup pnpm
+        run: corepack enable && corepack prepare pnpm@latest --activate
+
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v3
+        uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
-        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: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           registry: docker.io
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Run GoReleaser
-        uses: goreleaser/goreleaser-action@v6
+        uses: goreleaser/goreleaser-action@v7
         with:
           distribution: goreleaser
           version: ~> v2
@@ -91,6 +104,11 @@ jobs:
           GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
           DOCKERHUB_IMAGE_NAME: ${{ vars.DOCKERHUB_REPOSITORY }}
           GOVERSION: ${{ steps.setup-go.outputs.go-version }}
+          MACOS_SIGN_P12: ${{ secrets.MACOS_SIGN_P12 }}
+          MACOS_SIGN_PASSWORD: ${{ secrets.MACOS_SIGN_PASSWORD }}
+          MACOS_NOTARY_ISSUER_ID: ${{ secrets.MACOS_NOTARY_ISSUER_ID }}
+          MACOS_NOTARY_KEY_ID: ${{ secrets.MACOS_NOTARY_KEY_ID }}
+          MACOS_NOTARY_KEY: ${{ secrets.MACOS_NOTARY_KEY }}
 
       - name: Apply release flags
         shell: bash
@@ -100,3 +118,12 @@ jobs:
           gh release edit "${{ inputs.tag }}" \
             --draft=${{ inputs.draft }} \
             --prerelease=${{ inputs.prerelease }}
+
+  upload-tos:
+    name: Upload to TOS
+    needs: release
+    if: ${{ inputs.upload_tos }}
+    uses: ./.github/workflows/upload-tos.yml
+    with:
+      tag: ${{ inputs.tag }}
+    secrets: inherit
diff --git a/.github/workflows/upload-tos.yml b/.github/workflows/upload-tos.yml
new file mode 100644
index 000000000..6d3916d53
--- /dev/null
+++ b/.github/workflows/upload-tos.yml
@@ -0,0 +1,49 @@
+name: Upload to Volcengine TOS
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to download and upload (e.g. v0.2.0)"
+        required: true
+        type: string
+  workflow_call:
+    inputs:
+      tag:
+        description: "Release tag to download and upload"
+        required: true
+        type: string
+
+jobs:
+  upload-tos:
+    name: Upload to Volcengine TOS
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download release assets
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          mkdir -p artifacts
+          gh release download "${{ inputs.tag }}" \
+            --repo "${{ github.repository }}" \
+            --dir artifacts \
+            --pattern "*.tar.gz" \
+            --pattern "*.zip" \
+            --pattern "*.rpm" \
+            --pattern "*.deb"
+
+      - name: Upload to Volcengine TOS
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.VOLC_TOS_ACCESS_KEY }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.VOLC_TOS_SECRET_KEY }}
+          AWS_DEFAULT_REGION: cn-beijing
+        run: |
+          aws configure set default.s3.addressing_style virtual
+          TOS_ENDPOINT="https://tos-s3-cn-beijing.volces.com"
+          # Upload to versioned directory
+          aws s3 sync artifacts/ "s3://picoclaw-downloads/${{ inputs.tag }}/" \
+            --endpoint-url "$TOS_ENDPOINT"
+          # Upload to latest (overwrite)
+          aws s3 sync artifacts/ "s3://picoclaw-downloads/latest/" \
+            --endpoint-url "$TOS_ENDPOINT" \
+            --delete
diff --git a/.gitignore b/.gitignore
index 02ef18d1f..72f3b1761 100644
--- a/.gitignore
+++ b/.gitignore
@@ -38,12 +38,29 @@ ralph/
 .ralph/
 tasks/
 
+# Plans
+docs/plans/
+docs/superpowers/
+
 # Editors
 .vscode/
 .idea/
 
 # Added by goreleaser init:
 dist/
+*.vite/
 
 # Windows Application Icon/Resource
 *.syso
+
+# Test telegram integration
+cmd/telegram/
+
+# Keep embedded backend dist directory placeholder in VCS
+!web/backend/dist/
+web/backend/dist/*
+!web/backend/dist/.gitkeep
+
+.claude/
+
+docker/data
diff --git a/.golangci.yaml b/.golangci.yaml
index d0ba90716..ea3107ec8 100644
--- a/.golangci.yaml
+++ b/.golangci.yaml
@@ -7,7 +7,6 @@ linters:
     - containedctx
     - cyclop
     - depguard
-    - dupl
     - dupword
     - err113
     - exhaustruct
diff --git a/.goreleaser.yaml b/.goreleaser.yaml
index d531d106b..ea93d0377 100644
--- a/.goreleaser.yaml
+++ b/.goreleaser.yaml
@@ -6,45 +6,59 @@ before:
   hooks:
     - go mod tidy
     - go generate ./...
+    - sh -c 'cd web/frontend && pnpm install && pnpm build:backend'
     - go install github.com/tc-hib/go-winres@latest
-    - go-winres make --in cmd/picoclaw-launcher/winres/winres.json --out cmd/picoclaw-launcher/rsrc --product-version={{ .Version }} --file-version={{ .Version }}
+    - go-winres make --in web/backend/winres/winres.json --out web/backend/rsrc --product-version={{ .Version }} --file-version={{ .Version }}
 
 builds:
   - id: picoclaw
     env:
       - CGO_ENABLED=0
     tags:
+      - goolm
       - stdjson
     ldflags:
       - -s -w
-      - -X github.com/sipeed/picoclaw/cmd/picoclaw/internal.version={{ .Version }}
-      - -X github.com/sipeed/picoclaw/cmd/picoclaw/internal.gitCommit={{ .ShortCommit }}
-      - -X github.com/sipeed/picoclaw/cmd/picoclaw/internal.buildTime={{ .Date }}
-      - -X github.com/sipeed/picoclaw/cmd/picoclaw/internal.goVersion={{ .Env.GOVERSION }}
+      - -X github.com/sipeed/picoclaw/pkg/config.Version={{ .Version }}
+      - -X github.com/sipeed/picoclaw/pkg/config.GitCommit={{ .ShortCommit }}
+      - -X github.com/sipeed/picoclaw/pkg/config.BuildTime={{ .Date }}
+      - -X github.com/sipeed/picoclaw/pkg/config.GoVersion={{ .Env.GOVERSION }}
     goos:
       - linux
       - windows
       - darwin
       - freebsd
+      - netbsd
     goarch:
       - amd64
       - arm64
       - riscv64
       - loong64
       - arm
+      - s390x
+      - mipsle
     goarm:
       - "6"
       - "7"
+    gomips:
+      - softfloat
     main: ./cmd/picoclaw
     ignore:
       - goos: windows
         goarch: arm
+      - goos: netbsd
+        goarch: s390x
+      - goos: netbsd
+        goarch: mips64
+      - goos: netbsd
+        goarch: arm
 
   - id: picoclaw-launcher
     binary: picoclaw-launcher
     env:
       - CGO_ENABLED=0
     tags:
+      - goolm
       - stdjson
     ldflags:
       - -s -w
@@ -53,25 +67,37 @@ builds:
       - windows
       - darwin
       - freebsd
+      - netbsd
     goarch:
       - amd64
       - arm64
       - riscv64
       - loong64
       - arm
+      - s390x
+      - mipsle
     goarm:
       - "6"
       - "7"
-    main: ./cmd/picoclaw-launcher
+    gomips:
+      - softfloat
+    main: ./web/backend
     ignore:
       - goos: windows
         goarch: arm
+      - goos: netbsd
+        goarch: s390x
+      - goos: netbsd
+        goarch: mips64
+      - goos: netbsd
+        goarch: arm
 
   - id: picoclaw-launcher-tui
     binary: picoclaw-launcher-tui
     env:
       - CGO_ENABLED=0
     tags:
+      - goolm
       - stdjson
     ldflags:
       - -s -w
@@ -80,19 +106,30 @@ builds:
       - windows
       - darwin
       - freebsd
+      - netbsd
     goarch:
       - amd64
       - arm64
       - riscv64
       - loong64
       - arm
+      - s390x
+      - mipsle
     goarm:
       - "6"
       - "7"
+    gomips:
+      - softfloat
     main: ./cmd/picoclaw-launcher-tui
     ignore:
       - goos: windows
         goarch: arm
+      - goos: netbsd
+        goarch: s390x
+      - goos: netbsd
+        goarch: mips64
+      - goos: netbsd
+        goarch: arm
 
 dockers_v2:
   - id: picoclaw
@@ -103,15 +140,49 @@ dockers_v2:
       - picoclaw
     images:
       - "ghcr.io/{{ .Env.GITHUB_REPOSITORY_OWNER }}/picoclaw"
-      - "docker.io/{{ .Env.DOCKERHUB_IMAGE_NAME }}"
+      - 'docker.io/{{ .Env.DOCKERHUB_IMAGE_NAME }}'
     tags:
-      - "{{ .Tag }}"
-      - "latest"
+      - '{{ if isEnvSet "NIGHTLY_BUILD" }}nightly{{ else }}{{ .Tag }}{{ end }}'
+      - '{{ if isEnvSet "NIGHTLY_BUILD" }}nightly{{ else }}latest{{ end }}'
     platforms:
       - linux/amd64
       - linux/arm64
       - linux/riscv64
 
+  - id: picoclaw-launcher
+    dockerfile: docker/Dockerfile.goreleaser.launcher
+    ids:
+      - picoclaw
+      - picoclaw-launcher
+      - picoclaw-launcher-tui
+    images:
+      - "ghcr.io/{{ .Env.GITHUB_REPOSITORY_OWNER }}/picoclaw"
+      - 'docker.io/{{ .Env.DOCKERHUB_IMAGE_NAME }}'
+    tags:
+      - '{{ if isEnvSet "NIGHTLY_BUILD" }}nightly-launcher{{ else }}{{ .Tag }}-launcher{{ end }}'
+      - '{{ if isEnvSet "NIGHTLY_BUILD" }}nightly-launcher{{ else }}launcher{{ end }}'
+    platforms:
+      - linux/amd64
+      - linux/arm64
+      - linux/riscv64
+
+notarize:
+  macos:
+    - enabled: '{{ isEnvSet "MACOS_SIGN_P12" }}'
+      ids:
+        - picoclaw
+        - picoclaw-launcher
+        - picoclaw-launcher-tui
+      sign:
+        certificate: "{{.Env.MACOS_SIGN_P12}}"
+        password: "{{.Env.MACOS_SIGN_PASSWORD}}"
+      notarize:
+        issuer_id: "{{.Env.MACOS_NOTARY_ISSUER_ID}}"
+        key_id: "{{.Env.MACOS_NOTARY_KEY_ID}}"
+        key: "{{.Env.MACOS_NOTARY_KEY}}"
+        wait: true
+        timeout: 20m
+
 archives:
   - formats: [tar.gz]
     # this name template makes the OS and Arch compatible with the results of `uname`.
@@ -129,7 +200,7 @@ archives:
 
 nfpms:
   - id: picoclaw
-    builds:
+    ids:
       - picoclaw
       - picoclaw-launcher
       - picoclaw-launcher-tui
@@ -149,6 +220,11 @@ nfpms:
       - rpm
       - deb
     bindir: /usr/bin
+    contents:
+      - src: web/picoclaw-launcher.desktop
+        dst: /usr/share/applications/picoclaw-launcher.desktop
+      - src: web/picoclaw-launcher.png
+        dst: /usr/share/icons/hicolor/512x512/apps/picoclaw-launcher.png
 
 changelog:
   sort: asc
@@ -163,6 +239,7 @@ changelog:
 #      lzma: true
 
 release:
+  disable: '{{ isEnvSet "NIGHTLY_BUILD" }}'
   footer: >-
 
     ---
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 88227f493..ceff723d2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -269,8 +269,8 @@ Once your PR is submitted, you can reach out to the assigned reviewers listed in
 |Function| Reviewer|
 |---     |---      |
 |Provider|@yinwm   |
-|Channel |@yinwm   |
-|Agent   |@lxowalle|
+|Channel |@yinwm/@alexhoshina   |
+|Agent   |@lxowalle/@Zhaoyikaiii|
 |Tools   |@lxowalle|
 |SKill   ||
 |MCP     ||
diff --git a/CONTRIBUTING.zh.md b/CONTRIBUTING.zh.md
index 01a1abfd5..196aecc65 100644
--- a/CONTRIBUTING.zh.md
+++ b/CONTRIBUTING.zh.md
@@ -268,8 +268,8 @@ Release 分支的保护级别高于 `main`，在任何情况下均不允许直
 |Function| Reviewer|
 |---     |---      |
 |Provider|@yinwm   |
-|Channel |@yinwm   |
-|Agent   |@lxowalle|
+|Channel |@yinwm/@alexhoshina   |
+|Agent   |@lxowalle/@Zhaoyikaiii|
 |Tools   |@lxowalle|
 |SKill   ||
 |MCP     ||
diff --git a/LICENSE b/LICENSE
index 410acae26..b38d9340d 100644
--- a/LICENSE
+++ b/LICENSE
@@ -19,7 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
----
-
-PicoClaw is heavily inspired by and based on [nanobot](https://github.com/HKUDS/nanobot) by HKUDS.
diff --git a/Makefile b/Makefile
index c7375a544..8ffadb4ef 100644
--- a/Makefile
+++ b/Makefile
@@ -11,12 +11,41 @@ VERSION?=$(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 GIT_COMMIT=$(shell git rev-parse --short=8 HEAD 2>/dev/null || echo "dev")
 BUILD_TIME=$(shell date +%FT%T%z)
 GO_VERSION=$(shell $(GO) version | awk '{print $$3}')
-INTERNAL=github.com/sipeed/picoclaw/cmd/picoclaw/internal
-LDFLAGS=-ldflags "-X $(INTERNAL).version=$(VERSION) -X $(INTERNAL).gitCommit=$(GIT_COMMIT) -X $(INTERNAL).buildTime=$(BUILD_TIME) -X $(INTERNAL).goVersion=$(GO_VERSION) -s -w"
+CONFIG_PKG=github.com/sipeed/picoclaw/pkg/config
+LDFLAGS=-X $(CONFIG_PKG).Version=$(VERSION) -X $(CONFIG_PKG).GitCommit=$(GIT_COMMIT) -X $(CONFIG_PKG).BuildTime=$(BUILD_TIME) -X $(CONFIG_PKG).GoVersion=$(GO_VERSION) -s -w
 
 # Go variables
 GO?=CGO_ENABLED=0 go
-GOFLAGS?=-v -tags stdjson
+WEB_GO?=$(GO)
+GO_BUILD_TAGS?=goolm,stdjson
+GOFLAGS?=-v -tags $(GO_BUILD_TAGS)
+comma:=,
+empty:=
+space:=$(empty) $(empty)
+GO_BUILD_TAGS_NO_GOOLM:=$(subst $(space),$(comma),$(strip $(filter-out goolm,$(subst $(comma),$(space),$(GO_BUILD_TAGS)))))
+GOFLAGS_NO_GOOLM?=-v -tags $(GO_BUILD_TAGS_NO_GOOLM)
+
+# Patch MIPS LE ELF e_flags (offset 36) for NaN2008-only kernels (e.g. Ingenic X2600).
+#
+# Bytes (octal): \004 \024 \000 \160  →  little-endian 0x70001404
+#   0x70000000  EF_MIPS_ARCH_32R2   MIPS32 Release 2
+#   0x00001000  EF_MIPS_ABI_O32     O32 ABI
+#   0x00000400  EF_MIPS_NAN2008     IEEE 754-2008 NaN encoding
+#   0x00000004  EF_MIPS_CPIC        PIC calling sequence
+#
+# Go's GOMIPS=softfloat emits no FP instructions, so the NaN mode is irrelevant
+# at runtime — this is purely an ELF metadata fix to satisfy the kernel's check.
+# patchelf cannot modify e_flags; dd at a fixed offset is the most portable way.
+#
+# Ref: https://codebrowser.dev/linux/linux/arch/mips/include/asm/elf.h.html
+define PATCH_MIPS_FLAGS
+	@if [ -f "$(1)" ]; then \
+		printf '\004\024\000\160' | dd of=$(1) bs=1 seek=36 count=4 conv=notrunc 2>/dev/null || \
+		{ echo "Error: failed to patch MIPS e_flags for $(1)"; exit 1; }; \
+	else \
+		echo "Error: $(1) not found, cannot patch MIPS e_flags"; exit 1; \
+	fi
+endef
 
 # Golangci-lint
 GOLANGCI_LINT?=golangci-lint
@@ -50,11 +79,14 @@ ifeq ($(UNAME_S),Linux)
 		ARCH=loong64
 	else ifeq ($(UNAME_M),riscv64)
 		ARCH=riscv64
+	else ifeq ($(UNAME_M),mipsel)
+		ARCH=mipsle
 	else
 		ARCH=$(UNAME_M)
 	endif
 else ifeq ($(UNAME_S),Darwin)
 	PLATFORM=darwin
+	WEB_GO=CGO_ENABLED=1 go
 	ifeq ($(UNAME_M),x86_64)
 		ARCH=amd64
 	else ifeq ($(UNAME_M),arm64)
@@ -83,23 +115,37 @@ generate:
 build: generate
 	@echo "Building $(BINARY_NAME) for $(PLATFORM)/$(ARCH)..."
 	@mkdir -p $(BUILD_DIR)
-	@$(GO) build $(GOFLAGS) $(LDFLAGS) -o $(BINARY_PATH) ./$(CMD_DIR)
+	@$(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BINARY_PATH) ./$(CMD_DIR)
 	@echo "Build complete: $(BINARY_PATH)"
 	@ln -sf $(BINARY_NAME)-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/$(BINARY_NAME)
 
+## build-launcher: Build the picoclaw-launcher (web console) binary
+build-launcher:
+	@echo "Building picoclaw-launcher for $(PLATFORM)/$(ARCH)..."
+	@mkdir -p $(BUILD_DIR)
+	@if [ ! -f web/backend/dist/index.html ]; then \
+		echo "Building frontend..."; \
+		cd web/frontend && pnpm install && pnpm build:backend; \
+	fi
+	@$(WEB_GO) build $(GOFLAGS) -o $(BUILD_DIR)/picoclaw-launcher-$(PLATFORM)-$(ARCH) ./web/backend
+	@ln -sf picoclaw-launcher-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/picoclaw-launcher
+	@echo "Build complete: $(BUILD_DIR)/picoclaw-launcher"
+
 ## build-whatsapp-native: Build with WhatsApp native (whatsmeow) support; larger binary
 build-whatsapp-native: generate
 ## @echo "Building $(BINARY_NAME) with WhatsApp native for $(PLATFORM)/$(ARCH)..."
 	@echo "Building for multiple platforms..."
 	@mkdir -p $(BUILD_DIR)
-	GOOS=linux GOARCH=amd64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 ./$(CMD_DIR)
-	GOOS=linux GOARCH=arm GOARM=7 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm ./$(CMD_DIR)
-	GOOS=linux GOARCH=arm64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
-	GOOS=linux GOARCH=loong64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-loong64 ./$(CMD_DIR)
-	GOOS=linux GOARCH=riscv64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-riscv64 ./$(CMD_DIR)
-	GOOS=darwin GOARCH=arm64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 ./$(CMD_DIR)
-	GOOS=windows GOARCH=amd64 $(GO) build -tags whatsapp_native $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe ./$(CMD_DIR)
-## @$(GO) build $(GOFLAGS) -tags whatsapp_native $(LDFLAGS) -o $(BINARY_PATH) ./$(CMD_DIR)
+	GOOS=linux GOARCH=amd64 $(GO) build -tags $(GO_BUILD_TAGS),whatsapp_native -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm GOARM=7 $(GO) build -tags $(GO_BUILD_TAGS),whatsapp_native -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm64 $(GO) build -tags $(GO_BUILD_TAGS),whatsapp_native -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=loong64 $(GO) build -tags $(GO_BUILD_TAGS),whatsapp_native -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-loong64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=riscv64 $(GO) build -tags $(GO_BUILD_TAGS),whatsapp_native -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-riscv64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=mipsle GOMIPS=softfloat $(GO) build -tags $(GO_BUILD_TAGS_NO_GOOLM),whatsapp_native -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-mipsle ./$(CMD_DIR)
+	$(call PATCH_MIPS_FLAGS,$(BUILD_DIR)/$(BINARY_NAME)-linux-mipsle)
+	GOOS=darwin GOARCH=arm64 $(GO) build -tags $(GO_BUILD_TAGS),whatsapp_native -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 ./$(CMD_DIR)
+	GOOS=windows GOARCH=amd64 $(GO) build -tags $(GO_BUILD_TAGS),whatsapp_native -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe ./$(CMD_DIR)
+## @$(GO) build $(GOFLAGS) -tags whatsapp_native -ldflags "$(LDFLAGS)" -o $(BINARY_PATH) ./$(CMD_DIR)
 	@echo "Build complete"
 ##	@ln -sf $(BINARY_NAME)-$(PLATFORM)-$(ARCH) $(BUILD_DIR)/$(BINARY_NAME)
 
@@ -107,16 +153,24 @@ build-whatsapp-native: generate
 build-linux-arm: generate
 	@echo "Building for linux/arm (GOARM=7)..."
 	@mkdir -p $(BUILD_DIR)
-	GOOS=linux GOARCH=arm GOARM=7 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm GOARM=7 $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm ./$(CMD_DIR)
 	@echo "Build complete: $(BUILD_DIR)/$(BINARY_NAME)-linux-arm"
 
 ## build-linux-arm64: Build for Linux ARM64 (e.g. Raspberry Pi Zero 2 W 64-bit)
 build-linux-arm64: generate
 	@echo "Building for linux/arm64..."
 	@mkdir -p $(BUILD_DIR)
-	GOOS=linux GOARCH=arm64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm64 $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
 	@echo "Build complete: $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64"
 
+## build-linux-mipsle: Build for Linux MIPS32 LE
+build-linux-mipsle: generate
+	@echo "Building for linux/mipsle (softfloat)..."
+	@mkdir -p $(BUILD_DIR)
+	GOOS=linux GOARCH=mipsle GOMIPS=softfloat $(GO) build $(GOFLAGS_NO_GOOLM) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-mipsle ./$(CMD_DIR)
+	$(call PATCH_MIPS_FLAGS,$(BUILD_DIR)/$(BINARY_NAME)-linux-mipsle)
+	@echo "Build complete: $(BUILD_DIR)/$(BINARY_NAME)-linux-mipsle"
+
 ## build-pi-zero: Build for Raspberry Pi Zero 2 W (32-bit and 64-bit)
 build-pi-zero: build-linux-arm build-linux-arm64
 	@echo "Pi Zero 2 W builds: $(BUILD_DIR)/$(BINARY_NAME)-linux-arm (32-bit), $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 (64-bit)"
@@ -125,14 +179,18 @@ build-pi-zero: build-linux-arm build-linux-arm64
 build-all: generate
 	@echo "Building for multiple platforms..."
 	@mkdir -p $(BUILD_DIR)
-	GOOS=linux GOARCH=amd64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 ./$(CMD_DIR)
-	GOOS=linux GOARCH=arm GOARM=7 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm ./$(CMD_DIR)
-	GOOS=linux GOARCH=arm64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
-	GOOS=linux GOARCH=loong64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-loong64 ./$(CMD_DIR)
-	GOOS=linux GOARCH=riscv64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-riscv64 ./$(CMD_DIR)
-	GOOS=linux GOARCH=arm GOARM=7 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-linux-armv7 ./$(CMD_DIR)
-	GOOS=darwin GOARCH=arm64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 ./$(CMD_DIR)
-	GOOS=windows GOARCH=amd64 $(GO) build $(LDFLAGS) -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe ./$(CMD_DIR)
+	GOOS=linux GOARCH=amd64 $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-amd64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm GOARM=7 $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm ./$(CMD_DIR)
+	GOOS=linux GOARCH=arm64 $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-arm64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=loong64 $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-loong64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=riscv64 $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-riscv64 ./$(CMD_DIR)
+	GOOS=linux GOARCH=mipsle GOMIPS=softfloat $(GO) build $(GOFLAGS_NO_GOOLM) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-mipsle ./$(CMD_DIR)
+	$(call PATCH_MIPS_FLAGS,$(BUILD_DIR)/$(BINARY_NAME)-linux-mipsle)
+	GOOS=linux GOARCH=arm GOARM=7 $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-linux-armv7 ./$(CMD_DIR)
+	GOOS=darwin GOARCH=arm64 $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-darwin-arm64 ./$(CMD_DIR)
+	GOOS=windows GOARCH=amd64 $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-windows-amd64.exe ./$(CMD_DIR)
+	GOOS=netbsd GOARCH=amd64 $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-netbsd-amd64 ./$(CMD_DIR)
+	GOOS=netbsd GOARCH=arm64 $(GO) build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/$(BINARY_NAME)-netbsd-arm64 ./$(CMD_DIR)
 	@echo "All builds complete"
 
 ## install: Install picoclaw to system and copy builtin skills
@@ -168,12 +226,15 @@ clean:
 	@echo "Clean complete"
 
 ## vet: Run go vet for static analysis
-vet:
-	@$(GO) vet ./...
+vet: generate
+	@packages="$$($(GO) list $(GOFLAGS) ./...)" && \
+		$(GO) vet $(GOFLAGS) $$(printf '%s\n' "$$packages" | grep -v '^github.com/sipeed/picoclaw/web/')
+	@cd web/backend && $(WEB_GO) vet ./...
 
 ## test: Test Go code
-test:
-	@$(GO) test ./...
+test: generate
+	@$(GO) test $(GOFLAGS) $$($(GO) list $(GOFLAGS) ./... | grep -v github.com/sipeed/picoclaw/web/)
+	@cd web && make test
 
 ## fmt: Format Go code
 fmt:
@@ -181,11 +242,11 @@ fmt:
 
 ## lint: Run linters
 lint:
-	@$(GOLANGCI_LINT) run
+	@CGO_ENABLED=0 $(GOLANGCI_LINT) run --build-tags $(GO_BUILD_TAGS)
 
 ## fix: Fix linting issues
 fix:
-	@$(GOLANGCI_LINT) run --fix
+	@CGO_ENABLED=0 $(GOLANGCI_LINT) run --fix --build-tags $(GO_BUILD_TAGS)
 
 ## deps: Download dependencies
 deps:
@@ -204,6 +265,56 @@ check: deps fmt vet test
 run: build
 	@$(BUILD_DIR)/$(BINARY_NAME) $(ARGS)
 
+## docker-build: Build Docker image (minimal Alpine-based)
+docker-build:
+	@echo "Building minimal Docker image (Alpine-based)..."
+	docker compose -f docker/docker-compose.yml build picoclaw-agent picoclaw-gateway
+
+## docker-build-full: Build Docker image with full MCP support (Node.js 24)
+docker-build-full:
+	@echo "Building full-featured Docker image (Node.js 24)..."
+	docker compose -f docker/docker-compose.full.yml build picoclaw-agent picoclaw-gateway
+
+## docker-test: Test MCP tools in Docker container
+docker-test:
+	@echo "Testing MCP tools in Docker..."
+	@chmod +x scripts/test-docker-mcp.sh
+	@./scripts/test-docker-mcp.sh
+
+## docker-run: Run picoclaw gateway in Docker (Alpine-based)
+docker-run:
+	docker compose -f docker/docker-compose.yml --profile gateway up
+
+## docker-run-full: Run picoclaw gateway in Docker (full-featured)
+docker-run-full:
+	docker compose -f docker/docker-compose.full.yml --profile gateway up
+
+## docker-run-agent: Run picoclaw agent in Docker (interactive, Alpine-based)
+docker-run-agent:
+	docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+
+## docker-run-agent-full: Run picoclaw agent in Docker (interactive, full-featured)
+docker-run-agent-full:
+	docker compose -f docker/docker-compose.full.yml run --rm picoclaw-agent
+
+## docker-clean: Clean Docker images and volumes
+docker-clean:
+	docker compose -f docker/docker-compose.yml down -v
+	docker compose -f docker/docker-compose.full.yml down -v
+	docker rmi picoclaw:latest picoclaw:full 2>/dev/null || true
+
+
+## build-macos-app: Build PicoClaw macOS .app bundle (no terminal window)
+build-macos-app:
+	@echo "Building macOS .app bundle..."
+	@if [ "$(UNAME_S)" != "Darwin" ]; then \
+		echo "Error: This target is only available on macOS"; \
+		exit 1; \
+	fi
+	@cd web && $(MAKE) build && cd ..
+	@./scripts/build-macos-app.sh $(BINARY_NAME)-$(PLATFORM)-$(ARCH)
+	@echo "macOS .app bundle created: $(BUILD_DIR)/PicoClaw.app"
+
 ## help: Show this help message
 help:
 	@echo "picoclaw Makefile"
@@ -219,6 +330,8 @@ help:
 	@echo "  make install            # Install to ~/.local/bin"
 	@echo "  make uninstall          # Remove from /usr/local/bin"
 	@echo "  make install-skills     # Install skills to workspace"
+	@echo "  make docker-build       # Build minimal Docker image"
+	@echo "  make docker-test        # Test MCP tools in Docker"
 	@echo ""
 	@echo "Environment Variables:"
 	@echo "  INSTALL_PREFIX          # Installation prefix (default: ~/.local)"
diff --git a/README.fr.md b/README.fr.md
index 2bec768fc..a4fa628c9 100644
--- a/README.fr.md
+++ b/README.fr.md
@@ -1,143 +1,167 @@
 <div align="center">
-  <img src="assets/logo.jpg" alt="PicoClaw" width="512">
+  <img src="assets/logo.webp" alt="PicoClaw" width="512">
 
   <h1>PicoClaw : Assistant IA Ultra-Efficace en Go</h1>
 
-  <h3>Matériel à 10$ · 10 Mo de RAM · Démarrage en 1s · 皮皮虾，我们走！</h3>
-
+  <h3>Matériel à $10 · 10 Mo de RAM · Démarrage en ms · Let's Go, PicoClaw!</h3>
   <p>
-    <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
-    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20RISC--V-blue" alt="Hardware">
+    <img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
+    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V%2C%20LoongArch-blue" alt="Hardware">
     <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
     <br>
     <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
+    <a href="https://docs.picoclaw.io/"><img src="https://img.shields.io/badge/Docs-Official-007acc?style=flat&logo=read-the-docs&logoColor=white" alt="Docs"></a>
+    <a href="https://deepwiki.com/sipeed/picoclaw"><img src="https://img.shields.io/badge/Wiki-DeepWiki-FFA500?style=flat&logo=wikipedia&logoColor=white" alt="Wiki"></a>
+    <br>
     <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
+    <a href="./assets/wechat.png"><img src="https://img.shields.io/badge/WeChat-Group-41d56b?style=flat&logo=wechat&logoColor=white"></a>
+    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
   </p>
 
- [中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [English](README.md) | **Français**
+[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | **Français** | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md)
+
 </div>
 
 ---
 
-🦐 **PicoClaw** est un assistant personnel IA ultra-léger inspiré de [nanobot](https://github.com/HKUDS/nanobot), entièrement réécrit en **Go** via un processus d'auto-amorçage (self-bootstrapping) — où l'agent IA lui-même a piloté l'intégralité de la migration architecturale et de l'optimisation du code.
+> **PicoClaw** est un projet open-source indépendant initié par [Sipeed](https://sipeed.com), entièrement écrit en **Go** à partir de zéro — ce n'est pas un fork d'OpenClaw, de NanoBot ou de tout autre projet.
+
+**PicoClaw** est un assistant personnel IA ultra-léger inspiré de [NanoBot](https://github.com/HKUDS/nanobot). Il a été entièrement reconstruit en **Go** via un processus d'auto-amorçage (self-bootstrapping) — l'Agent IA lui-même a piloté la migration architecturale et l'optimisation du code.
+
+**Fonctionne sur du matériel à $10 avec <10 Mo de RAM** — c'est 99% de mémoire en moins qu'OpenClaw et 98% moins cher qu'un Mac mini !
 
-⚡️ **Extrêmement léger :** Fonctionne sur du matériel à seulement **10$** avec **<10 Mo** de RAM. C'est 99% de mémoire en moins qu'OpenClaw et 98% moins cher qu'un Mac mini !
 
 <table align="center">
-  <tr align="center">
-    <td align="center" valign="top">
-      <p align="center">
-        <img src="assets/picoclaw_mem.gif" width="360" height="240">
-      </p>
-    </td>
-    <td align="center" valign="top">
-      <p align="center">
-        <img src="assets/licheervnano.png" width="400" height="240">
-      </p>
-    </td>
-  </tr>
+<tr align="center">
+<td align="center" valign="top">
+<p align="center">
+<img src="assets/picoclaw_mem.gif" width="360" height="240">
+</p>
+</td>
+<td align="center" valign="top">
+<p align="center">
+<img src="assets/licheervnano.png" width="400" height="240">
+</p>
+</td>
+</tr>
 </table>
 
 > [!CAUTION]
-> **🚨 SÉCURITÉ & CANAUX OFFICIELS**
+> **Avis de sécurité**
 >
-> * **PAS DE CRYPTO :** PicoClaw n'a **AUCUN** token/jeton officiel. Toute annonce sur `pump.fun` ou d'autres plateformes de trading est une **ARNAQUE**.
-> * **DOMAINE OFFICIEL :** Le **SEUL** site officiel est **[picoclaw.io](https://picoclaw.io)**, et le site de l'entreprise est **[sipeed.com](https://sipeed.com)**.
-> * **Attention :** De nombreux domaines `.ai/.org/.com/.net/...` sont enregistrés par des tiers et ne nous appartiennent pas.
-> * **Attention :** PicoClaw est en phase de développement précoce et peut présenter des problèmes de sécurité réseau non résolus. Ne déployez pas en environnement de production avant la version v1.0.
-> * **Note :** PicoClaw a récemment fusionné de nombreuses PR, ce qui peut entraîner une empreinte mémoire plus importante (10–20 Mo) dans les dernières versions. Nous prévoyons de prioriser l'optimisation des ressources dès que l'ensemble des fonctionnalités sera stabilisé.
-
+> * **PAS DE CRYPTO :** PicoClaw n'a **pas** émis de tokens officiels ni de cryptomonnaie. Toute affirmation sur `pump.fun` ou d'autres plateformes de trading est une **arnaque**.
+> * **DOMAINE OFFICIEL :** Le **SEUL** site officiel est **[picoclaw.io](https://picoclaw.io)**, et le site de l'entreprise est **[sipeed.com](https://sipeed.com)**
+> * **ATTENTION :** De nombreux domaines `.ai/.org/.com/.net/...` ont été enregistrés par des tiers. Ne leur faites pas confiance.
+> * **NOTE :** PicoClaw est en développement rapide précoce. Des problèmes de sécurité non résolus peuvent exister. Ne pas déployer en production avant la v1.0.
+> * **NOTE :** PicoClaw a récemment fusionné de nombreuses PRs. Les builds récents peuvent utiliser 10-20 Mo de RAM. L'optimisation des ressources est prévue après la stabilisation des fonctionnalités.
 
 ## 📢 Actualités
 
-2026-02-16 🎉 PicoClaw a atteint 12K étoiles en une semaine ! Merci à tous pour votre soutien ! PicoClaw grandit plus vite que nous ne l'avions jamais imaginé. Vu le volume élevé de PR, nous avons un besoin urgent de mainteneurs communautaires. Nos rôles de bénévoles et notre feuille de route sont officiellement publiés [ici](docs/ROADMAP.md) — nous avons hâte de vous accueillir !
+2026-03-17 🚀 **v0.2.3 publiée !** Interface system tray (Windows & Linux), requête de statut des sous-agents (`spawn_status`), rechargement à chaud expérimental du Gateway, sécurisation Cron, et 2 correctifs de sécurité. PicoClaw a atteint **25K Stars** !
 
-2026-02-13 🎉 PicoClaw a atteint 5000 étoiles en 4 jours ! Merci à la communauté ! Nous finalisons la **Feuille de Route du Projet** et mettons en place le **Groupe de Développeurs** pour accélérer le développement de PicoClaw.
-🚀 **Appel à l'action :** Soumettez vos demandes de fonctionnalités dans les GitHub Discussions. Nous les examinerons et les prioriserons lors de notre prochaine réunion hebdomadaire.
+2026-03-09 🎉 **v0.2.1 — La plus grande mise à jour à ce jour !** Support du protocole MCP, 4 nouveaux channels (Matrix/IRC/WeCom/Discord Proxy), 3 nouveaux providers (Kimi/Minimax/Avian), pipeline vision, stockage mémoire JSONL, routage de modèles.
+
+2026-02-28 📦 **v0.2.0** publiée avec support Docker Compose et Web UI Launcher.
+
+2026-02-26 🎉 PicoClaw atteint **20K Stars** en seulement 17 jours ! L'orchestration automatique des channels et les interfaces de capacités sont disponibles.
+
+<details>
+<summary>Actualités précédentes...</summary>
+
+2026-02-16 🎉 PicoClaw dépasse 12K Stars en une semaine ! Rôles de mainteneurs communautaires et [Roadmap](ROADMAP.md) officiellement lancés.
+
+2026-02-13 🎉 PicoClaw dépasse 5000 Stars en 4 jours ! Roadmap du projet et groupes de développeurs en cours.
+
+2026-02-09 🎉 **PicoClaw publié !** Construit en 1 jour pour apporter les Agents IA sur du matériel à $10 avec <10 Mo de RAM. Let's Go, PicoClaw !
+
+</details>
 
-2026-02-09 🎉 PicoClaw est lancé ! Construit en 1 jour pour apporter les Agents IA au matériel à 10$ avec <10 Mo de RAM. 🦐 PicoClaw, c'est parti !
 
 ## ✨ Fonctionnalités
 
-🪶 **Ultra-Léger** : Empreinte mémoire <10 Mo — 99% plus petit que Clawdbot pour les fonctionnalités essentielles.
+🪶 **Ultra-léger** : Empreinte mémoire du cœur <10 Mo — 99% plus petit qu'OpenClaw.*
 
-💰 **Coût Minimal** : Suffisamment efficace pour fonctionner sur du matériel à 10$ — 98% moins cher qu'un Mac mini.
+💰 **Coût minimal** : Suffisamment efficace pour fonctionner sur du matériel à $10 — 98% moins cher qu'un Mac mini.
 
-⚡️ **Démarrage Éclair** : Temps de démarrage 400X plus rapide, boot en 1 seconde même sur un cœur unique à 0,6 GHz.
+⚡️ **Démarrage ultra-rapide** : 400x plus rapide au démarrage. Démarre en <1s même sur un processeur monocœur à 0,6 GHz.
 
-🌍 **Véritable Portabilité** : Un seul binaire autonome pour RISC-V, ARM et x86. Un clic et c'est parti !
+🌍 **Vraiment portable** : Binaire unique pour les architectures RISC-V, ARM, MIPS et x86. Un seul binaire, fonctionne partout !
 
-🤖 **Auto-Construit par l'IA** : Implémentation native en Go de manière autonome — 95% du cœur généré par l'Agent avec affinement humain dans la boucle.
+🤖 **Auto-amorcé par IA** : Implémentation native pure Go — 95% du code principal a été généré par un Agent et affiné via une révision humaine en boucle.
 
-|                               | OpenClaw      | NanoBot                  | **PicoClaw**                              |
-| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
-| **Langage**                   | TypeScript    | Python                   | **Go**                                    |
-| **RAM**                       | >1 Go         | >100 Mo                  | **< 10 Mo**                               |
-| **Démarrage**</br>(cœur 0,8 GHz) | >500s     | >30s                     | **<1s**                                   |
-| **Coût**                      | Mac Mini 599$ | La plupart des SBC Linux </br>~50$ | **N'importe quelle carte Linux**</br>**À partir de 10$** |
+🔌 **Support MCP** : Intégration native du [Model Context Protocol](https://modelcontextprotocol.io/) — connectez n'importe quel serveur MCP pour étendre les capacités de l'Agent.
+
+👁️ **Pipeline vision** : Envoyez des images et des fichiers directement à l'Agent — encodage base64 automatique pour les LLMs multimodaux.
+
+🧠 **Routage intelligent** : Routage de modèles basé sur des règles — les requêtes simples vont vers des modèles légers, économisant les coûts API.
+
+_*Les builds récents peuvent utiliser 10-20 Mo en raison des fusions rapides de PRs. L'optimisation des ressources est prévue. Comparaison de vitesse de démarrage basée sur des benchmarks monocœur à 0,8 GHz (voir tableau ci-dessous)._
+
+<div align="center">
+
+|                                | OpenClaw      | NanoBot                  | **PicoClaw**                           |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **Langage**                    | TypeScript    | Python                   | **Go**                                 |
+| **RAM**                        | >1 Go         | >100 Mo                  | **< 10 Mo***                           |
+| **Temps de démarrage**</br>(cœur 0,8 GHz) | >500s | >30s              | **<1s**                                |
+| **Coût**                       | Mac Mini $599 | La plupart des cartes Linux ~$50 | **N'importe quelle carte Linux**</br>**à partir de $10** |
 
 <img src="assets/compare.jpg" alt="PicoClaw" width="512">
 
+</div>
+
+> **[Liste de compatibilité matérielle](docs/fr/hardware-compatibility.md)** — Voir toutes les cartes testées, du RISC-V à $5 au Raspberry Pi en passant par les téléphones Android. Votre carte n'est pas listée ? Soumettez une PR !
+
+<p align="center">
+<img src="assets/hardware-banner.jpg" alt="PicoClaw Hardware Compatibility" width="100%">
+</p>
+
 ## 🦾 Démonstration
 
-### 🛠️ Flux de Travail Standard de l'Assistant
+### 🛠️ Flux de travail standard de l'assistant
 
 <table align="center">
-  <tr align="center">
-    <th><p align="center">🧩 Ingénieur Full-Stack</p></th>
-    <th><p align="center">🗂️ Gestion des Logs & Planification</p></th>
-    <th><p align="center">🔎 Recherche Web & Apprentissage</p></th>
-  </tr>
-  <tr>
-    <td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
-    <td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
-    <td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
-  </tr>
-  <tr>
-    <td align="center">Développer • Déployer • Mettre à l'échelle</td>
-    <td align="center">Planifier • Automatiser • Mémoriser</td>
-    <td align="center">Découvrir • Analyser • Tendances</td>
-  </tr>
+<tr align="center">
+<th><p align="center">Mode Ingénieur Full-Stack</p></th>
+<th><p align="center">Journalisation & Planification</p></th>
+<th><p align="center">Recherche Web & Apprentissage</p></th>
+</tr>
+<tr>
+<td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
+<td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
+<td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
+</tr>
+<tr>
+<td align="center">Développer · Déployer · Mettre à l'échelle</td>
+<td align="center">Planifier · Automatiser · Mémoriser</td>
+<td align="center">Découvrir · Analyser · Tendances</td>
+</tr>
 </table>
 
-### 📱 Utiliser sur d'anciens téléphones Android
-
-Donnez une seconde vie à votre téléphone d'il y a dix ans ! Transformez-le en assistant IA intelligent avec PicoClaw. Démarrage rapide :
-
-1. **Installez Termux** (disponible sur F-Droid ou Google Play).
-2. **Exécutez les commandes**
-
-```bash
-# Note : Remplacez v0.1.1 par la dernière version depuis la page des Releases
-wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
-chmod +x picoclaw-linux-arm64
-pkg install proot
-termux-chroot ./picoclaw-linux-arm64 onboard
-```
-
-Puis suivez les instructions de la section « Démarrage Rapide » pour terminer la configuration !
-
-<img src="assets/termux.jpg" alt="PicoClaw" width="512">
-
-### 🐜 Déploiement Innovant à Faible Empreinte
+### 🐜 Déploiement innovant à faible empreinte
 
 PicoClaw peut être déployé sur pratiquement n'importe quel appareil Linux !
 
-- 9,9$ [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) version E (Ethernet) ou W (WiFi6), pour un Assistant Domotique Minimaliste
-- 30~50$ [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou 100$ [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) pour la Maintenance Automatisée de Serveurs
-- 50$ [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou 100$ [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) pour la Surveillance Intelligente
+- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) édition E(Ethernet) ou W(WiFi6), pour un assistant domestique minimal
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), pour des opérations serveur automatisées
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), pour la surveillance intelligente
 
 <https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4>
 
-🌟 Encore plus de scénarios de déploiement vous attendent !
+🌟 D'autres cas de déploiement vous attendent !
+
 
 ## 📦 Installation
 
-### Installer avec un binaire précompilé
+### Télécharger depuis picoclaw.io (Recommandé)
 
-Téléchargez le binaire pour votre plateforme depuis la page des [releases](https://github.com/sipeed/picoclaw/releases).
+Visitez **[picoclaw.io](https://picoclaw.io)** — le site officiel détecte automatiquement votre plateforme et fournit un téléchargement en un clic. Pas besoin de choisir manuellement une architecture.
 
-### Installer depuis les sources (dernières fonctionnalités, recommandé pour le développement)
+### Télécharger le binaire précompilé
+
+Vous pouvez aussi télécharger le binaire pour votre plateforme depuis la page [GitHub Releases](https://github.com/sipeed/picoclaw/releases).
+
+### Compiler depuis les sources (pour le développement)
 
 ```bash
 git clone https://github.com/sipeed/picoclaw.git
@@ -145,70 +169,141 @@ git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 make deps
 
-# Compiler, pas besoin d'installer
+# Compiler le binaire principal
 make build
 
+# Compiler le Web UI Launcher (requis pour le mode WebUI)
+make build-launcher
+
 # Compiler pour plusieurs plateformes
 make build-all
 
-# Compiler et Installer
+# Compiler pour Raspberry Pi Zero 2 W (32 bits : make build-linux-arm ; 64 bits : make build-linux-arm64)
+make build-pi-zero
+
+# Compiler et installer
 make install
 ```
 
-## 🐳 Docker Compose
+**Raspberry Pi Zero 2 W :** Utilisez le binaire correspondant à votre OS : Raspberry Pi OS 32 bits -> `make build-linux-arm` ; 64 bits -> `make build-linux-arm64`. Ou exécutez `make build-pi-zero` pour compiler les deux.
 
-Vous pouvez également exécuter PicoClaw avec Docker Compose sans rien installer localement.
+## 🚀 Guide de démarrage rapide
+
+### 🌐 WebUI Launcher (Recommandé pour le bureau)
+
+Le WebUI Launcher fournit une interface basée sur navigateur pour la configuration et le chat. C'est la façon la plus simple de démarrer — aucune connaissance de la ligne de commande requise.
+
+**Option 1 : Double-clic (Bureau)**
+
+Après téléchargement depuis [picoclaw.io](https://picoclaw.io), double-cliquez sur `picoclaw-launcher` (ou `picoclaw-launcher.exe` sous Windows). Votre navigateur s'ouvrira automatiquement sur `http://localhost:18800`.
+
+**Option 2 : Ligne de commande**
 
 ```bash
-# 1. Clonez ce dépôt
+picoclaw-launcher
+# Ouvrez http://localhost:18800 dans votre navigateur
+```
+
+> [!TIP]
+> **Accès distant / Docker / VM :** Ajoutez le flag `-public` pour écouter sur toutes les interfaces :
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+<p align="center">
+<img src="assets/launcher-webui.jpg" alt="WebUI Launcher" width="600">
+</p>
+
+**Pour commencer :**
+
+Ouvrez le WebUI, puis : **1)** Configurez un Provider (ajoutez votre clé API LLM) -> **2)** Configurez un Channel (ex. Telegram) -> **3)** Démarrez le Gateway -> **4)** Chattez !
+
+Pour la documentation détaillée du WebUI, voir [docs.picoclaw.io](https://docs.picoclaw.io).
+
+<details>
+<summary><b>Docker (alternative)</b></summary>
+
+```bash
+# 1. Cloner ce dépôt
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Premier lancement — génère docker/data/config.json puis s'arrête
-docker compose -f docker/docker-compose.yml --profile gateway up
-# Le conteneur affiche "First-run setup complete." puis s'arrête.
+# 2. Premier lancement — génère automatiquement docker/data/config.json puis s'arrête
+#    (se déclenche uniquement quand config.json et workspace/ sont tous deux absents)
+docker compose -f docker/docker-compose.yml --profile launcher up
+# Le conteneur affiche "First-run setup complete." et s'arrête.
 
-# 3. Configurez vos clés API
-vim docker/data/config.json   # Clés API du fournisseur, tokens de bot, etc.
+# 3. Définir vos clés API
+vim docker/data/config.json
 
 # 4. Démarrer
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+# Ouvrez http://localhost:18800
 ```
 
-> [!TIP]
-> **Utilisateurs Docker** : Par défaut, le Gateway écoute sur `127.0.0.1`, ce qui n'est pas accessible depuis l'hôte. Si vous avez besoin d'accéder aux endpoints de santé ou d'exposer des ports, définissez `PICOCLAW_GATEWAY_HOST=0.0.0.0` dans votre environnement ou mettez à jour `config.json`.
+> **Utilisateurs Docker / VM :** Le Gateway écoute sur `127.0.0.1` par défaut. Définissez `PICOCLAW_GATEWAY_HOST=0.0.0.0` ou utilisez le flag `-public` pour le rendre accessible depuis l'hôte.
 
 ```bash
-# 5. Voir les logs
-docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+# Vérifier les logs
+docker compose -f docker/docker-compose.yml logs -f
 
-# 6. Arrêter
-docker compose -f docker/docker-compose.yml --profile gateway down
-```
+# Arrêter
+docker compose -f docker/docker-compose.yml --profile launcher down
 
-### Mode Agent (exécution unique)
-
-```bash
-# Poser une question
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Combien font 2+2 ?"
-
-# Mode interactif
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
-```
-
-### Mettre à jour
-
-```bash
+# Mettre à jour
 docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile launcher up -d
 ```
 
-### 🚀 Démarrage Rapide
+</details>
 
-> [!TIP]
-> Configurez votre clé API dans `~/.picoclaw/config.json`.
-> Obtenir des clés API : [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)
-> La recherche web est **optionnelle** — obtenez gratuitement l'[API Brave Search](https://brave.com/search/api) (2000 requêtes gratuites/mois) ou utilisez le repli automatique intégré.
+### 💻 TUI Launcher (Recommandé pour les environnements sans interface / SSH)
+
+Le TUI (Terminal UI) Launcher fournit une interface terminal complète pour la configuration et la gestion. Idéal pour les serveurs, Raspberry Pi et autres environnements sans interface graphique.
+
+```bash
+picoclaw-launcher-tui
+```
+
+<p align="center">
+<img src="assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
+</p>
+
+**Pour commencer :**
+
+Utilisez les menus TUI pour : **1)** Configurer un Provider -> **2)** Configurer un Channel -> **3)** Démarrer le Gateway -> **4)** Chattez !
+
+Pour la documentation détaillée du TUI, voir [docs.picoclaw.io](https://docs.picoclaw.io).
+
+### 📱 Android
+
+Donnez une seconde vie à votre téléphone vieux de dix ans ! Transformez-le en assistant IA intelligent avec PicoClaw.
+
+**Option 1 : Termux (disponible maintenant)**
+
+1. Installez [Termux](https://github.com/termux/termux-app) (téléchargez depuis [GitHub Releases](https://github.com/termux/termux-app/releases), ou cherchez dans F-Droid / Google Play)
+2. Exécutez les commandes suivantes :
+
+```bash
+# Télécharger la dernière version
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard   # chroot fournit une arborescence Linux standard
+```
+
+Suivez ensuite la section Terminal Launcher ci-dessous pour terminer la configuration.
+
+<img src="assets/termux.jpg" alt="PicoClaw on Termux" width="512">
+
+**Option 2 : Installation APK (bientôt disponible)**
+
+Un APK Android autonome avec WebUI intégré est en développement. Restez à l'écoute !
+
+<details>
+<summary><b>Terminal Launcher (pour les environnements à ressources limitées)</b></summary>
+
+Pour les environnements minimaux où seul le binaire principal `picoclaw` est disponible (sans Launcher UI), vous pouvez tout configurer via la ligne de commande et un fichier de configuration JSON.
 
 **1. Initialiser**
 
@@ -216,956 +311,276 @@ docker compose -f docker/docker-compose.yml --profile gateway up -d
 picoclaw onboard
 ```
 
+Cela crée `~/.picoclaw/config.json` et le répertoire workspace.
+
 **2. Configurer** (`~/.picoclaw/config.json`)
 
 ```json
 {
+  "agents": {
+    "defaults": {
+      "model_name": "gpt-5.4"
+    }
+  },
   "model_list": [
     {
-      "model_name": "gpt4",
-      "model": "openai/gpt-5.2",
-      "api_key": "sk-your-openai-key",
-      "request_timeout": 300,
-      "api_base": "https://api.openai.com/v1"
-    }
-  ],
-  "agents": {
-    "defaults": {
-      "model_name": "gpt4"
-    }
-  },
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "VOTRE_TOKEN_BOT",
-      "allow_from": ["VOTRE_USER_ID"]
-    }
-  },
-  "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "VOTRE_CLE_API_BRAVE",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
-      }
-    }
-  }
-}
-```
-
-> **Nouveau** : Le format de configuration `model_list` permet d'ajouter des fournisseurs sans modifier le code. Voir [Configuration de Modèle](#configuration-de-modèle-model_list) pour plus de détails.
-> `request_timeout` est optionnel et s'exprime en secondes. S'il est omis ou défini à `<= 0`, PicoClaw utilise le délai d'expiration par défaut (120s).
-
-**3. Obtenir des Clés API**
-
-* **Fournisseur LLM** : [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
-* **Recherche Web** (optionnel) : [Brave Search](https://brave.com/search/api) - Offre gratuite disponible (2000 requêtes/mois)
-
-> **Note** : Consultez `config.example.json` pour un modèle de configuration complet.
-
-**4. Discuter**
-
-```bash
-picoclaw agent -m "Combien font 2+2 ?"
-```
-
-Et voilà ! Vous avez un assistant IA fonctionnel en 2 minutes.
-
----
-
-## 💬 Applications de Chat
-
-Discutez avec votre PicoClaw via Telegram, Discord, DingTalk, LINE ou WeCom
-
-| Canal        | Configuration                          |
-| ------------ | -------------------------------------- |
-| **Telegram** | Facile (juste un token)                |
-| **Discord**  | Facile (token bot + intents)           |
-| **QQ**       | Facile (AppID + AppSecret)             |
-| **DingTalk** | Moyen (identifiants de l'application)  |
-| **LINE**     | Moyen (identifiants + URL de webhook)  |
-| **WeCom**    | Moyen (CorpID + configuration webhook) |
-
-<details>
-<summary><b>Telegram</b> (Recommandé)</summary>
-
-**1. Créer un bot**
-
-* Ouvrez Telegram, recherchez `@BotFather`
-* Envoyez `/newbot`, suivez les instructions
-* Copiez le token
-
-**2. Configurer**
-
-```json
-{
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "VOTRE_TOKEN_BOT",
-      "allow_from": ["VOTRE_USER_ID"]
-    }
-  }
-}
-```
-
-> Obtenez votre User ID via `@userinfobot` sur Telegram.
-
-**3. Lancer**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>Discord</b></summary>
-
-**1. Créer un bot**
-
-* Rendez-vous sur <https://discord.com/developers/applications>
-* Créez une application → Bot → Add Bot
-* Copiez le token du bot
-
-**2. Activer les intents**
-
-* Dans les paramètres du Bot, activez **MESSAGE CONTENT INTENT**
-* (Optionnel) Activez **SERVER MEMBERS INTENT** si vous souhaitez utiliser des listes d'autorisation basées sur les données des membres
-
-**3. Obtenir votre User ID**
-
-* Paramètres Discord → Avancé → activez le **Mode Développeur**
-* Clic droit sur votre avatar → **Copier l'identifiant**
-
-**4. Configurer**
-
-```json
-{
-  "channels": {
-    "discord": {
-      "enabled": true,
-      "token": "VOTRE_TOKEN_BOT",
-      "allow_from": ["VOTRE_USER_ID"]
-    }
-  }
-}
-```
-
-**5. Inviter le bot**
-
-* OAuth2 → URL Generator
-* Scopes : `bot`
-* Permissions du Bot : `Send Messages`, `Read Message History`
-* Ouvrez l'URL d'invitation générée et ajoutez le bot à votre serveur
-
-**6. Lancer**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>QQ</b></summary>
-
-**1. Créer un bot**
-
-- Rendez-vous sur la [QQ Open Platform](https://q.qq.com/#)
-- Créez une application → Obtenez l'**AppID** et l'**AppSecret**
-
-**2. Configurer**
-
-```json
-{
-  "channels": {
-    "qq": {
-      "enabled": true,
-      "app_id": "VOTRE_APP_ID",
-      "app_secret": "VOTRE_APP_SECRET",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> Laissez `allow_from` vide pour autoriser tous les utilisateurs, ou spécifiez des numéros QQ pour restreindre l'accès.
-
-**3. Lancer**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>DingTalk</b></summary>
-
-**1. Créer un bot**
-
-* Rendez-vous sur la [Open Platform](https://open.dingtalk.com/)
-* Créez une application interne
-* Copiez le Client ID et le Client Secret
-
-**2. Configurer**
-
-```json
-{
-  "channels": {
-    "dingtalk": {
-      "enabled": true,
-      "client_id": "VOTRE_CLIENT_ID",
-      "client_secret": "VOTRE_CLIENT_SECRET",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> Laissez `allow_from` vide pour autoriser tous les utilisateurs, ou spécifiez des identifiants pour restreindre l'accès.
-
-**3. Lancer**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>LINE</b></summary>
-
-**1. Créer un Compte Officiel LINE**
-
-- Rendez-vous sur la [LINE Developers Console](https://developers.line.biz/)
-- Créez un provider → Créez un canal Messaging API
-- Copiez le **Channel Secret** et le **Channel Access Token**
-
-**2. Configurer**
-
-```json
-{
-  "channels": {
-    "line": {
-      "enabled": true,
-      "channel_secret": "VOTRE_CHANNEL_SECRET",
-      "channel_access_token": "VOTRE_CHANNEL_ACCESS_TOKEN",
-      "webhook_path": "/webhook/line",
-      "allow_from": []
-    }
-  }
-}
-```
-
-**3. Configurer l'URL du Webhook**
-
-LINE exige HTTPS pour les webhooks. Utilisez un reverse proxy ou un tunnel :
-
-```bash
-# Exemple avec ngrok (tunnel vers le serveur Gateway partagé)
-ngrok http 18790
-```
-
-Puis configurez l'URL du Webhook dans la LINE Developers Console sur `https://votre-domaine/webhook/line` et activez **Use webhook**.
-
-> **Note** : Le webhook LINE est servi par le serveur Gateway partagé (par défaut `127.0.0.1:18790`). Si vous utilisez ngrok ou un proxy inverse, faites pointer le tunnel vers le port `18790`.
-
-**4. Lancer**
-
-```bash
-picoclaw gateway
-```
-
-> Dans les discussions de groupe, le bot répond uniquement lorsqu'il est mentionné avec @. Les réponses citent le message original.
-
-> **Docker Compose** : Si vous avez besoin d'exposer le webhook LINE via Docker, mappez le port du Gateway partagé (par défaut `18790`) vers l'hôte, par exemple `ports: ["18790:18790"]`. Notez que le serveur Gateway sert les webhooks de tous les canaux à partir de ce port.
-
-</details>
-
-<details>
-<summary><b>WeCom (WeChat Work)</b></summary>
-
-PicoClaw prend en charge deux types d'intégration WeCom :
-
-**Option 1 : WeCom Bot (Robot Intelligent)** - Configuration plus facile, prend en charge les discussions de groupe
-**Option 2 : WeCom App (Application Personnalisée)** - Plus de fonctionnalités, messagerie proactive
-
-Voir le [Guide de Configuration WeCom App](docs/wecom-app-configuration.md) pour des instructions détaillées.
-
-**Configuration Rapide - WeCom Bot :**
-
-**1. Créer un bot**
-
-* Accédez à la Console d'Administration WeCom → Discussion de Groupe → Ajouter un Bot de Groupe
-* Copiez l'URL du webhook (format : `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
-
-**2. Configurer**
-
-```json
-{
-  "channels": {
-    "wecom": {
-      "enabled": true,
-      "token": "YOUR_TOKEN",
-      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_path": "/webhook/wecom",
-      "allow_from": []
-    }
-  }
-}
-```
-
-**Configuration Rapide - WeCom App :**
-
-**1. Créer une application**
-
-* Accédez à la Console d'Administration WeCom → Gestion des Applications → Créer une Application
-* Copiez l'**AgentId** et le **Secret**
-* Accédez à la page "Mon Entreprise", copiez le **CorpID**
-
-**2. Configurer la réception des messages**
-
-* Dans les détails de l'application, cliquez sur "Recevoir les Messages" → "Configurer l'API"
-* Définissez l'URL sur `http://your-server:18790/webhook/wecom-app`
-* Générez le **Token** et l'**EncodingAESKey**
-
-**3. Configurer**
-
-```json
-{
-  "channels": {
-    "wecom_app": {
-      "enabled": true,
-      "corp_id": "wwxxxxxxxxxxxxxxxx",
-      "corp_secret": "YOUR_CORP_SECRET",
-      "agent_id": 1000002,
-      "token": "YOUR_TOKEN",
-      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_path": "/webhook/wecom-app",
-      "allow_from": []
-    }
-  }
-}
-```
-
-**4. Lancer**
-
-```bash
-picoclaw gateway
-```
-
-> **Note** : Les callbacks webhook WeCom App sont servis par le serveur Gateway partagé (par défaut `127.0.0.1:18790`). Assurez-vous que le port `18790` est accessible ou utilisez un proxy inverse HTTPS en production.
-
-</details>
-
-## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Rejoignez le Réseau Social d'Agents
-
-Connectez PicoClaw au Réseau Social d'Agents simplement en envoyant un seul message via le CLI ou n'importe quelle application de chat intégrée.
-
-**Lisez `https://clawdchat.ai/skill.md` et suivez les instructions pour rejoindre [ClawdChat.ai](https://clawdchat.ai)**
-
-## ⚙️ Configuration
-
-Fichier de configuration : `~/.picoclaw/config.json`
-
-### Variables d'Environnement
-
-Vous pouvez remplacer les chemins par défaut à l'aide de variables d'environnement. Ceci est utile pour les installations portables, les déploiements conteneurisés ou l'exécution de picoclaw en tant que service système. Ces variables sont indépendantes et contrôlent différents chemins.
-
-| Variable          | Description                                                                                                                             | Chemin par Défaut         |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
-| `PICOCLAW_CONFIG` | Remplace le chemin du fichier de configuration. Cela indique directement à picoclaw quel `config.json` charger, en ignorant tous les autres emplacements. | `~/.picoclaw/config.json` |
-| `PICOCLAW_HOME`   | Remplace le répertoire racine des données picoclaw. Cela modifie l'emplacement par défaut du `workspace` et des autres répertoires de données.          | `~/.picoclaw`             |
-
-**Exemples :**
-
-```bash
-# Exécuter picoclaw en utilisant un fichier de configuration spécifique
-# Le chemin du workspace sera lu à partir de ce fichier de configuration
-PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
-
-# Exécuter picoclaw avec toutes ses données stockées dans /opt/picoclaw
-# La configuration sera chargée à partir du fichier par défaut ~/.picoclaw/config.json
-# Le workspace sera créé dans /opt/picoclaw/workspace
-PICOCLAW_HOME=/opt/picoclaw picoclaw agent
-
-# Utiliser les deux pour une configuration entièrement personnalisée
-PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
-```
-
-### Structure du Workspace
-
-PicoClaw stocke les données dans votre workspace configuré (par défaut : `~/.picoclaw/workspace`) :
-
-```
-~/.picoclaw/workspace/
-├── sessions/          # Sessions de conversation et historique
-├── memory/           # Mémoire à long terme (MEMORY.md)
-├── state/            # État persistant (dernier canal, etc.)
-├── cron/             # Base de données des tâches planifiées
-├── skills/           # Compétences personnalisées
-├── AGENTS.md         # Guide de comportement de l'Agent
-├── HEARTBEAT.md      # Invites de tâches périodiques (vérifiées toutes les 30 min)
-├── IDENTITY.md       # Identité de l'Agent
-├── SOUL.md           # Âme de l'Agent
-├── TOOLS.md          # Description des outils
-└── USER.md           # Préférences utilisateur
-```
-
-### 🔒 Bac à Sable de Sécurité
-
-PicoClaw s'exécute dans un environnement sandboxé par défaut. L'agent ne peut accéder aux fichiers et exécuter des commandes qu'au sein du workspace configuré.
-
-#### Configuration par Défaut
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "restrict_to_workspace": true
-    }
-  }
-}
-```
-
-| Option | Par défaut | Description |
-|--------|------------|-------------|
-| `workspace` | `~/.picoclaw/workspace` | Répertoire de travail de l'agent |
-| `restrict_to_workspace` | `true` | Restreindre l'accès fichiers/commandes au workspace |
-
-#### Outils Protégés
-
-Lorsque `restrict_to_workspace: true`, les outils suivants sont restreints au bac à sable :
-
-| Outil | Fonction | Restriction |
-|-------|----------|-------------|
-| `read_file` | Lire des fichiers | Uniquement les fichiers dans le workspace |
-| `write_file` | Écrire des fichiers | Uniquement les fichiers dans le workspace |
-| `list_dir` | Lister des répertoires | Uniquement les répertoires dans le workspace |
-| `edit_file` | Éditer des fichiers | Uniquement les fichiers dans le workspace |
-| `append_file` | Ajouter à des fichiers | Uniquement les fichiers dans le workspace |
-| `exec` | Exécuter des commandes | Les chemins doivent être dans le workspace |
-
-#### Protection Supplémentaire d'Exec
-
-Même avec `restrict_to_workspace: false`, l'outil `exec` bloque ces commandes dangereuses :
-
-* `rm -rf`, `del /f`, `rmdir /s` — Suppression en masse
-* `format`, `mkfs`, `diskpart` — Formatage de disque
-* `dd if=` — Écriture d'image disque
-* Écriture vers `/dev/sd[a-z]` — Écriture directe sur le disque
-* `shutdown`, `reboot`, `poweroff` — Arrêt du système
-* Fork bomb `:(){ :|:& };:`
-
-#### Exemples d'Erreurs
-
-```
-[ERROR] tool: Tool execution failed
-{tool=exec, error=Command blocked by safety guard (path outside working dir)}
-```
-
-```
-[ERROR] tool: Tool execution failed
-{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
-```
-
-#### Désactiver les Restrictions (Risque de Sécurité)
-
-Si vous avez besoin que l'agent accède à des chemins en dehors du workspace :
-
-**Méthode 1 : Fichier de configuration**
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "restrict_to_workspace": false
-    }
-  }
-}
-```
-
-**Méthode 2 : Variable d'environnement**
-
-```bash
-export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
-```
-
-> ⚠️ **Attention** : Désactiver cette restriction permet à l'agent d'accéder à n'importe quel chemin sur votre système. À utiliser avec précaution uniquement dans des environnements contrôlés.
-
-#### Cohérence du Périmètre de Sécurité
-
-Le paramètre `restrict_to_workspace` s'applique de manière cohérente sur tous les chemins d'exécution :
-
-| Chemin d'Exécution | Périmètre de Sécurité |
-|--------------------|----------------------|
-| Agent Principal | `restrict_to_workspace` ✅ |
-| Sous-agent / Spawn | Hérite de la même restriction ✅ |
-| Tâches Heartbeat | Hérite de la même restriction ✅ |
-
-Tous les chemins partagent la même restriction de workspace — il est impossible de contourner le périmètre de sécurité via des sous-agents ou des tâches planifiées.
-
-### Heartbeat (Tâches Périodiques)
-
-PicoClaw peut exécuter des tâches périodiques automatiquement. Créez un fichier `HEARTBEAT.md` dans votre workspace :
-
-```markdown
-# Tâches Périodiques
-
-- Vérifier mes e-mails pour les messages importants
-- Consulter mon agenda pour les événements à venir
-- Vérifier les prévisions météo
-```
-
-L'agent lira ce fichier toutes les 30 minutes (configurable) et exécutera les tâches à l'aide des outils disponibles.
-
-#### Tâches Asynchrones avec Spawn
-
-Pour les tâches de longue durée (recherche web, appels API), utilisez l'outil `spawn` pour créer un **sous-agent** :
-
-```markdown
-# Tâches Périodiques
-
-## Tâches Rapides (réponse directe)
-- Indiquer l'heure actuelle
-
-## Tâches Longues (utiliser spawn pour l'asynchrone)
-- Rechercher les actualités IA sur le web et les résumer
-- Vérifier les e-mails et signaler les messages importants
-```
-
-**Comportements clés :**
-
-| Fonctionnalité | Description |
-|----------------|-------------|
-| **spawn** | Crée un sous-agent asynchrone, ne bloque pas le heartbeat |
-| **Contexte indépendant** | Le sous-agent a son propre contexte, sans historique de session |
-| **Outil message** | Le sous-agent communique directement avec l'utilisateur via l'outil message |
-| **Non-bloquant** | Après le spawn, le heartbeat continue vers la tâche suivante |
-
-#### Fonctionnement de la Communication du Sous-agent
-
-```
-Le Heartbeat se déclenche
-    ↓
-L'Agent lit HEARTBEAT.md
-    ↓
-Pour une tâche longue : spawn d'un sous-agent
-    ↓                           ↓
-Continue la tâche suivante   Le sous-agent travaille indépendamment
-    ↓                           ↓
-Toutes les tâches terminées  Le sous-agent utilise l'outil "message"
-    ↓                           ↓
-Répond HEARTBEAT_OK          L'utilisateur reçoit le résultat directement
-```
-
-Le sous-agent a accès aux outils (message, web_search, etc.) et peut communiquer avec l'utilisateur indépendamment sans passer par l'agent principal.
-
-**Configuration :**
-
-```json
-{
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-| Option | Par défaut | Description |
-|--------|------------|-------------|
-| `enabled` | `true` | Activer/désactiver le heartbeat |
-| `interval` | `30` | Intervalle de vérification en minutes (min : 5) |
-
-**Variables d'environnement :**
-
-* `PICOCLAW_HEARTBEAT_ENABLED=false` pour désactiver
-* `PICOCLAW_HEARTBEAT_INTERVAL=60` pour modifier l'intervalle
-
-### Fournisseurs
-
-> [!NOTE]
-> Groq fournit la transcription vocale gratuite via Whisper. Si configuré, les messages vocaux Telegram seront automatiquement transcrits.
-
-| Fournisseur              | Utilisation                              | Obtenir une Clé API                                    |
-| ------------------------ | ---------------------------------------- | ------------------------------------------------------ |
-| `gemini`                 | LLM (Gemini direct)                      | [aistudio.google.com](https://aistudio.google.com)     |
-| `zhipu`                  | LLM (Zhipu direct)                       | [bigmodel.cn](bigmodel.cn)                             |
-| `openrouter` (À tester)  | LLM (recommandé, accès à tous les modèles) | [openrouter.ai](https://openrouter.ai)               |
-| `anthropic` (À tester)   | LLM (Claude direct)                      | [console.anthropic.com](https://console.anthropic.com) |
-| `openai` (À tester)      | LLM (GPT direct)                         | [platform.openai.com](https://platform.openai.com)     |
-| `deepseek` (À tester)    | LLM (DeepSeek direct)                    | [platform.deepseek.com](https://platform.deepseek.com) |
-| `qwen`                   | LLM (Alibaba Qwen)                      | [dashscope.aliyuncs.com](https://dashscope.aliyuncs.com/compatible-mode/v1) |
-| `cerebras`               | LLM (Cerebras)                           | [cerebras.ai](https://api.cerebras.ai/v1)              |
-| `groq`                   | LLM + **Transcription vocale** (Whisper) | [console.groq.com](https://console.groq.com)           |
-
-<details>
-<summary><b>Configuration Zhipu</b></summary>
-
-**1. Obtenir la clé API**
-
-* Obtenez la [clé API](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
-
-**2. Configurer**
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "model": "glm-4.7",
-      "max_tokens": 8192,
-      "temperature": 0.7,
-      "max_tool_iterations": 20
-    }
-  },
-  "providers": {
-    "zhipu": {
-      "api_key": "Votre Clé API",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  }
-}
-```
-
-**3. Lancer**
-
-```bash
-picoclaw agent -m "Bonjour, comment ça va ?"
-```
-
-</details>
-
-<details>
-<summary><b>Exemple de configuration complète</b></summary>
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "model": "anthropic/claude-opus-4-5"
-    }
-  },
-  "providers": {
-    "openrouter": {
-      "api_key": "sk-or-v1-xxx"
-    },
-    "groq": {
-      "api_key": "gsk_xxx"
-    }
-  },
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "123456:ABC...",
-      "allow_from": ["123456789"]
-    },
-    "discord": {
-      "enabled": true,
-      "token": "",
-      "allow_from": [""]
-    },
-    "whatsapp": {
-      "enabled": false
-    },
-    "feishu": {
-      "enabled": false,
-      "app_id": "cli_xxx",
-      "app_secret": "xxx",
-      "encrypt_key": "",
-      "verification_token": "",
-      "allow_from": []
-    },
-    "qq": {
-      "enabled": false,
-      "app_id": "",
-      "app_secret": "",
-      "allow_from": []
-    }
-  },
-  "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "BSA...",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
-      }
-    },
-    "cron": {
-      "exec_timeout_minutes": 5
-    }
-  },
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-</details>
-
-### Configuration de Modèle (model_list)
-
-> **Nouveau !** PicoClaw utilise désormais une approche de configuration **centrée sur le modèle**. Spécifiez simplement le format `fournisseur/modèle` (par exemple, `zhipu/glm-4.7`) pour ajouter de nouveaux fournisseurs—**aucune modification de code requise !**
-
-Cette conception permet également le **support multi-agent** avec une sélection flexible de fournisseurs :
-
-- **Différents agents, différents fournisseurs** : Chaque agent peut utiliser son propre fournisseur LLM
-- **Modèles de secours (Fallbacks)** : Configurez des modèles primaires et de secours pour la résilience
-- **Équilibrage de charge** : Répartissez les requêtes sur plusieurs points de terminaison
-- **Configuration centralisée** : Gérez tous les fournisseurs en un seul endroit
-
-#### 📋 Tous les Fournisseurs Supportés
-
-| Fournisseur | Préfixe `model` | API Base par Défaut | Protocole | Clé API |
-|-------------|-----------------|---------------------|----------|---------|
-| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Obtenir Clé](https://platform.openai.com) |
-| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Obtenir Clé](https://console.anthropic.com) |
-| **Zhipu AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Obtenir Clé](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
-| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Obtenir Clé](https://platform.deepseek.com) |
-| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Obtenir Clé](https://aistudio.google.com/api-keys) |
-| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Obtenir Clé](https://console.groq.com) |
-| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Obtenir Clé](https://platform.moonshot.cn) |
-| **Qwen (Alibaba)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Obtenir Clé](https://dashscope.console.aliyun.com) |
-| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Obtenir Clé](https://build.nvidia.com) |
-| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (pas de clé nécessaire) |
-| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Obtenir Clé](https://openrouter.ai/keys) |
-| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local |
-| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Obtenir Clé](https://cerebras.ai) |
-| **Volcengine** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Obtenir Clé](https://console.volcengine.com) |
-| **ShengsuanYun** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |
-| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth uniquement |
-| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |
-
-#### Configuration de Base
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_key": "sk-your-openai-key"
-    },
-    {
-      "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
-      "api_key": "sk-ant-your-key"
-    },
-    {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-zhipu-key"
-    }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "gpt-5.2"
-    }
-  }
-}
-```
-
-#### Exemples par Fournisseur
-
-**OpenAI**
-```json
-{
-  "model_name": "gpt-5.2",
-  "model": "openai/gpt-5.2",
-  "api_key": "sk-..."
-}
-```
-
-**Zhipu AI (GLM)**
-```json
-{
-  "model_name": "glm-4.7",
-  "model": "zhipu/glm-4.7",
-  "api_key": "your-key"
-}
-```
-
-**Anthropic (avec OAuth)**
-```json
-{
-  "model_name": "claude-sonnet-4.6",
-  "model": "anthropic/claude-sonnet-4.6",
-  "auth_method": "oauth"
-}
-```
-> Exécutez `picoclaw auth login --provider anthropic` pour configurer les identifiants OAuth.
-
-**Proxy/API personnalisée**
-```json
-{
-  "model_name": "my-custom-model",
-  "model": "openai/custom-model",
-  "api_base": "https://my-proxy.com/v1",
-  "api_key": "sk-...",
-  "request_timeout": 300
-}
-```
-
-#### Équilibrage de Charge
-
-Configurez plusieurs points de terminaison pour le même nom de modèle—PicoClaw utilisera automatiquement le round-robin entre eux :
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_base": "https://api1.example.com/v1",
-      "api_key": "sk-key1"
-    },
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_base": "https://api2.example.com/v1",
-      "api_key": "sk-key2"
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-api-key"
     }
   ]
 }
 ```
 
-#### Migration depuis l'Ancienne Configuration `providers`
+> Voir `config/config.example.json` dans le dépôt pour un modèle de configuration complet avec toutes les options disponibles.
 
-L'ancienne configuration `providers` est **dépréciée** mais toujours supportée pour la rétrocompatibilité.
+**3. Chatter**
 
-**Ancienne Configuration (dépréciée) :**
-```json
-{
-  "providers": {
-    "zhipu": {
-      "api_key": "your-key",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  },
-  "agents": {
-    "defaults": {
-      "provider": "zhipu",
-      "model": "glm-4.7"
-    }
-  }
-}
+```bash
+# Question ponctuelle
+picoclaw agent -m "What is 2+2?"
+
+# Mode interactif
+picoclaw agent
+
+# Démarrer le gateway pour l'intégration d'applications de chat
+picoclaw gateway
 ```
 
-**Nouvelle Configuration (recommandée) :**
+</details>
+
+
+## 🔌 Providers (LLM)
+
+PicoClaw supporte plus de 30 providers LLM via la configuration `model_list`. Utilisez le format `protocole/modèle` :
+
+| Provider | Protocole | Clé API | Notes |
+|----------|-----------|---------|-------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Requise | GPT-5.4, GPT-4o, o3, etc. |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Requise | Claude Opus 4.6, Sonnet 4.6, etc. |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Requise | Gemini 3 Flash, 2.5 Pro, etc. |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Requise | 200+ modèles, API unifiée |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Requise | GLM-4.7, GLM-5, etc. |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Requise | DeepSeek-V3, DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | Requise | Modèles Doubao, Ark |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Requise | Qwen3, Qwen-Max, etc. |
+| [Groq](https://console.groq.com/keys) | `groq/` | Requise | Inférence rapide (Llama, Mixtral) |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Requise | Modèles Kimi |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Requise | Modèles MiniMax |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Requise | Mistral Large, Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Requise | Modèles hébergés NVIDIA |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Requise | Inférence rapide |
+| [Novita AI](https://novita.ai/) | `novita/` | Requise | Divers modèles open |
+| [Ollama](https://ollama.com/) | `ollama/` | Non requise | Modèles locaux, auto-hébergé |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | Non requise | Déploiement local, compatible OpenAI |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Variable | Proxy pour 100+ providers |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Requise | Déploiement Azure entreprise |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Connexion par code appareil |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+<details>
+<summary><b>Déploiement local (Ollama, vLLM, etc.)</b></summary>
+
+**Ollama :**
 ```json
 {
   "model_list": [
     {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-key"
+      "model_name": "local-llama",
+      "model": "ollama/llama3.1:8b",
+      "api_base": "http://localhost:11434/v1"
     }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "glm-4.7"
-    }
-  }
+  ]
 }
 ```
 
-Pour le guide de migration détaillé, voir [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md).
+**vLLM :**
+```json
+{
+  "model_list": [
+    {
+      "model_name": "local-vllm",
+      "model": "vllm/your-model",
+      "api_base": "http://localhost:8000/v1"
+    }
+  ]
+}
+```
 
-## Référence CLI
+Pour les détails complets de configuration des providers, voir [Providers & Models](docs/fr/providers.md).
 
-| Commande                  | Description                           |
-| ------------------------- | ------------------------------------- |
-| `picoclaw onboard`        | Initialiser la configuration & le workspace |
-| `picoclaw agent -m "..."` | Discuter avec l'agent                 |
-| `picoclaw agent`          | Mode de discussion interactif         |
-| `picoclaw gateway`        | Démarrer la passerelle                |
-| `picoclaw status`         | Afficher le statut                    |
-| `picoclaw cron list`      | Lister toutes les tâches planifiées   |
-| `picoclaw cron add ...`   | Ajouter une tâche planifiée           |
+</details>
 
-### Tâches Planifiées / Rappels
+## 💬 Channels (Applications de chat)
 
-PicoClaw prend en charge les rappels planifiés et les tâches récurrentes via l'outil `cron` :
+Parlez à votre PicoClaw via plus de 17 plateformes de messagerie :
 
-* **Rappels ponctuels** : « Rappelle-moi dans 10 minutes » → se déclenche une fois après 10 min
-* **Tâches récurrentes** : « Rappelle-moi toutes les 2 heures » → se déclenche toutes les 2 heures
-* **Expressions Cron** : « Rappelle-moi à 9h tous les jours » → utilise une expression cron
+| Channel | Configuration | Protocole | Docs |
+|---------|---------------|-----------|------|
+| **Telegram** | Facile (token bot) | Long polling | [Guide](docs/channels/telegram/README.fr.md) |
+| **Discord** | Facile (token bot + intents) | WebSocket | [Guide](docs/channels/discord/README.fr.md) |
+| **WhatsApp** | Facile (scan QR ou URL bridge) | Natif / Bridge | [Guide](docs/fr/chat-apps.md#whatsapp) |
+| **Weixin** | Facile (scan QR natif) | iLink API | [Guide](docs/fr/chat-apps.md#weixin) |
+| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guide](docs/channels/qq/README.fr.md) |
+| **Slack** | Facile (token bot + app) | Socket Mode | [Guide](docs/channels/slack/README.fr.md) |
+| **Matrix** | Moyen (homeserver + token) | Sync API | [Guide](docs/channels/matrix/README.fr.md) |
+| **DingTalk** | Moyen (identifiants client) | Stream | [Guide](docs/channels/dingtalk/README.fr.md) |
+| **Feishu / Lark** | Moyen (App ID + Secret) | WebSocket/SDK | [Guide](docs/channels/feishu/README.fr.md) |
+| **LINE** | Moyen (identifiants + webhook) | Webhook | [Guide](docs/channels/line/README.fr.md) |
+| **WeCom Bot** | Moyen (URL webhook) | Webhook | [Guide](docs/channels/wecom/wecom_bot/README.fr.md) |
+| **WeCom App** | Moyen (identifiants corp) | Webhook | [Guide](docs/channels/wecom/wecom_app/README.fr.md) |
+| **WeCom AI Bot** | Moyen (token + clé AES) | WebSocket / Webhook | [Guide](docs/channels/wecom/wecom_aibot/README.fr.md) |
+| **IRC** | Moyen (serveur + pseudo) | Protocole IRC | [Guide](docs/fr/chat-apps.md#irc) |
+| **OneBot** | Moyen (URL WebSocket) | OneBot v11 | [Guide](docs/channels/onebot/README.fr.md) |
+| **MaixCam** | Facile (activer) | Socket TCP | [Guide](docs/channels/maixcam/README.fr.md) |
+| **Pico** | Facile (activer) | Protocole natif | Intégré |
+| **Pico Client** | Facile (URL WebSocket) | WebSocket | Intégré |
 
-Les tâches sont stockées dans `~/.picoclaw/workspace/cron/` et traitées automatiquement.
+> Tous les channels basés sur webhook partagent un seul serveur HTTP Gateway (`gateway.host`:`gateway.port`, par défaut `127.0.0.1:18790`). Feishu utilise le mode WebSocket/SDK et n'utilise pas le serveur HTTP partagé.
 
-## 🤝 Contribuer & Feuille de Route
+Pour les instructions détaillées de configuration des channels, voir [Configuration des applications de chat](docs/fr/chat-apps.md).
 
-Les PR sont les bienvenues ! Le code source est volontairement petit et lisible. 🤗
+## 🔧 Outils
 
-Feuille de route à venir...
+### 🔍 Recherche Web
 
-Groupe de développeurs en construction. Condition d'entrée : au moins 1 PR fusionnée.
+PicoClaw peut effectuer des recherches sur le web pour fournir des informations à jour. Configurez dans `tools.web` :
 
-Groupes d'utilisateurs :
+| Moteur de recherche | Clé API | Niveau gratuit | Lien |
+|--------------------|---------|----------------|------|
+| DuckDuckGo | Non requise | Illimité | Fallback intégré |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Requise | 1000 requêtes/jour | IA, optimisé pour le chinois |
+| [Tavily](https://tavily.com) | Requise | 1000 requêtes/mois | Optimisé pour les Agents IA |
+| [Brave Search](https://brave.com/search/api) | Requise | 2000 requêtes/mois | Rapide et privé |
+| [Perplexity](https://www.perplexity.ai) | Requise | Payant | Recherche propulsée par IA |
+| [SearXNG](https://github.com/searxng/searxng) | Non requise | Auto-hébergé | Métamoteur de recherche gratuit |
+| [GLM Search](https://open.bigmodel.cn/) | Requise | Variable | Recherche web Zhipu |
 
-Discord : <https://discord.gg/V4sAZ9XWpN>
+### ⚙️ Autres outils
 
-<img src="assets/wechat.png" alt="PicoClaw" width="512">
+PicoClaw inclut des outils intégrés pour les opérations sur fichiers, l'exécution de code, la planification et plus encore. Voir [Configuration des outils](docs/fr/tools_configuration.md) pour les détails.
 
-## 🐛 Dépannage
+## 🎯 Skills
 
-### La recherche web affiche « API 配置问题 »
+Les Skills sont des capacités modulaires qui étendent votre Agent. Elles sont chargées depuis les fichiers `SKILL.md` dans votre workspace.
 
-C'est normal si vous n'avez pas encore configuré de clé API de recherche. PicoClaw fournira des liens utiles pour la recherche manuelle.
+**Installer des Skills depuis ClawHub :**
 
-Pour activer la recherche web :
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install <skill-name>
+```
 
-1. **Option 1 (Recommandé)** : Obtenez une clé API gratuite sur [https://brave.com/search/api](https://brave.com/search/api) (2000 requêtes gratuites/mois) pour les meilleurs résultats.
-2. **Option 2 (Sans carte bancaire)** : Si vous n'avez pas de clé, le système bascule automatiquement sur **DuckDuckGo** (aucune clé requise).
-
-Ajoutez la clé dans `~/.picoclaw/config.json` si vous utilisez Brave :
+**Configurer le token ClawHub** (optionnel, pour des limites de débit plus élevées) :
 
+Ajoutez à votre `config.json` :
 ```json
 {
   "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "VOTRE_CLE_API_BRAVE",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "auth_token": "your-clawhub-token"
+        }
       }
     }
   }
 }
 ```
 
-### Erreurs de filtrage de contenu
+Pour plus de détails, voir [Configuration des outils - Skills](docs/fr/tools_configuration.md#skills-tool).
 
-Certains fournisseurs (comme Zhipu) disposent d'un filtrage de contenu. Essayez de reformuler votre requête ou utilisez un modèle différent.
+## 🔗 MCP (Model Context Protocol)
 
-### Le bot Telegram affiche « Conflict: terminated by other getUpdates »
+PicoClaw supporte nativement [MCP](https://modelcontextprotocol.io/) — connectez n'importe quel serveur MCP pour étendre les capacités de votre Agent avec des outils et sources de données externes.
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+        }
+      }
+    }
+  }
+}
+```
+
+Pour la configuration MCP complète (transports stdio, SSE, HTTP, Tool Discovery), voir [Configuration des outils - MCP](docs/fr/tools_configuration.md#mcp-tool).
+
+## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Rejoignez le réseau social des Agents
+
+Connectez PicoClaw au réseau social des Agents simplement en envoyant un seul message via le CLI ou n'importe quelle application de chat intégrée.
+
+**Lisez `https://clawdchat.ai/skill.md` et suivez les instructions pour rejoindre [ClawdChat.ai](https://clawdchat.ai)**
+
+## 🖥️ Référence CLI
+
+| Commande                  | Description                              |
+| ------------------------- | ---------------------------------------- |
+| `picoclaw onboard`        | Initialiser la config & le workspace     |
+| `picoclaw auth weixin` | Connecter un compte WeChat via QR |
+| `picoclaw agent -m "..."` | Chatter avec l'agent                     |
+| `picoclaw agent`          | Mode chat interactif                     |
+| `picoclaw gateway`        | Démarrer le gateway                      |
+| `picoclaw status`         | Afficher le statut                       |
+| `picoclaw version`        | Afficher les informations de version     |
+| `picoclaw model`          | Voir ou changer le modèle par défaut     |
+| `picoclaw cron list`      | Lister toutes les tâches planifiées      |
+| `picoclaw cron add ...`   | Ajouter une tâche planifiée              |
+| `picoclaw cron disable`   | Désactiver une tâche planifiée           |
+| `picoclaw cron remove`    | Supprimer une tâche planifiée            |
+| `picoclaw skills list`    | Lister les Skills installées             |
+| `picoclaw skills install` | Installer une Skill                      |
+| `picoclaw migrate`        | Migrer les données depuis d'anciennes versions |
+| `picoclaw auth login`     | S'authentifier auprès des providers      |
+
+### ⏰ Tâches planifiées / Rappels
+
+PicoClaw supporte les rappels planifiés et les tâches récurrentes via l'outil `cron` :
+
+* **Rappels ponctuels** : "Rappelle-moi dans 10 minutes" -> se déclenche une fois après 10 min
+* **Tâches récurrentes** : "Rappelle-moi toutes les 2 heures" -> se déclenche toutes les 2 heures
+* **Expressions cron** : "Rappelle-moi à 9h chaque jour" -> utilise une expression cron
+
+## 📚 Documentation
+
+Pour des guides détaillés au-delà de ce README :
+
+| Sujet | Description |
+|-------|-------------|
+| [Docker & Démarrage rapide](docs/fr/docker.md) | Configuration Docker Compose, modes Launcher/Agent |
+| [Applications de chat](docs/fr/chat-apps.md) | Guides de configuration pour les 17+ channels |
+| [Configuration](docs/fr/configuration.md) | Variables d'environnement, structure du workspace, sandbox de sécurité |
+| [Providers & Modèles](docs/fr/providers.md) | 30+ providers LLM, routage de modèles, configuration model_list |
+| [Spawn & Tâches asynchrones](docs/fr/spawn-tasks.md) | Tâches rapides, tâches longues avec spawn, orchestration de sous-agents asynchrones |
+| [Hooks](docs/hooks/README.md) | Système de hooks événementiels : observateurs, intercepteurs, hooks d'approbation |
+| [Steering](docs/steering.md) | Injecter des messages dans une boucle agent en cours d'exécution |
+| [SubTurn](docs/subturn.md) | Coordination de subagents, contrôle de concurrence, cycle de vie |
+| [Dépannage](docs/fr/troubleshooting.md) | Problèmes courants et solutions |
+| [Configuration des outils](docs/fr/tools_configuration.md) | Activation/désactivation par outil, politiques d'exécution, MCP, Skills |
+| [Compatibilité matérielle](docs/fr/hardware-compatibility.md) | Cartes testées, exigences minimales |
+
+## 🤝 Contribuer & Roadmap
+
+Les PRs sont les bienvenues ! Le code source est intentionnellement petit et lisible.
+
+Consultez notre [Roadmap communautaire](https://github.com/sipeed/picoclaw/issues/988) et [CONTRIBUTING.md](CONTRIBUTING.md) pour les directives.
+
+Groupe de développeurs en construction, rejoignez-le après votre première PR fusionnée !
+
+Groupes d'utilisateurs :
+
+Discord : <https://discord.gg/V4sAZ9XWpN>
+
+WeChat :
+<img src="assets/wechat.png" alt="WeChat group QR code" width="512">
 
-Cela se produit lorsqu'une autre instance du bot est en cours d'exécution. Assurez-vous qu'un seul `picoclaw gateway` fonctionne à la fois.
 
----
 
-## 📝 Comparaison des Clés API
 
-| Service          | Offre Gratuite       | Cas d'Utilisation                     |
-| ---------------- | -------------------- | ------------------------------------- |
-| **OpenRouter**   | 200K tokens/mois     | Multiples modèles (Claude, GPT-4, etc.) |
-| **Zhipu**        | 200K tokens/mois     | Idéal pour les utilisateurs chinois   |
-| **Brave Search** | 2000 requêtes/mois   | Fonctionnalité de recherche web       |
-| **Groq**         | Offre gratuite dispo | Inférence ultra-rapide (Llama, Mixtral) |
diff --git a/README.id.md b/README.id.md
new file mode 100644
index 000000000..6d62dcb9b
--- /dev/null
+++ b/README.id.md
@@ -0,0 +1,579 @@
+<div align="center">
+<img src="assets/logo.webp" alt="PicoClaw" width="512">
+
+<h1>PicoClaw: Asisten AI Super Ringan berbasis Go</h1>
+
+<h3>Perangkat Keras $10 · RAM 10MB · Boot ms · Let's Go, PicoClaw!</h3>
+  <p>
+    <img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
+    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V%2C%20LoongArch-blue" alt="Hardware">
+    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+    <br>
+    <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
+    <a href="https://docs.picoclaw.io/"><img src="https://img.shields.io/badge/Docs-Official-007acc?style=flat&logo=read-the-docs&logoColor=white" alt="Docs"></a>
+    <a href="https://deepwiki.com/sipeed/picoclaw"><img src="https://img.shields.io/badge/Wiki-DeepWiki-FFA500?style=flat&logo=wikipedia&logoColor=white" alt="Wiki"></a>
+    <br>
+    <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
+    <a href="./assets/wechat.png"><img src="https://img.shields.io/badge/WeChat-Group-41d56b?style=flat&logo=wechat&logoColor=white"></a>
+    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
+  </p>
+
+[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [English](README.md) | **Bahasa Indonesia**
+
+</div>
+
+---
+
+> **PicoClaw** adalah proyek open-source independen yang diinisiasi oleh [Sipeed](https://sipeed.com), ditulis sepenuhnya dalam **Go** — bukan fork dari OpenClaw, NanoBot, atau proyek lainnya.
+
+**PicoClaw** adalah asisten AI pribadi yang super ringan, terinspirasi dari [NanoBot](https://github.com/HKUDS/nanobot). Dibangun ulang dari awal dalam **Go** melalui proses "self-bootstrapping" — AI Agent itu sendiri yang memandu migrasi arsitektur dan optimasi kode.
+
+**Berjalan di perangkat keras $10 dengan RAM <10MB** — hemat 99% memori dibanding OpenClaw dan 98% lebih murah dari Mac mini!
+
+<table align="center">
+<tr align="center">
+<td align="center" valign="top">
+<p align="center">
+<img src="assets/picoclaw_mem.gif" width="360" height="240">
+</p>
+</td>
+<td align="center" valign="top">
+<p align="center">
+<img src="assets/licheervnano.png" width="400" height="240">
+</p>
+</td>
+</tr>
+</table>
+
+> [!CAUTION]
+> **Peringatan Keamanan**
+>
+> * **TANPA KRIPTO:** PicoClaw **tidak** menerbitkan token atau cryptocurrency resmi apa pun. Semua klaim di `pump.fun` atau platform trading lainnya adalah **penipuan**.
+> * **DOMAIN RESMI:** Satu-satunya website resmi adalah **[picoclaw.io](https://picoclaw.io)**, dan website perusahaan adalah **[sipeed.com](https://sipeed.com)**
+> * **WASPADA:** Banyak domain `.ai/.org/.com/.net/...` telah didaftarkan oleh pihak ketiga. Jangan percaya mereka.
+> * **CATATAN:** PicoClaw masih dalam tahap pengembangan awal yang cepat. Mungkin ada masalah keamanan yang belum terselesaikan. Jangan deploy ke produksi sebelum v1.0.
+> * **CATATAN:** PicoClaw baru-baru ini menggabungkan banyak PR. Build terbaru mungkin menggunakan RAM 10-20MB. Optimasi sumber daya direncanakan setelah fitur stabil.
+
+## 📢 Berita
+
+2026-03-17 🚀 **v0.2.3 Dirilis!** UI system tray (Windows & Linux), pelacakan status sub-agent (`spawn_status`), eksperimental Gateway hot-reload, gerbang keamanan Cron, dan 2 perbaikan keamanan. PicoClaw telah mencapai **25K Stars**!
+
+2026-03-09 🎉 **v0.2.1 — Update terbesar sejauh ini!** Dukungan protokol MCP, 4 channel baru (Matrix/IRC/WeCom/Discord Proxy), 3 provider baru (Kimi/Minimax/Avian), pipeline vision, penyimpanan memori JSONL, routing model.
+
+2026-02-28 📦 **v0.2.0** dirilis dengan dukungan Docker Compose dan Web UI Launcher.
+
+2026-02-26 🎉 PicoClaw mencapai **20K Stars** hanya dalam 17 hari! Orkestrasi channel otomatis dan antarmuka kapabilitas kini aktif.
+
+<details>
+<summary>Berita sebelumnya...</summary>
+
+2026-02-16 🎉 PicoClaw menembus 12K Stars dalam satu minggu! Peran maintainer komunitas dan [Roadmap](ROADMAP.md) resmi diluncurkan.
+
+2026-02-13 🎉 PicoClaw menembus 5000 Stars dalam 4 hari! Roadmap proyek dan grup pengembang sedang dalam proses.
+
+2026-02-09 🎉 **PicoClaw Diluncurkan!** Dibangun dalam 1 hari untuk menghadirkan AI Agent ke perangkat keras $10 dengan RAM <10MB. Let's Go, PicoClaw!
+
+</details>
+
+## ✨ Fitur
+
+🪶 **Super Ringan**: Penggunaan memori inti <10MB — 99% lebih kecil dari OpenClaw.*
+
+💰 **Biaya Minimal**: Cukup efisien untuk berjalan di perangkat keras $10 — 98% lebih murah dari Mac mini.
+
+⚡️ **Boot Secepat Kilat**: Startup 400x lebih cepat. Boot dalam <1 detik bahkan di prosesor single-core 0,6GHz.
+
+🌍 **Portabilitas Sejati**: Satu binary untuk RISC-V, ARM, MIPS, dan x86. Satu binary, jalan di mana saja!
+
+🤖 **AI-Bootstrapped**: Implementasi Go native murni — 95% kode inti dihasilkan oleh Agent dengan penyempurnaan human-in-the-loop.
+
+🔌 **Dukungan MCP**: Integrasi [Model Context Protocol](https://modelcontextprotocol.io/) native — hubungkan server MCP mana pun untuk memperluas kapabilitas Agent.
+
+👁️ **Pipeline Vision**: Kirim gambar dan file langsung ke Agent — encoding base64 otomatis untuk LLM multimodal.
+
+🧠 **Routing Cerdas**: Routing model berbasis aturan — kueri sederhana diarahkan ke model ringan, menghemat biaya API.
+
+_*Build terbaru mungkin menggunakan 10-20MB karena penggabungan PR yang cepat. Optimasi sumber daya direncanakan. Perbandingan kecepatan boot berdasarkan benchmark single-core 0,8GHz (lihat tabel di bawah)._
+
+<div align="center">
+
+|                                | OpenClaw      | NanoBot                  | **PicoClaw**                           |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **Bahasa**                     | TypeScript    | Python                   | **Go**                                 |
+| **RAM**                        | >1GB          | >100MB                   | **< 10MB***                            |
+| **Waktu Boot**</br>(core 0,8GHz) | >500d       | >30d                     | **<1d**                                |
+| **Biaya**                      | Mac Mini $599 | Kebanyakan board Linux ~$50 | **Board Linux mana pun**</br>**mulai $10** |
+
+<img src="assets/compare.jpg" alt="PicoClaw" width="512">
+
+</div>
+
+> **[Daftar Kompatibilitas Hardware](docs/hardware-compatibility.md)** — Lihat semua board yang telah diuji, dari RISC-V $5 hingga Raspberry Pi hingga ponsel Android. Board Anda belum terdaftar? Kirim PR!
+
+<p align="center">
+<img src="assets/hardware-banner.jpg" alt="PicoClaw Hardware Compatibility" width="100%">
+</p>
+
+## 🦾 Demonstrasi
+
+### 🛠️ Alur Kerja Asisten Standar
+
+<table align="center">
+<tr align="center">
+<th><p align="center">Mode Full-Stack Engineer</p></th>
+<th><p align="center">Pencatatan & Perencanaan</p></th>
+<th><p align="center">Pencarian Web & Pembelajaran</p></th>
+</tr>
+<tr>
+<td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
+<td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
+<td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
+</tr>
+<tr>
+<td align="center">Develop · Deploy · Scale</td>
+<td align="center">Jadwal · Otomasi · Ingat</td>
+<td align="center">Temukan · Wawasan · Tren</td>
+</tr>
+</table>
+
+### 🐜 Deploy Inovatif dengan Footprint Rendah
+
+PicoClaw dapat di-deploy di hampir semua perangkat Linux!
+
+- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versi E(Ethernet) atau W(WiFi6), untuk home assistant minimal
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), atau $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), untuk operasi server otomatis
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) atau $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), untuk pengawasan cerdas
+
+<https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4>
+
+🌟 Lebih Banyak Kasus Deploy Menanti!
+
+## 📦 Instalasi
+
+### Unduh dari picoclaw.io (Direkomendasikan)
+
+Kunjungi **[picoclaw.io](https://picoclaw.io)** — website resmi mendeteksi platform Anda secara otomatis dan menyediakan unduhan satu klik. Tidak perlu memilih arsitektur secara manual.
+
+### Unduh binary yang sudah dikompilasi
+
+Atau, unduh binary untuk platform Anda dari halaman [GitHub Releases](https://github.com/sipeed/picoclaw/releases).
+
+### Build dari source (untuk pengembangan)
+
+```bash
+git clone https://github.com/sipeed/picoclaw.git
+
+cd picoclaw
+make deps
+
+# Build binary inti
+make build
+
+# Build Web UI Launcher (diperlukan untuk mode WebUI)
+make build-launcher
+
+# Build untuk berbagai platform
+make build-all
+
+# Build untuk Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
+make build-pi-zero
+
+# Build dan instal
+make install
+```
+
+**Raspberry Pi Zero 2 W:** Gunakan binary yang sesuai dengan OS Anda: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Atau jalankan `make build-pi-zero` untuk build keduanya.
+
+## 🚀 Panduan Memulai Cepat
+
+### 🌐 WebUI Launcher (Direkomendasikan untuk Desktop)
+
+WebUI Launcher menyediakan antarmuka berbasis browser untuk konfigurasi dan chat. Ini adalah cara termudah untuk memulai — tidak perlu pengetahuan command-line.
+
+**Opsi 1: Klik dua kali (Desktop)**
+
+Setelah mengunduh dari [picoclaw.io](https://picoclaw.io), klik dua kali `picoclaw-launcher` (atau `picoclaw-launcher.exe` di Windows). Browser Anda akan terbuka otomatis di `http://localhost:18800`.
+
+**Opsi 2: Command line**
+
+```bash
+picoclaw-launcher
+# Buka http://localhost:18800 di browser Anda
+```
+
+> [!TIP]
+> **Akses jarak jauh / Docker / VM:** Tambahkan flag `-public` untuk mendengarkan di semua antarmuka:
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+<p align="center">
+<img src="assets/launcher-webui.jpg" alt="WebUI Launcher" width="600">
+</p>
+
+**Memulai:**
+
+Buka WebUI, lalu: **1)** Konfigurasi Provider (tambahkan API key LLM Anda) -> **2)** Konfigurasi Channel (mis. Telegram) -> **3)** Mulai Gateway -> **4)** Chat!
+
+Untuk dokumentasi WebUI lengkap, lihat [docs.picoclaw.io](https://docs.picoclaw.io).
+
+<details>
+<summary><b>Docker (alternatif)</b></summary>
+
+```bash
+# 1. Clone repo ini
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. Jalankan pertama kali — otomatis membuat docker/data/config.json lalu keluar
+#    (hanya terpicu ketika config.json dan workspace/ keduanya tidak ada)
+docker compose -f docker/docker-compose.yml --profile launcher up
+# Container mencetak "First-run setup complete." dan berhenti.
+
+# 3. Atur API key Anda
+vim docker/data/config.json
+
+# 4. Mulai
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+# Buka http://localhost:18800
+```
+
+> **Pengguna Docker / VM:** Gateway mendengarkan di `127.0.0.1` secara default. Atur `PICOCLAW_GATEWAY_HOST=0.0.0.0` atau gunakan flag `-public` agar dapat diakses dari host.
+
+```bash
+# Cek log
+docker compose -f docker/docker-compose.yml logs -f
+
+# Hentikan
+docker compose -f docker/docker-compose.yml --profile launcher down
+
+# Update
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+```
+
+</details>
+
+### 💻 TUI Launcher (Direkomendasikan untuk Headless / SSH)
+
+TUI (Terminal UI) Launcher menyediakan antarmuka terminal lengkap untuk konfigurasi dan manajemen. Ideal untuk server, Raspberry Pi, dan lingkungan headless lainnya.
+
+```bash
+picoclaw-launcher-tui
+```
+
+<p align="center">
+<img src="assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
+</p>
+
+**Memulai:**
+
+Gunakan menu TUI untuk: **1)** Konfigurasi Provider -> **2)** Konfigurasi Channel -> **3)** Mulai Gateway -> **4)** Chat!
+
+Untuk dokumentasi TUI lengkap, lihat [docs.picoclaw.io](https://docs.picoclaw.io).
+
+### 📱 Android
+
+Berikan kehidupan kedua untuk ponsel lama Anda! Ubah menjadi Asisten AI pintar dengan PicoClaw.
+
+**Opsi 1: Termux (tersedia sekarang)**
+
+1. Instal [Termux](https://github.com/termux/termux-app) (unduh dari [GitHub Releases](https://github.com/termux/termux-app/releases), atau cari di F-Droid / Google Play)
+2. Jalankan perintah berikut:
+
+```bash
+# Unduh rilis terbaru
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard   # chroot menyediakan tata letak filesystem Linux standar
+```
+
+Kemudian ikuti bagian Terminal Launcher di bawah untuk menyelesaikan konfigurasi.
+
+<img src="assets/termux.jpg" alt="PicoClaw on Termux" width="512">
+
+**Opsi 2: Instal APK (segera hadir)**
+
+APK Android mandiri dengan WebUI bawaan sedang dalam pengembangan. Pantau terus!
+
+<details>
+<summary><b>Terminal Launcher (untuk lingkungan dengan sumber daya terbatas)</b></summary>
+
+Untuk lingkungan minimal di mana hanya binary inti `picoclaw` yang tersedia (tanpa Launcher UI), Anda dapat mengonfigurasi semuanya melalui command line dan file konfigurasi JSON.
+
+**1. Inisialisasi**
+
+```bash
+picoclaw onboard
+```
+
+Ini membuat `~/.picoclaw/config.json` dan direktori workspace.
+
+**2. Konfigurasi** (`~/.picoclaw/config.json`)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "gpt-5.4"
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-api-key"
+    }
+  ]
+}
+```
+
+> Lihat `config/config.example.json` di repo untuk template konfigurasi lengkap dengan semua opsi yang tersedia.
+
+**3. Chat**
+
+```bash
+# Pertanyaan satu kali
+picoclaw agent -m "What is 2+2?"
+
+# Mode interaktif
+picoclaw agent
+
+# Mulai gateway untuk integrasi aplikasi chat
+picoclaw gateway
+```
+
+</details>
+
+## 🔌 Providers (LLM)
+
+PicoClaw mendukung 30+ provider LLM melalui konfigurasi `model_list`. Gunakan format `protocol/model`:
+
+| Provider | Protocol | API Key | Catatan |
+|----------|----------|---------|---------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Diperlukan | GPT-5.4, GPT-4o, o3, dll. |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Diperlukan | Claude Opus 4.6, Sonnet 4.6, dll. |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Diperlukan | Gemini 3 Flash, 2.5 Pro, dll. |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Diperlukan | 200+ model, API terpadu |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Diperlukan | GLM-4.7, GLM-5, dll. |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Diperlukan | DeepSeek-V3, DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | Diperlukan | Doubao, model Ark |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Diperlukan | Qwen3, Qwen-Max, dll. |
+| [Groq](https://console.groq.com/keys) | `groq/` | Diperlukan | Inferensi cepat (Llama, Mixtral) |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Diperlukan | Model Kimi |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Diperlukan | Model MiniMax |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Diperlukan | Mistral Large, Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Diperlukan | Model yang di-host NVIDIA |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Diperlukan | Inferensi cepat |
+| [Novita AI](https://novita.ai/) | `novita/` | Diperlukan | Berbagai model open |
+| [Ollama](https://ollama.com/) | `ollama/` | Tidak perlu | Model lokal, self-hosted |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | Tidak perlu | Deploy lokal, kompatibel OpenAI |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Bervariasi | Proxy untuk 100+ provider |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Diperlukan | Deploy Azure enterprise |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Login dengan device code |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+<details>
+<summary><b>Deploy lokal (Ollama, vLLM, dll.)</b></summary>
+
+**Ollama:**
+```json
+{
+  "model_list": [
+    {
+      "model_name": "local-llama",
+      "model": "ollama/llama3.1:8b",
+      "api_base": "http://localhost:11434/v1"
+    }
+  ]
+}
+```
+
+**vLLM:**
+```json
+{
+  "model_list": [
+    {
+      "model_name": "local-vllm",
+      "model": "vllm/your-model",
+      "api_base": "http://localhost:8000/v1"
+    }
+  ]
+}
+```
+
+Untuk detail konfigurasi provider lengkap, lihat [Providers & Models](docs/providers.md).
+
+</details>
+
+## 💬 Channels (Aplikasi Chat)
+
+Bicara dengan PicoClaw Anda melalui 17+ platform pesan:
+
+| Channel | Pengaturan | Protocol | Dokumentasi |
+|---------|------------|----------|-------------|
+| **Telegram** | Mudah (bot token) | Long polling | [Panduan](docs/channels/telegram/README.md) |
+| **Discord** | Mudah (bot token + intents) | WebSocket | [Panduan](docs/channels/discord/README.md) |
+| **WhatsApp** | Mudah (scan QR atau bridge URL) | Native / Bridge | [Panduan](docs/chat-apps.md#whatsapp) |
+| **Weixin** | Mudah (scan QR native) | iLink API | [Panduan](docs/chat-apps.md#weixin) |
+| **QQ** | Mudah (AppID + AppSecret) | WebSocket | [Panduan](docs/channels/qq/README.md) |
+| **Slack** | Mudah (bot + app token) | Socket Mode | [Panduan](docs/channels/slack/README.md) |
+| **Matrix** | Sedang (homeserver + token) | Sync API | [Panduan](docs/channels/matrix/README.md) |
+| **DingTalk** | Sedang (client credentials) | Stream | [Panduan](docs/channels/dingtalk/README.md) |
+| **Feishu / Lark** | Sedang (App ID + Secret) | WebSocket/SDK | [Panduan](docs/channels/feishu/README.md) |
+| **LINE** | Sedang (credentials + webhook) | Webhook | [Panduan](docs/channels/line/README.md) |
+| **WeCom Bot** | Sedang (webhook URL) | Webhook | [Panduan](docs/channels/wecom/wecom_bot/README.md) |
+| **WeCom App** | Sedang (corp credentials) | Webhook | [Panduan](docs/channels/wecom/wecom_app/README.md) |
+| **WeCom AI Bot** | Sedang (token + AES key) | WebSocket / Webhook | [Panduan](docs/channels/wecom/wecom_aibot/README.md) |
+| **IRC** | Sedang (server + nick) | IRC protocol | [Panduan](docs/chat-apps.md#irc) |
+| **OneBot** | Sedang (WebSocket URL) | OneBot v11 | [Panduan](docs/channels/onebot/README.md) |
+| **MaixCam** | Mudah (aktifkan) | TCP socket | [Panduan](docs/channels/maixcam/README.md) |
+| **Pico** | Mudah (aktifkan) | Native protocol | Bawaan |
+| **Pico Client** | Mudah (WebSocket URL) | WebSocket | Bawaan |
+
+> Semua channel berbasis webhook berbagi satu server HTTP Gateway (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu menggunakan mode WebSocket/SDK dan tidak menggunakan server HTTP bersama.
+
+Untuk instruksi pengaturan channel lengkap, lihat [Konfigurasi Aplikasi Chat](docs/chat-apps.md).
+
+## 🔧 Tools
+
+### 🔍 Pencarian Web
+
+PicoClaw dapat mencari web untuk memberikan informasi terkini. Konfigurasi di `tools.web`:
+
+| Mesin Pencari | API Key | Tier Gratis | Tautan |
+|--------------|---------|-------------|--------|
+| DuckDuckGo | Tidak perlu | Tidak terbatas | Fallback bawaan |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Diperlukan | 1000 kueri/hari | Bertenaga AI, dioptimalkan untuk bahasa Mandarin |
+| [Tavily](https://tavily.com) | Diperlukan | 1000 kueri/bulan | Dioptimalkan untuk AI Agent |
+| [Brave Search](https://brave.com/search/api) | Diperlukan | 2000 kueri/bulan | Cepat dan privat |
+| [Perplexity](https://www.perplexity.ai) | Diperlukan | Berbayar | Pencarian bertenaga AI |
+| [SearXNG](https://github.com/searxng/searxng) | Tidak perlu | Self-hosted | Mesin metasearch gratis |
+| [GLM Search](https://open.bigmodel.cn/) | Diperlukan | Bervariasi | Pencarian web Zhipu |
+
+### ⚙️ Tools Lainnya
+
+PicoClaw menyertakan tools bawaan untuk operasi file, eksekusi kode, penjadwalan, dan lainnya. Lihat [Konfigurasi Tools](docs/tools_configuration.md) untuk detail.
+
+## 🎯 Skills
+
+Skills adalah kapabilitas modular yang memperluas Agent Anda. Dimuat dari file `SKILL.md` di workspace Anda.
+
+**Instal skills dari ClawHub:**
+
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install <skill-name>
+```
+
+**Konfigurasi token ClawHub** (opsional, untuk rate limit lebih tinggi):
+
+Tambahkan ke `config.json` Anda:
+```json
+{
+  "tools": {
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "auth_token": "your-clawhub-token"
+        }
+      }
+    }
+  }
+}
+```
+
+Untuk detail lebih lanjut, lihat [Konfigurasi Tools - Skills](docs/tools_configuration.md#skills-tool).
+
+## 🔗 MCP (Model Context Protocol)
+
+PicoClaw mendukung [MCP](https://modelcontextprotocol.io/) secara native — hubungkan server MCP mana pun untuk memperluas kapabilitas Agent Anda dengan tools dan sumber data eksternal.
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+        }
+      }
+    }
+  }
+}
+```
+
+Untuk konfigurasi MCP lengkap (transport stdio, SSE, HTTP, Tool Discovery), lihat [Konfigurasi Tools - MCP](docs/tools_configuration.md#mcp-tool).
+
+## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Bergabung dengan Jaringan Sosial Agent
+
+Hubungkan PicoClaw ke Jaringan Sosial Agent hanya dengan mengirim satu pesan melalui CLI atau Aplikasi Chat terintegrasi mana pun.
+
+**Baca `https://clawdchat.ai/skill.md` dan ikuti instruksi untuk bergabung dengan [ClawdChat.ai](https://clawdchat.ai)**
+
+## 🖥️ Referensi CLI
+
+| Perintah                   | Deskripsi                        |
+| -------------------------- | -------------------------------- |
+| `picoclaw onboard`         | Inisialisasi konfigurasi & workspace |
+| `picoclaw auth weixin` | Hubungkan akun WeChat via QR |
+| `picoclaw agent -m "..."` | Chat dengan agent                |
+| `picoclaw agent`           | Mode chat interaktif             |
+| `picoclaw gateway`         | Mulai gateway                    |
+| `picoclaw status`          | Tampilkan status                 |
+| `picoclaw version`         | Tampilkan info versi             |
+| `picoclaw model`           | Lihat atau ganti model default   |
+| `picoclaw cron list`       | Daftar semua tugas terjadwal     |
+| `picoclaw cron add ...`    | Tambah tugas terjadwal           |
+| `picoclaw cron disable`    | Nonaktifkan tugas terjadwal      |
+| `picoclaw cron remove`     | Hapus tugas terjadwal            |
+| `picoclaw skills list`     | Daftar skill yang terinstal      |
+| `picoclaw skills install`  | Instal skill                     |
+| `picoclaw migrate`         | Migrasi data dari versi lama     |
+| `picoclaw auth login`      | Autentikasi dengan provider      |
+
+### ⏰ Tugas Terjadwal / Pengingat
+
+PicoClaw mendukung pengingat terjadwal dan tugas berulang melalui tool `cron`:
+
+* **Pengingat satu kali**: "Ingatkan saya dalam 10 menit" -> terpicu sekali setelah 10 menit
+* **Tugas berulang**: "Ingatkan saya setiap 2 jam" -> terpicu setiap 2 jam
+* **Ekspresi cron**: "Ingatkan saya jam 9 pagi setiap hari" -> menggunakan ekspresi cron
+
+## 📚 Dokumentasi
+
+Untuk panduan lengkap di luar README ini:
+
+| Topik | Deskripsi |
+|-------|-----------|
+| [Docker & Panduan Cepat](docs/docker.md) | Pengaturan Docker Compose, mode Launcher/Agent |
+| [Aplikasi Chat](docs/chat-apps.md) | Semua 17+ panduan pengaturan channel |
+| [Konfigurasi](docs/configuration.md) | Variabel environment, tata letak workspace, sandbox keamanan |
+| [Providers & Models](docs/providers.md) | 30+ provider LLM, routing model, konfigurasi model_list |
+| [Spawn & Tugas Async](docs/spawn-tasks.md) | Tugas cepat, tugas panjang dengan spawn, orkestrasi sub-agent async |
+| [Hooks](docs/hooks/README.md) | Sistem hook berbasis event: observer, interceptor, approval hook |
+| [Steering](docs/steering.md) | Menyuntikkan pesan ke dalam loop agent yang sedang berjalan |
+| [SubTurn](docs/subturn.md) | Koordinasi subagent, kontrol konkurensi, siklus hidup |
+| [Pemecahan Masalah](docs/troubleshooting.md) | Masalah umum dan solusinya |
+| [Konfigurasi Tools](docs/tools_configuration.md) | Aktifkan/nonaktifkan per-tool, kebijakan exec, MCP, Skills |
+| [Kompatibilitas Hardware](docs/hardware-compatibility.md) | Board yang telah diuji, persyaratan minimum |
+
+## 🤝 Kontribusi & Roadmap
+
+PR sangat diterima! Codebase sengaja dibuat kecil dan mudah dibaca.
+
+Lihat [Roadmap Komunitas](https://github.com/sipeed/picoclaw/issues/988) dan [CONTRIBUTING.md](CONTRIBUTING.md) untuk panduan.
+
+Grup pengembang sedang dibangun, bergabunglah setelah PR pertama Anda di-merge!
+
+Grup Pengguna:
+
+Discord: <https://discord.gg/V4sAZ9XWpN>
+
+WeChat:
+<img src="assets/wechat.png" alt="Kode QR grup WeChat" width="512">
+
diff --git a/README.it.md b/README.it.md
new file mode 100644
index 000000000..1ed73ee54
--- /dev/null
+++ b/README.it.md
@@ -0,0 +1,578 @@
+<div align="center">
+<img src="assets/logo.webp" alt="PicoClaw" width="512">
+
+<h1>PicoClaw: Assistente IA Ultra-Efficiente in Go</h1>
+
+<h3>Hardware da $10 · 10MB di RAM · Avvio in ms · Let's Go, PicoClaw!</h3>
+  <p>
+    <img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
+    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V%2C%20LoongArch-blue" alt="Hardware">
+    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+    <br>
+    <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
+    <a href="https://docs.picoclaw.io/"><img src="https://img.shields.io/badge/Docs-Official-007acc?style=flat&logo=read-the-docs&logoColor=white" alt="Docs"></a>
+    <a href="https://deepwiki.com/sipeed/picoclaw"><img src="https://img.shields.io/badge/Wiki-DeepWiki-FFA500?style=flat&logo=wikipedia&logoColor=white" alt="Wiki"></a>
+    <br>
+    <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
+    <a href="./assets/wechat.png"><img src="https://img.shields.io/badge/WeChat-Group-41d56b?style=flat&logo=wechat&logoColor=white"></a>
+    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
+  </p>
+
+[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **Italiano** | [Bahasa Indonesia](README.id.md) | [English](README.md)
+
+</div>
+
+---
+
+> **PicoClaw** è un progetto open-source indipendente avviato da [Sipeed](https://sipeed.com), scritto interamente in **Go** da zero — non è un fork di OpenClaw, NanoBot o di qualsiasi altro progetto.
+
+**PicoClaw** è un assistente IA personale ultra-leggero ispirato a [NanoBot](https://github.com/HKUDS/nanobot). È stato riscritto da zero in **Go** attraverso un processo di "auto-bootstrapping" — l'Agent IA stesso ha guidato la migrazione architetturale e l'ottimizzazione del codice.
+
+**Funziona su hardware da $10 con <10MB di RAM** — il 99% di memoria in meno rispetto a OpenClaw e il 98% più economico di un Mac mini!
+
+<table align="center">
+<tr align="center">
+<td align="center" valign="top">
+<p align="center">
+<img src="assets/picoclaw_mem.gif" width="360" height="240">
+</p>
+</td>
+<td align="center" valign="top">
+<p align="center">
+<img src="assets/licheervnano.png" width="400" height="240">
+</p>
+</td>
+</tr>
+</table>
+
+> [!CAUTION]
+> **Avviso di Sicurezza**
+>
+> * **NESSUNA CRYPTO:** PicoClaw **non** ha emesso token o criptovalute ufficiali. Qualsiasi annuncio su `pump.fun` o altre piattaforme di trading è una **truffa**.
+> * **DOMINIO UFFICIALE:** L'**UNICO** sito ufficiale è **[picoclaw.io](https://picoclaw.io)**, e il sito aziendale è **[sipeed.com](https://sipeed.com)**
+> * **ATTENZIONE:** Molti domini `.ai/.org/.com/.net/...` sono stati registrati da terze parti. Non fidarti di essi.
+> * **NOTA:** PicoClaw è in fase di sviluppo iniziale rapido. Potrebbero esserci problemi di sicurezza non risolti. Non distribuire in produzione prima della v1.0.
+> * **NOTA:** PicoClaw ha recentemente unito molte PR. Le build recenti potrebbero usare 10-20MB di RAM. L'ottimizzazione delle risorse è pianificata dopo la stabilizzazione delle funzionalità.
+
+## 📢 Novità
+
+2026-03-17 🚀 **v0.2.3 rilasciata!** Interfaccia system tray (Windows & Linux), query sullo stato dei sub-agent (`spawn_status`), hot-reload sperimentale del Gateway, gate di sicurezza per Cron e 2 correzioni di sicurezza. PicoClaw raggiunge **25K Stars**!
+
+2026-03-09 🎉 **v0.2.1 — Il più grande aggiornamento di sempre!** Supporto al protocollo MCP, 4 nuovi canali (Matrix/IRC/WeCom/Discord Proxy), 3 nuovi provider (Kimi/Minimax/Avian), pipeline di visione, store di memoria JSONL e routing dei modelli.
+
+2026-02-28 📦 **v0.2.0** rilasciata con supporto Docker Compose e Web UI Launcher.
+
+2026-02-26 🎉 PicoClaw raggiunge **20K stelle** in soli 17 giorni! Orchestrazione automatica dei canali e interfacce di capacità sono attive.
+
+<details>
+<summary>Notizie precedenti...</summary>
+
+2026-02-16 🎉 PicoClaw supera 12K stelle in una settimana! Ruoli di maintainer della community e [Roadmap](ROADMAP.md) pubblicati ufficialmente.
+
+2026-02-13 🎉 PicoClaw supera 5000 stelle in 4 giorni! Roadmap del progetto e gruppi sviluppatori in fase di avvio.
+
+2026-02-09 🎉 **PicoClaw lanciato!** Costruito in 1 giorno per portare gli AI Agent su hardware da $10 con <10MB di RAM. Let's Go, PicoClaw!
+
+</details>
+
+## ✨ Caratteristiche
+
+🪶 **Ultra-Leggero**: Impronta di memoria <10MB — il 99% più piccolo rispetto a OpenClaw.*
+
+💰 **Costo Minimo**: Abbastanza efficiente da girare su hardware da $10 — il 98% più economico di un Mac mini.
+
+⚡️ **Avvio Fulmineo**: Avvio 400 volte più veloce. Boot in meno di 1 secondo anche su un singolo core a 0,6 GHz.
+
+🌍 **Vera Portabilità**: Singolo binario per RISC-V, ARM, MIPS e x86. Un binario, funziona ovunque!
+
+🤖 **Auto-Costruito dall'IA**: Implementazione nativa in Go — il 95% del codice core è stato generato da un Agent e perfezionato tramite revisione umana nel ciclo.
+
+🔌 **Supporto MCP**: Integrazione nativa del [Model Context Protocol](https://modelcontextprotocol.io/) — connetti qualsiasi server MCP per estendere le capacità dell'Agent.
+
+👁️ **Pipeline di Visione**: Invia immagini e file direttamente all'Agent — codifica base64 automatica per LLM multimodali.
+
+🧠 **Routing Intelligente**: Routing dei modelli basato su regole — le query semplici vanno verso modelli leggeri, risparmiando sui costi API.
+
+_*Le build recenti potrebbero usare 10-20MB a causa delle fusioni rapide di PR. L'ottimizzazione delle risorse è pianificata. Il confronto dell'avvio è basato su benchmark con singolo core a 0,8 GHz (vedi tabella sotto)._
+
+<div align="center">
+
+|                                | OpenClaw      | NanoBot                  | **PicoClaw**                           |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **Linguaggio**                 | TypeScript    | Python                   | **Go**                                 |
+| **RAM**                        | >1GB          | >100MB                   | **< 10MB***                            |
+| **Avvio**</br>(core 0,8 GHz)  | >500s         | >30s                     | **<1s**                                |
+| **Costo**                      | Mac Mini $599 | La maggior parte degli SBC Linux ~$50 | **Qualsiasi scheda Linux**</br>**a partire da $10** |
+
+<img src="assets/compare.jpg" alt="PicoClaw" width="512">
+
+</div>
+
+> **[Lista di Compatibilità Hardware](docs/hardware-compatibility.md)** — Vedi tutte le schede testate, dai $5 RISC-V al Raspberry Pi ai telefoni Android. La tua scheda non è elencata? Invia una PR!
+
+<p align="center">
+<img src="assets/hardware-banner.jpg" alt="PicoClaw Hardware Compatibility" width="100%">
+</p>
+
+## 🦾 Dimostrazione
+
+### 🛠️ Flussi di Lavoro Standard dell'Assistente
+
+<table align="center">
+<tr align="center">
+<th><p align="center">Modalità Ingegnere Full-Stack</p></th>
+<th><p align="center">Log & Pianificazione</p></th>
+<th><p align="center">Ricerca Web & Apprendimento</p></th>
+</tr>
+<tr>
+<td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
+<td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
+<td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
+</tr>
+<tr>
+<td align="center">Sviluppa · Distribuisci · Scala</td>
+<td align="center">Pianifica · Automatizza · Memorizza</td>
+<td align="center">Scopri · Analizza · Tendenze</td>
+</tr>
+</table>
+
+### 🐜 Deploy Innovativo a Bassa Impronta
+
+PicoClaw può essere distribuito su quasi qualsiasi dispositivo Linux!
+
+- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versione E (Ethernet) o W (WiFi6), per un assistente domotico minimale
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), o $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), per la manutenzione automatizzata dei server
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) o $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), per la sorveglianza intelligente
+
+<https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4>
+
+🌟 Molti altri scenari di deploy ti aspettano!
+
+## 📦 Installazione
+
+### Scarica da picoclaw.io (Consigliato)
+
+Visita **[picoclaw.io](https://picoclaw.io)** — il sito ufficiale rileva automaticamente la tua piattaforma e fornisce il download con un clic. Non è necessario scegliere manualmente l'architettura.
+
+### Scarica il binario precompilato
+
+In alternativa, scarica il binario per la tua piattaforma dalla pagina delle [GitHub Releases](https://github.com/sipeed/picoclaw/releases).
+
+### Compila dai sorgenti (per lo sviluppo)
+
+```bash
+git clone https://github.com/sipeed/picoclaw.git
+
+cd picoclaw
+make deps
+
+# Compila il binario core
+make build
+
+# Compila il Web UI Launcher (necessario per la modalità WebUI)
+make build-launcher
+
+# Compila per più piattaforme
+make build-all
+
+# Compila per Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
+make build-pi-zero
+
+# Compila e installa
+make install
+```
+
+**Raspberry Pi Zero 2 W:** Usa il binario che corrisponde al tuo OS: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Oppure esegui `make build-pi-zero` per compilare entrambi.
+
+## 🚀 Guida Rapida
+
+### 🌐 WebUI Launcher (Consigliato per Desktop)
+
+Il WebUI Launcher fornisce un'interfaccia basata su browser per la configurazione e la chat. È il modo più semplice per iniziare — non è richiesta alcuna conoscenza della riga di comando.
+
+**Opzione 1: Doppio clic (Desktop)**
+
+Dopo aver scaricato da [picoclaw.io](https://picoclaw.io), fai doppio clic su `picoclaw-launcher` (o `picoclaw-launcher.exe` su Windows). Il browser si aprirà automaticamente su `http://localhost:18800`.
+
+**Opzione 2: Riga di comando**
+
+```bash
+picoclaw-launcher
+# Apri http://localhost:18800 nel browser
+```
+
+> [!TIP]
+> **Accesso remoto / Docker / VM:** Aggiungi il flag `-public` per ascoltare su tutte le interfacce:
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+<p align="center">
+<img src="assets/launcher-webui.jpg" alt="WebUI Launcher" width="600">
+</p>
+
+**Per iniziare:**
+
+Apri il WebUI, poi: **1)** Configura un Provider (aggiungi la tua API key LLM) -> **2)** Configura un Channel (es. Telegram) -> **3)** Avvia il Gateway -> **4)** Chatta!
+
+Per la documentazione dettagliata del WebUI, vedi [docs.picoclaw.io](https://docs.picoclaw.io).
+
+<details>
+<summary><b>Docker (alternativa)</b></summary>
+
+```bash
+# 1. Clona questo repo
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. Prima esecuzione — genera automaticamente docker/data/config.json poi si ferma
+#    (si attiva solo quando sia config.json che workspace/ sono assenti)
+docker compose -f docker/docker-compose.yml --profile launcher up
+# Il container stampa "First-run setup complete." e si ferma.
+
+# 3. Imposta le tue API key
+vim docker/data/config.json
+
+# 4. Avvia
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+# Apri http://localhost:18800
+```
+
+> **Utenti Docker / VM:** Il Gateway ascolta su `127.0.0.1` per impostazione predefinita. Imposta `PICOCLAW_GATEWAY_HOST=0.0.0.0` o usa il flag `-public` per renderlo accessibile dall'host.
+
+```bash
+# Controlla i log
+docker compose -f docker/docker-compose.yml logs -f
+
+# Ferma
+docker compose -f docker/docker-compose.yml --profile launcher down
+
+# Aggiorna
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+```
+
+</details>
+
+### 💻 TUI Launcher (Consigliato per Headless / SSH)
+
+Il TUI (Terminal UI) Launcher fornisce un'interfaccia terminale completa per la configurazione e la gestione. Ideale per server, Raspberry Pi e altri ambienti headless.
+
+```bash
+picoclaw-launcher-tui
+```
+
+<p align="center">
+<img src="assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
+</p>
+
+**Per iniziare:**
+
+Usa i menu TUI per: **1)** Configurare un Provider -> **2)** Configurare un Channel -> **3)** Avviare il Gateway -> **4)** Chattare!
+
+Per la documentazione dettagliata del TUI, vedi [docs.picoclaw.io](https://docs.picoclaw.io).
+
+### 📱 Android
+
+Dai una seconda vita al tuo telefono di dieci anni fa! Trasformalo in un assistente IA intelligente con PicoClaw.
+
+**Opzione 1: Termux (disponibile ora)**
+
+1. Installa [Termux](https://github.com/termux/termux-app) (scarica da [GitHub Releases](https://github.com/termux/termux-app/releases), o cerca su F-Droid / Google Play)
+2. Esegui i seguenti comandi:
+
+```bash
+# Scarica l'ultima release
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard   # chroot fornisce un layout standard del filesystem Linux
+```
+
+Poi segui la sezione Terminal Launcher qui sotto per completare la configurazione.
+
+<img src="assets/termux.jpg" alt="PicoClaw on Termux" width="512">
+
+**Opzione 2: APK Install (prossimamente)**
+
+Un APK Android standalone con WebUI integrato è in sviluppo. Resta sintonizzato!
+
+<details>
+<summary><b>Terminal Launcher (per ambienti con risorse limitate)</b></summary>
+
+Per ambienti minimali dove è disponibile solo il binario core `picoclaw` (senza Launcher UI), puoi configurare tutto tramite riga di comando e un file di configurazione JSON.
+
+**1. Inizializza**
+
+```bash
+picoclaw onboard
+```
+
+Questo crea `~/.picoclaw/config.json` e la directory workspace.
+
+**2. Configura** (`~/.picoclaw/config.json`)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "gpt-5.4"
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-api-key"
+    }
+  ]
+}
+```
+
+> Vedi `config/config.example.json` nel repo per un template di configurazione completo con tutte le opzioni disponibili.
+
+**3. Chatta**
+
+```bash
+# Domanda singola
+picoclaw agent -m "Quanto fa 2+2?"
+
+# Modalità interattiva
+picoclaw agent
+
+# Avvia il gateway per l'integrazione con app di chat
+picoclaw gateway
+```
+
+</details>
+
+## 🔌 Provider (LLM)
+
+PicoClaw supporta 30+ provider LLM tramite la configurazione `model_list`. Usa il formato `protocollo/modello`:
+
+| Provider | Protocollo | API Key | Note |
+|----------|------------|---------|------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Richiesta | GPT-5.4, GPT-4o, o3, ecc. |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Richiesta | Claude Opus 4.6, Sonnet 4.6, ecc. |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Richiesta | Gemini 3 Flash, 2.5 Pro, ecc. |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Richiesta | 200+ modelli, API unificata |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Richiesta | GLM-4.7, GLM-5, ecc. |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Richiesta | DeepSeek-V3, DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | Richiesta | Doubao, modelli Ark |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Richiesta | Qwen3, Qwen-Max, ecc. |
+| [Groq](https://console.groq.com/keys) | `groq/` | Richiesta | Inferenza veloce (Llama, Mixtral) |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Richiesta | Modelli Kimi |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Richiesta | Modelli MiniMax |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Richiesta | Mistral Large, Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Richiesta | Modelli ospitati NVIDIA |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Richiesta | Inferenza veloce |
+| [Novita AI](https://novita.ai/) | `novita/` | Richiesta | Vari modelli open |
+| [Ollama](https://ollama.com/) | `ollama/` | Non necessaria | Modelli locali, self-hosted |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | Non necessaria | Deploy locale, compatibile OpenAI |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Variabile | Proxy per 100+ provider |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Richiesta | Deploy Azure enterprise |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Login con device code |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+<details>
+<summary><b>Deploy locale (Ollama, vLLM, ecc.)</b></summary>
+
+**Ollama:**
+```json
+{
+  "model_list": [
+    {
+      "model_name": "local-llama",
+      "model": "ollama/llama3.1:8b",
+      "api_base": "http://localhost:11434/v1"
+    }
+  ]
+}
+```
+
+**vLLM:**
+```json
+{
+  "model_list": [
+    {
+      "model_name": "local-vllm",
+      "model": "vllm/your-model",
+      "api_base": "http://localhost:8000/v1"
+    }
+  ]
+}
+```
+
+Per i dettagli completi sulla configurazione dei provider, vedi [Provider & Modelli](docs/providers.md).
+
+</details>
+
+## 💬 Channel (App di Chat)
+
+Parla con il tuo PicoClaw attraverso 17+ piattaforme di messaggistica:
+
+| Channel | Configurazione | Protocollo | Docs |
+|---------|----------------|------------|------|
+| **Telegram** | Facile (bot token) | Long polling | [Guida](docs/channels/telegram/README.md) |
+| **Discord** | Facile (bot token + intents) | WebSocket | [Guida](docs/channels/discord/README.md) |
+| **WhatsApp** | Facile (QR scan o bridge URL) | Nativo / Bridge | [Guida](docs/chat-apps.md#whatsapp) |
+| **Weixin** | Facile (scan QR nativo) | iLink API | [Guida](docs/chat-apps.md#weixin) |
+| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guida](docs/channels/qq/README.md) |
+| **Slack** | Facile (bot + app token) | Socket Mode | [Guida](docs/channels/slack/README.md) |
+| **Matrix** | Medio (homeserver + token) | Sync API | [Guida](docs/channels/matrix/README.md) |
+| **DingTalk** | Medio (credenziali client) | Stream | [Guida](docs/channels/dingtalk/README.md) |
+| **Feishu / Lark** | Medio (App ID + Secret) | WebSocket/SDK | [Guida](docs/channels/feishu/README.md) |
+| **LINE** | Medio (credenziali + webhook) | Webhook | [Guida](docs/channels/line/README.md) |
+| **WeCom Bot** | Medio (webhook URL) | Webhook | [Guida](docs/channels/wecom/wecom_bot/README.md) |
+| **WeCom App** | Medio (credenziali aziendali) | Webhook | [Guida](docs/channels/wecom/wecom_app/README.md) |
+| **WeCom AI Bot** | Medio (token + AES key) | WebSocket / Webhook | [Guida](docs/channels/wecom/wecom_aibot/README.md) |
+| **IRC** | Medio (server + nick) | Protocollo IRC | [Guida](docs/chat-apps.md#irc) |
+| **OneBot** | Medio (WebSocket URL) | OneBot v11 | [Guida](docs/channels/onebot/README.md) |
+| **MaixCam** | Facile (abilita) | TCP socket | [Guida](docs/channels/maixcam/README.md) |
+| **Pico** | Facile (abilita) | Protocollo nativo | Integrato |
+| **Pico Client** | Facile (WebSocket URL) | WebSocket | Integrato |
+
+> Tutti i channel basati su webhook condividono un singolo server HTTP Gateway (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu usa la modalità WebSocket/SDK e non usa il server HTTP condiviso.
+
+Per istruzioni dettagliate sulla configurazione dei channel, vedi [Configurazione App di Chat](docs/chat-apps.md).
+
+## 🔧 Strumenti
+
+### 🔍 Ricerca Web
+
+PicoClaw può cercare sul web per fornire informazioni aggiornate. Configura in `tools.web`:
+
+| Motore di Ricerca | API Key | Piano Gratuito | Link |
+|-------------------|---------|----------------|------|
+| DuckDuckGo | Non necessaria | Illimitato | Fallback integrato |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Richiesta | 1000 query/giorno | IA, ottimizzato per il cinese |
+| [Tavily](https://tavily.com) | Richiesta | 1000 query/mese | Ottimizzato per AI Agent |
+| [Brave Search](https://brave.com/search/api) | Richiesta | 2000 query/mese | Veloce e privato |
+| [Perplexity](https://www.perplexity.ai) | Richiesta | A pagamento | Ricerca potenziata dall'IA |
+| [SearXNG](https://github.com/searxng/searxng) | Non necessaria | Self-hosted | Metasearch engine gratuito |
+| [GLM Search](https://open.bigmodel.cn/) | Richiesta | Variabile | Ricerca web Zhipu |
+
+### ⚙️ Altri Strumenti
+
+PicoClaw include strumenti integrati per operazioni su file, esecuzione di codice, pianificazione e altro. Vedi [Configurazione degli Strumenti](docs/tools_configuration.md) per i dettagli.
+
+## 🎯 Skill
+
+Le Skill sono capacità modulari che estendono il tuo Agent. Vengono caricate dai file `SKILL.md` nel tuo workspace.
+
+**Installa skill da ClawHub:**
+
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install <skill-name>
+```
+
+**Configura il token ClawHub** (opzionale, per limiti di frequenza più alti):
+
+Aggiungi al tuo `config.json`:
+```json
+{
+  "tools": {
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "auth_token": "your-clawhub-token"
+        }
+      }
+    }
+  }
+}
+```
+
+Per maggiori dettagli, vedi [Configurazione degli Strumenti - Skill](docs/tools_configuration.md#skills-tool).
+
+## 🔗 MCP (Model Context Protocol)
+
+PicoClaw supporta nativamente [MCP](https://modelcontextprotocol.io/) — connetti qualsiasi server MCP per estendere le capacità del tuo Agent con strumenti e sorgenti di dati esterni.
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+        }
+      }
+    }
+  }
+}
+```
+
+Per la configurazione MCP completa (trasporti stdio, SSE, HTTP, Tool Discovery), vedi [Configurazione degli Strumenti - MCP](docs/tools_configuration.md#mcp-tool).
+
+## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Unisciti al Social Network degli Agent
+
+Connetti PicoClaw al Social Network degli Agent semplicemente inviando un singolo messaggio tramite CLI o qualsiasi app di chat integrata.
+
+**Leggi `https://clawdchat.ai/skill.md` e segui le istruzioni per unirti a [ClawdChat.ai](https://clawdchat.ai)**
+
+## 🖥️ Riferimento CLI
+
+| Comando                   | Descrizione                        |
+| ------------------------- | ---------------------------------- |
+| `picoclaw onboard`        | Inizializza config & workspace     |
+| `picoclaw auth weixin` | Connetti account WeChat tramite QR |
+| `picoclaw agent -m "..."` | Chatta con l'agent                 |
+| `picoclaw agent`          | Modalità chat interattiva          |
+| `picoclaw gateway`        | Avvia il gateway                   |
+| `picoclaw status`         | Mostra lo stato                    |
+| `picoclaw version`        | Mostra le info sulla versione      |
+| `picoclaw model`          | Visualizza o cambia il modello predefinito |
+| `picoclaw cron list`      | Elenca tutti i job pianificati     |
+| `picoclaw cron add ...`   | Aggiunge un job pianificato        |
+| `picoclaw cron disable`   | Disabilita un job pianificato      |
+| `picoclaw cron remove`    | Rimuove un job pianificato         |
+| `picoclaw skills list`    | Elenca le skill installate         |
+| `picoclaw skills install` | Installa una skill                 |
+| `picoclaw migrate`        | Migra i dati dalle versioni precedenti |
+| `picoclaw auth login`     | Autenticazione con i provider      |
+
+### ⏰ Task Pianificati / Promemoria
+
+PicoClaw supporta promemoria pianificati e task ricorrenti tramite lo strumento `cron`:
+
+* **Promemoria una tantum**: "Ricordami tra 10 minuti" -> si attiva una volta dopo 10 min
+* **Task ricorrenti**: "Ricordami ogni 2 ore" -> si attiva ogni 2 ore
+* **Espressioni cron**: "Ricordami alle 9 ogni giorno" -> usa un'espressione cron
+
+## 📚 Documentazione
+
+Per guide dettagliate oltre questo README:
+
+| Argomento | Descrizione |
+|-----------|-------------|
+| [Docker & Avvio Rapido](docs/docker.md) | Configurazione Docker Compose, modalità Launcher/Agent |
+| [App di Chat](docs/chat-apps.md) | Tutte le guide di configurazione per 17+ channel |
+| [Configurazione](docs/configuration.md) | Variabili d'ambiente, struttura del workspace, sandbox di sicurezza |
+| [Provider & Modelli](docs/providers.md) | 30+ provider LLM, routing dei modelli, configurazione model_list |
+| [Spawn & Task Asincroni](docs/spawn-tasks.md) | Task veloci, task lunghi con spawn, orchestrazione asincrona di sub-agent |
+| [Hooks](docs/hooks/README.md) | Sistema di hook event-driven: observer, interceptor, approval hook |
+| [Steering](docs/steering.md) | Iniettare messaggi in un loop agent in esecuzione |
+| [SubTurn](docs/subturn.md) | Coordinamento subagent, controllo concorrenza, ciclo di vita |
+| [Risoluzione Problemi](docs/troubleshooting.md) | Problemi comuni e soluzioni |
+| [Configurazione degli Strumenti](docs/tools_configuration.md) | Abilitazione/disabilitazione per strumento, politiche exec, MCP, Skill |
+| [Compatibilità Hardware](docs/hardware-compatibility.md) | Schede testate, requisiti minimi |
+
+## 🤝 Contribuisci & Roadmap
+
+Le PR sono benvenute! Il codice è volutamente piccolo e leggibile.
+
+Consulta la nostra [Roadmap della Community](https://github.com/sipeed/picoclaw/issues/988) e [CONTRIBUTING.md](CONTRIBUTING.md) per le linee guida.
+
+Gruppo sviluppatori in costruzione, unisciti dopo la tua prima PR accettata!
+
+Gruppi utenti:
+
+Discord: <https://discord.gg/V4sAZ9XWpN>
+
+WeChat:
+<img src="assets/wechat.png" alt="WeChat group QR code" width="512">
diff --git a/README.ja.md b/README.ja.md
index 15ed1f649..9165986ba 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -1,27 +1,34 @@
 <div align="center">
-<img src="assets/logo.jpg" alt="PicoClaw" width="512">
+  <img src="assets/logo.webp" alt="PicoClaw" width="512">
 
-<h1>PicoClaw: Go で書かれた超効率 AI アシスタント</h1>
+  <h1>PicoClaw: Go で書かれた超効率 AI アシスタント</h1>
 
-<h3>$10 ハードウェア · 10MB RAM · 1秒起動 · 行くぜ、シャコ！</h3>
-<h3></h3>
+  <h3>$10 ハードウェア · 10MB RAM · ms 起動 · Let's Go, PicoClaw!</h3>
+  <p>
+    <img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
+    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V%2C%20LoongArch-blue" alt="Hardware">
+    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+    <br>
+    <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
+    <a href="https://docs.picoclaw.io/"><img src="https://img.shields.io/badge/Docs-Official-007acc?style=flat&logo=read-the-docs&logoColor=white" alt="Docs"></a>
+    <a href="https://deepwiki.com/sipeed/picoclaw"><img src="https://img.shields.io/badge/Wiki-DeepWiki-FFA500?style=flat&logo=wikipedia&logoColor=white" alt="Wiki"></a>
+    <br>
+    <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
+    <a href="./assets/wechat.png"><img src="https://img.shields.io/badge/WeChat-Group-41d56b?style=flat&logo=wechat&logoColor=white"></a>
+    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
+  </p>
 
-<p>
-<img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
-<img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20RISC--V-blue" alt="Hardware">
-<img src="https://img.shields.io/badge/license-MIT-green" alt="License">
-</p>
-
-[中文](README.zh.md) | **日本語** | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md)
+[中文](README.zh.md) | **日本語** | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md)
 
 </div>
 
-
 ---
 
-🦐 PicoClaw は [nanobot](https://github.com/HKUDS/nanobot) にインスパイアされた超軽量パーソナル AI アシスタントです。Go でゼロからリファクタリングされ、AI エージェント自身がアーキテクチャの移行とコード最適化を推進するセルフブートストラッピングプロセスで構築されました。
+> **PicoClaw** は [Sipeed](https://sipeed.com) が立ち上げた独立したオープンソースプロジェクトです。完全に **Go 言語**で一から書かれており、OpenClaw、NanoBot、その他のプロジェクトのフォークではありません。
 
-⚡️ $10 のハードウェアで 10MB 未満の RAM で動作：OpenClaw より 99% 少ないメモリ、Mac mini より 98% 安い！
+**PicoClaw** は [NanoBot](https://github.com/HKUDS/nanobot) にインスパイアされた超軽量パーソナル AI アシスタントです。**Go** でゼロからリビルドされ、「セルフブートストラッピング」プロセスで構築されました — AI Agent 自身がアーキテクチャの移行とコード最適化を推進しました。
+
+**$10 のハードウェアで 10MB 未満の RAM で動作** — OpenClaw より 99% 少ないメモリ、Mac mini より 98% 安い！
 
 <table align="center">
   <tr align="center">
@@ -38,68 +45,120 @@
   </tr>
 </table>
 
+> [!CAUTION]
+> **セキュリティに関する注意**
+>
+> * **暗号通貨なし:** PicoClaw には公式トークン/コインは**一切ありません**。`pump.fun` やその他の取引プラットフォームでの主張はすべて**詐欺**です。
+> * **公式ドメイン:** **唯一**の公式サイトは **[picoclaw.io](https://picoclaw.io)**、企業サイトは **[sipeed.com](https://sipeed.com)** です。
+> * **注意:** 多くの `.ai/.org/.com/.net/...` ドメインは第三者によって登録されています。信頼しないでください。
+> * **注記:** PicoClaw は初期開発段階にあり、未解決のネットワークセキュリティ問題がある可能性があります。v1.0 リリース前に本番環境へのデプロイは避けてください。
+> * **注記:** PicoClaw は最近多くの PR をマージしており、最新バージョンではメモリフットプリントが大きくなる場合があります（10〜20MB）。機能セットが安定次第、リソース最適化を優先する予定です。
+
 ## 📢 ニュース
-2026-02-09 🎉 PicoClaw リリース！$10 ハードウェアで 10MB 未満の RAM で動く AI エージェントを 1 日で構築。🦐 行くぜ、シャコ！
+
+2026-03-17 🚀 **v0.2.3 リリース！** システムトレイ UI（Windows & Linux）、サブエージェントステータス追跡（`spawn_status`）、実験的 Gateway ホットリロード、cron セキュリティゲート、セキュリティ修正 2 件。PicoClaw **25K ⭐** 達成！
+
+2026-03-09 🎉 **v0.2.1 — 史上最大のアップデート！** MCP プロトコル対応、4 つの新 Channel（Matrix/IRC/WeCom/Discord Proxy）、3 つの新 Provider（Kimi/Minimax/Avian）、ビジョンパイプライン、JSONL メモリストア、モデルルーティング。
+
+2026-02-28 📦 **v0.2.0** リリース — Docker Compose 対応と Web UI Launcher。
+
+2026-02-26 🎉 PicoClaw がわずか 17 日で **20K スター** 達成！Channel 自動オーケストレーションとケイパビリティインターフェースが実装されました。
+
+<details>
+<summary>過去のニュース...</summary>
+
+2026-02-16 🎉 PicoClaw が 1 週間で 12K スター達成！コミュニティメンテナーの役割と[ロードマップ](ROADMAP.md)が正式に公開されました。
+
+2026-02-13 🎉 PicoClaw が 4 日間で 5000 スター達成！プロジェクトロードマップと開発者グループの準備が進行中。
+
+2026-02-09 🎉 **PicoClaw リリース！** $10 ハードウェアで 10MB 未満の RAM で動く AI Agent を 1 日で構築。Let's Go, PicoClaw!
+
+</details>
 
 ## ✨ 特徴
 
-🪶 **超軽量**: メモリフットプリント 10MB 未満 — Clawdbot のコア機能より 99% 小さい。
+🪶 **超軽量**: コアメモリフットプリント 10MB 未満 — OpenClaw より 99% 小さい。*
 
 💰 **最小コスト**: $10 ハードウェアで動作 — Mac mini より 98% 安い。
 
-⚡️ **超高速**: 起動時間 400 倍高速、0.6GHz シングルコアでも 1 秒で起動。
+⚡️ **超高速起動**: 起動時間 400 倍高速。0.6GHz シングルコアでも 1 秒未満で起動。
 
-🌍 **真のポータビリティ**: RISC-V、ARM、x86 対応の単一バイナリ。ワンクリックで Go！
+🌍 **真のポータビリティ**: RISC-V、ARM、MIPS、x86 対応の単一バイナリ。どこでも動く！
 
-🤖 **AI ブートストラップ**: 自律的な Go ネイティブ実装 — コアの 95% が AI 生成、人間によるレビュー付き。
+🤖 **AI ブートストラップ**: 純粋な Go ネイティブ実装 — コアコードの 95% が Agent によって生成され、人間によるレビューで調整。
+
+🔌 **MCP 対応**: ネイティブ [Model Context Protocol](https://modelcontextprotocol.io/) 統合 — 任意の MCP サーバーに接続して Agent 機能を拡張。
+
+👁️ **ビジョンパイプライン**: 画像やファイルを Agent に直接送信 — マルチモーダル LLM 向けの自動 base64 エンコーディング。
+
+🧠 **スマートルーティング**: ルールベースのモデルルーティング — 簡単なクエリは軽量モデルへ、API コストを節約。
+
+_*最近のバージョンでは急速な PR マージにより 10〜20MB になる場合があります。リソース最適化は計画中です。起動時間の比較は 0.8GHz シングルコアベンチマークに基づいています（下表参照）。_
+
+<div align="center">
+
+|                                | OpenClaw      | NanoBot                  | **PicoClaw**                           |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **言語**                       | TypeScript    | Python                   | **Go**                                 |
+| **RAM**                        | >1GB          | >100MB                   | **< 10MB***                            |
+| **起動時間**</br>(0.8GHz コア) | >500秒        | >30秒                    | **<1秒**                               |
+| **コスト**                     | Mac Mini $599 | 大半の Linux ボード ~$50 | **あらゆる Linux ボード**</br>**最安 $10** |
 
-|  | OpenClaw  | NanoBot | **PicoClaw** |
-| --- | --- | --- |--- |
-| **言語** | TypeScript | Python | **Go** |
-| **RAM** | >1GB |>100MB| **< 10MB** |
-| **起動時間**</br>(0.8GHz コア) | >500秒 | >30秒 |  **<1秒** |
-| **コスト** | Mac Mini 599$ | 大半の Linux SBC </br>~50$ |**あらゆる Linux ボード**</br>**最安 10$** |
 <img src="assets/compare.jpg" alt="PicoClaw" width="512">
 
+</div>
+
+> **[ハードウェア互換性リスト](docs/ja/hardware-compatibility.md)** — テスト済みの全ボード一覧（$5 RISC-V から Raspberry Pi、Android スマートフォンまで）。お使いのボードが未掲載？PR を送ってください！
+
+<p align="center">
+<img src="assets/hardware-banner.jpg" alt="PicoClaw Hardware Compatibility" width="100%">
+</p>
 
 ## 🦾 デモンストレーション
+
 ### 🛠️ スタンダードアシスタントワークフロー
+
 <table align="center">
-  <tr align="center">
-    <th><p align="center">🧩 フルスタックエンジニア</p></th>
-    <th><p align="center">🗂️ ログ＆計画管理</p></th>
-    <th><p align="center">🔎 Web 検索＆学習</p></th>
-  </tr>
-  <tr>
-    <td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
-    <td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
-    <td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
-  </tr>
-  <tr>
-    <td align="center">開発 · デプロイ · スケール</td>
-    <td align="center">スケジュール · 自動化 · メモリ</td>
-    <td align="center">発見 · インサイト · トレンド</td>
-  </tr>
+<tr align="center">
+<th><p align="center">フルスタックエンジニアモード</p></th>
+<th><p align="center">ログ＆計画管理</p></th>
+<th><p align="center">Web 検索＆学習</p></th>
+</tr>
+<tr>
+<td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
+<td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
+<td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
+</tr>
+<tr>
+<td align="center">開発 · デプロイ · スケール</td>
+<td align="center">スケジュール · 自動化 · メモリ</td>
+<td align="center">発見 · インサイト · トレンド</td>
+</tr>
 </table>
 
 ### 🐜 革新的な省フットプリントデプロイ
+
 PicoClaw はほぼすべての Linux デバイスにデプロイできます！
 
 - $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) または W(WiFi6) バージョン、最小ホームアシスタントに
 - $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html) または $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) サーバー自動メンテナンスに
 - $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) または $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) スマート監視に
 
-https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4
+<https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4>
 
 🌟 もっと多くのデプロイ事例が待っています！
 
 ## 📦 インストール
 
-### コンパイル済みバイナリでインストール
+### picoclaw.io からダウンロード（推奨）
 
-[リリースページ](https://github.com/sipeed/picoclaw/releases) からお使いのプラットフォーム用のファームウェアをダウンロードしてください。
+**[picoclaw.io](https://picoclaw.io)** にアクセス — 公式サイトがプラットフォームを自動検出し、ワンクリックでダウンロードできます。アーキテクチャを手動で選ぶ必要はありません。
 
-### ソースからインストール（最新機能、開発向け推奨）
+### プリコンパイル済みバイナリをダウンロード
+
+または、[GitHub Releases](https://github.com/sipeed/picoclaw/releases) ページからプラットフォームに合ったバイナリをダウンロードしてください。
+
+### ソースからビルド（開発用）
 
 ```bash
 git clone https://github.com/sipeed/picoclaw.git
@@ -107,70 +166,141 @@ git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 make deps
 
-# ビルド（インストール不要）
+# コアバイナリをビルド
 make build
 
+# Web UI Launcher をビルド（WebUI モードに必要）
+make build-launcher
+
 # 複数プラットフォーム向けビルド
 make build-all
 
+# Raspberry Pi Zero 2 W 向けビルド（32-bit: make build-linux-arm; 64-bit: make build-linux-arm64）
+make build-pi-zero
+
 # ビルドとインストール
 make install
 ```
 
-## 🐳 Docker Compose
+**Raspberry Pi Zero 2 W:** OS に合ったバイナリを使用してください：32-bit Raspberry Pi OS → `make build-linux-arm`、64-bit → `make build-linux-arm64`。または `make build-pi-zero` で両方をビルド。
 
-Docker Compose を使えば、ローカルにインストールせずに PicoClaw を実行できます。
+## 🚀 クイックスタートガイド
+
+### 🌐 WebUI Launcher（デスクトップ向け推奨）
+
+WebUI Launcher はブラウザベースの設定・チャットインターフェースを提供します。コマンドラインの知識不要で、最も簡単に始められる方法です。
+
+**オプション 1: ダブルクリック（デスクトップ）**
+
+[picoclaw.io](https://picoclaw.io) からダウンロード後、`picoclaw-launcher`（Windows では `picoclaw-launcher.exe`）をダブルクリックしてください。ブラウザが自動的に `http://localhost:18800` を開きます。
+
+**オプション 2: コマンドライン**
 
 ```bash
-# 1. リポジトリをクローン
+picoclaw-launcher
+# ブラウザで http://localhost:18800 を開く
+```
+
+> [!TIP]
+> **リモートアクセス / Docker / VM:** すべてのインターフェースでリッスンするには `-public` フラグを追加してください：
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+<p align="center">
+<img src="assets/launcher-webui.jpg" alt="WebUI Launcher" width="600">
+</p>
+
+**始め方:**
+
+WebUI を開いたら：**1)** Provider を設定（LLM API キーを追加）→ **2)** Channel を設定（例：Telegram）→ **3)** Gateway を起動 → **4)** チャット！
+
+WebUI の詳細なドキュメントは [docs.picoclaw.io](https://docs.picoclaw.io) を参照してください。
+
+<details>
+<summary><b>Docker（代替手段）</b></summary>
+
+```bash
+# 1. このリポジトリをクローン
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. 初回起動 — docker/data/config.json を自動生成して終了
-docker compose -f docker/docker-compose.yml --profile gateway up
-# コンテナが "First-run setup complete." を表示して停止します。
+# 2. 初回実行 — docker/data/config.json を自動生成して終了
+#    （config.json と workspace/ の両方が存在しない場合のみ実行）
+docker compose -f docker/docker-compose.yml --profile launcher up
+# コンテナが "First-run setup complete." を出力して停止します。
 
 # 3. API キーを設定
-vim docker/data/config.json   # プロバイダー API キー、Bot トークンなどを設定
+vim docker/data/config.json
 
 # 4. 起動
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+# http://localhost:18800 を開く
 ```
 
-> [!TIP]
-> **Docker ユーザー**: デフォルトでは、Gateway は `127.0.0.1` でリッスンしており、ホストからアクセスできません。ヘルスチェックエンドポイントにアクセスしたり、ポートを公開したりする必要がある場合は、環境変数で `PICOCLAW_GATEWAY_HOST=0.0.0.0` を設定するか、`config.json` を更新してください。
+> **Docker / VM ユーザー:** Gateway はデフォルトで `127.0.0.1` でリッスンします。ホストからアクセスできるようにするには `PICOCLAW_GATEWAY_HOST=0.0.0.0` を設定するか、`-public` フラグを使用してください。
 
 ```bash
-# 5. ログ確認
-docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+# ログを確認
+docker compose -f docker/docker-compose.yml logs -f
 
-# 6. 停止
-docker compose -f docker/docker-compose.yml --profile gateway down
-```
+# 停止
+docker compose -f docker/docker-compose.yml --profile launcher down
 
-### Agent モード（ワンショット）
-
-```bash
-# 質問を投げる
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
-
-# インタラクティブモード
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
-```
-
-### アップデート
-
-```bash
+# 更新
 docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile launcher up -d
 ```
 
-### 🚀 クイックスタート（ネイティブ）
+</details>
 
-> [!TIP]
-> `~/.picoclaw/config.json` に API キーを設定してください。
-> API キーの取得先: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)
-> Web 検索は **任意** です - 無料の [Tavily API](https://tavily.com) (月 1000 クエリ無料) または [Brave Search API](https://brave.com/search/api) (月 2000 クエリ無料)
+### 💻 TUI Launcher（ヘッドレス / SSH 向け推奨）
+
+TUI（Terminal UI）Launcher は設定と管理のためのフル機能ターミナルインターフェースを提供します。サーバー、Raspberry Pi、その他のヘッドレス環境に最適です。
+
+```bash
+picoclaw-launcher-tui
+```
+
+<p align="center">
+<img src="assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
+</p>
+
+**始め方:**
+
+TUI メニューを使って：**1)** Provider を設定 → **2)** Channel を設定 → **3)** Gateway を起動 → **4)** チャット！
+
+TUI の詳細なドキュメントは [docs.picoclaw.io](https://docs.picoclaw.io) を参照してください。
+
+### 📱 Android
+
+10 年前のスマホに第二の人生を！PicoClaw でスマート AI アシスタントに変身させましょう。
+
+**オプション 1: Termux（現在利用可能）**
+
+1. [Termux](https://github.com/termux/termux-app) をインストール（[GitHub Releases](https://github.com/termux/termux-app/releases) からダウンロード、または F-Droid / Google Play で検索）
+2. 以下のコマンドを実行：
+
+```bash
+# 最新リリースをダウンロード
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard   # chroot で標準的な Linux ファイルシステムレイアウトを提供
+```
+
+その後、下記の Terminal Launcher セクションの手順に従って設定を完了してください。
+
+<img src="assets/termux.jpg" alt="PicoClaw on Termux" width="512">
+
+**オプション 2: APK インストール（近日公開）**
+
+内蔵 WebUI を備えたスタンドアロン Android APK を開発中です。お楽しみに！
+
+<details>
+<summary><b>Terminal Launcher（リソース制約環境向け）</b></summary>
+
+`picoclaw` コアバイナリのみが利用可能な最小環境（Launcher UI なし）では、コマンドラインと JSON 設定ファイルですべてを設定できます。
 
 **1. 初期化**
 
@@ -178,917 +308,271 @@ docker compose -f docker/docker-compose.yml --profile gateway up -d
 picoclaw onboard
 ```
 
+`~/.picoclaw/config.json` とワークスペースディレクトリが作成されます。
+
 **2. 設定** (`~/.picoclaw/config.json`)
 
 ```json
 {
+  "agents": {
+    "defaults": {
+      "model_name": "gpt-5.4"
+    }
+  },
   "model_list": [
     {
-      "model_name": "gpt4",
-      "model": "openai/gpt-5.2",
-      "api_key": "sk-your-openai-key",
-      "request_timeout": 300,
-      "api_base": "https://api.openai.com/v1"
-    }
-  ],
-  "agents": {
-    "defaults": {
-      "model_name": "gpt4"
-    }
-  },
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "YOUR_TELEGRAM_BOT_TOKEN",
-      "allow_from": []
-    }
-  },
-  "tools": {
-    "web": {
-      "search": {
-        "api_key": "YOUR_BRAVE_API_KEY",
-        "max_results": 5
-      },
-      "tavily": {
-        "enabled": false,
-        "api_key": "YOUR_TAVILY_API_KEY",
-        "max_results": 5
-      }
-    },
-    "cron": {
-      "exec_timeout_minutes": 5
-    }
-  },
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-> **新機能**: `model_list` 形式により、プロバイダーをコード変更なしで追加できます。詳細は [モデル設定](#モデル設定-model_list) を参照してください。
-> `request_timeout` は任意の秒単位設定です。省略または `<= 0` の場合、PicoClaw はデフォルトのタイムアウト（120秒）を使用します。
-
-**3. API キーの取得**
-
-- **LLM プロバイダー**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
-- **Web 検索**（任意）: [Tavily](https://tavily.com) - AI エージェント向けに最適化 (月 1000 リクエスト) · [Brave Search](https://brave.com/search/api) - 無料枠あり（月 2000 リクエスト）
-
-> **注意**: 完全な設定テンプレートは `config.example.json` を参照してください。
-
-**4. チャット**
-
-```bash
-picoclaw agent -m "What is 2+2?"
-```
-
-これだけです！2 分で AI アシスタントが動きます。
-
----
-
-## 💬 チャットアプリ
-
-Telegram、Discord、QQ、DingTalk、LINE、WeCom で PicoClaw と会話できます
-
-| チャネル | セットアップ |
-|---------|------------|
-| **Telegram** | 簡単（トークンのみ） |
-| **Discord** | 簡単（Bot トークン + Intents） |
-| **QQ** | 簡単（AppID + AppSecret） |
-| **DingTalk** | 普通（アプリ認証情報） |
-| **LINE** | 普通（認証情報 + Webhook URL） |
-| **WeCom** | 普通（CorpID + Webhook設定） |
-
-<details>
-<summary><b>Telegram</b>（推奨）</summary>
-
-**1. Bot を作成**
-
-- Telegram を開き、`@BotFather` を検索
-- `/newbot` を送信、プロンプトに従う
-- トークンをコピー
-
-**2. 設定**
-
-```json
-{
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "YOUR_BOT_TOKEN",
-      "allow_from": ["YOUR_USER_ID"]
-    }
-  }
-}
-```
-
-> ユーザー ID は Telegram の `@userinfobot` から取得できます。
-
-**3. 起動**
-
-```bash
-picoclaw gateway
-```
-</details>
-
-
-<details>
-<summary><b>Discord</b></summary>
-
-**1. Bot を作成**
-- https://discord.com/developers/applications にアクセス
-- アプリケーションを作成 → Bot → Add Bot
-- Bot トークンをコピー
-
-**2. Intents を有効化**
-- Bot の設定画面で **MESSAGE CONTENT INTENT** を有効化
-- （任意）**SERVER MEMBERS INTENT** も有効化
-
-**3. ユーザー ID を取得**
-- Discord 設定 → 詳細設定 → **開発者モード** を有効化
-- 自分のアバターを右クリック → **ユーザーIDをコピー**
-
-**4. 設定**
-
-```json
-{
-  "channels": {
-    "discord": {
-      "enabled": true,
-      "token": "YOUR_BOT_TOKEN",
-      "allow_from": ["YOUR_USER_ID"]
-    }
-  }
-}
-```
-
-**5. Bot を招待**
-- OAuth2 → URL Generator
-- Scopes: `bot`
-- Bot Permissions: `Send Messages`, `Read Message History`
-- 生成された招待 URL を開き、サーバーに Bot を追加
-
-**6. 起動**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>QQ</b></summary>
-
-**1. Bot を作成**
-
-- [QQ オープンプラットフォーム](https://q.qq.com/#) にアクセス
-- アプリケーションを作成 → **AppID** と **AppSecret** を取得
-
-**2. 設定**
-
-```json
-{
-  "channels": {
-    "qq": {
-      "enabled": true,
-      "app_id": "YOUR_APP_ID",
-      "app_secret": "YOUR_APP_SECRET",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> `allow_from` を空にすると全ユーザーを許可、QQ番号を指定してアクセス制限可能。
-
-**3. 起動**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>DingTalk</b></summary>
-
-**1. Bot を作成**
-
-- [オープンプラットフォーム](https://open.dingtalk.com/) にアクセス
-- 内部アプリを作成
-- Client ID と Client Secret をコピー
-
-**2. 設定**
-
-```json
-{
-  "channels": {
-    "dingtalk": {
-      "enabled": true,
-      "client_id": "YOUR_CLIENT_ID",
-      "client_secret": "YOUR_CLIENT_SECRET",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> `allow_from` を空にすると全ユーザーを許可、ユーザーIDを指定してアクセス制限可能。
-
-**3. 起動**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>LINE</b></summary>
-
-**1. LINE 公式アカウントを作成**
-
-- [LINE Developers Console](https://developers.line.biz/) にアクセス
-- プロバイダーを作成 → Messaging API チャネルを作成
-- **チャネルシークレット** と **チャネルアクセストークン** をコピー
-
-**2. 設定**
-
-```json
-{
-  "channels": {
-    "line": {
-      "enabled": true,
-      "channel_secret": "YOUR_CHANNEL_SECRET",
-      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_path": "/webhook/line",
-      "allow_from": []
-    }
-  }
-}
-```
-
-**3. Webhook URL を設定**
-
-LINE の Webhook には HTTPS が必要です。リバースプロキシまたはトンネルを使用してください:
-
-```bash
-# ngrok の例
-ngrok http 18790
-```
-
-LINE Developers Console で Webhook URL を `https://あなたのドメイン/webhook/line` に設定し、**Webhook の利用** を有効にしてください。
-
-> **注意**: LINE の Webhook は共有の Gateway HTTP サーバー（デフォルト: `127.0.0.1:18790`）で提供されます。ホストからアクセスする場合は Gateway のポートを公開するか、リバースプロキシを設定してください。
-
-**4. 起動**
-
-```bash
-picoclaw gateway
-```
-
-> グループチャットでは @メンション時のみ応答します。返信は元メッセージを引用する形式です。
-
-> **Docker Compose**: Gateway HTTP サーバーは共有の `127.0.0.1:18790` で Webhook を提供します。ホストからアクセスするには `picoclaw-gateway` サービスに `ports: ["18790:18790"]` を追加してください。
-
-</details>
-
-<details>
-<summary><b>WeCom (企業微信)</b></summary>
-
-PicoClaw は2種類の WeCom 統合をサポートしています：
-
-**オプション1: WeCom Bot (智能ロボット)** - 簡単な設定、グループチャット対応
-**オプション2: WeCom App (自作アプリ)** - より多機能、アクティブメッセージング対応
-
-詳細な設定手順は [WeCom App Configuration Guide](docs/wecom-app-configuration.md) を参照してください。
-
-**クイックセットアップ - WeCom Bot:**
-
-**1. ボットを作成**
-
-* WeCom 管理コンソール → グループチャット → グループボットを追加
-* Webhook URL をコピー（形式: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`）
-
-**2. 設定**
-
-```json
-{
-  "channels": {
-    "wecom": {
-      "enabled": true,
-      "token": "YOUR_TOKEN",
-      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_path": "/webhook/wecom",
-      "allow_from": []
-    }
-  }
-}
-
-> **注意**: WeCom Bot の Webhook 受信は共有の Gateway HTTP サーバー（デフォルト: `127.0.0.1:18790`）で提供されます。ホストからアクセスする場合は Gateway のポートを公開するか、HTTPS 用のリバースプロキシを設定してください。
-```
-
-**クイックセットアップ - WeCom App:**
-
-**1. アプリを作成**
-
-* WeCom 管理コンソール → アプリ管理 → アプリを作成
-* **AgentId** と **Secret** をコピー
-* "マイ会社" ページで **CorpID** をコピー
-
-**2. メッセージ受信を設定**
-
-* アプリ詳細で "メッセージを受信" → "APIを設定" をクリック
-* URL を `http://your-server:18790/webhook/wecom-app` に設定
-* **Token** と **EncodingAESKey** を生成
-
-**3. 設定**
-
-```json
-{
-  "channels": {
-    "wecom_app": {
-      "enabled": true,
-      "corp_id": "wwxxxxxxxxxxxxxxxx",
-      "corp_secret": "YOUR_CORP_SECRET",
-      "agent_id": 1000002,
-      "token": "YOUR_TOKEN",
-      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_path": "/webhook/wecom-app",
-      "allow_from": []
-    }
-  }
-}
-```
-
-**4. 起動**
-
-```bash
-picoclaw gateway
-```
-
-> **注意**: WeCom App の Webhook コールバックは共有の Gateway HTTP サーバー（デフォルト: `127.0.0.1:18790`）で提供されます。ホストからアクセスする場合は HTTPS 用のリバースプロキシを設定してください。
-
-</details>
-
-## ⚙️ 設定
-
-設定ファイル: `~/.picoclaw/config.json`
-
-### 環境変数
-
-環境変数を使用してデフォルトのパスを上書きできます。これは、ポータブルインストール、コンテナ化されたデプロイメント、または picoclaw をシステムサービスとして実行する場合に便利です。これらの変数は独立しており、異なるパスを制御します。
-
-| 変数              | 説明                                                                                                                             | デフォルトパス            |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
-| `PICOCLAW_CONFIG` | 設定ファイルへのパスを上書きします。これにより、picoclaw は他のすべての場所を無視して、指定された `config.json` をロードします。 | `~/.picoclaw/config.json` |
-| `PICOCLAW_HOME`   | picoclaw データのルートディレクトリを上書きします。これにより、`workspace` やその他のデータディレクトリのデフォルトの場所が変更されます。          | `~/.picoclaw`             |
-
-**例：**
-
-```bash
-# 特定の設定ファイルを使用して picoclaw を実行する
-# ワークスペースのパスはその設定ファイル内から読み込まれます
-PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
-
-# すべてのデータを /opt/picoclaw に保存して picoclaw を実行する
-# 設定はデフォルトの ~/.picoclaw/config.json からロードされます
-# ワークスペースは /opt/picoclaw/workspace に作成されます
-PICOCLAW_HOME=/opt/picoclaw picoclaw agent
-
-# 両方を使用して完全にカスタマイズされたセットアップを行う
-PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
-```
-
-### ワークスペース構成
-
-PicoClaw は設定されたワークスペース（デフォルト: `~/.picoclaw/workspace`）にデータを保存します：
-
-```
-~/.picoclaw/workspace/
-├── sessions/          # 会話セッションと履歴
-├── memory/            # 長期メモリ（MEMORY.md）
-├── state/             # 永続状態（最後のチャネルなど）
-├── cron/              # スケジュールジョブデータベース
-├── skills/            # カスタムスキル
-├── AGENTS.md          # エージェントの行動ガイド
-├── HEARTBEAT.md       # 定期タスクプロンプト（30分ごとに確認）
-├── IDENTITY.md        # エージェントのアイデンティティ
-├── SOUL.md            # エージェントのソウル
-├── TOOLS.md           # ツールの説明
-└── USER.md            # ユーザー設定
-```
-
-### 🔒 セキュリティサンドボックス
-
-PicoClaw はデフォルトでサンドボックス環境で実行されます。エージェントは設定されたワークスペース内のファイルにのみアクセスし、コマンドを実行できます。
-
-#### デフォルト設定
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "restrict_to_workspace": true
-    }
-  }
-}
-```
-
-| オプション | デフォルト | 説明 |
-|-----------|-----------|------|
-| `workspace` | `~/.picoclaw/workspace` | エージェントの作業ディレクトリ |
-| `restrict_to_workspace` | `true` | ファイル/コマンドアクセスをワークスペースに制限 |
-
-#### 保護対象ツール
-
-`restrict_to_workspace: true` の場合、以下のツールがサンドボックス化されます：
-
-| ツール | 機能 | 制限 |
-|-------|------|------|
-| `read_file` | ファイル読み込み | ワークスペース内のファイルのみ |
-| `write_file` | ファイル書き込み | ワークスペース内のファイルのみ |
-| `list_dir` | ディレクトリ一覧 | ワークスペース内のディレクトリのみ |
-| `edit_file` | ファイル編集 | ワークスペース内のファイルのみ |
-| `append_file` | ファイル追記 | ワークスペース内のファイルのみ |
-| `exec` | コマンド実行 | コマンドパスはワークスペース内である必要あり |
-
-#### exec ツールの追加保護
-
-`restrict_to_workspace: false` でも、`exec` ツールは以下の危険なコマンドをブロックします：
-
-- `rm -rf`, `del /f`, `rmdir /s` — 一括削除
-- `format`, `mkfs`, `diskpart` — ディスクフォーマット
-- `dd if=` — ディスクイメージング
-- `/dev/sd[a-z]` への書き込み — 直接ディスク書き込み
-- `shutdown`, `reboot`, `poweroff` — システムシャットダウン
-- フォークボム `:(){ :|:& };:`
-
-#### エラー例
-
-```
-[ERROR] tool: Tool execution failed
-{tool=exec, error=Command blocked by safety guard (path outside working dir)}
-```
-
-```
-[ERROR] tool: Tool execution failed
-{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
-```
-
-#### 制限の無効化（セキュリティリスク）
-
-エージェントにワークスペース外のパスへのアクセスが必要な場合：
-
-**方法1: 設定ファイル**
-```json
-{
-  "agents": {
-    "defaults": {
-      "restrict_to_workspace": false
-    }
-  }
-}
-```
-
-**方法2: 環境変数**
-```bash
-export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
-```
-
-> ⚠️ **警告**: この制限を無効にすると、エージェントはシステム上の任意のパスにアクセスできるようになります。制御された環境でのみ慎重に使用してください。
-
-#### セキュリティ境界の一貫性
-
-`restrict_to_workspace` 設定は、すべての実行パスで一貫して適用されます：
-
-| 実行パス | セキュリティ境界 |
-|---------|-----------------|
-| メインエージェント | `restrict_to_workspace` ✅ |
-| サブエージェント / Spawn | 同じ制限を継承 ✅ |
-| ハートビートタスク | 同じ制限を継承 ✅ |
-
-すべてのパスで同じワークスペース制限が適用されます — サブエージェントやスケジュールタスクを通じてセキュリティ境界をバイパスする方法はありません。
-
-### ハートビート（定期タスク）
-
-PicoClaw は自動的に定期タスクを実行できます。ワークスペースに `HEARTBEAT.md` ファイルを作成します：
-
-```markdown
-# 定期タスク
-
-- 重要なメールをチェック
-- 今後の予定を確認
-- 天気予報をチェック
-```
-
-エージェントは30分ごと（設定可能）にこのファイルを読み込み、利用可能なツールを使ってタスクを実行します。
-
-#### spawn で非同期タスク実行
-
-時間のかかるタスク（Web検索、API呼び出し）には `spawn` ツールを使って**サブエージェント**を作成します：
-
-```markdown
-# 定期タスク
-
-## クイックタスク（直接応答）
-- 現在時刻を報告
-
-## 長時間タスク（spawn で非同期）
-- AIニュースを検索して要約
-- メールをチェックして重要なメッセージを報告
-```
-
-**主な特徴:**
-
-| 機能 | 説明 |
-|------|------|
-| **spawn** | 非同期サブエージェントを作成、ハートビートをブロックしない |
-| **独立コンテキスト** | サブエージェントは独自のコンテキストを持ち、セッション履歴なし |
-| **message ツール** | サブエージェントは message ツールで直接ユーザーと通信 |
-| **非ブロッキング** | spawn 後、ハートビートは次のタスクへ継続 |
-
-#### サブエージェントの通信方法
-
-```
-ハートビート発動
-    ↓
-エージェントが HEARTBEAT.md を読む
-    ↓
-長いタスク: spawn サブエージェント
-    ↓                           ↓
-次のタスクへ継続          サブエージェントが独立して動作
-    ↓                           ↓
-全タスク完了              message ツールを使用
-    ↓                           ↓
-HEARTBEAT_OK 応答         ユーザーが直接結果を受け取る
-```
-
-サブエージェントはツール（message、web_search など）にアクセスでき、メインエージェントを経由せずにユーザーと通信できます。
-
-**設定:**
-
-```json
-{
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-| オプション | デフォルト | 説明 |
-|-----------|-----------|------|
-| `enabled` | `true` | ハートビートの有効/無効 |
-| `interval` | `30` | チェック間隔（分）、最小5分 |
-
-**環境変数:**
-- `PICOCLAW_HEARTBEAT_ENABLED=false` で無効化
-- `PICOCLAW_HEARTBEAT_INTERVAL=60` で間隔変更
-
-### プロバイダー
-
-> [!NOTE]
-> Groq は Whisper による無料の音声文字起こしを提供しています。設定すると、Telegram の音声メッセージが自動的に文字起こしされます。
-
-| プロバイダー | 用途 | API キー取得先 |
-| --- | --- | --- |
-| `gemini` | LLM（Gemini 直接） | [aistudio.google.com](https://aistudio.google.com) |
-| `zhipu` | LLM（Zhipu 直接） | [bigmodel.cn](https://bigmodel.cn) |
-| `openrouter`（要テスト） | LLM（推奨、全モデルにアクセス可能） | [openrouter.ai](https://openrouter.ai) |
-| `anthropic`（要テスト） | LLM（Claude 直接） | [console.anthropic.com](https://console.anthropic.com) |
-| `openai`（要テスト） | LLM（GPT 直接） | [platform.openai.com](https://platform.openai.com) |
-| `deepseek`（要テスト） | LLM（DeepSeek 直接） | [platform.deepseek.com](https://platform.deepseek.com) |
-| `groq` | LLM + **音声文字起こし**（Whisper） | [console.groq.com](https://console.groq.com) |
-| `cerebras` | LLM（Cerebras 直接） | [cerebras.ai](https://cerebras.ai) |
-
-### 基本設定
-
-1.  **設定ファイルの作成:**
-
-    ```bash
-    cp config.example.json config/config.json
-    ```
-
-2.  **設定の編集:**
-
-    ```json
-    {
-      "providers": {
-        "openrouter": {
-          "api_key": "sk-or-v1-..."
-        }
-      },
-      "channels": {
-        "discord": {
-          "enabled": true,
-          "token": "YOUR_DISCORD_BOT_TOKEN"
-        }
-      }
-    }
-    ```
-
-3.  **実行**
-
-    ```bash
-    picoclaw agent -m "Hello"
-    ```
-</details>
-
-<details>
-<summary><b>完全な設定例</b></summary>
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "model": "anthropic/claude-opus-4-5"
-    }
-  },
-  "providers": {
-    "openrouter": {
-      "api_key": "sk-or-v1-xxx"
-    },
-    "groq": {
-      "api_key": "gsk_xxx"
-    }
-  },
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "123456:ABC...",
-      "allow_from": ["123456789"]
-    },
-    "discord": {
-      "enabled": true,
-      "token": "",
-      "allow_from": [""]
-    },
-    "whatsapp": {
-      "enabled": false
-    },
-    "feishu": {
-      "enabled": false,
-      "app_id": "cli_xxx",
-      "app_secret": "xxx",
-      "encrypt_key": "",
-      "verification_token": "",
-      "allow_from": []
-    }
-  },
-  "tools": {
-    "web": {
-      "search": {
-        "api_key": "BSA..."
-      }
-    },
-    "cron": {
-      "exec_timeout_minutes": 5
-    }
-  },
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-</details>
-
-### モデル設定 (model_list)
-
-> **新機能！** PicoClaw は現在 **モデル中心** の設定アプローチを採用しています。`ベンダー/モデル` 形式（例: `zhipu/glm-4.7`）を指定するだけで、新しいプロバイダーを追加できます—**コードの変更は一切不要！**
-
-この設計は、柔軟なプロバイダー選択による **マルチエージェントサポート** も可能にします：
-
-- **異なるエージェント、異なるプロバイダー** : 各エージェントは独自の LLM プロバイダーを使用可能
-- **フォールバックモデル** : 耐障性のため、プライマリモデルとフォールバックモデルを設定可能
-- **ロードバランシング** : 複数のエンドポイントにリクエストを分散
-- **集中設定管理** : すべてのプロバイダーを一箇所で管理
-
-#### 📋 サポートされているすべてのベンダー
-
-| ベンダー | `model` プレフィックス | デフォルト API Base | プロトコル | API キー |
-|-------------|-----------------|---------------------|----------|---------|
-| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [キーを取得](https://platform.openai.com) |
-| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [キーを取得](https://console.anthropic.com) |
-| **Zhipu AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [キーを取得](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
-| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [キーを取得](https://platform.deepseek.com) |
-| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [キーを取得](https://aistudio.google.com/api-keys) |
-| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [キーを取得](https://console.groq.com) |
-| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [キーを取得](https://platform.moonshot.cn) |
-| **Qwen (Alibaba)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [キーを取得](https://dashscope.console.aliyun.com) |
-| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [キーを取得](https://build.nvidia.com) |
-| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | ローカル（キー不要） |
-| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [キーを取得](https://openrouter.ai/keys) |
-| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | ローカル |
-| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [キーを取得](https://cerebras.ai) |
-| **Volcengine** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [キーを取得](https://console.volcengine.com) |
-| **ShengsuanYun** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |
-| **Antigravity** | `antigravity/` | Google Cloud | カスタム | OAuthのみ |
-| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |
-
-#### 基本設定
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_key": "sk-your-openai-key"
-    },
-    {
-      "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
-      "api_key": "sk-ant-your-key"
-    },
-    {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-zhipu-key"
-    }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "gpt-5.2"
-    }
-  }
-}
-```
-
-#### ベンダー別の例
-
-**OpenAI**
-```json
-{
-  "model_name": "gpt-5.2",
-  "model": "openai/gpt-5.2",
-  "api_key": "sk-..."
-}
-```
-
-**Zhipu AI (GLM)**
-```json
-{
-  "model_name": "glm-4.7",
-  "model": "zhipu/glm-4.7",
-  "api_key": "your-key"
-}
-```
-
-**Anthropic (OAuth使用)**
-```json
-{
-  "model_name": "claude-sonnet-4.6",
-  "model": "anthropic/claude-sonnet-4.6",
-  "auth_method": "oauth"
-}
-```
-> OAuth認証を設定するには、`picoclaw auth login --provider anthropic` を実行してください。
-
-**カスタムプロキシ/API**
-```json
-{
-  "model_name": "my-custom-model",
-  "model": "openai/custom-model",
-  "api_base": "https://my-proxy.com/v1",
-  "api_key": "sk-...",
-  "request_timeout": 300
-}
-```
-
-#### ロードバランシング
-
-同じモデル名で複数のエンドポイントを設定すると、PicoClaw が自動的にラウンドロビンで分散します：
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_base": "https://api1.example.com/v1",
-      "api_key": "sk-key1"
-    },
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_base": "https://api2.example.com/v1",
-      "api_key": "sk-key2"
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-api-key"
     }
   ]
 }
 ```
 
-#### 従来の `providers` 設定からの移行
+> 利用可能なすべてのオプションを含む完全な設定テンプレートは、リポジトリの `config/config.example.json` を参照してください。
 
-古い `providers` 設定は**非推奨**ですが、後方互換性のためにサポートされています。
+**3. チャット**
 
-**旧設定（非推奨）:**
-```json
-{
-  "providers": {
-    "zhipu": {
-      "api_key": "your-key",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  },
-  "agents": {
-    "defaults": {
-      "provider": "zhipu",
-      "model": "glm-4.7"
-    }
-  }
-}
+```bash
+# ワンショット質問
+picoclaw agent -m "What is 2+2?"
+
+# インタラクティブモード
+picoclaw agent
+
+# チャットアプリ統合用 Gateway を起動
+picoclaw gateway
 ```
 
-**新設定（推奨）:**
+</details>
+
+## 🔌 Provider（LLM）
+
+PicoClaw は `model_list` 設定を通じて 30 以上の LLM Provider をサポートしています。`protocol/model` 形式を使用してください：
+
+| Provider | Protocol | API キー | 備考 |
+|----------|----------|---------|------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | 必須 | GPT-5.4、GPT-4o、o3 など |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | 必須 | Claude Opus 4.6、Sonnet 4.6 など |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | 必須 | Gemini 3 Flash、2.5 Pro など |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | 必須 | 200 以上のモデル、統合 API |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | 必須 | GLM-4.7、GLM-5 など |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | 必須 | DeepSeek-V3、DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | 必須 | Doubao、Ark モデル |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | 必須 | Qwen3、Qwen-Max など |
+| [Groq](https://console.groq.com/keys) | `groq/` | 必須 | 高速推論（Llama、Mixtral） |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | 必須 | Kimi モデル |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | 必須 | MiniMax モデル |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | 必須 | Mistral Large、Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | 必須 | NVIDIA ホスティングモデル |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | 必須 | 高速推論 |
+| [Novita AI](https://novita.ai/) | `novita/` | 必須 | 各種オープンモデル |
+| [Ollama](https://ollama.com/) | `ollama/` | 不要 | ローカルモデル、セルフホスト |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | 不要 | ローカルデプロイ、OpenAI 互換 |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | 場合による | 100 以上の Provider のプロキシ |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | 必須 | エンタープライズ Azure デプロイ |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | デバイスコードログイン |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+<details>
+<summary><b>ローカルデプロイ（Ollama、vLLM など）</b></summary>
+
+**Ollama:**
 ```json
 {
   "model_list": [
     {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-key"
+      "model_name": "local-llama",
+      "model": "ollama/llama3.1:8b",
+      "api_base": "http://localhost:11434/v1"
     }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "glm-4.7"
+  ]
+}
+```
+
+**vLLM:**
+```json
+{
+  "model_list": [
+    {
+      "model_name": "local-vllm",
+      "model": "vllm/your-model",
+      "api_base": "http://localhost:8000/v1"
+    }
+  ]
+}
+```
+
+Provider の完全な設定詳細は [Provider とモデル](docs/ja/providers.md) を参照してください。
+
+</details>
+
+## 💬 Channel（チャットアプリ）
+
+17 以上のメッセージングプラットフォームで PicoClaw と会話できます：
+
+| Channel | セットアップ | Protocol | ドキュメント |
+|---------|------------|----------|------------|
+| **Telegram** | 簡単（bot トークン） | Long polling | [ガイド](docs/channels/telegram/README.ja.md) |
+| **Discord** | 簡単（bot トークン + intents） | WebSocket | [ガイド](docs/channels/discord/README.ja.md) |
+| **WhatsApp** | 簡単（QR スキャンまたは bridge URL） | Native / Bridge | [ガイド](docs/ja/chat-apps.md#whatsapp) |
+| **微信 (Weixin)** | 簡単（QR スキャン） | iLink API | [ガイド](docs/ja/chat-apps.md#weixin) |
+| **QQ** | 簡単（AppID + AppSecret） | WebSocket | [ガイド](docs/channels/qq/README.ja.md) |
+| **Slack** | 簡単（bot + app トークン） | Socket Mode | [ガイド](docs/channels/slack/README.ja.md) |
+| **Matrix** | 中級（homeserver + トークン） | Sync API | [ガイド](docs/channels/matrix/README.ja.md) |
+| **DingTalk** | 中級（クライアント認証情報） | Stream | [ガイド](docs/channels/dingtalk/README.ja.md) |
+| **Feishu / Lark** | 中級（App ID + Secret） | WebSocket/SDK | [ガイド](docs/channels/feishu/README.ja.md) |
+| **LINE** | 中級（認証情報 + webhook） | Webhook | [ガイド](docs/channels/line/README.ja.md) |
+| **WeCom Bot** | 中級（webhook URL） | Webhook | [ガイド](docs/channels/wecom/wecom_bot/README.ja.md) |
+| **WeCom App** | 中級（corp 認証情報） | Webhook | [ガイド](docs/channels/wecom/wecom_app/README.ja.md) |
+| **WeCom AI Bot** | 中級（トークン + AES キー） | WebSocket / Webhook | [ガイド](docs/channels/wecom/wecom_aibot/README.ja.md) |
+| **IRC** | 中級（サーバー + nick） | IRC protocol | [ガイド](docs/ja/chat-apps.md#irc) |
+| **OneBot** | 中級（WebSocket URL） | OneBot v11 | [ガイド](docs/channels/onebot/README.ja.md) |
+| **MaixCam** | 簡単（有効化） | TCP socket | [ガイド](docs/channels/maixcam/README.ja.md) |
+| **Pico** | 簡単（有効化） | Native protocol | 内蔵 |
+| **Pico Client** | 簡単（WebSocket URL） | WebSocket | 内蔵 |
+
+> webhook ベースのすべての Channel は単一の Gateway HTTP サーバー（`gateway.host`:`gateway.port`、デフォルト `127.0.0.1:18790`）を共有します。Feishu は WebSocket/SDK モードを使用し、共有 HTTP サーバーを使用しません。
+
+Channel の詳細なセットアップ手順は [チャットアプリ設定](docs/ja/chat-apps.md) を参照してください。
+
+## 🔧 ツール
+
+### 🔍 Web 検索
+
+PicoClaw は最新情報を提供するために Web を検索できます。`tools.web` で設定してください：
+
+| 検索エンジン | API キー | 無料枠 | リンク |
+|------------|---------|--------|-------|
+| DuckDuckGo | 不要 | 無制限 | 内蔵フォールバック |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | 必須 | 1000 クエリ/日 | AI 搭載、中国語に最適化 |
+| [Tavily](https://tavily.com) | 必須 | 1000 クエリ/月 | AI Agent 向けに最適化 |
+| [Brave Search](https://brave.com/search/api) | 必須 | 2000 クエリ/月 | 高速でプライベート |
+| [Perplexity](https://www.perplexity.ai) | 必須 | 有料 | AI 搭載検索 |
+| [SearXNG](https://github.com/searxng/searxng) | 不要 | セルフホスト | 無料メタ検索エンジン |
+| [GLM Search](https://open.bigmodel.cn/) | 必須 | 場合による | Zhipu Web 検索 |
+
+### ⚙️ その他のツール
+
+PicoClaw にはファイル操作、コード実行、スケジューリングなどの組み込みツールが含まれています。詳細は [ツール設定](docs/ja/tools_configuration.md) を参照してください。
+
+## 🎯 Skill
+
+Skill は Agent を拡張するモジュール型の機能です。ワークスペース内の `SKILL.md` ファイルから読み込まれます。
+
+**ClawHub から Skill をインストール：**
+
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install <skill-name>
+```
+
+**ClawHub トークンを設定**（オプション、レート制限を上げるため）：
+
+`config.json` に追加：
+```json
+{
+  "tools": {
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "auth_token": "your-clawhub-token"
+        }
+      }
     }
   }
 }
 ```
 
-詳細な移行ガイドは、[docs/migration/model-list-migration.md](docs/migration/model-list-migration.md) を参照してください。
+詳細は [ツール設定 - Skill](docs/ja/tools_configuration.md#skills-tool) を参照してください。
 
-## CLI リファレンス
+## 🔗 MCP（Model Context Protocol）
 
-| コマンド | 説明 |
+PicoClaw は [MCP](https://modelcontextprotocol.io/) をネイティブサポートしています — 任意の MCP サーバーに接続して、外部ツールやデータソースで Agent の機能を拡張できます。
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+        }
+      }
+    }
+  }
+}
+```
+
+MCP の完全な設定（stdio、SSE、HTTP トランスポート、Tool Discovery）は [ツール設定 - MCP](docs/ja/tools_configuration.md#mcp-tool) を参照してください。
+
+## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> エージェントソーシャルネットワークに参加
+
+CLI または統合チャットアプリからメッセージを 1 つ送るだけで、PicoClaw をエージェントソーシャルネットワークに接続できます。
+
+**`https://clawdchat.ai/skill.md` を読み、指示に従って [ClawdChat.ai](https://clawdchat.ai) に参加してください**
+
+## 🖥️ CLI リファレンス
+
+| コマンド                    | 説明                           |
+| ------------------------- | ------------------------------ |
+| `picoclaw onboard`        | 設定＆ワークスペースの初期化     |
+| `picoclaw auth weixin` | WeChat アカウントを QR で接続 |
+| `picoclaw agent -m "..."` | Agent とチャット                |
+| `picoclaw agent`          | インタラクティブチャットモード   |
+| `picoclaw gateway`        | Gateway を起動                  |
+| `picoclaw status`         | ステータスを表示                |
+| `picoclaw version`        | バージョン情報を表示            |
+| `picoclaw model`          | デフォルトモデルの表示・切替    |
+| `picoclaw cron list`      | スケジュールジョブ一覧          |
+| `picoclaw cron add ...`   | スケジュールジョブを追加         |
+| `picoclaw cron disable`   | スケジュールジョブを無効化       |
+| `picoclaw cron remove`    | スケジュールジョブを削除         |
+| `picoclaw skills list`    | インストール済み Skill 一覧      |
+| `picoclaw skills install` | Skill をインストール             |
+| `picoclaw migrate`        | 旧バージョンからデータを移行     |
+| `picoclaw auth login`     | Provider への認証               |
+
+### ⏰ スケジュールタスク / リマインダー
+
+PicoClaw は `cron` ツールによるスケジュールリマインダーと定期タスクをサポートしています：
+
+* **ワンタイムリマインダー**: 「10分後にリマインド」→ 10分後に1回トリガー
+* **定期タスク**: 「2時間ごとにリマインド」→ 2時間ごとにトリガー
+* **Cron 式**: 「毎日9時にリマインド」→ cron 式を使用
+
+## 📚 ドキュメント
+
+この README を超えた詳細なガイドについては：
+
+| トピック | 説明 |
 |---------|------|
-| `picoclaw onboard` | 設定＆ワークスペースの初期化 |
-| `picoclaw agent -m "..."` | エージェントとチャット |
-| `picoclaw agent` | インタラクティブチャットモード |
-| `picoclaw gateway` | ゲートウェイを起動 |
-| `picoclaw status` | ステータスを表示 |
+| [Docker & クイックスタート](docs/ja/docker.md) | Docker Compose セットアップ、Launcher/Agent モード |
+| [チャットアプリ](docs/ja/chat-apps.md) | 17 以上の Channel セットアップガイド |
+| [設定](docs/ja/configuration.md) | 環境変数、ワークスペース構成、セキュリティサンドボックス |
+| [Provider とモデル](docs/ja/providers.md) | 30 以上の LLM Provider、モデルルーティング、model_list 設定 |
+| [Spawn & 非同期タスク](docs/ja/spawn-tasks.md) | クイックタスク、spawn による長時間タスク、非同期サブエージェントオーケストレーション |
+| [Hook システム](docs/hooks/README.md) | イベント駆動 Hook：オブザーバー、インターセプター、承認 Hook |
+| [Steering](docs/steering.md) | 実行中の Agent ループにメッセージを注入 |
+| [SubTurn](docs/subturn.md) | サブ Agent の調整、並行制御、ライフサイクル |
+| [トラブルシューティング](docs/ja/troubleshooting.md) | よくある問題と解決策 |
+| [ツール設定](docs/ja/tools_configuration.md) | ツールごとの有効/無効、exec ポリシー、MCP、Skill |
+| [ハードウェア互換性](docs/ja/hardware-compatibility.md) | テスト済みボード、最小要件 |
 
 ## 🤝 コントリビュート＆ロードマップ
 
-PR 歓迎！コードベースは意図的に小さく読みやすくしています。🤗
+PR 歓迎！コードベースは意図的に小さく読みやすくしています。
 
-Discord: https://discord.gg/V4sAZ9XWpN
+[コミュニティロードマップ](https://github.com/sipeed/picoclaw/issues/988)と[CONTRIBUTING.md](CONTRIBUTING.md)をご覧ください。
 
-<img src="assets/wechat.png" alt="PicoClaw" width="512">
+開発者グループ構築中、最初の PR がマージされたら参加できます！
 
+ユーザーグループ:
 
-## 🐛 トラブルシューティング
+Discord: <https://discord.gg/V4sAZ9XWpN>
 
-### Web 検索で「API 設定の問題」と表示される
-
-検索 API キーをまだ設定していない場合、これは正常です。PicoClaw は手動検索用の便利なリンクを提供します。
-
-Web 検索を有効にするには：
-1. [https://tavily.com](https://tavily.com) (月 1000 クエリ無料) または [https://brave.com/search/api](https://brave.com/search/api) で無料の API キーを取得（月 2000 クエリ無料）
-2. `~/.picoclaw/config.json` に追加：
-   ```json
-   {
-     "tools": {
-       "web": {
-         "brave": {
-           "enabled": true,
-           "api_key": "YOUR_BRAVE_API_KEY",
-           "max_results": 5
-         },
-         "duckduckgo": {
-           "enabled": true,
-           "max_results": 5
-         }
-       }
-     }
-   }
-   ```
-
-### コンテンツフィルタリングエラーが出る
-
-一部のプロバイダー（Zhipu など）にはコンテンツフィルタリングがあります。クエリを言い換えるか、別のモデルを使用してください。
-
-### Telegram Bot で「Conflict: terminated by other getUpdates」と表示される
-
-別のインスタンスが実行中の場合に発生します。`picoclaw gateway` が 1 つだけ実行されていることを確認してください。
-
----
-
-## 📝 API キー比較
-
-| サービス | 無料枠 | ユースケース |
-|---------|--------|------------|
-| **OpenRouter** | 月 200K トークン | 複数モデル（Claude, GPT-4 など） |
-| **Zhipu** | 月 200K トークン | 中国ユーザー向け最適 |
-| **Qwen** | 無料枠あり | 通義千問 (Qwen) |
-| **Brave Search** | 月 2000 クエリ | Web 検索機能 |
-| **Tavily** | 月 1000 クエリ | AI エージェント検索最適化 |
-| **Groq** | 無料枠あり | 高速推論（Llama, Mixtral） |
-| **Cerebras** | 無料枠あり | 高速推論（Llama, Qwen など） |
+WeChat:
+<img src="assets/wechat.png" alt="WeChat group QR code" width="512">
diff --git a/README.md b/README.md
index 2fc60343b..568c87e59 100644
--- a/README.md
+++ b/README.md
@@ -1,146 +1,164 @@
 <div align="center">
-  <img src="assets/logo.jpg" alt="PicoClaw" width="512">
+<img src="assets/logo.webp" alt="PicoClaw" width="512">
 
-  <h1>PicoClaw: Ultra-Efficient AI Assistant in Go</h1>
-
-  <h3>$10 Hardware · 10MB RAM · 1s Boot · 皮皮虾，我们走！</h3>
+<h1>PicoClaw: Ultra-Efficient AI Assistant in Go</h1>
 
+<h3>$10 Hardware · 10MB RAM · ms Boot · Let's Go, PicoClaw!</h3>
   <p>
-    <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
-    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20RISC--V-blue" alt="Hardware">
+    <img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
+    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V%2C%20LoongArch-blue" alt="Hardware">
     <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
     <br>
     <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
-    <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
+    <a href="https://docs.picoclaw.io/"><img src="https://img.shields.io/badge/Docs-Official-007acc?style=flat&logo=read-the-docs&logoColor=white" alt="Docs"></a>
+    <a href="https://deepwiki.com/sipeed/picoclaw"><img src="https://img.shields.io/badge/Wiki-DeepWiki-FFA500?style=flat&logo=wikipedia&logoColor=white" alt="Wiki"></a>
     <br>
+    <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
     <a href="./assets/wechat.png"><img src="https://img.shields.io/badge/WeChat-Group-41d56b?style=flat&logo=wechat&logoColor=white"></a>
     <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
   </p>
 
-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | **English**
+[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | **English**
 
 </div>
 
 ---
 
-🦐 PicoClaw is an ultra-lightweight personal AI Assistant inspired by [nanobot](https://github.com/HKUDS/nanobot), refactored from the ground up in Go through a self-bootstrapping process, where the AI agent itself drove the entire architectural migration and code optimization.
+> **PicoClaw** is an independent open-source project initiated by [Sipeed](https://sipeed.com), written entirely in **Go** from scratch — not a fork of OpenClaw, NanoBot, or any other project.
 
-⚡️ Runs on $10 hardware with <10MB RAM: That's 99% less memory than OpenClaw and 98% cheaper than a Mac mini!
+**PicoClaw** is an ultra-lightweight personal AI assistant inspired by [NanoBot](https://github.com/HKUDS/nanobot). It was rebuilt from the ground up in **Go** through a "self-bootstrapping" process — the AI Agent itself drove the architecture migration and code optimization.
+
+**Runs on $10 hardware with <10MB RAM** — that's 99% less memory than OpenClaw and 98% cheaper than a Mac mini!
 
 <table align="center">
-  <tr align="center">
-    <td align="center" valign="top">
-      <p align="center">
-        <img src="assets/picoclaw_mem.gif" width="360" height="240">
-      </p>
-    </td>
-    <td align="center" valign="top">
-      <p align="center">
-        <img src="assets/licheervnano.png" width="400" height="240">
-      </p>
-    </td>
-  </tr>
+<tr align="center">
+<td align="center" valign="top">
+<p align="center">
+<img src="assets/picoclaw_mem.gif" width="360" height="240">
+</p>
+</td>
+<td align="center" valign="top">
+<p align="center">
+<img src="assets/licheervnano.png" width="400" height="240">
+</p>
+</td>
+</tr>
 </table>
 
 > [!CAUTION]
-> **🚨 SECURITY & OFFICIAL CHANNELS / 安全声明**
->
-> * **NO CRYPTO:** PicoClaw has **NO** official token/coin. All claims on `pump.fun` or other trading platforms are **SCAMS**.
+> **Security Notice**
 >
+> * **NO CRYPTO:** PicoClaw has **not** issued any official tokens or cryptocurrency. All claims on `pump.fun` or other trading platforms are **scams**.
 > * **OFFICIAL DOMAIN:** The **ONLY** official website is **[picoclaw.io](https://picoclaw.io)**, and company website is **[sipeed.com](https://sipeed.com)**
-> * **Warning:** Many `.ai/.org/.com/.net/...` domains are registered by third parties.
-> * **Warning:** picoclaw is in early development now and may have unresolved network security issues. Do not deploy to production environments before the v1.0 release.
-> * **Note:** picoclaw has recently merged a lot of PRs, which may result in a larger memory footprint (10–20MB) in the latest versions. We plan to prioritize resource optimization as soon as the current feature set reaches a stable state.
+> * **BEWARE:** Many `.ai/.org/.com/.net/...` domains have been registered by third parties. Do not trust them.
+> * **NOTE:** PicoClaw is in early rapid development. There may be unresolved security issues. Do not deploy to production before v1.0.
+> * **NOTE:** PicoClaw has recently merged many PRs. Recent builds may use 10-20MB RAM. Resource optimization is planned after feature stabilization.
 
 ## 📢 News
 
-2026-02-16 🎉 PicoClaw hit 12K stars in one week! Thank you all for your support! PicoClaw is growing faster than we ever imagined. Given the high volume of PRs, we urgently need community maintainers. Our volunteer roles and roadmap are officially posted [here](docs/ROADMAP.md) —we can’t wait to have you on board!
+2026-03-17 🚀 **v0.2.3 Released!** System tray UI (Windows & Linux), sub-agent status query (`spawn_status`), experimental Gateway hot-reload, Cron security gating, and 2 security fixes. PicoClaw has reached **25K Stars**!
 
-2026-02-13 🎉 PicoClaw hit 5000 stars in 4days! Thank you for the community! There are so many PRs & issues coming in (during Chinese New Year holidays), we are finalizing the Project Roadmap and setting up the Developer Group to accelerate PicoClaw's development.  
-🚀 Call to Action: Please submit your feature requests in GitHub Discussions. We will review and prioritize them during our upcoming weekly meeting.
+2026-03-09 🎉 **v0.2.1 — Biggest update yet!** MCP protocol support, 4 new channels (Matrix/IRC/WeCom/Discord Proxy), 3 new providers (Kimi/Minimax/Avian), vision pipeline, JSONL memory store, model routing.
 
-2026-02-09 🎉 PicoClaw Launched! Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. 🦐 PicoClaw，Let's Go！
+2026-02-28 📦 **v0.2.0** released with Docker Compose and Web UI Launcher support.
+
+2026-02-26 🎉 PicoClaw hits **20K Stars** in just 17 days! Channel auto-orchestration and capability interfaces are live.
+
+<details>
+<summary>Earlier news...</summary>
+
+2026-02-16 🎉 PicoClaw breaks 12K Stars in one week! Community maintainer roles and [Roadmap](ROADMAP.md) officially launched.
+
+2026-02-13 🎉 PicoClaw breaks 5000 Stars in 4 days! Project roadmap and developer groups in progress.
+
+2026-02-09 🎉 **PicoClaw Released!** Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. Let's Go, PicoClaw!
+
+</details>
 
 ## ✨ Features
 
-🪶 **Ultra-Lightweight**: <10MB Memory footprint — 99% smaller than Clawdbot - core functionality.
+🪶 **Ultra-lightweight**: Core memory footprint <10MB — 99% smaller than OpenClaw.*
 
-💰 **Minimal Cost**: Efficient enough to run on $10 Hardware — 98% cheaper than a Mac mini.
+💰 **Minimal cost**: Efficient enough to run on $10 hardware — 98% cheaper than a Mac mini.
 
-⚡️ **Lightning Fast**: 400X Faster startup time, boot in 1 second even in 0.6GHz single core.
+⚡️ **Lightning-fast boot**: 400x faster startup. Boots in <1s even on a 0.6GHz single-core processor.
 
-🌍 **True Portability**: Single self-contained binary across RISC-V, ARM, and x86, One-click to Go!
+🌍 **Truly portable**: Single binary across RISC-V, ARM, MIPS, and x86 architectures. One binary, runs everywhere!
 
-🤖 **AI-Bootstrapped**: Autonomous Go-native implementation — 95% Agent-generated core with human-in-the-loop refinement.
+🤖 **AI-bootstrapped**: Pure Go native implementation — 95% of core code was generated by an Agent and fine-tuned through human-in-the-loop review.
 
-|                               | OpenClaw      | NanoBot                  | **PicoClaw**                              |
-| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
-| **Language**                  | TypeScript    | Python                   | **Go**                                    |
-| **RAM**                       | >1GB          | >100MB                   | **< 10MB**                                |
-| **Startup**</br>(0.8GHz core) | >500s         | >30s                     | **<1s**                                   |
-| **Cost**                      | Mac Mini 599$ | Most Linux SBC </br>~50$ | **Any Linux Board**</br>**As low as 10$** |
+🔌 **MCP support**: Native [Model Context Protocol](https://modelcontextprotocol.io/) integration — connect any MCP server to extend Agent capabilities.
+
+👁️ **Vision pipeline**: Send images and files directly to the Agent — automatic base64 encoding for multimodal LLMs.
+
+🧠 **Smart routing**: Rule-based model routing — simple queries go to lightweight models, saving API costs.
+
+_*Recent builds may use 10-20MB due to rapid PR merges. Resource optimization is planned. Boot speed comparison based on 0.8GHz single-core benchmarks (see table below)._
+
+<div align="center">
+
+|                                | OpenClaw      | NanoBot                  | **PicoClaw**                           |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **Language**                   | TypeScript    | Python                   | **Go**                                 |
+| **RAM**                        | >1GB          | >100MB                   | **< 10MB***                            |
+| **Boot time**</br>(0.8GHz core) | >500s         | >30s                     | **<1s**                                |
+| **Cost**                       | Mac Mini $599 | Most Linux boards ~$50   | **Any Linux board**</br>**from $10**   |
 
 <img src="assets/compare.jpg" alt="PicoClaw" width="512">
 
+</div>
+
+> **[Hardware Compatibility List](docs/hardware-compatibility.md)** — See all tested boards, from $5 RISC-V to Raspberry Pi to Android phones. Your board not listed? Submit a PR!
+
+<p align="center">
+<img src="assets/hardware-banner.jpg" alt="PicoClaw Hardware Compatibility" width="100%">
+</p>
+
 ## 🦾 Demonstration
 
 ### 🛠️ Standard Assistant Workflows
 
 <table align="center">
-  <tr align="center">
-    <th><p align="center">🧩 Full-Stack Engineer</p></th>
-    <th><p align="center">🗂️ Logging & Planning Management</p></th>
-    <th><p align="center">🔎 Web Search & Learning</p></th>
-  </tr>
-  <tr>
-    <td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
-    <td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
-    <td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
-  </tr>
-  <tr>
-    <td align="center">Develop • Deploy • Scale</td>
-    <td align="center">Schedule • Automate • Memory</td>
-    <td align="center">Discovery • Insights • Trends</td>
-  </tr>
+<tr align="center">
+<th><p align="center">Full-Stack Engineer Mode</p></th>
+<th><p align="center">Logging & Planning</p></th>
+<th><p align="center">Web Search & Learning</p></th>
+</tr>
+<tr>
+<td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
+<td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
+<td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
+</tr>
+<tr>
+<td align="center">Develop · Deploy · Scale</td>
+<td align="center">Schedule · Automate · Remember</td>
+<td align="center">Discover · Insights · Trends</td>
+</tr>
 </table>
 
-### 📱 Run on old Android Phones
+### 🐜 Innovative Low-Footprint Deployment
 
-Give your decade-old phone a second life! Turn it into a smart AI Assistant with PicoClaw. Quick Start:
+PicoClaw can be deployed on virtually any Linux device!
 
-1. **Install Termux** (Available on F-Droid or Google Play).
-2. **Execute cmds**
-
-```bash
-# Note: Replace v0.1.1 with the latest version from the Releases page
-wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
-chmod +x picoclaw-linux-arm64
-pkg install proot
-termux-chroot ./picoclaw-linux-arm64 onboard
-```
-
-And then follow the instructions in the "Quick Start" section to complete the configuration!
-<img src="assets/termux.jpg" alt="PicoClaw" width="512">
-
-### 🐜 Innovative Low-Footprint Deploy
-
-PicoClaw can be deployed on almost any Linux device!
-
-- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) or W(WiFi6) version, for Minimal Home Assistant
-- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), or $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) for Automated Server Maintenance
-- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) or $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) for Smart Monitoring
+- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) or W(WiFi6) edition, for a minimal home assistant
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), or $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), for automated server operations
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) or $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), for smart surveillance
 
 <https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4>
 
-🌟 More Deployment Cases Await！
+🌟 More Deployment Cases Await!
 
 ## 📦 Install
 
-### Install with precompiled binary
+### Download from picoclaw.io (Recommended)
 
-Download the firmware for your platform from the [release](https://github.com/sipeed/picoclaw/releases) page.
+Visit **[picoclaw.io](https://picoclaw.io)** — the official website auto-detects your platform and provides one-click download. No need to manually pick an architecture.
 
-### Install from source (latest features, recommended for development)
+### Download precompiled binary
+
+Alternatively, download the binary for your platform from the [GitHub Releases](https://github.com/sipeed/picoclaw/releases) page.
+
+### Build from source (for development)
 
 ```bash
 git clone https://github.com/sipeed/picoclaw.git
@@ -148,24 +166,59 @@ git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 make deps
 
-# Build, no need to install
+# Build core binary
 make build
 
+# Build Web UI Launcher (required for WebUI mode)
+make build-launcher
+
 # Build for multiple platforms
 make build-all
 
 # Build for Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
 make build-pi-zero
 
-# Build And Install
+# Build and install
 make install
 ```
 
-**Raspberry Pi Zero 2 W:** Use the binary that matches your OS: 32-bit Raspberry Pi OS → `make build-linux-arm` (output: `build/picoclaw-linux-arm`); 64-bit → `make build-linux-arm64` (output: `build/picoclaw-linux-arm64`). Or run `make build-pi-zero` to build both.
+**Raspberry Pi Zero 2 W:** Use the binary that matches your OS: 32-bit Raspberry Pi OS -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Or run `make build-pi-zero` to build both.
 
-## 🐳 Docker Compose
+## 🚀 Quick Start Guide
 
-You can also run PicoClaw using Docker Compose without installing anything locally.
+### 🌐 WebUI Launcher (Recommended for Desktop)
+
+The WebUI Launcher provides a browser-based interface for configuration and chat. This is the easiest way to get started — no command-line knowledge required.
+
+**Option 1: Double-click (Desktop)**
+
+After downloading from [picoclaw.io](https://picoclaw.io), double-click `picoclaw-launcher` (or `picoclaw-launcher.exe` on Windows). Your browser will open automatically at `http://localhost:18800`.
+
+**Option 2: Command line**
+
+```bash
+picoclaw-launcher
+# Open http://localhost:18800 in your browser
+```
+
+> [!TIP]
+> **Remote access / Docker / VM:** Add the `-public` flag to listen on all interfaces:
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+<p align="center">
+<img src="assets/launcher-webui.jpg" alt="WebUI Launcher" width="600">
+</p>
+
+**Getting started:** 
+
+Open the WebUI, then: **1)** Configure a Provider (add your LLM API key) -> **2)** Configure a Channel (e.g., Telegram) -> **3)** Start the Gateway -> **4)** Chat!
+
+For detailed WebUI documentation, see [docs.picoclaw.io](https://docs.picoclaw.io).
+
+<details>
+<summary><b>Docker (alternative)</b></summary>
 
 ```bash
 # 1. Clone this repo
@@ -173,50 +226,81 @@ git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
 # 2. First run — auto-generates docker/data/config.json then exits
-docker compose -f docker/docker-compose.yml --profile gateway up
+#    (only triggers when both config.json and workspace/ are missing)
+docker compose -f docker/docker-compose.yml --profile launcher up
 # The container prints "First-run setup complete." and stops.
 
 # 3. Set your API keys
-vim docker/data/config.json   # Set provider API keys, bot tokens, etc.
+vim docker/data/config.json
 
 # 4. Start
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+# Open http://localhost:18800
 ```
 
-> [!TIP]
-> **Docker Users**: By default, the Gateway listens on `127.0.0.1` which is not accessible from the host. If you need to access the health endpoints or expose ports, set `PICOCLAW_GATEWAY_HOST=0.0.0.0` in your environment or update `config.json`.
+> **Docker / VM users:** The Gateway listens on `127.0.0.1` by default. Set `PICOCLAW_GATEWAY_HOST=0.0.0.0` or use the `-public` flag to make it accessible from the host.
 
 ```bash
-# 5. Check logs
-docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+# Check logs
+docker compose -f docker/docker-compose.yml logs -f
 
-# 6. Stop
-docker compose -f docker/docker-compose.yml --profile gateway down
-```
+# Stop
+docker compose -f docker/docker-compose.yml --profile launcher down
 
-### Agent Mode (One-shot)
-
-```bash
-# Ask a question
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
-
-# Interactive mode
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
-```
-
-### Update
-
-```bash
+# Update
 docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile launcher up -d
 ```
 
-### 🚀 Quick Start
+</details>
 
-> [!TIP]
-> Set your API key in `~/.picoclaw/config.json`.
-> Get API keys: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)
-> Web Search is **optional** - get free [Tavily API](https://tavily.com) (1000 free queries/month) or [Brave Search API](https://brave.com/search/api) (2000 free queries/month) or use built-in auto fallback.
+### 💻 TUI Launcher (Recommended for Headless / SSH)
+
+The TUI (Terminal UI) Launcher provides a full-featured terminal interface for configuration and management. Ideal for servers, Raspberry Pi, and other headless environments.
+
+```bash
+picoclaw-launcher-tui
+```
+
+<p align="center">
+<img src="assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
+</p>
+
+**Getting started:** 
+
+Use the TUI menus to: **1)** Configure a Provider -> **2)** Configure a Channel -> **3)** Start the Gateway -> **4)** Chat!
+
+For detailed TUI documentation, see [docs.picoclaw.io](https://docs.picoclaw.io).
+
+### 📱 Android
+
+Give your decade-old phone a second life! Turn it into a smart AI Assistant with PicoClaw.
+
+**Option 1: Termux (available now)**
+
+1. Install [Termux](https://github.com/termux/termux-app) (download from [GitHub Releases](https://github.com/termux/termux-app/releases), or search in F-Droid / Google Play)
+2. Run the following commands:
+
+```bash
+# Download the latest release
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard   # chroot provides a standard Linux filesystem layout
+```
+
+Then follow the Terminal Launcher section below to complete configuration.
+
+<img src="assets/termux.jpg" alt="PicoClaw on Termux" width="512">
+
+**Option 2: APK Install (coming soon)**
+
+A standalone Android APK with built-in WebUI is in development. Stay tuned!
+
+<details>
+<summary><b>Terminal Launcher (for resource-constrained environments)</b></summary>
+
+For minimal environments where only the `picoclaw` core binary is available (no Launcher UI), you can configure everything via the command line and a JSON config file.
 
 **1. Initialize**
 
@@ -224,1059 +308,274 @@ docker compose -f docker/docker-compose.yml --profile gateway up -d
 picoclaw onboard
 ```
 
+This creates `~/.picoclaw/config.json` and the workspace directory.
+
 **2. Configure** (`~/.picoclaw/config.json`)
 
 ```json
 {
   "agents": {
     "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "model_name": "gpt4",
-      "max_tokens": 8192,
-      "temperature": 0.7,
-      "max_tool_iterations": 20
+      "model_name": "gpt-5.4"
     }
   },
   "model_list": [
     {
-      "model_name": "gpt4",
-      "model": "openai/gpt-5.2",
-      "api_key": "your-api-key",
-      "request_timeout": 300
-    },
-    {
-      "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
-      "api_key": "your-anthropic-key"
-    }
-  ],
-  "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "YOUR_BRAVE_API_KEY",
-        "max_results": 5
-      },
-      "tavily": {
-        "enabled": false,
-        "api_key": "YOUR_TAVILY_API_KEY",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
-      }
-    }
-  }
-}
-```
-
-> **New**: The `model_list` configuration format allows zero-code provider addition. See [Model Configuration](#model-configuration-model_list) for details.
-> `request_timeout` is optional and uses seconds. If omitted or set to `<= 0`, PicoClaw uses the default timeout (120s).
-
-**3. Get API Keys**
-
-* **LLM Provider**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
-* **Web Search** (optional): [Tavily](https://tavily.com) - Optimized for AI Agents (1000 requests/month) · [Brave Search](https://brave.com/search/api) - Free tier available (2000 requests/month)
-
-> **Note**: See `config.example.json` for a complete configuration template.
-
-**4. Chat**
-
-```bash
-picoclaw agent -m "What is 2+2?"
-```
-
-That's it! You have a working AI assistant in 2 minutes.
-
----
-
-## 💬 Chat Apps
-
-Talk to your picoclaw through Telegram, Discord, WhatsApp, DingTalk, LINE, or WeCom
-
-> **Note**: All webhook-based channels (LINE, WeCom, etc.) are served on a single shared Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). There are no per-channel ports to configure. Note: Feishu uses WebSocket/SDK mode and does not use the shared HTTP webhook server.
-
-| Channel      | Setup                              |
-| ------------ | ---------------------------------- |
-| **Telegram** | Easy (just a token)                |
-| **Discord**  | Easy (bot token + intents)         |
-| **WhatsApp** | Easy (native: QR scan; or bridge URL) |
-| **QQ**       | Easy (AppID + AppSecret)           |
-| **DingTalk** | Medium (app credentials)           |
-| **LINE**     | Medium (credentials + webhook URL) |
-| **WeCom**    | Medium (CorpID + webhook setup)    |
-
-<details>
-<summary><b>Telegram</b> (Recommended)</summary>
-
-**1. Create a bot**
-
-* Open Telegram, search `@BotFather`
-* Send `/newbot`, follow prompts
-* Copy the token
-
-**2. Configure**
-
-```json
-{
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "YOUR_BOT_TOKEN",
-      "allow_from": ["YOUR_USER_ID"]
-    }
-  }
-}
-```
-
-> Get your user ID from `@userinfobot` on Telegram.
-
-**3. Run**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>Discord</b></summary>
-
-**1. Create a bot**
-
-* Go to <https://discord.com/developers/applications>
-* Create an application → Bot → Add Bot
-* Copy the bot token
-
-**2. Enable intents**
-
-* In the Bot settings, enable **MESSAGE CONTENT INTENT**
-* (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data
-
-**3. Get your User ID**
-* Discord Settings → Advanced → enable **Developer Mode**
-* Right-click your avatar → **Copy User ID**
-
-**4. Configure**
-
-```json
-{
-  "channels": {
-    "discord": {
-      "enabled": true,
-      "token": "YOUR_BOT_TOKEN",
-      "allow_from": ["YOUR_USER_ID"]
-    }
-  }
-}
-```
-
-**5. Invite the bot**
-
-* OAuth2 → URL Generator
-* Scopes: `bot`
-* Bot Permissions: `Send Messages`, `Read Message History`
-* Open the generated invite URL and add the bot to your server
-
-**Optional: Group trigger mode**
-
-By default the bot responds to all messages in a server channel. To restrict responses to @-mentions only, add:
-
-```json
-{
-  "channels": {
-    "discord": {
-      "group_trigger": { "mention_only": true }
-    }
-  }
-}
-```
-
-You can also trigger by keyword prefixes (e.g. `!bot`):
-
-```json
-{
-  "channels": {
-    "discord": {
-      "group_trigger": { "prefixes": ["!bot"] }
-    }
-  }
-}
-```
-
-**6. Run**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>WhatsApp</b> (native via whatsmeow)</summary>
-
-PicoClaw can connect to WhatsApp in two ways:
-
-- **Native (recommended):** In-process using [whatsmeow](https://github.com/tulir/whatsmeow). No separate bridge. Set `"use_native": true` and leave `bridge_url` empty. On first run, scan the QR code with WhatsApp (Linked Devices). Session is stored under your workspace (e.g. `workspace/whatsapp/`). The native channel is **optional** to keep the default binary small; build with `-tags whatsapp_native` (e.g. `make build-whatsapp-native` or `go build -tags whatsapp_native ./cmd/...`).
-- **Bridge:** Connect to an external WebSocket bridge. Set `bridge_url` (e.g. `ws://localhost:3001`) and keep `use_native` false.
-
-**Configure (native)**
-
-```json
-{
-  "channels": {
-    "whatsapp": {
-      "enabled": true,
-      "use_native": true,
-      "session_store_path": "",
-      "allow_from": []
-    }
-  }
-}
-```
-
-If `session_store_path` is empty, the session is stored in `&lt;workspace&gt;/whatsapp/`. Run `picoclaw gateway`; on first run, scan the QR code printed in the terminal with WhatsApp → Linked Devices.
-
-</details>
-
-<details>
-<summary><b>QQ</b></summary>
-
-**1. Create a bot**
-
-- Go to [QQ Open Platform](https://q.qq.com/#)
-- Create an application → Get **AppID** and **AppSecret**
-
-**2. Configure**
-
-```json
-{
-  "channels": {
-    "qq": {
-      "enabled": true,
-      "app_id": "YOUR_APP_ID",
-      "app_secret": "YOUR_APP_SECRET",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access.
-
-**3. Run**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>DingTalk</b></summary>
-
-**1. Create a bot**
-
-* Go to [Open Platform](https://open.dingtalk.com/)
-* Create an internal app
-* Copy Client ID and Client Secret
-
-**2. Configure**
-
-```json
-{
-  "channels": {
-    "dingtalk": {
-      "enabled": true,
-      "client_id": "YOUR_CLIENT_ID",
-      "client_secret": "YOUR_CLIENT_SECRET",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> Set `allow_from` to empty to allow all users, or specify DingTalk user IDs to restrict access.
-
-**3. Run**
-
-```bash
-picoclaw gateway
-```
-</details>
-
-<details>
-<summary><b>LINE</b></summary>
-
-**1. Create a LINE Official Account**
-
-- Go to [LINE Developers Console](https://developers.line.biz/)
-- Create a provider → Create a Messaging API channel
-- Copy **Channel Secret** and **Channel Access Token**
-
-**2. Configure**
-
-```json
-{
-  "channels": {
-    "line": {
-      "enabled": true,
-      "channel_secret": "YOUR_CHANNEL_SECRET",
-      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_path": "/webhook/line",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> LINE webhook is served on the shared Gateway server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`).
-
-**3. Set up Webhook URL**
-
-LINE requires HTTPS for webhooks. Use a reverse proxy or tunnel:
-
-```bash
-# Example with ngrok (gateway default port is 18790)
-ngrok http 18790
-```
-
-Then set the Webhook URL in LINE Developers Console to `https://your-domain/webhook/line` and enable **Use webhook**.
-
-**4. Run**
-
-```bash
-picoclaw gateway
-```
-
-> In group chats, the bot responds only when @mentioned. Replies quote the original message.
-
-</details>
-
-<details>
-<summary><b>WeCom (企业微信)</b></summary>
-
-PicoClaw supports two types of WeCom integration:
-
-**Option 1: WeCom Bot (智能机器人)** - Easier setup, supports group chats
-**Option 2: WeCom App (自建应用)** - More features, proactive messaging
-
-See [WeCom App Configuration Guide](docs/wecom-app-configuration.md) for detailed setup instructions.
-
-**Quick Setup - WeCom Bot:**
-
-**1. Create a bot**
-
-* Go to WeCom Admin Console → Group Chat → Add Group Bot
-* Copy the webhook URL (format: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
-
-**2. Configure**
-
-```json
-{
-  "channels": {
-    "wecom": {
-      "enabled": true,
-      "token": "YOUR_TOKEN",
-      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_path": "/webhook/wecom",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> WeCom webhook is served on the shared Gateway server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`).
-
-**Quick Setup - WeCom App:**
-
-**1. Create an app**
-
-* Go to WeCom Admin Console → App Management → Create App
-* Copy **AgentId** and **Secret**
-* Go to "My Company" page, copy **CorpID**
-
-**2. Configure receive message**
-
-* In App details, click "Receive Message" → "Set API"
-* Set URL to `http://your-server:18790/webhook/wecom-app`
-* Generate **Token** and **EncodingAESKey**
-
-**3. Configure**
-
-```json
-{
-  "channels": {
-    "wecom_app": {
-      "enabled": true,
-      "corp_id": "wwxxxxxxxxxxxxxxxx",
-      "corp_secret": "YOUR_CORP_SECRET",
-      "agent_id": 1000002,
-      "token": "YOUR_TOKEN",
-      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_path": "/webhook/wecom-app",
-      "allow_from": []
-    }
-  }
-}
-```
-
-**4. Run**
-
-```bash
-picoclaw gateway
-```
-
-> **Note**: WeCom webhook callbacks are served on the Gateway port (default 18790). Use a reverse proxy for HTTPS.
-
-</details>
-
-## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Join the Agent Social Network
-
-Connect Picoclaw to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App.
-
-**Read `https://clawdchat.ai/skill.md` and follow the instructions to join [ClawdChat.ai](https://clawdchat.ai)**
-
-## ⚙️ Configuration
-
-Config file: `~/.picoclaw/config.json`
-
-### Environment Variables
-
-You can override default paths using environment variables. This is useful for portable installations, containerized deployments, or running picoclaw as a system service. These variables are independent and control different paths.
-
-| Variable          | Description                                                                                                                             | Default Path              |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
-| `PICOCLAW_CONFIG` | Overrides the path to the configuration file. This directly tells picoclaw which `config.json` to load, ignoring all other locations. | `~/.picoclaw/config.json` |
-| `PICOCLAW_HOME`   | Overrides the root directory for picoclaw data. This changes the default location of the `workspace` and other data directories.          | `~/.picoclaw`             |
-
-**Examples:**
-
-```bash
-# Run picoclaw using a specific config file
-# The workspace path will be read from within that config file
-PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
-
-# Run picoclaw with all its data stored in /opt/picoclaw
-# Config will be loaded from the default ~/.picoclaw/config.json
-# Workspace will be created at /opt/picoclaw/workspace
-PICOCLAW_HOME=/opt/picoclaw picoclaw agent
-
-# Use both for a fully customized setup
-PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
-```
-
-### Workspace Layout
-
-PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspace`):
-
-```
-~/.picoclaw/workspace/
-├── sessions/          # Conversation sessions and history
-├── memory/           # Long-term memory (MEMORY.md)
-├── state/            # Persistent state (last channel, etc.)
-├── cron/             # Scheduled jobs database
-├── skills/           # Custom skills
-├── AGENTS.md         # Agent behavior guide
-├── HEARTBEAT.md      # Periodic task prompts (checked every 30 min)
-├── IDENTITY.md       # Agent identity
-├── SOUL.md           # Agent soul
-├── TOOLS.md          # Tool descriptions
-└── USER.md           # User preferences
-```
-
-### 🔒 Security Sandbox
-
-PicoClaw runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace.
-
-#### Default Configuration
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "restrict_to_workspace": true
-    }
-  }
-}
-```
-
-| Option                  | Default                 | Description                               |
-| ----------------------- | ----------------------- | ----------------------------------------- |
-| `workspace`             | `~/.picoclaw/workspace` | Working directory for the agent           |
-| `restrict_to_workspace` | `true`                  | Restrict file/command access to workspace |
-
-#### Protected Tools
-
-When `restrict_to_workspace: true`, the following tools are sandboxed:
-
-| Tool          | Function         | Restriction                            |
-| ------------- | ---------------- | -------------------------------------- |
-| `read_file`   | Read files       | Only files within workspace            |
-| `write_file`  | Write files      | Only files within workspace            |
-| `list_dir`    | List directories | Only directories within workspace      |
-| `edit_file`   | Edit files       | Only files within workspace            |
-| `append_file` | Append to files  | Only files within workspace            |
-| `exec`        | Execute commands | Command paths must be within workspace |
-
-#### Additional Exec Protection
-
-Even with `restrict_to_workspace: false`, the `exec` tool blocks these dangerous commands:
-
-* `rm -rf`, `del /f`, `rmdir /s` — Bulk deletion
-* `format`, `mkfs`, `diskpart` — Disk formatting
-* `dd if=` — Disk imaging
-* Writing to `/dev/sd[a-z]` — Direct disk writes
-* `shutdown`, `reboot`, `poweroff` — System shutdown
-* Fork bomb `:(){ :|:& };:`
-
-#### Error Examples
-
-```
-[ERROR] tool: Tool execution failed
-{tool=exec, error=Command blocked by safety guard (path outside working dir)}
-```
-
-```
-[ERROR] tool: Tool execution failed
-{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
-```
-
-#### Disabling Restrictions (Security Risk)
-
-If you need the agent to access paths outside the workspace:
-
-**Method 1: Config file**
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "restrict_to_workspace": false
-    }
-  }
-}
-```
-
-**Method 2: Environment variable**
-
-```bash
-export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
-```
-
-> ⚠️ **Warning**: Disabling this restriction allows the agent to access any path on your system. Use with caution in controlled environments only.
-
-#### Security Boundary Consistency
-
-The `restrict_to_workspace` setting applies consistently across all execution paths:
-
-| Execution Path   | Security Boundary            |
-| ---------------- | ---------------------------- |
-| Main Agent       | `restrict_to_workspace` ✅   |
-| Subagent / Spawn | Inherits same restriction ✅ |
-| Heartbeat tasks  | Inherits same restriction ✅ |
-
-All paths share the same workspace restriction — there's no way to bypass the security boundary through subagents or scheduled tasks.
-
-### Heartbeat (Periodic Tasks)
-
-PicoClaw can perform periodic tasks automatically. Create a `HEARTBEAT.md` file in your workspace:
-
-```markdown
-# Periodic Tasks
-
-- Check my email for important messages
-- Review my calendar for upcoming events
-- Check the weather forecast
-```
-
-The agent will read this file every 30 minutes (configurable) and execute any tasks using available tools.
-
-#### Async Tasks with Spawn
-
-For long-running tasks (web search, API calls), use the `spawn` tool to create a **subagent**:
-
-```markdown
-# Periodic Tasks
-
-## Quick Tasks (respond directly)
-
-- Report current time
-
-## Long Tasks (use spawn for async)
-
-- Search the web for AI news and summarize
-- Check email and report important messages
-```
-
-**Key behaviors:**
-
-| Feature                 | Description                                               |
-| ----------------------- | --------------------------------------------------------- |
-| **spawn**               | Creates async subagent, doesn't block heartbeat           |
-| **Independent context** | Subagent has its own context, no session history          |
-| **message tool**        | Subagent communicates with user directly via message tool |
-| **Non-blocking**        | After spawning, heartbeat continues to next task          |
-
-#### How Subagent Communication Works
-
-```
-Heartbeat triggers
-    ↓
-Agent reads HEARTBEAT.md
-    ↓
-For long task: spawn subagent
-    ↓                           ↓
-Continue to next task      Subagent works independently
-    ↓                           ↓
-All tasks done            Subagent uses "message" tool
-    ↓                           ↓
-Respond HEARTBEAT_OK      User receives result directly
-```
-
-The subagent has access to tools (message, web_search, etc.) and can communicate with the user independently without going through the main agent.
-
-**Configuration:**
-
-```json
-{
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-| Option     | Default | Description                        |
-| ---------- | ------- | ---------------------------------- |
-| `enabled`  | `true`  | Enable/disable heartbeat           |
-| `interval` | `30`    | Check interval in minutes (min: 5) |
-
-**Environment variables:**
-
-* `PICOCLAW_HEARTBEAT_ENABLED=false` to disable
-* `PICOCLAW_HEARTBEAT_INTERVAL=60` to change interval
-
-### Providers
-
-> [!NOTE]
-> Groq provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed.
-
-| Provider                   | Purpose                                 | Get API Key                                                          |
-| -------------------------- | --------------------------------------- | -------------------------------------------------------------------- |
-| `gemini`                   | LLM (Gemini direct)                     | [aistudio.google.com](https://aistudio.google.com)                   |
-| `zhipu`                    | LLM (Zhipu direct)                      | [bigmodel.cn](https://bigmodel.cn)                                   |
-| `openrouter(To be tested)` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai)                               |
-| `anthropic(To be tested)`  | LLM (Claude direct)                     | [console.anthropic.com](https://console.anthropic.com)               |
-| `openai(To be tested)`     | LLM (GPT direct)                        | [platform.openai.com](https://platform.openai.com)                   |
-| `deepseek(To be tested)`   | LLM (DeepSeek direct)                   | [platform.deepseek.com](https://platform.deepseek.com)               |
-| `qwen`                     | LLM (Qwen direct)                       | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
-| `groq`                     | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com)                         |
-| `cerebras`                 | LLM (Cerebras direct)                   | [cerebras.ai](https://cerebras.ai)                                   |
-
-### Model Configuration (model_list)
-
-> **What's New?** PicoClaw now uses a **model-centric** configuration approach. Simply specify `vendor/model` format (e.g., `zhipu/glm-4.7`) to add new providers—**zero code changes required!**
-
-This design also enables **multi-agent support** with flexible provider selection:
-
-- **Different agents, different providers**: Each agent can use its own LLM provider
-- **Model fallbacks**: Configure primary and fallback models for resilience
-- **Load balancing**: Distribute requests across multiple endpoints
-- **Centralized configuration**: Manage all providers in one place
-
-#### 📋 All Supported Vendors
-
-| Vendor              | `model` Prefix    | Default API Base                                    | Protocol  | API Key                                                          |
-| ------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
-| **OpenAI**          | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [Get Key](https://platform.openai.com)                           |
-| **Anthropic**       | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [Get Key](https://console.anthropic.com)                         |
-| **智谱 AI (GLM)**   | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
-| **DeepSeek**        | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [Get Key](https://platform.deepseek.com)                         |
-| **Google Gemini**   | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI    | [Get Key](https://aistudio.google.com/api-keys)                  |
-| **Groq**            | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [Get Key](https://console.groq.com)                              |
-| **Moonshot**        | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [Get Key](https://platform.moonshot.cn)                          |
-| **通义千问 (Qwen)** | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Get Key](https://dashscope.console.aliyun.com)                  |
-| **NVIDIA**          | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [Get Key](https://build.nvidia.com)                              |
-| **Ollama**          | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | Local (no key needed)                                            |
-| **OpenRouter**      | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [Get Key](https://openrouter.ai/keys)                            |
-| **VLLM**            | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | Local                                                            |
-| **Cerebras**        | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [Get Key](https://cerebras.ai)                                   |
-| **火山引擎**        | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Get Key](https://console.volcengine.com)                        |
-| **神算云**          | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                |
-| **Antigravity**     | `antigravity/`    | Google Cloud                                        | Custom    | OAuth only                                                       |
-| **GitHub Copilot**  | `github-copilot/` | `localhost:4321`                                    | gRPC      | -                                                                |
-
-#### Basic Configuration
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_key": "sk-your-openai-key"
-    },
-    {
-      "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
-      "api_key": "sk-ant-your-key"
-    },
-    {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-zhipu-key"
-    }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "gpt-5.2"
-    }
-  }
-}
-```
-
-#### Vendor-Specific Examples
-
-**OpenAI**
-
-```json
-{
-  "model_name": "gpt-5.2",
-  "model": "openai/gpt-5.2",
-  "api_key": "sk-..."
-}
-```
-
-**智谱 AI (GLM)**
-
-```json
-{
-  "model_name": "glm-4.7",
-  "model": "zhipu/glm-4.7",
-  "api_key": "your-key"
-}
-```
-
-**DeepSeek**
-
-```json
-{
-  "model_name": "deepseek-chat",
-  "model": "deepseek/deepseek-chat",
-  "api_key": "sk-..."
-}
-```
-
-**Anthropic (with API key)**
-
-```json
-{
-  "model_name": "claude-sonnet-4.6",
-  "model": "anthropic/claude-sonnet-4.6",
-  "api_key": "sk-ant-your-key"
-}
-```
-
-> Run `picoclaw auth login --provider anthropic` to paste your API token.
-
-**Ollama (local)**
-
-```json
-{
-  "model_name": "llama3",
-  "model": "ollama/llama3"
-}
-```
-
-**Custom Proxy/API**
-
-```json
-{
-  "model_name": "my-custom-model",
-  "model": "openai/custom-model",
-  "api_base": "https://my-proxy.com/v1",
-  "api_key": "sk-...",
-  "request_timeout": 300
-}
-```
-
-#### Load Balancing
-
-Configure multiple endpoints for the same model name—PicoClaw will automatically round-robin between them:
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_base": "https://api1.example.com/v1",
-      "api_key": "sk-key1"
-    },
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_base": "https://api2.example.com/v1",
-      "api_key": "sk-key2"
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-api-key"
     }
   ]
 }
 ```
 
-#### Migration from Legacy `providers` Config
+> See `config/config.example.json` in the repo for a complete configuration template with all available options.
 
-The old `providers` configuration is **deprecated** but still supported for backward compatibility.
+**3. Chat**
 
-**Old Config (deprecated):**
+```bash
+# One-shot question
+picoclaw agent -m "What is 2+2?"
 
-```json
-{
-  "providers": {
-    "zhipu": {
-      "api_key": "your-key",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  },
-  "agents": {
-    "defaults": {
-      "provider": "zhipu",
-      "model": "glm-4.7"
-    }
-  }
-}
+# Interactive mode
+picoclaw agent
+
+# Start gateway for chat app integration
+picoclaw gateway
 ```
 
-**New Config (recommended):**
+</details>
 
+## 🔌 Providers (LLM)
+
+PicoClaw supports 30+ LLM providers through the `model_list` configuration. Use the `protocol/model` format:
+
+| Provider | Protocol | API Key | Notes |
+|----------|----------|---------|-------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Required | GPT-5.4, GPT-4o, o3, etc. |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Required | Claude Opus 4.6, Sonnet 4.6, etc. |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Required | Gemini 3 Flash, 2.5 Pro, etc. |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Required | 200+ models, unified API |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Required | GLM-4.7, GLM-5, etc. |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Required | DeepSeek-V3, DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | Required | Doubao, Ark models |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Required | Qwen3, Qwen-Max, etc. |
+| [Groq](https://console.groq.com/keys) | `groq/` | Required | Fast inference (Llama, Mixtral) |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Required | Kimi models |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Required | MiniMax models |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Required | Mistral Large, Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Required | NVIDIA hosted models |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Required | Fast inference |
+| [Novita AI](https://novita.ai/) | `novita/` | Required | Various open models |
+| [Ollama](https://ollama.com/) | `ollama/` | Not needed | Local models, self-hosted |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | Not needed | Local deployment, OpenAI-compatible |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Varies | Proxy for 100+ providers |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Required | Enterprise Azure deployment |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Device code login |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+| [AWS Bedrock](https://console.aws.amazon.com/bedrock)* | `bedrock/` | AWS credentials | Claude, Llama, Mistral on AWS |
+
+> \* AWS Bedrock requires build tag: `go build -tags bedrock`. Set `api_base` to a region name (e.g., `us-east-1`) for automatic endpoint resolution across all AWS partitions (aws, aws-cn, aws-us-gov). When using a full endpoint URL instead, you must also configure `AWS_REGION` via environment variable or AWS config/profile.
+
+<details>
+<summary><b>Local deployment (Ollama, vLLM, etc.)</b></summary>
+
+**Ollama:**
 ```json
 {
   "model_list": [
     {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-key"
+      "model_name": "local-llama",
+      "model": "ollama/llama3.1:8b",
+      "api_base": "http://localhost:11434/v1"
     }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "glm-4.7"
-    }
-  }
+  ]
 }
 ```
 
-For detailed migration guide, see [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md).
-
-### Provider Architecture
-
-PicoClaw routes providers by protocol family:
-
-- OpenAI-compatible protocol: OpenRouter, OpenAI-compatible gateways, Groq, Zhipu, and vLLM-style endpoints.
-- Anthropic protocol: Claude-native API behavior.
-- Codex/OAuth path: OpenAI OAuth/token authentication route.
-
-This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`).
-
-<details>
-<summary><b>Zhipu</b></summary>
-
-**1. Get API key and base URL**
-
-* Get [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
-
-**2. Configure**
-
+**vLLM:**
 ```json
 {
-  "agents": {
-    "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "model": "glm-4.7",
-      "max_tokens": 8192,
-      "temperature": 0.7,
-      "max_tool_iterations": 20
+  "model_list": [
+    {
+      "model_name": "local-vllm",
+      "model": "vllm/your-model",
+      "api_base": "http://localhost:8000/v1"
     }
-  },
-  "providers": {
-    "zhipu": {
-      "api_key": "Your API Key",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  }
+  ]
 }
 ```
 
-**3. Run**
+For full provider configuration details, see [Providers & Models](docs/providers.md).
+
+</details>
+
+## 💬 Channels (Chat Apps)
+
+Talk to your PicoClaw through 17+ messaging platforms:
+
+| Channel | Setup | Protocol | Docs |
+|---------|-------|----------|------|
+| **Telegram** | Easy (bot token) | Long polling | [Guide](docs/channels/telegram/README.md) |
+| **Discord** | Easy (bot token + intents) | WebSocket | [Guide](docs/channels/discord/README.md) |
+| **WhatsApp** | Easy (QR scan or bridge URL) | Native / Bridge | [Guide](docs/chat-apps.md#whatsapp) |
+| **Weixin** | Easy (Native QR scan) | iLink API | [Guide](docs/chat-apps.md#weixin) |
+| **QQ** | Easy (AppID + AppSecret) | WebSocket | [Guide](docs/channels/qq/README.md) |
+| **Slack** | Easy (bot + app token) | Socket Mode | [Guide](docs/channels/slack/README.md) |
+| **Matrix** | Medium (homeserver + token) | Sync API | [Guide](docs/channels/matrix/README.md) |
+| **DingTalk** | Medium (client credentials) | Stream | [Guide](docs/channels/dingtalk/README.md) |
+| **Feishu / Lark** | Medium (App ID + Secret) | WebSocket/SDK | [Guide](docs/channels/feishu/README.md) |
+| **LINE** | Medium (credentials + webhook) | Webhook | [Guide](docs/channels/line/README.md) |
+| **WeCom Bot** | Medium (webhook URL) | Webhook | [Guide](docs/channels/wecom/wecom_bot/README.md) |
+| **WeCom App** | Medium (corp credentials) | Webhook | [Guide](docs/channels/wecom/wecom_app/README.md) |
+| **WeCom AI Bot** | Medium (token + AES key) | WebSocket / Webhook | [Guide](docs/channels/wecom/wecom_aibot/README.md) |
+| **IRC** | Medium (server + nick) | IRC protocol | [Guide](docs/chat-apps.md#irc) |
+| **OneBot** | Medium (WebSocket URL) | OneBot v11 | [Guide](docs/channels/onebot/README.md) |
+| **MaixCam** | Easy (enable) | TCP socket | [Guide](docs/channels/maixcam/README.md) |
+| **Pico** | Easy (enable) | Native protocol | Built-in |
+| **Pico Client** | Easy (WebSocket URL) | WebSocket | Built-in |
+
+> All webhook-based channels share a single Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu uses WebSocket/SDK mode and does not use the shared HTTP server.
+
+For detailed channel setup instructions, see [Chat Apps Configuration](docs/chat-apps.md).
+
+## 🔧 Tools
+
+### 🔍 Web Search
+
+PicoClaw can search the web to provide up-to-date information. Configure in `tools.web`:
+
+| Search Engine | API Key | Free Tier | Link |
+|--------------|---------|-----------|------|
+| DuckDuckGo | Not needed | Unlimited | Built-in fallback |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Required | 1000 queries/day | AI-powered, China-optimized |
+| [Tavily](https://tavily.com) | Required | 1000 queries/month | Optimized for AI Agents |
+| [Brave Search](https://brave.com/search/api) | Required | 2000 queries/month | Fast and private |
+| [Perplexity](https://www.perplexity.ai) | Required | Paid | AI-powered search |
+| [SearXNG](https://github.com/searxng/searxng) | Not needed | Self-hosted | Free metasearch engine |
+| [GLM Search](https://open.bigmodel.cn/) | Required | Varies | Zhipu web search |
+
+### ⚙️ Other Tools
+
+PicoClaw includes built-in tools for file operations, code execution, scheduling, and more. See [Tools Configuration](docs/tools_configuration.md) for details.
+
+## 🎯 Skills
+
+Skills are modular capabilities that extend your Agent. They are loaded from `SKILL.md` files in your workspace.
+
+**Install skills from ClawHub:**
 
 ```bash
-picoclaw agent -m "Hello"
+picoclaw skills search "web scraping"
+picoclaw skills install <skill-name>
 ```
 
-</details>
-
-<details>
-<summary><b>Full config example</b></summary>
+**Configure ClawHub token** (optional, for higher rate limits):
 
+Add to your `config.json`:
 ```json
 {
-  "agents": {
-    "defaults": {
-      "model": "anthropic/claude-opus-4-5"
-    }
-  },
-  "providers": {
-    "openrouter": {
-      "api_key": "sk-or-v1-xxx"
-    },
-    "groq": {
-      "api_key": "gsk_xxx"
-    }
-  },
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "123456:ABC...",
-      "allow_from": ["123456789"]
-    },
-    "discord": {
-      "enabled": true,
-      "token": "",
-      "allow_from": [""]
-    },
-    "whatsapp": {
-      "enabled": false,
-      "bridge_url": "ws://localhost:3001",
-      "use_native": false,
-      "session_store_path": "",
-      "allow_from": []
-    },
-    "feishu": {
-      "enabled": false,
-      "app_id": "cli_xxx",
-      "app_secret": "xxx",
-      "encrypt_key": "",
-      "verification_token": "",
-      "allow_from": []
-    },
-    "qq": {
-      "enabled": false,
-      "app_id": "",
-      "app_secret": "",
-      "allow_from": []
-    }
-  },
   "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "BSA...",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "auth_token": "your-clawhub-token"
+        }
       }
-    },
-    "cron": {
-      "exec_timeout_minutes": 5
     }
-  },
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
   }
 }
 ```
 
-</details>
+For more details, see [Tools Configuration - Skills](docs/tools_configuration.md#skills-tool).
 
-## CLI Reference
+## 🔗 MCP (Model Context Protocol)
 
-| Command                   | Description                   |
-| ------------------------- | ----------------------------- |
-| `picoclaw onboard`        | Initialize config & workspace |
-| `picoclaw agent -m "..."` | Chat with the agent           |
-| `picoclaw agent`          | Interactive chat mode         |
-| `picoclaw gateway`        | Start the gateway             |
-| `picoclaw status`         | Show status                   |
-| `picoclaw cron list`      | List all scheduled jobs       |
-| `picoclaw cron add ...`   | Add a scheduled job           |
+PicoClaw natively supports [MCP](https://modelcontextprotocol.io/) — connect any MCP server to extend your Agent's capabilities with external tools and data sources.
 
-### Scheduled Tasks / Reminders
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+        }
+      }
+    }
+  }
+}
+```
+
+For full MCP configuration (stdio, SSE, HTTP transports, Tool Discovery), see [Tools Configuration - MCP](docs/tools_configuration.md#mcp-tool).
+
+## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Join the Agent Social Network
+
+Connect PicoClaw to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App.
+
+**Read `https://clawdchat.ai/skill.md` and follow the instructions to join [ClawdChat.ai](https://clawdchat.ai)**
+
+## 🖥️ CLI Reference
+
+| Command                   | Description                      |
+| ------------------------- | -------------------------------- |
+| `picoclaw onboard`        | Initialize config & workspace    |
+| `picoclaw auth weixin` | Connect WeChat account via QR |
+| `picoclaw agent -m "..."` | Chat with the agent              |
+| `picoclaw agent`          | Interactive chat mode            |
+| `picoclaw gateway`        | Start the gateway                |
+| `picoclaw status`         | Show status                      |
+| `picoclaw version`        | Show version info                |
+| `picoclaw model`          | View or switch the default model |
+| `picoclaw cron list`      | List all scheduled jobs          |
+| `picoclaw cron add ...`   | Add a scheduled job              |
+| `picoclaw cron disable`   | Disable a scheduled job          |
+| `picoclaw cron remove`    | Remove a scheduled job           |
+| `picoclaw skills list`    | List installed skills            |
+| `picoclaw skills install` | Install a skill                  |
+| `picoclaw migrate`        | Migrate data from older versions |
+| `picoclaw auth login`     | Authenticate with providers      |
+
+### ⏰ Scheduled Tasks / Reminders
 
 PicoClaw supports scheduled reminders and recurring tasks through the `cron` tool:
 
-* **One-time reminders**: "Remind me in 10 minutes" → triggers once after 10min
-* **Recurring tasks**: "Remind me every 2 hours" → triggers every 2 hours
-* **Cron expressions**: "Remind me at 9am daily" → uses cron expression
+* **One-time reminders**: "Remind me in 10 minutes" -> triggers once after 10min
+* **Recurring tasks**: "Remind me every 2 hours" -> triggers every 2 hours
+* **Cron expressions**: "Remind me at 9am daily" -> uses cron expression
 
-Jobs are stored in `~/.picoclaw/workspace/cron/` and processed automatically.
+## 📚 Documentation
+
+For detailed guides beyond this README:
+
+| Topic | Description |
+|-------|-------------|
+| [Docker & Quick Start](docs/docker.md) | Docker Compose setup, Launcher/Agent modes |
+| [Chat Apps](docs/chat-apps.md) | All 17+ channel setup guides |
+| [Configuration](docs/configuration.md) | Environment variables, workspace layout, security sandbox |
+| [Providers & Models](docs/providers.md) | 30+ LLM providers, model routing, model_list configuration |
+| [Spawn & Async Tasks](docs/spawn-tasks.md) | Quick tasks, long tasks with spawn, async sub-agent orchestration |
+| [Hooks](docs/hooks/README.md) | Event-driven hook system: observers, interceptors, approval hooks |
+| [Steering](docs/steering.md) | Inject messages into a running agent loop between tool calls |
+| [SubTurn](docs/subturn.md) | Subagent coordination, concurrency control, lifecycle |
+| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
+| [Tools Configuration](docs/tools_configuration.md) | Per-tool enable/disable, exec policies, MCP, Skills |
+| [Hardware Compatibility](docs/hardware-compatibility.md) | Tested boards, minimum requirements |
 
 ## 🤝 Contribute & Roadmap
 
-PRs welcome! The codebase is intentionally small and readable. 🤗
+PRs welcome! The codebase is intentionally small and readable.
 
-See our full [Community Roadmap](https://github.com/sipeed/picoclaw/blob/main/ROADMAP.md).
+See our [Community Roadmap](https://github.com/sipeed/picoclaw/issues/988) and [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 Developer group building, join after your first merged PR!
 
 User Groups:
 
-discord: <https://discord.gg/V4sAZ9XWpN>
+Discord: <https://discord.gg/V4sAZ9XWpN>
 
-<img src="assets/wechat.png" alt="PicoClaw" width="512">
-
-## 🐛 Troubleshooting
-
-### Web search says "API key configuration issue"
-
-This is normal if you haven't configured a search API key yet. PicoClaw will provide helpful links for manual searching.
-
-To enable web search:
-
-1. **Option 1 (Recommended)**: Get a free API key at [https://brave.com/search/api](https://brave.com/search/api) (2000 free queries/month) for the best results.
-2. **Option 2 (No Credit Card)**: If you don't have a key, we automatically fall back to **DuckDuckGo** (no key required).
-
-Add the key to `~/.picoclaw/config.json` if using Brave:
-
-```json
-{
-  "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "YOUR_BRAVE_API_KEY",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
-      }
-    }
-  }
-}
-```
-
-### Getting content filtering errors
-
-Some providers (like Zhipu) have content filtering. Try rephrasing your query or use a different model.
-
-### Telegram bot says "Conflict: terminated by other getUpdates"
-
-This happens when another instance of the bot is running. Make sure only one `picoclaw gateway` is running at a time.
-
----
-
-## 📝 API Key Comparison
-
-| Service          | Free Tier           | Use Case                              |
-| ---------------- | ------------------- | ------------------------------------- |
-| **OpenRouter**   | 200K tokens/month   | Multiple models (Claude, GPT-4, etc.) |
-| **Zhipu**        | 200K tokens/month   | Best for Chinese users                |
-| **Brave Search** | 2000 queries/month  | Web search functionality              |
-| **Groq**         | Free tier available | Fast inference (Llama, Mixtral)       |
-| **Cerebras**     | Free tier available | Fast inference (Llama, Qwen, etc.)    |
+WeChat:
+<img src="assets/wechat.png" alt="WeChat group QR code" width="512">
diff --git a/README.pt-br.md b/README.pt-br.md
index 611a61281..d4b303e24 100644
--- a/README.pt-br.md
+++ b/README.pt-br.md
@@ -1,27 +1,34 @@
 <div align="center">
-<img src="assets/logo.jpg" alt="PicoClaw" width="512">
+<img src="assets/logo.webp" alt="PicoClaw" width="512">
 
 <h1>PicoClaw: Assistente de IA Ultra-Eficiente em Go</h1>
 
-<h3>Hardware de $10 · 10MB de RAM · Boot em 1s · 皮皮虾，我们走！</h3>
-
+<h3>Hardware de $10 · 10MB de RAM · Boot em ms · Let's Go, PicoClaw!</h3>
   <p>
-    <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
-    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20RISC--V-blue" alt="Hardware">
+    <img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
+    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V%2C%20LoongArch-blue" alt="Hardware">
     <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
     <br>
     <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
+    <a href="https://docs.picoclaw.io/"><img src="https://img.shields.io/badge/Docs-Official-007acc?style=flat&logo=read-the-docs&logoColor=white" alt="Docs"></a>
+    <a href="https://deepwiki.com/sipeed/picoclaw"><img src="https://img.shields.io/badge/Wiki-DeepWiki-FFA500?style=flat&logo=wikipedia&logoColor=white" alt="Wiki"></a>
+    <br>
     <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
+    <a href="./assets/wechat.png"><img src="https://img.shields.io/badge/WeChat-Group-41d56b?style=flat&logo=wechat&logoColor=white"></a>
+    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
   </p>
 
- [中文](README.zh.md) | [日本語](README.ja.md) | **Português** | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | **Português** | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md)
+
 </div>
 
 ---
 
-🦐 **PicoClaw** é um assistente pessoal de IA ultra-leve inspirado no [nanobot](https://github.com/HKUDS/nanobot), reescrito do zero em **Go** por meio de um processo de "auto-inicialização" (self-bootstrapping) — onde o próprio agente de IA conduziu toda a migração de arquitetura e otimização de código.
+> **PicoClaw** é um projeto open-source independente iniciado pela [Sipeed](https://sipeed.com), escrito inteiramente em **Go** do zero — não é um fork do OpenClaw, NanoBot ou qualquer outro projeto.
 
-⚡️ **Extremamente leve:** Roda em hardware de apenas **$10** com **<10MB** de RAM. Isso é 99% menos memória que o OpenClaw e 98% mais barato que um Mac mini!
+**PicoClaw** é um assistente de IA pessoal ultra-leve inspirado no [NanoBot](https://github.com/HKUDS/nanobot). Foi reconstruído do zero em **Go** por meio de um processo de "auto-bootstrapping" — o próprio AI Agent conduziu a migração de arquitetura e a otimização do código.
+
+**Roda em hardware de $10 com menos de 10MB de RAM** — isso é 99% menos memória que o OpenClaw e 98% mais barato que um Mac mini!
 
 <table align="center">
 <tr align="center">
@@ -39,55 +46,83 @@
 </table>
 
 > [!CAUTION]
-> **🚨 DECLARAÇÃO DE SEGURANÇA & CANAIS OFICIAIS**
+> **Aviso de Segurança**
 >
-> * **SEM CRIPTOMOEDAS:** O PicoClaw **NÃO** possui nenhum token/moeda oficial. Todas as alegações no `pump.fun` ou outras plataformas de negociação são **GOLPES**.
-> * **DOMÍNIO OFICIAL:** O **ÚNICO** site oficial é o **[picoclaw.io](https://picoclaw.io)**, e o site da empresa é o **[sipeed.com](https://sipeed.com)**.
-> * **Aviso:** Muitos domínios `.ai/.org/.com/.net/...` foram registrados por terceiros, não são nossos.
-> * **Aviso:** O PicoClaw está em fase inicial de desenvolvimento e pode ter problemas de segurança de rede não resolvidos. Não implante em ambientes de produção antes da versão v1.0.
-> * **Nota:** O PicoClaw recentemente fez merge de muitos PRs, o que pode resultar em maior consumo de memória (10-20MB) nas versões mais recentes. Planejamos priorizar a otimização de recursos assim que o conjunto de funcionalidades estiver estável.
-
+> * **SEM CRIPTO:** O PicoClaw **não** emitiu nenhum token oficial ou criptomoeda. Todas as alegações no `pump.fun` ou outras plataformas de negociação são **golpes**.
+> * **DOMÍNIO OFICIAL:** O **ÚNICO** site oficial é **[picoclaw.io](https://picoclaw.io)**, e o site da empresa é **[sipeed.com](https://sipeed.com)**
+> * **ATENÇÃO:** Muitos domínios `.ai/.org/.com/.net/...` foram registrados por terceiros. Não confie neles.
+> * **NOTA:** O PicoClaw está em desenvolvimento rápido inicial. Podem existir problemas de segurança não resolvidos. Não implante em produção antes da v1.0.
+> * **NOTA:** O PicoClaw mesclou muitos PRs recentemente. Builds recentes podem usar 10-20MB de RAM. A otimização de recursos está planejada após a estabilização de funcionalidades.
 
 ## 📢 Novidades
 
-2026-02-16 🎉 PicoClaw atingiu 12K stars em uma semana! Obrigado a todos pelo apoio! O PicoClaw está crescendo mais rápido do que jamais imaginamos. Dado o alto volume de PRs, precisamos urgentemente de maintainers da comunidade. Nossos papéis de voluntários e roadmap foram publicados oficialmente [aqui](docs/ROADMAP.md) — estamos ansiosos para ter você a bordo!
+2026-03-17 🚀 **v0.2.3 Lançada!** UI na bandeja do sistema (Windows e Linux), consulta de status de sub-agent (`spawn_status`), hot-reload experimental do Gateway, controle de segurança do Cron e 2 correções de segurança. O PicoClaw atingiu **25K Stars**!
 
-2026-02-13 🎉 PicoClaw atingiu 5000 stars em 4 dias! Obrigado à comunidade! Estamos finalizando o **Roadmap do Projeto** e configurando o **Grupo de Desenvolvedores** para acelerar o desenvolvimento do PicoClaw.
+2026-03-09 🎉 **v0.2.1 — Maior atualização até agora!** Suporte ao protocolo MCP, 4 novos channels (Matrix/IRC/WeCom/Discord Proxy), 3 novos providers (Kimi/Minimax/Avian), pipeline de visão, armazenamento de memória JSONL, roteamento de modelos.
 
-🚀 **Chamada para Ação:** Envie suas solicitações de funcionalidades nas GitHub Discussions. Revisaremos e priorizaremos na próxima reunião semanal.
+2026-02-28 📦 **v0.2.0** lançada com suporte a Docker Compose e Web UI Launcher.
 
-2026-02-09 🎉 PicoClaw lançado oficialmente! Construído em 1 dia para trazer Agentes de IA para hardware de $10 com <10MB de RAM. 🦐 PicoClaw, Partiu!
+2026-02-26 🎉 O PicoClaw atinge **20K Stars** em apenas 17 dias! Orquestração automática de channels e interfaces de capacidade estão disponíveis.
+
+<details>
+<summary>Notícias anteriores...</summary>
+
+2026-02-16 🎉 O PicoClaw ultrapassa 12K Stars em uma semana! Funções de mantenedor da comunidade e [Roadmap](ROADMAP.md) lançados oficialmente.
+
+2026-02-13 🎉 O PicoClaw ultrapassa 5000 Stars em 4 dias! Roadmap do projeto e grupos de desenvolvedores em andamento.
+
+2026-02-09 🎉 **PicoClaw Lançado!** Construído em 1 dia para levar AI Agents a hardware de $10 com menos de 10MB de RAM. Let's Go, PicoClaw!
+
+</details>
 
 ## ✨ Funcionalidades
 
-🪶 **Ultra-Leve**: Consumo de memória <10MB — 99% menor que o Clawdbot para funcionalidades essenciais.
+🪶 **Ultra-leve**: Footprint de memória do núcleo <10MB — 99% menor que o OpenClaw.*
 
-💰 **Custo Mínimo**: Eficiente o suficiente para rodar em hardware de $10 — 98% mais barato que um Mac mini.
+💰 **Custo mínimo**: Eficiente o suficiente para rodar em hardware de $10 — 98% mais barato que um Mac mini.
 
-⚡️ **Inicialização Relámpago**: Tempo de inicialização 400X mais rápido, boot em 1 segundo mesmo em CPU single-core de 0.6GHz.
+⚡️ **Boot ultrarrápido**: Inicialização 400x mais rápida. Boot em menos de 1s mesmo em um processador single-core de 0,6GHz.
 
-🌍 **Portabilidade Real**: Um único binário auto-contido para RISC-V, ARM e x86. Um clique e já era!
+🌍 **Verdadeiramente portátil**: Binário único para arquiteturas RISC-V, ARM, MIPS e x86. Um binário, roda em qualquer lugar!
 
-🤖 **Auto-Construído por IA**: Implementação nativa em Go de forma autônoma — 95% do núcleo gerado pelo Agente com refinamento humano no loop.
+🤖 **Bootstrapped por IA**: Implementação nativa pura em Go — 95% do código principal foi gerado por um Agent e refinado por revisão humana.
 
-|                               | OpenClaw      | NanoBot                  | **PicoClaw**                              |
-| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
-| **Linguagem**                 | TypeScript    | Python                   | **Go**                                    |
-| **RAM**                       | >1GB          | >100MB                   | **< 10MB**                                |
-| **Inicialização**</br>(CPU 0.8GHz) | >500s         | >30s                     | **<1s**                                   |
-| **Custo**                     | Mac Mini $599 | Maioria dos SBC Linux </br>~$50 | **Qualquer placa Linux**</br>**A partir de $10** |
+🔌 **Suporte a MCP**: Integração nativa com o [Model Context Protocol](https://modelcontextprotocol.io/) — conecte qualquer servidor MCP para estender as capacidades do Agent.
+
+👁️ **Pipeline de visão**: Envie imagens e arquivos diretamente ao Agent — codificação base64 automática para LLMs multimodais.
+
+🧠 **Roteamento inteligente**: Roteamento de modelos baseado em regras — consultas simples vão para modelos leves, economizando custos de API.
+
+_*Builds recentes podem usar 10-20MB devido a merges rápidos de PRs. Otimização de recursos está planejada. Comparação de velocidade de boot baseada em benchmarks de single-core a 0,8GHz (veja tabela abaixo)._
+
+<div align="center">
+
+|                                | OpenClaw      | NanoBot                  | **PicoClaw**                           |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **Linguagem**                  | TypeScript    | Python                   | **Go**                                 |
+| **RAM**                        | >1GB          | >100MB                   | **< 10MB***                            |
+| **Tempo de boot**</br>(core 0,8GHz) | >500s    | >30s                     | **<1s**                                |
+| **Custo**                      | Mac Mini $599 | Maioria das placas Linux ~$50 | **Qualquer placa Linux**</br>**a partir de $10** |
 
 <img src="assets/compare.jpg" alt="PicoClaw" width="512">
 
+</div>
+
+> **[Lista de Compatibilidade de Hardware](docs/pt-br/hardware-compatibility.md)** — Veja todas as placas testadas, de RISC-V de $5 ao Raspberry Pi e celulares Android. Sua placa não está listada? Envie um PR!
+
+<p align="center">
+<img src="assets/hardware-banner.jpg" alt="PicoClaw Hardware Compatibility" width="100%">
+</p>
+
 ## 🦾 Demonstração
 
 ### 🛠️ Fluxos de Trabalho Padrão do Assistente
 
 <table align="center">
 <tr align="center">
-<th><p align="center">🧩 Engenharia Full-Stack</p></th>
-<th><p align="center">🗂️ Gerenciamento de Logs & Planejamento</p></th>
-<th><p align="center">🔎 Busca Web & Aprendizado</p></th>
+<th><p align="center">Modo Engenheiro Full-Stack</p></th>
+<th><p align="center">Registro e Planejamento</p></th>
+<th><p align="center">Busca na Web e Aprendizado</p></th>
 </tr>
 <tr>
 <td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
@@ -95,50 +130,35 @@
 <td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
 </tr>
 <tr>
-<td align="center">Desenvolver • Implantar • Escalar</td>
-<td align="center">Agendar • Automatizar • Memorizar</td>
-<td align="center">Descobrir • Analisar • Tendências</td>
+<td align="center">Desenvolver · Implantar · Escalar</td>
+<td align="center">Agendar · Automatizar · Lembrar</td>
+<td align="center">Descobrir · Insights · Tendências</td>
 </tr>
 </table>
 
-### 📱 Rode em celulares Android antigos
-
-Dê uma segunda vida ao seu celular de dez anos atrás! Transforme-o em um assistente de IA inteligente com o PicoClaw. Início rápido:
-
-1. **Instale o Termux** (Disponível no F-Droid ou Google Play).
-2. **Execute os comandos**
-
-```bash
-# Nota: Substitua v0.1.1 pela versao mais recente da pagina de Releases
-wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
-chmod +x picoclaw-linux-arm64
-pkg install proot
-termux-chroot ./picoclaw-linux-arm64 onboard
-```
-
-Depois siga as instruções na seção "Início Rápido" para completar a configuração!
-
-<img src="assets/termux.jpg" alt="PicoClaw" width="512">
-
-### 🐜 Implantação Inovadora com Baixo Consumo
+### 🐜 Implantação Inovadora de Baixo Consumo
 
 O PicoClaw pode ser implantado em praticamente qualquer dispositivo Linux!
 
-- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) versão E (Ethernet) ou W (WiFi6), para Assistente Doméstico Minimalista
-- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) para Manutenção Automatizada de Servidores
-- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) para Monitoramento Inteligente
+- $9,9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) edição E(Ethernet) ou W(WiFi6), para um assistente doméstico mínimo
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), ou $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), para operações automatizadas de servidor
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) ou $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), para vigilância inteligente
 
-https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4
+<https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4>
 
-🌟 Mais cenários de implantação aguardam você!
+🌟 Mais Casos de Implantação Aguardam!
 
 ## 📦 Instalação
 
-### Instalar com binário pré-compilado
+### Download pelo picoclaw.io (Recomendado)
 
-Baixe o binário para sua plataforma na página de [releases](https://github.com/sipeed/picoclaw/releases).
+Acesse **[picoclaw.io](https://picoclaw.io)** — o site oficial detecta automaticamente sua plataforma e fornece download com um clique. Não é necessário selecionar a arquitetura manualmente.
 
-### Instalar a partir do código-fonte (funcionalidades mais recentes, recomendado para desenvolvimento)
+### Download do binário pré-compilado
+
+Alternativamente, baixe o binário para sua plataforma na página de [GitHub Releases](https://github.com/sipeed/picoclaw/releases).
+
+### Compilar a partir do código-fonte (para desenvolvimento)
 
 ```bash
 git clone https://github.com/sipeed/picoclaw.git
@@ -146,70 +166,141 @@ git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 make deps
 
-# Build, sem necessidade de instalar
+# Compilar o binário principal
 make build
 
-# Build para multiplas plataformas
+# Compilar o Web UI Launcher (necessário para o modo WebUI)
+make build-launcher
+
+# Compilar para múltiplas plataformas
 make build-all
 
-# Build e Instalar
+# Compilar para Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
+make build-pi-zero
+
+# Compilar e instalar
 make install
 ```
 
-## 🐳 Docker Compose
+**Raspberry Pi Zero 2 W:** Use o binário que corresponde ao seu SO: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Ou execute `make build-pi-zero` para compilar ambos.
 
-Você tambêm pode rodar o PicoClaw usando Docker Compose sem instalar nada localmente.
+## 🚀 Guia de Início Rápido
+
+### 🌐 WebUI Launcher (Recomendado para Desktop)
+
+O WebUI Launcher fornece uma interface baseada em navegador para configuração e chat. Esta é a maneira mais fácil de começar — sem necessidade de conhecimento de linha de comando.
+
+**Opção 1: Duplo clique (Desktop)**
+
+Após baixar de [picoclaw.io](https://picoclaw.io), dê duplo clique em `picoclaw-launcher` (ou `picoclaw-launcher.exe` no Windows). Seu navegador abrirá automaticamente em `http://localhost:18800`.
+
+**Opção 2: Linha de comando**
 
 ```bash
-# 1. Clone este repositorio
+picoclaw-launcher
+# Abra http://localhost:18800 no seu navegador
+```
+
+> [!TIP]
+> **Acesso remoto / Docker / VM:** Adicione a flag `-public` para escutar em todas as interfaces:
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+<p align="center">
+<img src="assets/launcher-webui.jpg" alt="WebUI Launcher" width="600">
+</p>
+
+**Primeiros passos:**
+
+Abra o WebUI e então: **1)** Configure um Provider (adicione sua API key de LLM) -> **2)** Configure um Channel (ex.: Telegram) -> **3)** Inicie o Gateway -> **4)** Converse!
+
+Para documentação detalhada do WebUI, veja [docs.picoclaw.io](https://docs.picoclaw.io).
+
+<details>
+<summary><b>Docker (alternativa)</b></summary>
+
+```bash
+# 1. Clone este repositório
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Primeiro uso — gera docker/data/config.json automaticamente e para
-docker compose -f docker/docker-compose.yml --profile gateway up
-# O contêiner exibe "First-run setup complete." e para.
+# 2. Primeira execução — gera automaticamente docker/data/config.json e encerra
+#    (só é acionado quando config.json e workspace/ estão ausentes)
+docker compose -f docker/docker-compose.yml --profile launcher up
+# O container imprime "First-run setup complete." e para.
 
 # 3. Configure suas API keys
-vim docker/data/config.json   # Chaves de API do provedor, tokens de bot, etc.
+vim docker/data/config.json
 
 # 4. Iniciar
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+# Abra http://localhost:18800
 ```
 
-> [!TIP]
-> **Usuários Docker**: Por padrão, o Gateway ouve em `127.0.0.1`, o que não é acessível a partir do host. Se você precisar acessar os endpoints de integridade ou expor portas, defina `PICOCLAW_GATEWAY_HOST=0.0.0.0` em seu ambiente ou atualize o `config.json`.
+> **Usuários de Docker / VM:** O Gateway escuta em `127.0.0.1` por padrão. Defina `PICOCLAW_GATEWAY_HOST=0.0.0.0` ou use a flag `-public` para torná-lo acessível pelo host.
 
 ```bash
-# 5. Ver logs
-docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+# Verificar logs
+docker compose -f docker/docker-compose.yml logs -f
 
-# 6. Parar
-docker compose -f docker/docker-compose.yml --profile gateway down
-```
+# Parar
+docker compose -f docker/docker-compose.yml --profile launcher down
 
-### Modo Agente (Execução única)
-
-```bash
-# Fazer uma pergunta
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "Quanto e 2+2?"
-
-# Modo interativo
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
-```
-
-### Atualizar
-
-```bash
+# Atualizar
 docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile launcher up -d
 ```
 
-### 🚀 Início Rápido
+</details>
 
-> [!TIP]
-> Configure sua API key em `~/.picoclaw/config.json`.
-> Obtenha API keys: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)
-> Busca web e **opcional** — obtenha a [Brave Search API](https://brave.com/search/api) gratuita (2000 consultas grátis/mês) ou use o fallback automático integrado.
+### 💻 TUI Launcher (Recomendado para Headless / SSH)
+
+O TUI (Terminal UI) Launcher fornece uma interface de terminal completa para configuração e gerenciamento. Ideal para servidores, Raspberry Pi e outros ambientes headless.
+
+```bash
+picoclaw-launcher-tui
+```
+
+<p align="center">
+<img src="assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
+</p>
+
+**Primeiros passos:**
+
+Use os menus do TUI para: **1)** Configurar um Provider -> **2)** Configurar um Channel -> **3)** Iniciar o Gateway -> **4)** Conversar!
+
+Para documentação detalhada do TUI, veja [docs.picoclaw.io](https://docs.picoclaw.io).
+
+### 📱 Android
+
+Dê uma segunda vida ao seu celular de uma década! Transforme-o em um Assistente de IA inteligente com o PicoClaw.
+
+**Opção 1: Termux (disponível agora)**
+
+1. Instale o [Termux](https://github.com/termux/termux-app) (baixe nas [GitHub Releases](https://github.com/termux/termux-app/releases), ou pesquise no F-Droid / Google Play)
+2. Execute os seguintes comandos:
+
+```bash
+# Baixar a versão mais recente
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard   # chroot fornece um layout padrão de sistema de arquivos Linux
+```
+
+Em seguida, siga a seção Terminal Launcher abaixo para concluir a configuração.
+
+<img src="assets/termux.jpg" alt="PicoClaw on Termux" width="512">
+
+**Opção 2: Instalação via APK (em breve)**
+
+Um APK Android independente com WebUI integrado está em desenvolvimento. Fique ligado!
+
+<details>
+<summary><b>Terminal Launcher (para ambientes com recursos limitados)</b></summary>
+
+Para ambientes mínimos onde apenas o binário principal `picoclaw` está disponível (sem Launcher UI), você pode configurar tudo via linha de comando e um arquivo de configuração JSON.
 
 **1. Inicializar**
 
@@ -217,952 +308,271 @@ docker compose -f docker/docker-compose.yml --profile gateway up -d
 picoclaw onboard
 ```
 
+Isso cria `~/.picoclaw/config.json` e o diretório workspace.
+
 **2. Configurar** (`~/.picoclaw/config.json`)
 
 ```json
 {
+  "agents": {
+    "defaults": {
+      "model_name": "gpt-5.4"
+    }
+  },
   "model_list": [
     {
-      "model_name": "gpt4",
-      "model": "openai/gpt-5.2",
-      "api_key": "sk-your-openai-key",
-      "request_timeout": 300,
-      "api_base": "https://api.openai.com/v1"
-    }
-  ],
-  "agents": {
-    "defaults": {
-      "model_name": "gpt4"
-    }
-  },
-  "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "YOUR_BRAVE_API_KEY",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
-      }
-    }
-  }
-}
-```
-
-> **Novo**: O formato de configuração `model_list` permite adicionar provedores sem alterar código. Veja [Configuração de Modelo](#configuração-de-modelo-model_list) para detalhes.
-> `request_timeout` é opcional e usa segundos. Se omitido ou definido como `<= 0`, o PicoClaw usa o timeout padrão (120s).
-
-**3. Obter API Keys**
-
-* **Provedor de LLM**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
-* **Busca Web** (opcional): [Brave Search](https://brave.com/search/api) - Plano gratuito disponível (2000 consultas/mês)
-
-> **Nota**: Veja `config.example.json` para um modelo de configuração completo.
-
-**4. Conversar**
-
-```bash
-picoclaw agent -m "Quanto e 2+2?"
-```
-
-Pronto! Você tem um assistente de IA funcionando em 2 minutos.
-
----
-
-## 💬 Integração com Apps de Chat
-
-Converse com seu PicoClaw via Telegram, Discord, DingTalk, LINE ou WeCom.
-
-| Canal | Nível de Configuração |
-| --- | --- |
-| **Telegram** | Fácil (apenas um token) |
-| **Discord** | Fácil (bot token + intents) |
-| **QQ** | Fácil (AppID + AppSecret) |
-| **DingTalk** | Médio (credenciais do app) |
-| **LINE** | Médio (credenciais + webhook URL) |
-| **WeCom** | Médio (CorpID + configuração webhook) |
-
-<details>
-<summary><b>Telegram</b> (Recomendado)</summary>
-
-**1. Criar o bot**
-
-* Abra o Telegram, busque `@BotFather`
-* Envie `/newbot`, siga as instruções
-* Copie o token
-
-**2. Configurar**
-
-```json
-{
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "YOUR_BOT_TOKEN",
-      "allow_from": ["YOUR_USER_ID"]
-    }
-  }
-}
-```
-
-> Obtenha seu User ID pelo `@userinfobot` no Telegram.
-
-**3. Executar**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>Discord</b></summary>
-
-**1. Criar o bot**
-
-* Acesse <https://discord.com/developers/applications>
-* Crie um aplicativo → Bot → Add Bot
-* Copie o token do bot
-
-**2. Habilitar Intents**
-
-* Nas configurações do Bot, habilite **MESSAGE CONTENT INTENT**
-* (Opcional) Habilite **SERVER MEMBERS INTENT** se quiser usar lista de permissões baseada em dados dos membros
-
-**3. Obter seu User ID**
-
-* Configurações do Discord → Avançado → habilite **Modo Desenvolvedor**
-* Clique com botão direito no seu avatar → **Copiar ID do Usuário**
-
-**4. Configurar**
-
-```json
-{
-  "channels": {
-    "discord": {
-      "enabled": true,
-      "token": "YOUR_BOT_TOKEN",
-      "allow_from": ["YOUR_USER_ID"]
-    }
-  }
-}
-```
-
-**5. Convidar o bot**
-
-* OAuth2 → URL Generator
-* Scopes: `bot`
-* Bot Permissions: `Send Messages`, `Read Message History`
-* Abra a URL de convite gerada e adicione o bot ao seu servidor
-
-**6. Executar**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>QQ</b></summary>
-
-**1. Criar o bot**
-
-- Acesse a [QQ Open Platform](https://q.qq.com/#)
-- Crie um aplicativo → Obtenha **AppID** e **AppSecret**
-
-**2. Configurar**
-
-```json
-{
-  "channels": {
-    "qq": {
-      "enabled": true,
-      "app_id": "YOUR_APP_ID",
-      "app_secret": "YOUR_APP_SECRET",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> Deixe `allow_from` vazio para permitir todos os usuários, ou especifique números QQ para restringir o acesso.
-
-**3. Executar**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>DingTalk</b></summary>
-
-**1. Criar o bot**
-
-* Acesse a [Open Platform](https://open.dingtalk.com/)
-* Crie um app interno
-* Copie o Client ID e Client Secret
-
-**2. Configurar**
-
-```json
-{
-  "channels": {
-    "dingtalk": {
-      "enabled": true,
-      "client_id": "YOUR_CLIENT_ID",
-      "client_secret": "YOUR_CLIENT_SECRET",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> Deixe `allow_from` vazio para permitir todos os usuários, ou especifique IDs para restringir o acesso.
-
-**3. Executar**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>LINE</b></summary>
-
-**1. Criar uma Conta Oficial LINE**
-
-- Acesse o [LINE Developers Console](https://developers.line.biz/)
-- Crie um provider → Crie um canal Messaging API
-- Copie o **Channel Secret** e o **Channel Access Token**
-
-**2. Configurar**
-
-```json
-{
-  "channels": {
-    "line": {
-      "enabled": true,
-      "channel_secret": "YOUR_CHANNEL_SECRET",
-      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_path": "/webhook/line",
-      "allow_from": []
-    }
-  }
-}
-```
-
-**3. Configurar URL do Webhook**
-
-O LINE requer HTTPS para webhooks. Use um reverse proxy ou tunnel:
-
-```bash
-# Exemplo com ngrok
-ngrok http 18790
-```
-
-Em seguida, configure a Webhook URL no LINE Developers Console para `https://seu-dominio/webhook/line` e habilite **Use webhook**.
-
-> **Nota**: O webhook do LINE é servido pelo Gateway compartilhado (padrão 127.0.0.1:18790). Use um proxy reverso/HTTPS ou túnel (como ngrok) para expor o Gateway de forma segura quando necessário.
-
-**4. Executar**
-
-```bash
-picoclaw gateway
-```
-
-> Em chats de grupo, o bot responde apenas quando mencionado com @. As respostas citam a mensagem original.
-
-> **Docker Compose**: Se você usa Docker Compose, exponha o Gateway (padrão 127.0.0.1:18790) se precisar acessar o webhook LINE externamente, por exemplo `ports: ["18790:18790"]`.
-
-</details>
-
-<details>
-<summary><b>WeCom (WeChat Work)</b></summary>
-
-O PicoClaw suporta dois tipos de integração WeCom:
-
-**Opção 1: WeCom Bot (Robô Inteligente)** - Configuração mais fácil, suporta chats em grupo
-**Opção 2: WeCom App (Aplicativo Personalizado)** - Mais recursos, mensagens proativas
-
-Veja o [Guia de Configuração WeCom App](docs/wecom-app-configuration.md) para instruções detalhadas.
-
-**Configuração Rápida - WeCom Bot:**
-
-**1. Criar um bot**
-
-* Acesse o Console de Administração WeCom → Chat em Grupo → Adicionar Bot de Grupo
-* Copie a URL do webhook (formato: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
-
-**2. Configurar**
-
-```json
-{
-  "channels": {
-    "wecom": {
-      "enabled": true,
-      "token": "YOUR_TOKEN",
-      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_path": "/webhook/wecom",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> **Nota**: O webhook do WeCom Bot é atendido pelo Gateway compartilhado (padrão 127.0.0.1:18790). Use um proxy reverso/HTTPS ou túnel para expor o Gateway em produção.
-
-**Configuração Rápida - WeCom App:**
-
-**1. Criar um aplicativo**
-
-* Acesse o Console de Administração WeCom → Gerenciamento de Aplicativos → Criar Aplicativo
-* Copie o **AgentId** e o **Secret**
-* Acesse a página "Minha Empresa", copie o **CorpID**
-
-**2. Configurar recebimento de mensagens**
-
-* Nos detalhes do aplicativo, clique em "Receber Mensagens" → "Configurar API"
-* Defina a URL como `http://your-server:18790/webhook/wecom-app`
-* Gere o **Token** e o **EncodingAESKey**
-
-**3. Configurar**
-
-```json
-{
-  "channels": {
-    "wecom_app": {
-      "enabled": true,
-      "corp_id": "wwxxxxxxxxxxxxxxxx",
-      "corp_secret": "YOUR_CORP_SECRET",
-      "agent_id": 1000002,
-      "token": "YOUR_TOKEN",
-      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_path": "/webhook/wecom-app",
-      "allow_from": []
-    }
-  }
-}
-```
-
-**4. Executar**
-
-```bash
-picoclaw gateway
-```
-
-> **Nota**: O WeCom App (callbacks de webhook) é servido pelo Gateway compartilhado (padrão 127.0.0.1:18790). Em produção use um proxy reverso HTTPS para expor a porta do Gateway, ou atualize `PICOCLAW_GATEWAY_HOST` para `0.0.0.0` se necessário.
-
-</details>
-
-## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Junte-se a Rede Social de Agentes
-
-Conecte o PicoClaw a Rede Social de Agentes simplesmente enviando uma única mensagem via CLI ou qualquer App de Chat integrado.
-
-**Leia `https://clawdchat.ai/skill.md` e siga as instruções para entrar no [ClawdChat.ai](https://clawdchat.ai)**
-
-## ⚙️ Configuração Detalhada
-
-Arquivo de configuração: `~/.picoclaw/config.json`
-
-### Variáveis de Ambiente
-
-Você pode substituir os caminhos padrão usando variáveis de ambiente. Isso é útil para instalações portáteis, implantações em contêineres ou para executar o picoclaw como um serviço do sistema. Essas variáveis são independentes e controlam caminhos diferentes.
-
-| Variável          | Descrição                                                                                                                             | Caminho Padrão            |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
-| `PICOCLAW_CONFIG` | Substitui o caminho para o arquivo de configuração. Isso informa diretamente ao picoclaw qual `config.json` carregar, ignorando todos os outros locais. | `~/.picoclaw/config.json` |
-| `PICOCLAW_HOME`   | Substitui o diretório raiz dos dados do picoclaw. Isso altera o local padrão do `workspace` e de outros diretórios de dados.          | `~/.picoclaw`             |
-
-**Exemplos:**
-
-```bash
-# Executar o picoclaw usando um arquivo de configuração específico
-# O caminho do workspace será lido de dentro desse arquivo de configuração
-PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
-
-# Executar o picoclaw com todos os seus dados armazenados em /opt/picoclaw
-# A configuração será carregada do ~/.picoclaw/config.json padrão
-# O workspace será criado em /opt/picoclaw/workspace
-PICOCLAW_HOME=/opt/picoclaw picoclaw agent
-
-# Use ambos para uma configuração totalmente personalizada
-PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
-```
-
-### Estrutura do Workspace
-
-O PicoClaw armazena dados no workspace configurado (padrão: `~/.picoclaw/workspace`):
-
-```
-~/.picoclaw/workspace/
-├── sessions/          # Sessoes de conversa e historico
-├── memory/            # Memoria de longo prazo (MEMORY.md)
-├── state/             # Estado persistente (ultimo canal, etc.)
-├── cron/              # Banco de dados de tarefas agendadas
-├── skills/            # Skills personalizadas
-├── AGENTS.md          # Guia de comportamento do Agente
-├── HEARTBEAT.md       # Prompts de tarefas periodicas (verificado a cada 30 min)
-├── IDENTITY.md        # Identidade do Agente
-├── SOUL.md            # Alma do Agente
-├── TOOLS.md           # Descrição das ferramentas
-└── USER.md            # Preferencias do usuario
-```
-
-### 🔒 Sandbox de Segurança
-
-O PicoClaw roda em um ambiente sandbox por padrão. O agente so pode acessar arquivos e executar comandos dentro do workspace configurado.
-
-#### Configuração Padrão
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "restrict_to_workspace": true
-    }
-  }
-}
-```
-
-| Opção | Padrão | Descrição |
-|-------|--------|-----------|
-| `workspace` | `~/.picoclaw/workspace` | Diretório de trabalho do agente |
-| `restrict_to_workspace` | `true` | Restringir acesso de arquivos/comandos ao workspace |
-
-#### Ferramentas Protegidas
-
-Quando `restrict_to_workspace: true`, as seguintes ferramentas são restritas ao sandbox:
-
-| Ferramenta | Função | Restrição |
-|------------|--------|-----------|
-| `read_file` | Ler arquivos | Apenas arquivos dentro do workspace |
-| `write_file` | Escrever arquivos | Apenas arquivos dentro do workspace |
-| `list_dir` | Listar diretorios | Apenas diretorios dentro do workspace |
-| `edit_file` | Editar arquivos | Apenas arquivos dentro do workspace |
-| `append_file` | Adicionar a arquivos | Apenas arquivos dentro do workspace |
-| `exec` | Executar comandos | Caminhos dos comandos devem estar dentro do workspace |
-
-#### Proteção Adicional do Exec
-
-Mesmo com `restrict_to_workspace: false`, a ferramenta `exec` bloqueia estes comandos perigosos:
-
-* `rm -rf`, `del /f`, `rmdir /s` — Exclusão em massa
-* `format`, `mkfs`, `diskpart` — Formatação de disco
-* `dd if=` — Criação de imagem de disco
-* Escrita em `/dev/sd[a-z]` — Escrita direta no disco
-* `shutdown`, `reboot`, `poweroff` — Desligamento do sistema
-* Fork bomb `:(){ :|:& };:`
-
-#### Exemplos de Erro
-
-```
-[ERROR] tool: Tool execution failed
-{tool=exec, error=Command blocked by safety guard (path outside working dir)}
-```
-
-```
-[ERROR] tool: Tool execution failed
-{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
-```
-
-#### Desabilitar Restrições (Risco de Segurança)
-
-Se você precisa que o agente acesse caminhos fora do workspace:
-
-**Método 1: Arquivo de configuração**
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "restrict_to_workspace": false
-    }
-  }
-}
-```
-
-**Método 2: Variável de ambiente**
-
-```bash
-export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
-```
-
-> ⚠️ **Aviso**: Desabilitar esta restrição permite que o agente acesse qualquer caminho no seu sistema. Use com cuidado apenas em ambientes controlados.
-
-#### Consistência do Limite de Segurança
-
-A configuração `restrict_to_workspace` se aplica consistentemente em todos os caminhos de execução:
-
-| Caminho de Execução | Limite de Segurança |
-|----------------------|---------------------|
-| Agente Principal | `restrict_to_workspace` ✅ |
-| Subagente / Spawn | Herda a mesma restrição ✅ |
-| Tarefas Heartbeat | Herda a mesma restrição ✅ |
-
-Todos os caminhos compartilham a mesma restrição de workspace — nao há como contornar o limite de segurança por meio de subagentes ou tarefas agendadas.
-
-### Heartbeat (Tarefas Periódicas)
-
-O PicoClaw pode executar tarefas periódicas automaticamente. Crie um arquivo `HEARTBEAT.md` no seu workspace:
-
-```markdown
-# Tarefas Periodicas
-
-- Verificar meu email para mensagens importantes
-- Revisar minha agenda para proximos eventos
-- Verificar a previsao do tempo
-```
-
-O agente lerá este arquivo a cada 30 minutos (configurável) e executará as tarefas usando as ferramentas disponíveis.
-
-#### Tarefas Assincronas com Spawn
-
-Para tarefas de longa duração (busca web, chamadas de API), use a ferramenta `spawn` para criar um **subagente**:
-
-```markdown
-# Tarefas Periódicas
-
-## Tarefas Rápidas (resposta direta)
-- Informar hora atual
-
-## Tarefas Longas (usar spawn para async)
-- Buscar notícias de IA na web e resumir
-- Verificar email e reportar mensagens importantes
-```
-
-**Comportamentos principais:**
-
-| Funcionalidade | Descrição |
-|----------------|-----------|
-| **spawn** | Cria subagente assíncrono, não bloqueia o heartbeat |
-| **Contexto independente** | Subagente tem seu próprio contexto, sem histórico de sessão |
-| **Ferramenta message** | Subagente se comunica diretamente com o usuário via ferramenta message |
-| **Não-bloqueante** | Após o spawn, o heartbeat continua para a próxima tarefa |
-
-#### Como Funciona a Comunicação do Subagente
-
-```
-Heartbeat dispara
-    ↓
-Agente lê HEARTBEAT.md
-    ↓
-Para tarefa longa: spawn subagente
-    ↓                           ↓
-Continua próxima tarefa    Subagente trabalha independentemente
-    ↓                           ↓
-Todas tarefas concluídas   Subagente usa ferramenta "message"
-    ↓                           ↓
-Responde HEARTBEAT_OK      Usuário recebe resultado diretamente
-```
-
-O subagente tem acesso às ferramentas (message, web_search, etc.) e pode se comunicar com o usuário independentemente sem passar pelo agente principal.
-
-**Configuração:**
-
-```json
-{
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-| Opção | Padrão | Descrição |
-|-------|--------|-----------|
-| `enabled` | `true` | Habilitar/desabilitar heartbeat |
-| `interval` | `30` | Intervalo de verificação em minutos (min: 5) |
-
-**Variáveis de ambiente:**
-
-* `PICOCLAW_HEARTBEAT_ENABLED=false` para desabilitar
-* `PICOCLAW_HEARTBEAT_INTERVAL=60` para alterar o intervalo
-
-### Provedores
-
-> [!NOTE]
-> O Groq fornece transcrição de voz gratuita via Whisper. Se configurado, mensagens de voz do Telegram serão automaticamente transcritas.
-
-| Provedor | Finalidade | Obter API Key |
-| --- | --- | --- |
-| `gemini` | LLM (Gemini direto) | [aistudio.google.com](https://aistudio.google.com) |
-| `zhipu` | LLM (Zhipu direto) | [bigmodel.cn](bigmodel.cn) |
-| `openrouter` (Em teste) | LLM (recomendado, acesso a todos os modelos) | [openrouter.ai](https://openrouter.ai) |
-| `anthropic` (Em teste) | LLM (Claude direto) | [console.anthropic.com](https://console.anthropic.com) |
-| `openai` (Em teste) | LLM (GPT direto) | [platform.openai.com](https://platform.openai.com) |
-| `deepseek` (Em teste) | LLM (DeepSeek direto) | [platform.deepseek.com](https://platform.deepseek.com) |
-| `qwen` | Alibaba Qwen | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
-| `cerebras` | Cerebras | [cerebras.ai](https://cerebras.ai) |
-| `groq` | LLM + **Transcrição de voz** (Whisper) | [console.groq.com](https://console.groq.com) |
-
-<details>
-<summary><b>Configuração Zhipu</b></summary>
-
-**1. Obter API key**
-
-* Obtenha a [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
-
-**2. Configurar**
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "model": "glm-4.7",
-      "max_tokens": 8192,
-      "temperature": 0.7,
-      "max_tool_iterations": 20
-    }
-  },
-  "providers": {
-    "zhipu": {
-      "api_key": "Sua API Key",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  }
-}
-```
-
-**3. Executar**
-
-```bash
-picoclaw agent -m "Ola, como vai?"
-```
-
-</details>
-
-<details>
-<summary><b>Exemplo de configuraçao completa</b></summary>
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "model": "anthropic/claude-opus-4-5"
-    }
-  },
-  "providers": {
-    "openrouter": {
-      "api_key": "sk-or-v1-xxx"
-    },
-    "groq": {
-      "api_key": "gsk_xxx"
-    }
-  },
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "123456:ABC...",
-      "allow_from": ["123456789"]
-    },
-    "discord": {
-      "enabled": true,
-      "token": "",
-      "allow_from": [""]
-    },
-    "whatsapp": {
-      "enabled": false
-    },
-    "feishu": {
-      "enabled": false,
-      "app_id": "cli_xxx",
-      "app_secret": "xxx",
-      "encrypt_key": "",
-      "verification_token": "",
-      "allow_from": []
-    },
-    "qq": {
-      "enabled": false,
-      "app_id": "",
-      "app_secret": "",
-      "allow_from": []
-    }
-  },
-  "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "BSA...",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
-      }
-    },
-    "cron": {
-      "exec_timeout_minutes": 5
-    }
-  },
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-</details>
-
-### Configuração de Modelo (model_list)
-
-> **Novidade!** PicoClaw agora usa uma abordagem de configuração **centrada no modelo**. Basta especificar o formato `fornecedor/modelo` (ex: `zhipu/glm-4.7`) para adicionar novos provedores—**nenhuma alteração de código necessária!**
-
-Este design também possibilita o **suporte multi-agent** com seleção flexível de provedores:
-
-- **Diferentes agentes, diferentes provedores** : Cada agente pode usar seu próprio provedor LLM
-- **Modelos de fallback** : Configure modelos primários e de reserva para resiliência
-- **Balanceamento de carga** : Distribua solicitações entre múltiplos endpoints
-- **Configuração centralizada** : Gerencie todos os provedores em um só lugar
-
-#### 📋 Todos os Fornecedores Suportados
-
-| Fornecedor | Prefixo `model` | API Base Padrão | Protocolo | Chave API |
-|-------------|-----------------|------------------|----------|-----------|
-| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Obter Chave](https://platform.openai.com) |
-| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Obter Chave](https://console.anthropic.com) |
-| **Zhipu AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Obter Chave](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
-| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Obter Chave](https://platform.deepseek.com) |
-| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Obter Chave](https://aistudio.google.com/api-keys) |
-| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Obter Chave](https://console.groq.com) |
-| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Obter Chave](https://platform.moonshot.cn) |
-| **Qwen (Alibaba)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Obter Chave](https://dashscope.console.aliyun.com) |
-| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Obter Chave](https://build.nvidia.com) |
-| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (sem chave necessária) |
-| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Obter Chave](https://openrouter.ai/keys) |
-| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local |
-| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Obter Chave](https://cerebras.ai) |
-| **Volcengine** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Obter Chave](https://console.volcengine.com) |
-| **ShengsuanYun** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |
-| **Antigravity** | `antigravity/` | Google Cloud | Custom | Apenas OAuth |
-| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |
-
-#### Configuração Básica
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_key": "sk-your-openai-key"
-    },
-    {
-      "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
-      "api_key": "sk-ant-your-key"
-    },
-    {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-zhipu-key"
-    }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "gpt-5.2"
-    }
-  }
-}
-```
-
-#### Exemplos por Fornecedor
-
-**OpenAI**
-```json
-{
-  "model_name": "gpt-5.2",
-  "model": "openai/gpt-5.2",
-  "api_key": "sk-..."
-}
-```
-
-**Zhipu AI (GLM)**
-```json
-{
-  "model_name": "glm-4.7",
-  "model": "zhipu/glm-4.7",
-  "api_key": "your-key"
-}
-```
-
-**Anthropic (com OAuth)**
-```json
-{
-  "model_name": "claude-sonnet-4.6",
-  "model": "anthropic/claude-sonnet-4.6",
-  "auth_method": "oauth"
-}
-```
-> Execute `picoclaw auth login --provider anthropic` para configurar credenciais OAuth.
-
-**Proxy/API personalizada**
-```json
-{
-  "model_name": "my-custom-model",
-  "model": "openai/custom-model",
-  "api_base": "https://my-proxy.com/v1",
-  "api_key": "sk-...",
-  "request_timeout": 300
-}
-```
-
-#### Balanceamento de Carga
-
-Configure vários endpoints para o mesmo nome de modelo—PicoClaw fará round-robin automaticamente entre eles:
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_base": "https://api1.example.com/v1",
-      "api_key": "sk-key1"
-    },
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_base": "https://api2.example.com/v1",
-      "api_key": "sk-key2"
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-api-key"
     }
   ]
 }
 ```
 
-#### Migração da Configuração Legada `providers`
+> Veja `config/config.example.json` no repositório para um template de configuração completo com todas as opções disponíveis.
 
-A configuração antiga `providers` está **descontinuada** mas ainda é suportada para compatibilidade reversa.
+**3. Conversar**
 
-**Configuração Antiga (descontinuada):**
-```json
-{
-  "providers": {
-    "zhipu": {
-      "api_key": "your-key",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  },
-  "agents": {
-    "defaults": {
-      "provider": "zhipu",
-      "model": "glm-4.7"
-    }
-  }
-}
+```bash
+# Pergunta única
+picoclaw agent -m "What is 2+2?"
+
+# Modo interativo
+picoclaw agent
+
+# Iniciar gateway para integração com app de chat
+picoclaw gateway
 ```
 
-**Nova Configuração (recomendada):**
+</details>
+
+## 🔌 Providers (LLM)
+
+O PicoClaw suporta mais de 30 providers de LLM através da configuração `model_list`. Use o formato `protocolo/modelo`:
+
+| Provider | Protocolo | API Key | Notas |
+|----------|-----------|---------|-------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Obrigatória | GPT-5.4, GPT-4o, o3, etc. |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Obrigatória | Claude Opus 4.6, Sonnet 4.6, etc. |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Obrigatória | Gemini 3 Flash, 2.5 Pro, etc. |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Obrigatória | 200+ modelos, API unificada |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Obrigatória | GLM-4.7, GLM-5, etc. |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Obrigatória | DeepSeek-V3, DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | Obrigatória | Modelos Doubao, Ark |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Obrigatória | Qwen3, Qwen-Max, etc. |
+| [Groq](https://console.groq.com/keys) | `groq/` | Obrigatória | Inferência rápida (Llama, Mixtral) |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Obrigatória | Modelos Kimi |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Obrigatória | Modelos MiniMax |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Obrigatória | Mistral Large, Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Obrigatória | Modelos hospedados pela NVIDIA |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Obrigatória | Inferência rápida |
+| [Novita AI](https://novita.ai/) | `novita/` | Obrigatória | Vários modelos abertos |
+| [Ollama](https://ollama.com/) | `ollama/` | Não necessária | Modelos locais, self-hosted |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | Não necessária | Implantação local, compatível com OpenAI |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Varia | Proxy para 100+ providers |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Obrigatória | Implantação Azure Enterprise |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Login por código de dispositivo |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+<details>
+<summary><b>Implantação local (Ollama, vLLM, etc.)</b></summary>
+
+**Ollama:**
 ```json
 {
   "model_list": [
     {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-key"
+      "model_name": "local-llama",
+      "model": "ollama/llama3.1:8b",
+      "api_base": "http://localhost:11434/v1"
     }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "glm-4.7"
-    }
-  }
+  ]
 }
 ```
 
-Para o guia de migração detalhado, consulte [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md).
+**vLLM:**
+```json
+{
+  "model_list": [
+    {
+      "model_name": "local-vllm",
+      "model": "vllm/your-model",
+      "api_base": "http://localhost:8000/v1"
+    }
+  ]
+}
+```
 
-## Referência CLI
+Para detalhes completos de configuração de providers, veja [Providers & Models](docs/pt-br/providers.md).
 
-| Comando | Descrição |
-| --- | --- |
-| `picoclaw onboard` | Inicializar configuração & workspace |
-| `picoclaw agent -m "..."` | Conversar com o agente |
-| `picoclaw agent` | Modo de chat interativo |
-| `picoclaw gateway` | Iniciar o gateway (para bots de chat) |
-| `picoclaw status` | Mostrar status |
-| `picoclaw cron list` | Listar todas as tarefas agendadas |
-| `picoclaw cron add ...` | Adicionar uma tarefa agendada |
+</details>
 
-### Tarefas Agendadas / Lembretes
+## 💬 Channels (Apps de Chat)
 
-O PicoClaw suporta lembretes agendados e tarefas recorrentes por meio da ferramenta `cron`:
+Converse com seu PicoClaw por meio de mais de 17 plataformas de mensagens:
 
-* **Lembretes únicos**: "Remind me in 10 minutes" (Me lembre em 10 minutos) → dispara uma vez após 10min
-* **Tarefas recorrentes**: "Remind me every 2 hours" (Me lembre a cada 2 horas) → dispara a cada 2 horas
-* **Expressões Cron**: "Remind me at 9am daily" (Me lembre às 9h todos os dias) → usa expressão cron
+| Channel | Configuração | Protocolo | Docs |
+|---------|--------------|-----------|------|
+| **Telegram** | Fácil (bot token) | Long polling | [Guia](docs/channels/telegram/README.pt-br.md) |
+| **Discord** | Fácil (bot token + intents) | WebSocket | [Guia](docs/channels/discord/README.pt-br.md) |
+| **WhatsApp** | Fácil (QR scan ou bridge URL) | Nativo / Bridge | [Guia](docs/pt-br/chat-apps.md#whatsapp) |
+| **Weixin** | Fácil (scan QR nativo) | iLink API | [Guia](docs/pt-br/chat-apps.md#weixin) |
+| **QQ** | Fácil (AppID + AppSecret) | WebSocket | [Guia](docs/channels/qq/README.pt-br.md) |
+| **Slack** | Fácil (bot + app token) | Socket Mode | [Guia](docs/channels/slack/README.pt-br.md) |
+| **Matrix** | Médio (homeserver + token) | Sync API | [Guia](docs/channels/matrix/README.pt-br.md) |
+| **DingTalk** | Médio (credenciais do cliente) | Stream | [Guia](docs/channels/dingtalk/README.pt-br.md) |
+| **Feishu / Lark** | Médio (App ID + Secret) | WebSocket/SDK | [Guia](docs/channels/feishu/README.pt-br.md) |
+| **LINE** | Médio (credenciais + webhook) | Webhook | [Guia](docs/channels/line/README.pt-br.md) |
+| **WeCom Bot** | Médio (webhook URL) | Webhook | [Guia](docs/channels/wecom/wecom_bot/README.pt-br.md) |
+| **WeCom App** | Médio (credenciais corporativas) | Webhook | [Guia](docs/channels/wecom/wecom_app/README.pt-br.md) |
+| **WeCom AI Bot** | Médio (token + chave AES) | WebSocket / Webhook | [Guia](docs/channels/wecom/wecom_aibot/README.pt-br.md) |
+| **IRC** | Médio (servidor + nick) | Protocolo IRC | [Guia](docs/pt-br/chat-apps.md#irc) |
+| **OneBot** | Médio (WebSocket URL) | OneBot v11 | [Guia](docs/channels/onebot/README.pt-br.md) |
+| **MaixCam** | Fácil (habilitar) | TCP socket | [Guia](docs/channels/maixcam/README.pt-br.md) |
+| **Pico** | Fácil (habilitar) | Protocolo nativo | Integrado |
+| **Pico Client** | Fácil (WebSocket URL) | WebSocket | Integrado |
 
-As tarefas são armazenadas em `~/.picoclaw/workspace/cron/` e processadas automaticamente.
+> Todos os channels baseados em webhook compartilham um único servidor HTTP do Gateway (`gateway.host`:`gateway.port`, padrão `127.0.0.1:18790`). O Feishu usa modo WebSocket/SDK e não utiliza o servidor HTTP compartilhado.
 
-## 🤝 Contribuir & Roadmap
+Para instruções detalhadas de configuração de channels, veja [Configuração de Apps de Chat](docs/pt-br/chat-apps.md).
 
-PRs são bem-vindos! O código-fonte é intencionalmente pequeno e legível. 🤗
+## 🔧 Ferramentas
 
-Roadmap em breve...
+### 🔍 Busca na Web
 
-Grupo de desenvolvedores em formação. Requisito de entrada: Pelo menos 1 PR com merge.
+O PicoClaw pode pesquisar na web para fornecer informações atualizadas. Configure em `tools.web`:
 
-Grupos de usuários:
+| Motor de Busca | API Key | Nível Gratuito | Link |
+|----------------|---------|----------------|------|
+| DuckDuckGo | Não necessária | Ilimitado | Fallback integrado |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Obrigatória | 1000 consultas/dia | IA, otimizado para chinês |
+| [Tavily](https://tavily.com) | Obrigatória | 1000 consultas/mês | Otimizado para AI Agents |
+| [Brave Search](https://brave.com/search/api) | Obrigatória | 2000 consultas/mês | Rápido e privado |
+| [Perplexity](https://www.perplexity.ai) | Obrigatória | Pago | Busca com IA |
+| [SearXNG](https://github.com/searxng/searxng) | Não necessária | Self-hosted | Metabuscador gratuito |
+| [GLM Search](https://open.bigmodel.cn/) | Obrigatória | Varia | Busca web Zhipu |
 
-Discord: <https://discord.gg/V4sAZ9XWpN>
+### ⚙️ Outras Ferramentas
 
-<img src="assets/wechat.png" alt="PicoClaw" width="512">
+O PicoClaw inclui ferramentas integradas para operações de arquivo, execução de código, agendamento e mais. Veja [Configuração de Ferramentas](docs/pt-br/tools_configuration.md) para detalhes.
 
-## 🐛 Solução de Problemas
+## 🎯 Skills
 
-### Busca web mostra "API 配置问题"
+Skills são capacidades modulares que estendem seu Agent. Elas são carregadas a partir de arquivos `SKILL.md` no seu workspace.
 
-Isso é normal se você ainda não configurou uma API key de busca. O PicoClaw fornecerá links úteis para busca manual.
+**Instalar skills do ClawHub:**
 
-Para habilitar a busca web:
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install <skill-name>
+```
 
-1. **Opção 1 (Recomendado)**: Obtenha uma API key gratuita em [https://brave.com/search/api](https://brave.com/search/api) (2000 consultas grátis/mês) para os melhores resultados.
-2. **Opção 2 (Sem Cartão de Crédito)**: Se você não tem uma key, o sistema automaticamente usa o **DuckDuckGo** como fallback (sem necessidade de key).
-
-Adicione a key em `~/.picoclaw/config.json` se usar o Brave:
+**Configurar token do ClawHub** (opcional, para limites de taxa mais altos):
 
+Adicione ao seu `config.json`:
 ```json
 {
   "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "YOUR_BRAVE_API_KEY",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "auth_token": "your-clawhub-token"
+        }
       }
     }
   }
 }
 ```
 
-### Erros de filtragem de conteúdo
+Para mais detalhes, veja [Configuração de Ferramentas - Skills](docs/pt-br/tools_configuration.md#skills-tool).
 
-Alguns provedores (como Zhipu) possuem filtragem de conteúdo. Tente reformular sua pergunta ou use um modelo diferente.
+## 🔗 MCP (Model Context Protocol)
 
-### Bot do Telegram diz "Conflict: terminated by other getUpdates"
+O PicoClaw suporta nativamente o [MCP](https://modelcontextprotocol.io/) — conecte qualquer servidor MCP para estender as capacidades do seu Agent com ferramentas externas e fontes de dados.
 
-Isso acontece quando outra instância do bot está em execução. Certifique-se de que apenas um `picoclaw gateway` esteja rodando por vez.
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+        }
+      }
+    }
+  }
+}
+```
 
----
+Para configuração completa de MCP (transportes stdio, SSE, HTTP, Tool Discovery), veja [Configuração de Ferramentas - MCP](docs/pt-br/tools_configuration.md#mcp-tool).
 
-## 📝 Comparação de API Keys
+## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Junte-se à Rede Social de Agents
 
-| Serviço | Plano Gratuito | Caso de Uso |
-| --- | --- | --- |
-| **OpenRouter** | 200K tokens/mês | Múltiplos modelos (Claude, GPT-4, etc.) |
-| **Zhipu** | 200K tokens/mês | Melhor para usuários chineses |
-| **Brave Search** | 2000 consultas/mês | Funcionalidade de busca web |
-| **Groq** | Plano gratuito disponível | Inferência ultra-rápida (Llama, Mixtral) |
-| **Cerebras** | Plano gratuito disponível | Inferência ultra-rápida (Llama 3.3 70B) |
+Conecte o PicoClaw à Rede Social de Agents simplesmente enviando uma única mensagem via CLI ou qualquer App de Chat integrado.
+
+**Leia `https://clawdchat.ai/skill.md` e siga as instruções para entrar no [ClawdChat.ai](https://clawdchat.ai)**
+
+## 🖥️ Referência CLI
+
+| Comando                   | Descrição                              |
+| ------------------------- | -------------------------------------- |
+| `picoclaw onboard`        | Inicializar config e workspace         |
+| `picoclaw auth weixin` | Conectar conta WeChat via QR |
+| `picoclaw agent -m "..."` | Conversar com o agent                  |
+| `picoclaw agent`          | Modo de chat interativo                |
+| `picoclaw gateway`        | Iniciar o gateway                      |
+| `picoclaw status`         | Exibir status                          |
+| `picoclaw version`        | Exibir informações de versão           |
+| `picoclaw model`          | Ver ou trocar o modelo padrão          |
+| `picoclaw cron list`      | Listar todos os jobs agendados         |
+| `picoclaw cron add ...`   | Adicionar um job agendado              |
+| `picoclaw cron disable`   | Desabilitar um job agendado            |
+| `picoclaw cron remove`    | Remover um job agendado                |
+| `picoclaw skills list`    | Listar skills instaladas               |
+| `picoclaw skills install` | Instalar uma skill                     |
+| `picoclaw migrate`        | Migrar dados de versões anteriores     |
+| `picoclaw auth login`     | Autenticar com providers               |
+
+### ⏰ Tarefas Agendadas / Lembretes
+
+O PicoClaw suporta lembretes agendados e tarefas recorrentes através da ferramenta `cron`:
+
+* **Lembretes únicos**: "Lembre-me em 10 minutos" -> dispara uma vez após 10min
+* **Tarefas recorrentes**: "Lembre-me a cada 2 horas" -> dispara a cada 2 horas
+* **Expressões cron**: "Lembre-me às 9h diariamente" -> usa expressão cron
+
+## 📚 Documentação
+
+Para guias detalhados além deste README:
+
+| Tópico | Descrição |
+|--------|-----------|
+| [Docker & Início Rápido](docs/pt-br/docker.md) | Configuração do Docker Compose, modos Launcher/Agent |
+| [Apps de Chat](docs/pt-br/chat-apps.md) | Guias de configuração para todos os 17+ channels |
+| [Configuração](docs/pt-br/configuration.md) | Variáveis de ambiente, layout do workspace, sandbox de segurança |
+| [Providers & Models](docs/pt-br/providers.md) | 30+ providers de LLM, roteamento de modelos, configuração de model_list |
+| [Spawn & Tarefas Assíncronas](docs/pt-br/spawn-tasks.md) | Tarefas rápidas, tarefas longas com spawn, orquestração assíncrona de sub-agents |
+| [Hooks](docs/hooks/README.md) | Sistema de hooks orientado a eventos: observadores, interceptores, hooks de aprovação |
+| [Steering](docs/steering.md) | Injetar mensagens em um loop de agente em execução |
+| [SubTurn](docs/subturn.md) | Coordenação de subagentes, controle de concorrência, ciclo de vida |
+| [Solução de Problemas](docs/pt-br/troubleshooting.md) | Problemas comuns e soluções |
+| [Configuração de Ferramentas](docs/pt-br/tools_configuration.md) | Habilitar/desabilitar por ferramenta, políticas de exec, MCP, Skills |
+| [Compatibilidade de Hardware](docs/pt-br/hardware-compatibility.md) | Placas testadas, requisitos mínimos |
+
+## 🤝 Contribuir & Roadmap
+
+PRs são bem-vindos! O código-fonte é intencionalmente pequeno e legível.
+
+Veja nosso [Roadmap da Comunidade](https://github.com/sipeed/picoclaw/issues/988) e [CONTRIBUTING.md](CONTRIBUTING.md) para diretrizes.
+
+Grupo de desenvolvedores em formação, entre após seu primeiro PR mesclado!
+
+Grupos de Usuários:
+
+Discord: <https://discord.gg/V4sAZ9XWpN>
+
+WeChat:
+<img src="assets/wechat.png" alt="WeChat group QR code" width="512">
diff --git a/README.vi.md b/README.vi.md
index e836e30f0..ceeb02b63 100644
--- a/README.vi.md
+++ b/README.vi.md
@@ -1,27 +1,34 @@
 <div align="center">
-<img src="assets/logo.jpg" alt="PicoClaw" width="512">
+<img src="assets/logo.webp" alt="PicoClaw" width="512">
 
 <h1>PicoClaw: Trợ lý AI Siêu Nhẹ viết bằng Go</h1>
 
-<h3>Phần cứng $10 · RAM 10MB · Khởi động 1 giây · Nào, xuất phát!</h3>
-
+<h3>Phần cứng $10 · RAM 10MB · Khởi động ms · Let's Go, PicoClaw!</h3>
   <p>
-    <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
-    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20RISC--V-blue" alt="Hardware">
+    <img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
+    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V%2C%20LoongArch-blue" alt="Hardware">
     <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
     <br>
     <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
+    <a href="https://docs.picoclaw.io/"><img src="https://img.shields.io/badge/Docs-Official-007acc?style=flat&logo=read-the-docs&logoColor=white" alt="Docs"></a>
+    <a href="https://deepwiki.com/sipeed/picoclaw"><img src="https://img.shields.io/badge/Wiki-DeepWiki-FFA500?style=flat&logo=wikipedia&logoColor=white" alt="Wiki"></a>
+    <br>
     <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
+    <a href="./assets/wechat.png"><img src="https://img.shields.io/badge/WeChat-Group-41d56b?style=flat&logo=wechat&logoColor=white"></a>
+    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
   </p>
 
-[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md)
+
 </div>
 
 ---
 
-🦐 **PicoClaw** là trợ lý AI cá nhân siêu nhẹ, lấy cảm hứng từ [nanobot](https://github.com/HKUDS/nanobot), được viết lại hoàn toàn bằng **Go** thông qua quá trình "tự khởi tạo" (self-bootstrapping) — nơi chính AI Agent đã tự dẫn dắt toàn bộ quá trình chuyển đổi kiến trúc và tối ưu hóa mã nguồn.
+> **PicoClaw** là một dự án mã nguồn mở độc lập do [Sipeed](https://sipeed.com) khởi xướng, được viết hoàn toàn bằng **Go** từ đầu — không phải fork của OpenClaw, NanoBot hay bất kỳ dự án nào khác.
 
-⚡️ **Cực kỳ nhẹ:** Chạy trên phần cứng chỉ **$10** với RAM **<10MB**. Tiết kiệm 99% bộ nhớ so với OpenClaw và rẻ hơn 98% so với Mac mini!
+**PicoClaw** là trợ lý AI cá nhân siêu nhẹ lấy cảm hứng từ [NanoBot](https://github.com/HKUDS/nanobot). Nó được xây dựng lại từ đầu bằng **Go** thông qua quá trình "tự khởi động" — chính AI Agent đã dẫn dắt quá trình di chuyển kiến trúc và tối ưu hóa mã nguồn.
+
+**Chạy trên phần cứng $10 với <10MB RAM** — ít hơn 99% bộ nhớ so với OpenClaw và rẻ hơn 98% so với Mac mini!
 
 <table align="center">
 <tr align="center">
@@ -39,54 +46,83 @@
 </table>
 
 > [!CAUTION]
-> **🚨 TUYÊN BỐ BẢO MẬT & KÊNH CHÍNH THỨC**
+> **Thông báo Bảo mật**
 >
-> * **KHÔNG CÓ CRYPTO:** PicoClaw **KHÔNG** có bất kỳ token/coin chính thức nào. Mọi thông tin trên `pump.fun` hoặc các sàn giao dịch khác đều là **LỪA ĐẢO**.
-> * **DOMAIN CHÍNH THỨC:** Website chính thức **DUY NHẤT** là **[picoclaw.io](https://picoclaw.io)**, website công ty là **[sipeed.com](https://sipeed.com)**.
-> * **Cảnh báo:** Nhiều tên miền `.ai/.org/.com/.net/...` đã bị bên thứ ba đăng ký, không phải của chúng tôi.
-> * **Cảnh báo:** PicoClaw đang trong giai đoạn phát triển sớm và có thể còn các vấn đề bảo mật mạng chưa được giải quyết. Không nên triển khai lên môi trường production trước phiên bản v1.0.
-> * **Lưu ý:** PicoClaw gần đây đã merge nhiều PR, dẫn đến bộ nhớ sử dụng có thể lớn hơn (10–20MB) ở các phiên bản mới nhất. Chúng tôi sẽ ưu tiên tối ưu tài nguyên khi bộ tính năng đã ổn định.
-
+> * **KHÔNG CÓ CRYPTO:** PicoClaw **chưa** phát hành bất kỳ token hay tiền điện tử chính thức nào. Mọi thông tin trên `pump.fun` hoặc các nền tảng giao dịch khác đều là **lừa đảo**.
+> * **DOMAIN CHÍNH THỨC:** Website chính thức **DUY NHẤT** là **[picoclaw.io](https://picoclaw.io)**, và website công ty là **[sipeed.com](https://sipeed.com)**
+> * **CẢNH BÁO:** Nhiều domain `.ai/.org/.com/.net/...` đã bị bên thứ ba đăng ký. Đừng tin tưởng chúng.
+> * **LƯU Ý:** PicoClaw đang trong giai đoạn phát triển nhanh. Có thể còn các vấn đề bảo mật chưa được giải quyết. Không triển khai lên môi trường production trước v1.0.
+> * **LƯU Ý:** PicoClaw gần đây đã merge nhiều PR. Các bản build gần đây có thể dùng 10-20MB RAM. Tối ưu hóa tài nguyên được lên kế hoạch sau khi tính năng ổn định.
 
 ## 📢 Tin tức
 
-2026-02-16 🎉 PicoClaw đạt 12K stars chỉ trong một tuần! Cảm ơn tất cả mọi người! PicoClaw đang phát triển nhanh hơn chúng tôi tưởng tượng. Do số lượng PR tăng cao, chúng tôi cấp thiết cần maintainer từ cộng đồng. Các vai trò tình nguyện viên và roadmap đã được công bố [tại đây](docs/ROADMAP.md) — rất mong đón nhận sự tham gia của bạn!
+2026-03-17 🚀 **v0.2.3 đã phát hành!** Giao diện system tray (Windows & Linux), truy vấn trạng thái sub-agent (`spawn_status`), thử nghiệm Gateway hot-reload, bảo mật Cron, và 2 bản vá bảo mật. PicoClaw đã đạt **25K Stars**!
 
-2026-02-13 🎉 PicoClaw đạt 5000 stars trong 4 ngày! Cảm ơn cộng đồng! Chúng tôi đang hoàn thiện **Lộ trình dự án (Roadmap)** và thiết lập **Nhóm phát triển** để đẩy nhanh tốc độ phát triển PicoClaw.  
-🚀 **Kêu gọi hành động:** Vui lòng gửi yêu cầu tính năng tại GitHub Discussions. Chúng tôi sẽ xem xét và ưu tiên trong cuộc họp hàng tuần.
+2026-03-09 🎉 **v0.2.1 — Bản cập nhật lớn nhất từ trước đến nay!** Hỗ trợ giao thức MCP, 4 Channel mới (Matrix/IRC/WeCom/Discord Proxy), 3 Provider mới (Kimi/Minimax/Avian), pipeline thị giác, bộ nhớ JSONL, định tuyến mô hình.
 
-2026-02-09 🎉 PicoClaw chính thức ra mắt! Được xây dựng trong 1 ngày để mang AI Agent đến phần cứng $10 với RAM <10MB. 🦐 PicoClaw, Lên Đường!
+2026-02-28 📦 **v0.2.0** phát hành với hỗ trợ Docker Compose và Web UI Launcher.
 
-## ✨ Tính năng nổi bật
+2026-02-26 🎉 PicoClaw đạt **20K Stars** chỉ trong 17 ngày! Tự động điều phối Channel và giao diện khả năng đã hoạt động.
 
-🪶 **Siêu nhẹ**: Bộ nhớ sử dụng <10MB — nhỏ hơn 99% so với Clawdbot (chức năng cốt lõi).
+<details>
+<summary>Tin tức trước đó...</summary>
+
+2026-02-16 🎉 PicoClaw vượt 12K Stars trong một tuần! Vai trò người duy trì cộng đồng và [Lộ trình](ROADMAP.md) chính thức ra mắt.
+
+2026-02-13 🎉 PicoClaw vượt 5000 Stars trong 4 ngày! Lộ trình dự án và nhóm nhà phát triển đang được xây dựng.
+
+2026-02-09 🎉 **PicoClaw ra mắt!** Được xây dựng trong 1 ngày để đưa AI Agent lên phần cứng $10 với <10MB RAM. Let's Go, PicoClaw!
+
+</details>
+
+## ✨ Tính năng
+
+🪶 **Siêu nhẹ**: Bộ nhớ lõi <10MB — nhỏ hơn 99% so với OpenClaw.*
 
 💰 **Chi phí tối thiểu**: Đủ hiệu quả để chạy trên phần cứng $10 — rẻ hơn 98% so với Mac mini.
 
-⚡️ **Khởi động siêu nhanh**: Nhanh gấp 400 lần, khởi động trong 1 giây ngay cả trên CPU đơn nhân 0.6GHz.
+⚡️ **Khởi động cực nhanh**: Khởi động nhanh hơn 400 lần. Khởi động trong <1 giây ngay cả trên bộ xử lý đơn nhân 0.6GHz.
 
-🌍 **Di động thực sự**: Một file binary duy nhất chạy trên RISC-V, ARM và x86. Một click là chạy!
+🌍 **Thực sự di động**: Một binary duy nhất cho các kiến trúc RISC-V, ARM, MIPS và x86. Một binary, chạy mọi nơi!
 
-🤖 **AI tự xây dựng**: Triển khai Go-native tự động — 95% mã nguồn cốt lõi được Agent tạo ra, với sự tinh chỉnh của con người.
+🤖 **Được AI khởi động**: Triển khai Go thuần túy — 95% mã lõi được tạo bởi Agent và tinh chỉnh qua quy trình human-in-the-loop.
 
-|                               | OpenClaw      | NanoBot                  | **PicoClaw**                              |
-| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
-| **Ngôn ngữ**                  | TypeScript    | Python                   | **Go**                                    |
-| **RAM**                       | >1GB          | >100MB                   | **< 10MB**                                |
-| **Thời gian khởi động**</br>(CPU 0.8GHz) | >500s         | >30s                     | **<1s**                                   |
-| **Chi phí**                   | Mac Mini $599 | Hầu hết SBC Linux ~$50  | **Mọi bo mạch Linux**</br>**Chỉ từ $10** |
+🔌 **Hỗ trợ MCP**: Tích hợp [Model Context Protocol](https://modelcontextprotocol.io/) gốc — kết nối bất kỳ MCP server nào để mở rộng khả năng Agent.
+
+👁️ **Pipeline thị giác**: Gửi hình ảnh và tệp trực tiếp đến Agent — tự động mã hóa base64 cho LLM đa phương thức.
+
+🧠 **Định tuyến thông minh**: Định tuyến mô hình dựa trên quy tắc — các truy vấn đơn giản đến mô hình nhẹ, tiết kiệm chi phí API.
+
+_*Các bản build gần đây có thể dùng 10-20MB do merge PR nhanh. Tối ưu hóa tài nguyên đang được lên kế hoạch. So sánh tốc độ khởi động dựa trên benchmark lõi đơn 0.8GHz (xem bảng bên dưới)._
+
+<div align="center">
+
+|                                | OpenClaw      | NanoBot                  | **PicoClaw**                           |
+| ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
+| **Ngôn ngữ**                   | TypeScript    | Python                   | **Go**                                 |
+| **RAM**                        | >1GB          | >100MB                   | **< 10MB***                            |
+| **Thời gian khởi động**</br>(lõi 0.8GHz) | >500s         | >30s                     | **<1s**                                |
+| **Chi phí**                    | Mac Mini $599 | Hầu hết board Linux ~$50 | **Bất kỳ board Linux**</br>**từ $10**  |
 
 <img src="assets/compare.jpg" alt="PicoClaw" width="512">
 
-## 🦾 Demo
+</div>
 
-### 🛠️ Quy trình trợ lý tiêu chuẩn
+> **[Danh sách Tương thích Phần cứng](docs/vi/hardware-compatibility.md)** — Xem tất cả các board đã được kiểm tra, từ RISC-V $5 đến Raspberry Pi đến điện thoại Android. Board của bạn chưa có trong danh sách? Gửi PR!
+
+<p align="center">
+<img src="assets/hardware-banner.jpg" alt="PicoClaw Hardware Compatibility" width="100%">
+</p>
+
+## 🦾 Minh họa
+
+### 🛠️ Quy trình Trợ lý Tiêu chuẩn
 
 <table align="center">
 <tr align="center">
-<th><p align="center">🧩 Lập trình Full-Stack</p></th>
-<th><p align="center">🗂️ Quản lý Nhật ký & Kế hoạch</p></th>
-<th><p align="center">🔎 Tìm kiếm Web & Học hỏi</p></th>
+<th><p align="center">Chế độ Kỹ sư Full-Stack</p></th>
+<th><p align="center">Ghi nhật ký & Lập kế hoạch</p></th>
+<th><p align="center">Tìm kiếm Web & Học tập</p></th>
 </tr>
 <tr>
 <td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
@@ -94,31 +130,35 @@
 <td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
 </tr>
 <tr>
-<td align="center">Phát triển • Triển khai • Mở rộng</td>
-<td align="center">Lên lịch • Tự động hóa • Ghi nhớ</td>
-<td align="center">Khám phá • Phân tích • Xu hướng</td>
+<td align="center">Phát triển · Triển khai · Mở rộng</td>
+<td align="center">Lên lịch · Tự động hóa · Ghi nhớ</td>
+<td align="center">Khám phá · Thông tin · Xu hướng</td>
 </tr>
 </table>
 
-### 🐜 Triển khai sáng tạo trên phần cứng tối thiểu
+### 🐜 Triển khai Sáng tạo với Dấu chân Nhỏ
 
-PicoClaw có thể triển khai trên hầu hết mọi thiết bị Linux!
+PicoClaw có thể được triển khai trên hầu hết mọi thiết bị Linux!
 
-* $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) phiên bản E (Ethernet) hoặc W (WiFi6), dùng làm Trợ lý Gia đình tối giản.
-* $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), hoặc $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), dùng cho quản trị Server tự động.
-* $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) hoặc $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), dùng cho Giám sát thông minh.
+- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) phiên bản E(Ethernet) hoặc W(WiFi6), cho trợ lý gia đình tối giản
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), hoặc $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html), cho vận hành máy chủ tự động
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) hoặc $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera), cho giám sát thông minh
 
-https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4
+<https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4>
 
-🌟 Nhiều hình thức triển khai hơn đang chờ bạn khám phá!
+🌟 Còn nhiều trường hợp triển khai đang chờ đón!
 
 ## 📦 Cài đặt
 
-### Cài đặt bằng binary biên dịch sẵn
+### Tải xuống từ picoclaw.io (Khuyến nghị)
 
-Tải file binary cho nền tảng của bạn từ [trang Release](https://github.com/sipeed/picoclaw/releases).
+Truy cập **[picoclaw.io](https://picoclaw.io)** — website chính thức tự động phát hiện nền tảng của bạn và cung cấp tải xuống một cú nhấp. Không cần chọn kiến trúc thủ công.
 
-### Cài đặt từ mã nguồn (có tính năng mới nhất, khuyên dùng cho phát triển)
+### Tải xuống binary đã biên dịch sẵn
+
+Ngoài ra, tải binary cho nền tảng của bạn từ trang [GitHub Releases](https://github.com/sipeed/picoclaw/releases).
+
+### Xây dựng từ mã nguồn (để phát triển)
 
 ```bash
 git clone https://github.com/sipeed/picoclaw.git
@@ -126,70 +166,141 @@ git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 make deps
 
-# Build (không cần cài đặt)
+# Build core binary
 make build
 
-# Build cho nhiều nền tảng
+# Build Web UI Launcher (required for WebUI mode)
+make build-launcher
+
+# Build for multiple platforms
 make build-all
 
-# Build và cài đặt
+# Build for Raspberry Pi Zero 2 W (32-bit: make build-linux-arm; 64-bit: make build-linux-arm64)
+make build-pi-zero
+
+# Build and install
 make install
 ```
 
-## 🐳 Docker Compose
+**Raspberry Pi Zero 2 W:** Sử dụng binary phù hợp với hệ điều hành của bạn: Raspberry Pi OS 32-bit -> `make build-linux-arm`; 64-bit -> `make build-linux-arm64`. Hoặc chạy `make build-pi-zero` để xây dựng cả hai.
 
-Bạn cũng có thể chạy PicoClaw bằng Docker Compose mà không cần cài đặt gì trên máy.
+## 🚀 Hướng dẫn Khởi động Nhanh
+
+### 🌐 WebUI Launcher (Khuyến nghị cho Desktop)
+
+WebUI Launcher cung cấp giao diện dựa trên trình duyệt để cấu hình và trò chuyện. Đây là cách dễ nhất để bắt đầu — không cần kiến thức dòng lệnh.
+
+**Tùy chọn 1: Nhấp đúp (Desktop)**
+
+Sau khi tải xuống từ [picoclaw.io](https://picoclaw.io), nhấp đúp vào `picoclaw-launcher` (hoặc `picoclaw-launcher.exe` trên Windows). Trình duyệt của bạn sẽ tự động mở tại `http://localhost:18800`.
+
+**Tùy chọn 2: Dòng lệnh**
 
 ```bash
-# 1. Clone repo
+picoclaw-launcher
+# Mở http://localhost:18800 trong trình duyệt của bạn
+```
+
+> [!TIP]
+> **Truy cập từ xa / Docker / VM:** Thêm cờ `-public` để lắng nghe trên tất cả giao diện:
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+<p align="center">
+<img src="assets/launcher-webui.jpg" alt="WebUI Launcher" width="600">
+</p>
+
+**Bắt đầu:**
+
+Mở WebUI, sau đó: **1)** Cấu hình Provider (thêm API key LLM của bạn) -> **2)** Cấu hình Channel (ví dụ: Telegram) -> **3)** Khởi động Gateway -> **4)** Trò chuyện!
+
+Để biết tài liệu WebUI chi tiết, xem [docs.picoclaw.io](https://docs.picoclaw.io).
+
+<details>
+<summary><b>Docker (thay thế)</b></summary>
+
+```bash
+# 1. Clone this repo
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. Lần chạy đầu tiên — tự tạo docker/data/config.json rồi dừng lại
-docker compose -f docker/docker-compose.yml --profile gateway up
-# Container hiển thị "First-run setup complete." rồi tự dừng.
+# 2. First run — auto-generates docker/data/config.json then exits
+#    (only triggers when both config.json and workspace/ are missing)
+docker compose -f docker/docker-compose.yml --profile launcher up
+# The container prints "First-run setup complete." and stops.
 
-# 3. Thiết lập API Key
-vim docker/data/config.json   # API key của provider, bot token, v.v.
+# 3. Set your API keys
+vim docker/data/config.json
 
-# 4. Khởi động
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+# 4. Start
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+# Open http://localhost:18800
 ```
 
-> [!TIP]
-> **Người dùng Docker**: Theo mặc định, Gateway lắng nghe trên `127.0.0.1`, không thể truy cập từ máy chủ. Nếu bạn cần truy cập các endpoint kiểm tra sức khỏe hoặc mở cổng, hãy đặt `PICOCLAW_GATEWAY_HOST=0.0.0.0` trong môi trường của bạn hoặc cập nhật `config.json`.
+> **Người dùng Docker / VM:** Gateway lắng nghe trên `127.0.0.1` theo mặc định. Đặt `PICOCLAW_GATEWAY_HOST=0.0.0.0` hoặc dùng cờ `-public` để có thể truy cập từ host.
 
 ```bash
-# 5. Xem logs
-docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+# Check logs
+docker compose -f docker/docker-compose.yml logs -f
 
-# 6. Dừng
-docker compose -f docker/docker-compose.yml --profile gateway down
-```
+# Stop
+docker compose -f docker/docker-compose.yml --profile launcher down
 
-### Chế độ Agent (chạy một lần)
-
-```bash
-# Đặt câu hỏi
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 bằng mấy?"
-
-# Chế độ tương tác
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
-```
-
-### Cập nhật
-
-```bash
+# Update
 docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile launcher up -d
 ```
 
-### 🚀 Bắt đầu nhanh
+</details>
 
-> [!TIP]
-> Thiết lập API key trong `~/.picoclaw/config.json`.
-> Lấy API key: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)
-> Tìm kiếm web là **tùy chọn** — lấy [Brave Search API](https://brave.com/search/api) miễn phí (2000 truy vấn/tháng) hoặc dùng tính năng auto fallback tích hợp sẵn.
+### 💻 TUI Launcher (Khuyến nghị cho Headless / SSH)
+
+TUI (Terminal UI) Launcher cung cấp giao diện terminal đầy đủ tính năng để cấu hình và quản lý. Lý tưởng cho máy chủ, Raspberry Pi và các môi trường headless khác.
+
+```bash
+picoclaw-launcher-tui
+```
+
+<p align="center">
+<img src="assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
+</p>
+
+**Bắt đầu:**
+
+Sử dụng menu TUI để: **1)** Cấu hình Provider -> **2)** Cấu hình Channel -> **3)** Khởi động Gateway -> **4)** Trò chuyện!
+
+Để biết tài liệu TUI chi tiết, xem [docs.picoclaw.io](https://docs.picoclaw.io).
+
+### 📱 Android
+
+Hãy cho chiếc điện thoại cũ của bạn một cuộc sống mới! Biến nó thành Trợ lý AI thông minh với PicoClaw.
+
+**Tùy chọn 1: Termux (có sẵn ngay)**
+
+1. Cài đặt [Termux](https://github.com/termux/termux-app) (tải từ [GitHub Releases](https://github.com/termux/termux-app/releases), hoặc tìm kiếm trong F-Droid / Google Play)
+2. Chạy các lệnh sau:
+
+```bash
+# Download the latest release
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard   # chroot provides a standard Linux filesystem layout
+```
+
+Sau đó làm theo phần Terminal Launcher bên dưới để hoàn tất cấu hình.
+
+<img src="assets/termux.jpg" alt="PicoClaw on Termux" width="512">
+
+**Tùy chọn 2: Cài đặt APK (sắp ra mắt)**
+
+Một APK Android độc lập với WebUI tích hợp đang được phát triển. Hãy đón chờ!
+
+<details>
+<summary><b>Terminal Launcher (cho môi trường hạn chế tài nguyên)</b></summary>
+
+Đối với các môi trường tối giản chỉ có binary lõi `picoclaw` (không có Launcher UI), bạn có thể cấu hình mọi thứ qua dòng lệnh và tệp cấu hình JSON.
 
 **1. Khởi tạo**
 
@@ -197,940 +308,271 @@ docker compose -f docker/docker-compose.yml --profile gateway up -d
 picoclaw onboard
 ```
 
+Lệnh này tạo `~/.picoclaw/config.json` và thư mục workspace.
+
 **2. Cấu hình** (`~/.picoclaw/config.json`)
 
 ```json
 {
+  "agents": {
+    "defaults": {
+      "model_name": "gpt-5.4"
+    }
+  },
   "model_list": [
     {
-      "model_name": "gpt4",
-      "model": "openai/gpt-5.2",
-      "api_key": "sk-your-openai-key",
-      "request_timeout": 300,
-      "api_base": "https://api.openai.com/v1"
-    }
-  ],
-  "agents": {
-    "defaults": {
-      "model_name": "gpt4"
-    }
-  },
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "YOUR_TELEGRAM_BOT_TOKEN",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> **Mới**: Định dạng cấu hình `model_list` cho phép thêm nhà cung cấp mà không cần thay đổi mã nguồn. Xem [Cấu hình Mô hình](#cấu-hình-mô-hình-model_list) để biết chi tiết.
-> `request_timeout` là tùy chọn và dùng đơn vị giây. Nếu bỏ qua hoặc đặt `<= 0`, PicoClaw sẽ dùng timeout mặc định (120s).
-
-**3. Lấy API Key**
-
-* **Nhà cung cấp LLM**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
-* **Tìm kiếm Web** (tùy chọn): [Brave Search](https://brave.com/search/api) — Có gói miễn phí (2000 truy vấn/tháng)
-
-> **Lưu ý**: Xem `config.example.json` để có mẫu cấu hình đầy đủ.
-
-**4. Trò chuyện**
-
-```bash
-picoclaw agent -m "Xin chào, bạn là ai?"
-```
-
-Vậy là xong! Bạn đã có một trợ lý AI hoạt động chỉ trong 2 phút.
-
----
-
-## 💬 Tích hợp ứng dụng Chat
-
-Trò chuyện với PicoClaw qua Telegram, Discord, DingTalk, LINE hoặc WeCom.
-
-| Kênh | Mức độ thiết lập |
-| --- | --- |
-| **Telegram** | Dễ (chỉ cần token) |
-| **Discord** | Dễ (bot token + intents) |
-| **QQ** | Dễ (AppID + AppSecret) |
-| **DingTalk** | Trung bình (app credentials) |
-| **LINE** | Trung bình (credentials + webhook URL) |
-| **WeCom** | Trung bình (CorpID + cấu hình webhook) |
-
-<details>
-<summary><b>Telegram</b> (Khuyên dùng)</summary>
-
-**1. Tạo bot**
-
-* Mở Telegram, tìm `@BotFather`
-* Gửi `/newbot`, làm theo hướng dẫn
-* Sao chép token
-
-**2. Cấu hình**
-
-```json
-{
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "YOUR_BOT_TOKEN",
-      "allow_from": ["YOUR_USER_ID"]
-    }
-  }
-}
-```
-
-> Lấy User ID từ `@userinfobot` trên Telegram.
-
-**3. Chạy**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>Discord</b></summary>
-
-**1. Tạo bot**
-
-* Truy cập <https://discord.com/developers/applications>
-* Create an application → Bot → Add Bot
-* Sao chép bot token
-
-**2. Bật Intents**
-
-* Trong phần Bot settings, bật **MESSAGE CONTENT INTENT**
-* (Tùy chọn) Bật **SERVER MEMBERS INTENT** nếu muốn dùng danh sách cho phép theo thông tin thành viên
-
-**3. Lấy User ID**
-
-* Discord Settings → Advanced → bật **Developer Mode**
-* Click chuột phải vào avatar → **Copy User ID**
-
-**4. Cấu hình**
-
-```json
-{
-  "channels": {
-    "discord": {
-      "enabled": true,
-      "token": "YOUR_BOT_TOKEN",
-      "allow_from": ["YOUR_USER_ID"]
-    }
-  }
-}
-```
-
-**5. Mời bot vào server**
-
-* OAuth2 → URL Generator
-* Scopes: `bot`
-* Bot Permissions: `Send Messages`, `Read Message History`
-* Mở URL mời được tạo và thêm bot vào server của bạn
-
-**6. Chạy**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>QQ</b></summary>
-
-**1. Tạo bot**
-
-* Truy cập [QQ Open Platform](https://q.qq.com/#)
-* Tạo ứng dụng → Lấy **AppID** và **AppSecret**
-
-**2. Cấu hình**
-
-```json
-{
-  "channels": {
-    "qq": {
-      "enabled": true,
-      "app_id": "YOUR_APP_ID",
-      "app_secret": "YOUR_APP_SECRET",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> Để `allow_from` trống để cho phép tất cả người dùng, hoặc chỉ định số QQ để giới hạn quyền truy cập.
-
-**3. Chạy**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>DingTalk</b></summary>
-
-**1. Tạo bot**
-
-* Truy cập [Open Platform](https://open.dingtalk.com/)
-* Tạo ứng dụng nội bộ
-* Sao chép Client ID và Client Secret
-
-**2. Cấu hình**
-
-```json
-{
-  "channels": {
-    "dingtalk": {
-      "enabled": true,
-      "client_id": "YOUR_CLIENT_ID",
-      "client_secret": "YOUR_CLIENT_SECRET",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> Để `allow_from` trống để cho phép tất cả người dùng, hoặc chỉ định ID để giới hạn quyền truy cập.
-
-**3. Chạy**
-
-```bash
-picoclaw gateway
-```
-
-</details>
-
-<details>
-<summary><b>LINE</b></summary>
-
-**1. Tạo tài khoản LINE Official**
-
-- Truy cập [LINE Developers Console](https://developers.line.biz/)
-- Tạo provider → Tạo Messaging API channel
-- Sao chép **Channel Secret** và **Channel Access Token**
-
-**2. Cấu hình**
-
-```json
-{
-  "channels": {
-    "line": {
-      "enabled": true,
-      "channel_secret": "YOUR_CHANNEL_SECRET",
-      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
-      "webhook_path": "/webhook/line",
-      "allow_from": []
-    }
-  }
-}
-```
-
-**3. Thiết lập Webhook URL**
-
-LINE yêu cầu HTTPS cho webhook. Sử dụng reverse proxy hoặc tunnel:
-
-```bash
-# Ví dụ với ngrok
-ngrok http 18790
-```
-
-Sau đó cài đặt Webhook URL trong LINE Developers Console thành `https://your-domain/webhook/line` và bật **Use webhook**.
-
-**4. Chạy**
-
-```bash
-picoclaw gateway
-```
-
-> Trong nhóm chat, bot chỉ phản hồi khi được @mention. Các câu trả lời sẽ trích dẫn tin nhắn gốc.
-
-> **Docker Compose**: Nếu bạn cần mở port webhook cục bộ, hãy thêm một rule chuyển tiếp từ port Gateway (mặc định 18790) tới host. Lưu ý: LINE webhook được phục vụ bởi Gateway HTTP chung (mặc định 127.0.0.1:18790).
-
-</details>
-
-<details>
-<summary><b>WeCom (WeChat Work)</b></summary>
-
-PicoClaw hỗ trợ hai loại tích hợp WeCom:
-
-**Tùy chọn 1: WeCom Bot (Robot Thông minh)** - Thiết lập dễ dàng hơn, hỗ trợ chat nhóm
-**Tùy chọn 2: WeCom App (Ứng dụng Tự xây dựng)** - Nhiều tính năng hơn, nhắn tin chủ động
-
-Xem [Hướng dẫn Cấu hình WeCom App](docs/wecom-app-configuration.md) để biết hướng dẫn chi tiết.
-
-**Thiết lập Nhanh - WeCom Bot:**
-
-**1. Tạo bot**
-
-* Truy cập Bảng điều khiển Quản trị WeCom → Chat Nhóm → Thêm Bot Nhóm
-* Sao chép URL webhook (định dạng: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
-
-**2. Cấu hình**
-
-```json
-{
-  "channels": {
-    "wecom": {
-      "enabled": true,
-      "token": "YOUR_TOKEN",
-      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_path": "/webhook/wecom",
-      "allow_from": []
-    }
-  }
-}
-```
-
-> **Lưu ý:** Các endpoint webhook của WeCom Bot được phục vụ bởi máy chủ Gateway HTTP dùng chung (mặc định 127.0.0.1:18790). Nếu bạn cần truy cập từ bên ngoài, hãy cấu hình reverse proxy hoặc mở cổng Gateway tương ứng.
-
-**Thiết lập Nhanh - WeCom App:**
-
-**1. Tạo ứng dụng**
-
-* Truy cập Bảng điều khiển Quản trị WeCom → Quản lý Ứng dụng → Tạo Ứng dụng
-* Sao chép **AgentId** và **Secret**
-* Truy cập trang "Công ty của tôi", sao chép **CorpID**
-
-**2. Cấu hình nhận tin nhắn**
-
-* Trong chi tiết ứng dụng, nhấp vào "Nhận Tin nhắn" → "Thiết lập API"
-* Đặt URL thành `http://your-server:18790/webhook/wecom-app`
-* Tạo **Token** và **EncodingAESKey**
-
-**3. Cấu hình**
-
-```json
-{
-  "channels": {
-    "wecom_app": {
-      "enabled": true,
-      "corp_id": "wwxxxxxxxxxxxxxxxx",
-      "corp_secret": "YOUR_CORP_SECRET",
-      "agent_id": 1000002,
-      "token": "YOUR_TOKEN",
-      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
-      "webhook_path": "/webhook/wecom-app",
-      "allow_from": []
-    }
-  }
-}
-```
-
-**4. Chạy**
-
-```bash
-picoclaw gateway
-```
-
-> **Lưu ý**: WeCom App callback webhook được phục vụ bởi Gateway HTTP chung (mặc định 127.0.0.1:18790). Sử dụng proxy ngược để cung cấp HTTPS trong môi trường production nếu cần.
-
-</details>
-
-## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Tham gia Mạng xã hội Agent
-
-Kết nối PicoClaw với Mạng xã hội Agent chỉ bằng cách gửi một tin nhắn qua CLI hoặc bất kỳ ứng dụng Chat nào đã tích hợp.
-
-**Đọc `https://clawdchat.ai/skill.md` và làm theo hướng dẫn để tham gia [ClawdChat.ai](https://clawdchat.ai)**
-
-## ⚙️ Cấu hình chi tiết
-
-File cấu hình: `~/.picoclaw/config.json`
-
-### Biến môi trường
-
-Bạn có thể ghi đè các đường dẫn mặc định bằng cách sử dụng các biến môi trường. Điều này hữu ích cho việc cài đặt di động, triển khai container hóa hoặc chạy picoclaw như một dịch vụ hệ thống. Các biến này độc lập và kiểm soát các đường dẫn khác nhau.
-
-| Biến              | Mô tả                                                                                                                             | Đường dẫn mặc định        |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
-| `PICOCLAW_CONFIG` | Ghi đè đường dẫn đến file cấu hình. Điều này trực tiếp yêu cầu picoclaw tải file `config.json` nào, bỏ qua tất cả các vị trí khác. | `~/.picoclaw/config.json` |
-| `PICOCLAW_HOME`   | Ghi đè thư mục gốc cho dữ liệu picoclaw. Điều này thay đổi vị trí mặc định của `workspace` và các thư mục dữ liệu khác.          | `~/.picoclaw`             |
-
-**Ví dụ:**
-
-```bash
-# Chạy picoclaw bằng một file cấu hình cụ thể
-# Đường dẫn workspace sẽ được đọc từ trong file cấu hình đó
-PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
-
-# Chạy picoclaw với tất cả dữ liệu được lưu trữ trong /opt/picoclaw
-# Cấu hình sẽ được tải từ ~/.picoclaw/config.json mặc định
-# Workspace sẽ được tạo tại /opt/picoclaw/workspace
-PICOCLAW_HOME=/opt/picoclaw picoclaw agent
-
-# Sử dụng cả hai để có thiết lập tùy chỉnh hoàn toàn
-PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
-```
-
-### Cấu trúc Workspace
-
-PicoClaw lưu trữ dữ liệu trong workspace đã cấu hình (mặc định: `~/.picoclaw/workspace`):
-
-```
-~/.picoclaw/workspace/
-├── sessions/          # Phiên hội thoại và lịch sử
-├── memory/           # Bộ nhớ dài hạn (MEMORY.md)
-├── state/            # Trạng thái lưu trữ (kênh cuối cùng, v.v.)
-├── cron/             # Cơ sở dữ liệu tác vụ định kỳ
-├── skills/           # Kỹ năng tùy chỉnh
-├── AGENTS.md         # Hướng dẫn hành vi Agent
-├── HEARTBEAT.md      # Prompt tác vụ định kỳ (kiểm tra mỗi 30 phút)
-├── IDENTITY.md       # Danh tính Agent
-├── SOUL.md           # Tâm hồn/Tính cách Agent
-├── TOOLS.md          # Mô tả công cụ
-└── USER.md           # Tùy chọn người dùng
-```
-
-### 🔒 Hộp cát bảo mật (Security Sandbox)
-
-PicoClaw chạy trong môi trường sandbox theo mặc định. Agent chỉ có thể truy cập file và thực thi lệnh trong phạm vi workspace.
-
-#### Cấu hình mặc định
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "restrict_to_workspace": true
-    }
-  }
-}
-```
-
-| Tùy chọn | Mặc định | Mô tả |
-|----------|---------|-------|
-| `workspace` | `~/.picoclaw/workspace` | Thư mục làm việc của agent |
-| `restrict_to_workspace` | `true` | Giới hạn truy cập file/lệnh trong workspace |
-
-#### Công cụ được bảo vệ
-
-Khi `restrict_to_workspace: true`, các công cụ sau bị giới hạn trong sandbox:
-
-| Công cụ | Chức năng | Giới hạn |
-|---------|----------|---------|
-| `read_file` | Đọc file | Chỉ file trong workspace |
-| `write_file` | Ghi file | Chỉ file trong workspace |
-| `list_dir` | Liệt kê thư mục | Chỉ thư mục trong workspace |
-| `edit_file` | Sửa file | Chỉ file trong workspace |
-| `append_file` | Thêm vào file | Chỉ file trong workspace |
-| `exec` | Thực thi lệnh | Đường dẫn lệnh phải trong workspace |
-
-#### Bảo vệ bổ sung cho Exec
-
-Ngay cả khi `restrict_to_workspace: false`, công cụ `exec` vẫn chặn các lệnh nguy hiểm sau:
-
-* `rm -rf`, `del /f`, `rmdir /s` — Xóa hàng loạt
-* `format`, `mkfs`, `diskpart` — Định dạng ổ đĩa
-* `dd if=` — Tạo ảnh đĩa
-* Ghi vào `/dev/sd[a-z]` — Ghi trực tiếp lên đĩa
-* `shutdown`, `reboot`, `poweroff` — Tắt/khởi động lại hệ thống
-* Fork bomb `:(){ :|:& };:`
-
-#### Ví dụ lỗi
-
-```
-[ERROR] tool: Tool execution failed
-{tool=exec, error=Command blocked by safety guard (path outside working dir)}
-```
-
-```
-[ERROR] tool: Tool execution failed
-{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
-```
-
-#### Tắt giới hạn (Rủi ro bảo mật)
-
-Nếu bạn cần agent truy cập đường dẫn ngoài workspace:
-
-**Cách 1: File cấu hình**
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "restrict_to_workspace": false
-    }
-  }
-}
-```
-
-**Cách 2: Biến môi trường**
-
-```bash
-export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
-```
-
-> ⚠️ **Cảnh báo**: Tắt giới hạn này cho phép agent truy cập mọi đường dẫn trên hệ thống. Chỉ sử dụng cẩn thận trong môi trường được kiểm soát.
-
-#### Tính nhất quán của ranh giới bảo mật
-
-Cài đặt `restrict_to_workspace` áp dụng nhất quán trên mọi đường thực thi:
-
-| Đường thực thi | Ranh giới bảo mật |
-|----------------|-------------------|
-| Agent chính | `restrict_to_workspace` ✅ |
-| Subagent / Spawn | Kế thừa cùng giới hạn ✅ |
-| Tác vụ Heartbeat | Kế thừa cùng giới hạn ✅ |
-
-Tất cả đường thực thi chia sẻ cùng giới hạn workspace — không có cách nào vượt qua ranh giới bảo mật thông qua subagent hoặc tác vụ định kỳ.
-
-### Heartbeat (Tác vụ định kỳ)
-
-PicoClaw có thể tự động thực hiện các tác vụ định kỳ. Tạo file `HEARTBEAT.md` trong workspace:
-
-```markdown
-# Tác vụ định kỳ
-
-- Kiểm tra email xem có tin nhắn quan trọng không
-- Xem lại lịch cho các sự kiện sắp tới
-- Kiểm tra dự báo thời tiết
-```
-
-Agent sẽ đọc file này mỗi 30 phút (có thể cấu hình) và thực hiện các tác vụ bằng công cụ có sẵn.
-
-#### Tác vụ bất đồng bộ với Spawn
-
-Đối với các tác vụ chạy lâu (tìm kiếm web, gọi API), sử dụng công cụ `spawn` để tạo **subagent**:
-
-```markdown
-# Tác vụ định kỳ
-
-## Tác vụ nhanh (trả lời trực tiếp)
-- Báo cáo thời gian hiện tại
-
-## Tác vụ lâu (dùng spawn cho async)
-- Tìm kiếm tin tức AI trên web và tóm tắt
-- Kiểm tra email và báo cáo tin nhắn quan trọng
-```
-
-**Hành vi chính:**
-
-| Tính năng | Mô tả |
-|-----------|-------|
-| **spawn** | Tạo subagent bất đồng bộ, không chặn heartbeat |
-| **Context độc lập** | Subagent có context riêng, không có lịch sử phiên |
-| **message tool** | Subagent giao tiếp trực tiếp với người dùng qua công cụ message |
-| **Không chặn** | Sau khi spawn, heartbeat tiếp tục tác vụ tiếp theo |
-
-#### Cách Subagent giao tiếp
-
-```
-Heartbeat kích hoạt
-    ↓
-Agent đọc HEARTBEAT.md
-    ↓
-Tác vụ lâu: spawn subagent
-    ↓                           ↓
-Tiếp tục tác vụ tiếp theo   Subagent làm việc độc lập
-    ↓                           ↓
-Tất cả tác vụ hoàn thành    Subagent dùng công cụ "message"
-    ↓                           ↓
-Phản hồi HEARTBEAT_OK       Người dùng nhận kết quả trực tiếp
-```
-
-Subagent có quyền truy cập các công cụ (message, web_search, v.v.) và có thể giao tiếp với người dùng một cách độc lập mà không cần thông qua agent chính.
-
-**Cấu hình:**
-
-```json
-{
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-| Tùy chọn | Mặc định | Mô tả |
-|----------|---------|-------|
-| `enabled` | `true` | Bật/tắt heartbeat |
-| `interval` | `30` | Khoảng thời gian kiểm tra (phút, tối thiểu: 5) |
-
-**Biến môi trường:**
-
-* `PICOCLAW_HEARTBEAT_ENABLED=false` để tắt
-* `PICOCLAW_HEARTBEAT_INTERVAL=60` để thay đổi khoảng thời gian
-
-### Nhà cung cấp (Providers)
-
-> [!NOTE]
-> Groq cung cấp dịch vụ chuyển giọng nói thành văn bản miễn phí qua Whisper. Nếu đã cấu hình Groq, tin nhắn thoại trên Telegram sẽ được tự động chuyển thành văn bản.
-
-| Nhà cung cấp | Mục đích | Lấy API Key |
-| --- | --- | --- |
-| `gemini` | LLM (Gemini trực tiếp) | [aistudio.google.com](https://aistudio.google.com) |
-| `zhipu` | LLM (Zhipu trực tiếp) | [bigmodel.cn](bigmodel.cn) |
-| `openrouter` (Đang thử nghiệm) | LLM (khuyên dùng, truy cập mọi model) | [openrouter.ai](https://openrouter.ai) |
-| `anthropic` (Đang thử nghiệm) | LLM (Claude trực tiếp) | [console.anthropic.com](https://console.anthropic.com) |
-| `openai` (Đang thử nghiệm) | LLM (GPT trực tiếp) | [platform.openai.com](https://platform.openai.com) |
-| `deepseek` (Đang thử nghiệm) | LLM (DeepSeek trực tiếp) | [platform.deepseek.com](https://platform.deepseek.com) |
-| `groq` | LLM + **Chuyển giọng nói** (Whisper) | [console.groq.com](https://console.groq.com) |
-| `qwen` | LLM (Qwen trực tiếp) | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
-| `cerebras` | LLM (Cerebras trực tiếp) | [cerebras.ai](https://cerebras.ai) |
-
-<details>
-<summary><b>Cấu hình Zhipu</b></summary>
-
-**1. Lấy API key**
-
-* Lấy [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
-
-**2. Cấu hình**
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "model": "glm-4.7",
-      "max_tokens": 8192,
-      "temperature": 0.7,
-      "max_tool_iterations": 20
-    }
-  },
-  "providers": {
-    "zhipu": {
-      "api_key": "Your API Key",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  }
-}
-```
-
-**3. Chạy**
-
-```bash
-picoclaw agent -m "Xin chào"
-```
-
-</details>
-
-<details>
-<summary><b>Ví dụ cấu hình đầy đủ</b></summary>
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "model": "anthropic/claude-opus-4-5"
-    }
-  },
-  "providers": {
-    "openrouter": {
-      "api_key": "sk-or-v1-xxx"
-    },
-    "groq": {
-      "api_key": "gsk_xxx"
-    }
-  },
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "123456:ABC...",
-      "allow_from": ["123456789"]
-    },
-    "discord": {
-      "enabled": true,
-      "token": "",
-      "allow_from": [""]
-    },
-    "whatsapp": {
-      "enabled": false
-    },
-    "feishu": {
-      "enabled": false,
-      "app_id": "cli_xxx",
-      "app_secret": "xxx",
-      "encrypt_key": "",
-      "verification_token": "",
-      "allow_from": []
-    },
-    "qq": {
-      "enabled": false,
-      "app_id": "",
-      "app_secret": "",
-      "allow_from": []
-    }
-  },
-  "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "BSA...",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
-      }
-    }
-  },
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-</details>
-
-### Cấu hình Mô hình (model_list)
-
-> **Tính năng mới!** PicoClaw hiện sử dụng phương pháp cấu hình **đặt mô hình vào trung tâm**. Chỉ cần chỉ định dạng `nhà cung cấp/mô hình` (ví dụ: `zhipu/glm-4.7`) để thêm nhà cung cấp mới—**không cần thay đổi mã!**
-
-Thiết kế này cũng cho phép **hỗ trợ đa tác nhân** với lựa chọn nhà cung cấp linh hoạt:
-
-- **Tác nhân khác nhau, nhà cung cấp khác nhau** : Mỗi tác nhân có thể sử dụng nhà cung cấp LLM riêng
-- **Mô hình dự phòng** : Cấu hình mô hình chính và dự phòng để tăng độ tin cậy
-- **Cân bằng tải** : Phân phối yêu cầu trên nhiều endpoint khác nhau
-- **Cấu hình tập trung** : Quản lý tất cả nhà cung cấp ở một nơi
-
-#### 📋 Tất cả Nhà cung cấp được Hỗ trợ
-
-| Nhà cung cấp | Prefix `model` | API Base Mặc định | Giao thức | Khóa API |
-|-------------|----------------|-------------------|-----------|----------|
-| **OpenAI** | `openai/` | `https://api.openai.com/v1` | OpenAI | [Lấy Khóa](https://platform.openai.com) |
-| **Anthropic** | `anthropic/` | `https://api.anthropic.com/v1` | Anthropic | [Lấy Khóa](https://console.anthropic.com) |
-| **Zhipu AI (GLM)** | `zhipu/` | `https://open.bigmodel.cn/api/paas/v4` | OpenAI | [Lấy Khóa](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
-| **DeepSeek** | `deepseek/` | `https://api.deepseek.com/v1` | OpenAI | [Lấy Khóa](https://platform.deepseek.com) |
-| **Google Gemini** | `gemini/` | `https://generativelanguage.googleapis.com/v1beta` | OpenAI | [Lấy Khóa](https://aistudio.google.com/api-keys) |
-| **Groq** | `groq/` | `https://api.groq.com/openai/v1` | OpenAI | [Lấy Khóa](https://console.groq.com) |
-| **Moonshot** | `moonshot/` | `https://api.moonshot.cn/v1` | OpenAI | [Lấy Khóa](https://platform.moonshot.cn) |
-| **Qwen (Alibaba)** | `qwen/` | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI | [Lấy Khóa](https://dashscope.console.aliyun.com) |
-| **NVIDIA** | `nvidia/` | `https://integrate.api.nvidia.com/v1` | OpenAI | [Lấy Khóa](https://build.nvidia.com) |
-| **Ollama** | `ollama/` | `http://localhost:11434/v1` | OpenAI | Local (không cần khóa) |
-| **OpenRouter** | `openrouter/` | `https://openrouter.ai/api/v1` | OpenAI | [Lấy Khóa](https://openrouter.ai/keys) |
-| **VLLM** | `vllm/` | `http://localhost:8000/v1` | OpenAI | Local |
-| **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Lấy Khóa](https://cerebras.ai) |
-| **Volcengine** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Lấy Khóa](https://console.volcengine.com) |
-| **ShengsuanYun** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |
-| **Antigravity** | `antigravity/` | Google Cloud | Tùy chỉnh | Chỉ OAuth |
-| **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |
-
-#### Cấu hình Cơ bản
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_key": "sk-your-openai-key"
-    },
-    {
-      "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
-      "api_key": "sk-ant-your-key"
-    },
-    {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-zhipu-key"
-    }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "gpt-5.2"
-    }
-  }
-}
-```
-
-#### Ví dụ theo Nhà cung cấp
-
-**OpenAI**
-```json
-{
-  "model_name": "gpt-5.2",
-  "model": "openai/gpt-5.2",
-  "api_key": "sk-..."
-}
-```
-
-**Zhipu AI (GLM)**
-```json
-{
-  "model_name": "glm-4.7",
-  "model": "zhipu/glm-4.7",
-  "api_key": "your-key"
-}
-```
-
-**Anthropic (với OAuth)**
-```json
-{
-  "model_name": "claude-sonnet-4.6",
-  "model": "anthropic/claude-sonnet-4.6",
-  "auth_method": "oauth"
-}
-```
-> Chạy `picoclaw auth login --provider anthropic` để thiết lập thông tin xác thực OAuth.
-
-**Proxy/API tùy chỉnh**
-```json
-{
-  "model_name": "my-custom-model",
-  "model": "openai/custom-model",
-  "api_base": "https://my-proxy.com/v1",
-  "api_key": "sk-...",
-  "request_timeout": 300
-}
-```
-
-#### Cân bằng Tải tải
-
-Định cấu hình nhiều endpoint cho cùng một tên mô hình—PicoClaw sẽ tự động phân phối round-robin giữa chúng:
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_base": "https://api1.example.com/v1",
-      "api_key": "sk-key1"
-    },
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_base": "https://api2.example.com/v1",
-      "api_key": "sk-key2"
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-api-key"
     }
   ]
 }
 ```
 
-#### Chuyển đổi từ Cấu hình `providers` Cũ
+> Xem `config/config.example.json` trong repo để có mẫu cấu hình đầy đủ với tất cả các tùy chọn có sẵn.
 
-Cấu hình `providers` cũ đã **ngừng sử dụng** nhưng vẫn được hỗ trợ để tương thích ngược.
+**3. Trò chuyện**
 
-**Cấu hình Cũ (đã ngừng sử dụng):**
-```json
-{
-  "providers": {
-    "zhipu": {
-      "api_key": "your-key",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  },
-  "agents": {
-    "defaults": {
-      "provider": "zhipu",
-      "model": "glm-4.7"
-    }
-  }
-}
+```bash
+# One-shot question
+picoclaw agent -m "What is 2+2?"
+
+# Interactive mode
+picoclaw agent
+
+# Start gateway for chat app integration
+picoclaw gateway
 ```
 
-**Cấu hình Mới (khuyến nghị):**
+</details>
+
+## 🔌 Providers (LLM)
+
+PicoClaw hỗ trợ 30+ Provider LLM thông qua cấu hình `model_list`. Sử dụng định dạng `protocol/model`:
+
+| Provider | Protocol | API Key | Ghi chú |
+|----------|----------|---------|---------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | Bắt buộc | GPT-5.4, GPT-4o, o3, v.v. |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | Bắt buộc | Claude Opus 4.6, Sonnet 4.6, v.v. |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | Bắt buộc | Gemini 3 Flash, 2.5 Pro, v.v. |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | Bắt buộc | 200+ mô hình, API thống nhất |
+| [Zhipu (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | Bắt buộc | GLM-4.7, GLM-5, v.v. |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | Bắt buộc | DeepSeek-V3, DeepSeek-R1 |
+| [Volcengine](https://console.volcengine.com) | `volcengine/` | Bắt buộc | Doubao, Ark models |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | Bắt buộc | Qwen3, Qwen-Max, v.v. |
+| [Groq](https://console.groq.com/keys) | `groq/` | Bắt buộc | Suy luận nhanh (Llama, Mixtral) |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | Bắt buộc | Kimi models |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | Bắt buộc | MiniMax models |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | Bắt buộc | Mistral Large, Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | Bắt buộc | Mô hình do NVIDIA lưu trữ |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | Bắt buộc | Suy luận nhanh |
+| [Novita AI](https://novita.ai/) | `novita/` | Bắt buộc | Nhiều mô hình mở |
+| [Ollama](https://ollama.com/) | `ollama/` | Không cần | Mô hình cục bộ, tự lưu trữ |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | Không cần | Triển khai cục bộ, tương thích OpenAI |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | Tùy | Proxy cho 100+ provider |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | Bắt buộc | Triển khai Azure doanh nghiệp |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | Đăng nhập bằng device code |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+<details>
+<summary><b>Triển khai cục bộ (Ollama, vLLM, v.v.)</b></summary>
+
+**Ollama:**
 ```json
 {
   "model_list": [
     {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-key"
+      "model_name": "local-llama",
+      "model": "ollama/llama3.1:8b",
+      "api_base": "http://localhost:11434/v1"
     }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "glm-4.7"
-    }
-  }
+  ]
 }
 ```
 
-Xem hướng dẫn chuyển đổi chi tiết tại [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md).
+**vLLM:**
+```json
+{
+  "model_list": [
+    {
+      "model_name": "local-vllm",
+      "model": "vllm/your-model",
+      "api_base": "http://localhost:8000/v1"
+    }
+  ]
+}
+```
 
-## Tham chiếu CLI
+Để biết chi tiết cấu hình provider đầy đủ, xem [Providers & Models](docs/vi/providers.md).
 
-| Lệnh | Mô tả |
-| --- | --- |
-| `picoclaw onboard` | Khởi tạo cấu hình & workspace |
-| `picoclaw agent -m "..."` | Trò chuyện với agent |
-| `picoclaw agent` | Chế độ chat tương tác |
-| `picoclaw gateway` | Khởi động gateway (cho bot chat) |
-| `picoclaw status` | Hiển thị trạng thái |
-| `picoclaw cron list` | Liệt kê tất cả tác vụ định kỳ |
-| `picoclaw cron add ...` | Thêm tác vụ định kỳ |
+</details>
 
-### Tác vụ định kỳ / Nhắc nhở
+## 💬 Channels (Ứng dụng Chat)
 
-PicoClaw hỗ trợ nhắc nhở theo lịch và tác vụ lặp lại thông qua công cụ `cron`:
+Trò chuyện với PicoClaw của bạn qua 17+ nền tảng nhắn tin:
 
-* **Nhắc nhở một lần**: "Remind me in 10 minutes" (Nhắc tôi sau 10 phút) → kích hoạt một lần sau 10 phút
-* **Tác vụ lặp lại**: "Remind me every 2 hours" (Nhắc tôi mỗi 2 giờ) → kích hoạt mỗi 2 giờ
-* **Biểu thức Cron**: "Remind me at 9am daily" (Nhắc tôi lúc 9 giờ sáng mỗi ngày) → sử dụng biểu thức cron
+| Channel | Thiết lập | Protocol | Tài liệu |
+|---------|-----------|----------|----------|
+| **Telegram** | Dễ (bot token) | Long polling | [Hướng dẫn](docs/channels/telegram/README.vi.md) |
+| **Discord** | Dễ (bot token + intents) | WebSocket | [Hướng dẫn](docs/channels/discord/README.vi.md) |
+| **WhatsApp** | Dễ (quét QR hoặc bridge URL) | Native / Bridge | [Hướng dẫn](docs/vi/chat-apps.md#whatsapp) |
+| **Weixin** | Dễ (quét QR gốc) | iLink API | [Hướng dẫn](docs/vi/chat-apps.md#weixin) |
+| **QQ** | Dễ (AppID + AppSecret) | WebSocket | [Hướng dẫn](docs/channels/qq/README.vi.md) |
+| **Slack** | Dễ (bot + app token) | Socket Mode | [Hướng dẫn](docs/channels/slack/README.vi.md) |
+| **Matrix** | Trung bình (homeserver + token) | Sync API | [Hướng dẫn](docs/channels/matrix/README.vi.md) |
+| **DingTalk** | Trung bình (client credentials) | Stream | [Hướng dẫn](docs/channels/dingtalk/README.vi.md) |
+| **Feishu / Lark** | Trung bình (App ID + Secret) | WebSocket/SDK | [Hướng dẫn](docs/channels/feishu/README.vi.md) |
+| **LINE** | Trung bình (credentials + webhook) | Webhook | [Hướng dẫn](docs/channels/line/README.vi.md) |
+| **WeCom Bot** | Trung bình (webhook URL) | Webhook | [Hướng dẫn](docs/channels/wecom/wecom_bot/README.vi.md) |
+| **WeCom App** | Trung bình (corp credentials) | Webhook | [Hướng dẫn](docs/channels/wecom/wecom_app/README.vi.md) |
+| **WeCom AI Bot** | Trung bình (token + AES key) | WebSocket / Webhook | [Hướng dẫn](docs/channels/wecom/wecom_aibot/README.vi.md) |
+| **IRC** | Trung bình (server + nick) | IRC protocol | [Hướng dẫn](docs/vi/chat-apps.md#irc) |
+| **OneBot** | Trung bình (WebSocket URL) | OneBot v11 | [Hướng dẫn](docs/channels/onebot/README.vi.md) |
+| **MaixCam** | Dễ (bật) | TCP socket | [Hướng dẫn](docs/channels/maixcam/README.vi.md) |
+| **Pico** | Dễ (bật) | Native protocol | Tích hợp sẵn |
+| **Pico Client** | Dễ (WebSocket URL) | WebSocket | Tích hợp sẵn |
 
-Các tác vụ được lưu trong `~/.picoclaw/workspace/cron/` và được xử lý tự động.
+> Tất cả các Channel dựa trên webhook dùng chung một Gateway HTTP server (`gateway.host`:`gateway.port`, mặc định `127.0.0.1:18790`). Feishu sử dụng chế độ WebSocket/SDK và không dùng HTTP server chung.
 
-## 🤝 Đóng góp & Lộ trình
+Để biết hướng dẫn thiết lập Channel chi tiết, xem [Cấu hình Ứng dụng Chat](docs/vi/chat-apps.md).
 
-Chào đón mọi PR! Mã nguồn được thiết kế nhỏ gọn và dễ đọc. 🤗
+## 🔧 Tools
 
-Lộ trình sắp được công bố...
+### 🔍 Tìm kiếm Web
 
-Nhóm phát triển đang được xây dựng. Điều kiện tham gia: Ít nhất 1 PR đã được merge.
+PicoClaw có thể tìm kiếm web để cung cấp thông tin cập nhật. Cấu hình trong `tools.web`:
 
-Nhóm người dùng:
+| Công cụ Tìm kiếm | API Key | Gói miễn phí | Liên kết |
+|------------------|---------|--------------|----------|
+| DuckDuckGo | Không cần | Không giới hạn | Dự phòng tích hợp sẵn |
+| [Baidu Search](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | Bắt buộc | 1000 truy vấn/ngày | AI, tối ưu cho tiếng Trung |
+| [Tavily](https://tavily.com) | Bắt buộc | 1000 truy vấn/tháng | Tối ưu cho AI Agent |
+| [Brave Search](https://brave.com/search/api) | Bắt buộc | 2000 truy vấn/tháng | Nhanh và riêng tư |
+| [Perplexity](https://www.perplexity.ai) | Bắt buộc | Trả phí | Tìm kiếm hỗ trợ AI |
+| [SearXNG](https://github.com/searxng/searxng) | Không cần | Tự lưu trữ | Metasearch engine miễn phí |
+| [GLM Search](https://open.bigmodel.cn/) | Bắt buộc | Tùy | Tìm kiếm web Zhipu |
 
-Discord: <https://discord.gg/V4sAZ9XWpN>
+### ⚙️ Các Tools Khác
 
-<img src="assets/wechat.png" alt="PicoClaw" width="512">
+PicoClaw bao gồm các tool tích hợp sẵn cho thao tác tệp, thực thi mã, lên lịch và nhiều hơn nữa. Xem [Cấu hình Tools](docs/vi/tools_configuration.md) để biết chi tiết.
 
-## 🐛 Xử lý sự cố
+## 🎯 Skills
 
-### Tìm kiếm web hiện "API 配置问题"
+Skills là các khả năng mô-đun mở rộng Agent của bạn. Chúng được tải từ các tệp `SKILL.md` trong workspace của bạn.
 
-Điều này là bình thường nếu bạn chưa cấu hình API key cho tìm kiếm. PicoClaw sẽ cung cấp các liên kết hữu ích để tìm kiếm thủ công.
+**Cài đặt Skills từ ClawHub:**
 
-Để bật tìm kiếm web:
+```bash
+picoclaw skills search "web scraping"
+picoclaw skills install <skill-name>
+```
 
-1. **Tùy chọn 1 (Khuyên dùng)**: Lấy API key miễn phí tại [https://brave.com/search/api](https://brave.com/search/api) (2000 truy vấn miễn phí/tháng) để có kết quả tốt nhất.
-2. **Tùy chọn 2 (Không cần thẻ tín dụng)**: Nếu không có key, hệ thống tự động chuyển sang dùng **DuckDuckGo** (không cần key).
-
-Thêm key vào `~/.picoclaw/config.json` nếu dùng Brave:
+**Cấu hình token ClawHub** (tùy chọn, để có giới hạn tốc độ cao hơn):
 
+Thêm vào `config.json` của bạn:
 ```json
 {
   "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "YOUR_BRAVE_API_KEY",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "auth_token": "your-clawhub-token"
+        }
       }
     }
   }
 }
 ```
 
-### Gặp lỗi lọc nội dung (Content Filtering)
+Để biết thêm chi tiết, xem [Cấu hình Tools - Skills](docs/vi/tools_configuration.md#skills-tool).
 
-Một số nhà cung cấp (như Zhipu) có bộ lọc nội dung nghiêm ngặt. Thử diễn đạt lại câu hỏi hoặc sử dụng model khác.
+## 🔗 MCP (Model Context Protocol)
 
-### Telegram bot báo "Conflict: terminated by other getUpdates"
+PicoClaw hỗ trợ [MCP](https://modelcontextprotocol.io/) gốc — kết nối bất kỳ MCP server nào để mở rộng khả năng Agent của bạn với các tool và nguồn dữ liệu bên ngoài.
 
-Điều này xảy ra khi có một instance bot khác đang chạy. Đảm bảo chỉ có một tiến trình `picoclaw gateway` chạy tại một thời điểm.
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+        }
+      }
+    }
+  }
+}
+```
 
----
+Để biết cấu hình MCP đầy đủ (stdio, SSE, HTTP transports, Tool Discovery), xem [Cấu hình Tools - MCP](docs/vi/tools_configuration.md#mcp-tool).
 
-## 📝 So sánh API Key
+## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Tham gia Mạng xã hội Agent
 
-| Dịch vụ | Gói miễn phí | Trường hợp sử dụng |
-| --- | --- | --- |
-| **OpenRouter** | 200K tokens/tháng | Đa model (Claude, GPT-4, v.v.) |
-| **Zhipu** | 200K tokens/tháng | Tốt nhất cho người dùng Trung Quốc |
-| **Brave Search** | 2000 truy vấn/tháng | Chức năng tìm kiếm web |
-| **Groq** | Có gói miễn phí | Suy luận siêu nhanh (Llama, Mixtral) |
+Kết nối PicoClaw với Mạng xã hội Agent chỉ bằng cách gửi một tin nhắn duy nhất qua CLI hoặc bất kỳ Ứng dụng Chat nào đã tích hợp.
+
+**Đọc `https://clawdchat.ai/skill.md` và làm theo hướng dẫn để tham gia [ClawdChat.ai](https://clawdchat.ai)**
+
+## 🖥️ Tham chiếu CLI
+
+| Lệnh                      | Mô tả                                    |
+| ------------------------- | ---------------------------------------- |
+| `picoclaw onboard`        | Khởi tạo cấu hình & workspace           |
+| `picoclaw auth weixin` | Kết nối tài khoản WeChat qua QR |
+| `picoclaw agent -m "..."` | Trò chuyện với agent                     |
+| `picoclaw agent`          | Chế độ trò chuyện tương tác             |
+| `picoclaw gateway`        | Khởi động gateway                        |
+| `picoclaw status`         | Hiển thị trạng thái                      |
+| `picoclaw version`        | Hiển thị thông tin phiên bản            |
+| `picoclaw model`          | Xem hoặc chuyển đổi mô hình mặc định   |
+| `picoclaw cron list`      | Liệt kê tất cả công việc đã lên lịch   |
+| `picoclaw cron add ...`   | Thêm công việc đã lên lịch             |
+| `picoclaw cron disable`   | Vô hiệu hóa công việc đã lên lịch      |
+| `picoclaw cron remove`    | Xóa công việc đã lên lịch              |
+| `picoclaw skills list`    | Liệt kê các Skill đã cài đặt           |
+| `picoclaw skills install` | Cài đặt một Skill                       |
+| `picoclaw migrate`        | Di chuyển dữ liệu từ các phiên bản cũ  |
+| `picoclaw auth login`     | Xác thực với các provider               |
+
+### ⏰ Tác vụ Đã lên lịch / Nhắc nhở
+
+PicoClaw hỗ trợ nhắc nhở đã lên lịch và tác vụ định kỳ thông qua tool `cron`:
+
+* **Nhắc nhở một lần**: "Nhắc tôi sau 10 phút" -> kích hoạt một lần sau 10 phút
+* **Tác vụ định kỳ**: "Nhắc tôi mỗi 2 giờ" -> kích hoạt mỗi 2 giờ
+* **Biểu thức Cron**: "Nhắc tôi lúc 9 giờ sáng hàng ngày" -> sử dụng biểu thức cron
+
+## 📚 Tài liệu
+
+Để biết các hướng dẫn chi tiết ngoài README này:
+
+| Chủ đề | Mô tả |
+|--------|-------|
+| [Docker & Khởi động Nhanh](docs/vi/docker.md) | Thiết lập Docker Compose, chế độ Launcher/Agent |
+| [Ứng dụng Chat](docs/vi/chat-apps.md) | Hướng dẫn thiết lập 17+ Channel |
+| [Cấu hình](docs/vi/configuration.md) | Biến môi trường, bố cục workspace, sandbox bảo mật |
+| [Providers & Models](docs/vi/providers.md) | 30+ Provider LLM, định tuyến mô hình, cấu hình model_list |
+| [Spawn & Tác vụ Bất đồng bộ](docs/vi/spawn-tasks.md) | Tác vụ nhanh, tác vụ dài với spawn, điều phối sub-agent bất đồng bộ |
+| [Hooks](docs/hooks/README.md) | Hệ thống hook hướng sự kiện: observer, interceptor, approval hook |
+| [Steering](docs/steering.md) | Chèn tin nhắn vào vòng lặp agent đang chạy |
+| [SubTurn](docs/subturn.md) | Điều phối subagent, kiểm soát đồng thời, vòng đời |
+| [Khắc phục sự cố](docs/vi/troubleshooting.md) | Các vấn đề thường gặp và giải pháp |
+| [Cấu hình Tools](docs/vi/tools_configuration.md) | Bật/tắt từng tool, chính sách exec, MCP, Skills |
+| [Tương thích Phần cứng](docs/vi/hardware-compatibility.md) | Các board đã kiểm tra, yêu cầu tối thiểu |
+
+## 🤝 Đóng góp & Lộ trình
+
+PR luôn được chào đón! Codebase được thiết kế nhỏ gọn và dễ đọc.
+
+Xem [Lộ trình Cộng đồng](https://github.com/sipeed/picoclaw/issues/988) và [CONTRIBUTING.md](CONTRIBUTING.md) để biết hướng dẫn.
+
+Nhóm nhà phát triển đang được xây dựng, tham gia sau khi PR đầu tiên của bạn được merge!
+
+Nhóm Người dùng:
+
+Discord: <https://discord.gg/V4sAZ9XWpN>
+
+WeChat:
+<img src="assets/wechat.png" alt="WeChat group QR code" width="512">
diff --git a/README.zh.md b/README.zh.md
index 95984bbdf..93abf89d3 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -1,26 +1,32 @@
 <div align="center">
-<img src="assets/logo.jpg" alt="PicoClaw" width="512">
+<img src="assets/logo.webp" alt="PicoClaw" width="512">
 
 <h1>PicoClaw: 基于Go语言的超高效 AI 助手</h1>
 
-<h3>10$硬件 · 10MB内存 · 1秒启动 · 皮皮虾，我们走！</h3>
-
+<h3>$10 硬件 · 10MB 内存 · 毫秒启动 · 皮皮虾，我们走！</h3>
   <p>
-    <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
-    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20RISC--V-blue" alt="Hardware">
+    <img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
+    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20MIPS%2C%20RISC--V%2C%20LoongArch-blue" alt="Hardware">
     <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
     <br>
     <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
+    <a href="https://docs.picoclaw.io/"><img src="https://img.shields.io/badge/Docs-Official-007acc?style=flat&logo=read-the-docs&logoColor=white" alt="Docs"></a>
+    <a href="https://deepwiki.com/sipeed/picoclaw"><img src="https://img.shields.io/badge/Wiki-DeepWiki-FFA500?style=flat&logo=wikipedia&logoColor=white" alt="Wiki"></a>
+    <br>
     <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
+    <a href="./assets/wechat.png"><img src="https://img.shields.io/badge/WeChat-Group-41d56b?style=flat&logo=wechat&logoColor=white"></a>
+    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
   </p>
 
-**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [English](README.md)
+**中文** | [日本語](README.ja.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [English](README.md)
 
 </div>
 
 ---
 
-🦐 **PicoClaw** 是一个受 [nanobot](https://github.com/HKUDS/nanobot) 启发的超轻量级个人 AI 助手。它采用 **Go 语言** 从零重构，经历了一个“自举”过程——即由 AI Agent 自身驱动了整个架构迁移和代码优化。
+> **PicoClaw** 是由 [矽速科技 (Sipeed)](https://sipeed.com) 发起的独立开源项目，完全使用 **Go 语言**从零编写——不是 OpenClaw、NanoBot 或其他项目的分支。
+
+🦐 **PicoClaw** 是一个受 [NanoBot](https://github.com/HKUDS/nanobot) 启发的超轻量级个人 AI 助手。它采用 **Go 语言** 从零重构，经历了一个"自举"过程——即由 AI Agent 自身驱动了整个架构迁移和代码优化。
 
 ⚡️ **极致轻量**：可在 **10 美元** 的硬件上运行，内存占用 **<10MB**。这意味着比 OpenClaw 节省 99% 的内存，比 Mac mini 便宜 98%！
 
@@ -39,47 +45,75 @@
 </tr>
 </table>
 
-注意：人手有限，中文文档可能略有滞后，请优先查看英文文档。
-
 > [!CAUTION]
-> **🚨 SECURITY & OFFICIAL CHANNELS / 安全声明**
+> **🚨 安全声明**
 >
 > - **无加密货币 (NO CRYPTO):** PicoClaw **没有** 发行任何官方代币、Token 或虚拟货币。所有在 `pump.fun` 或其他交易平台上的相关声称均为 **诈骗**。
 > - **官方域名:** 唯一的官方网站是 **[picoclaw.io](https://picoclaw.io)**，公司官网是 **[sipeed.com](https://sipeed.com)**。
 > - **警惕:** 许多 `.ai/.org/.com/.net/...` 后缀的域名被第三方抢注，请勿轻信。
-> - **注意:** picoclaw正在初期的快速功能开发阶段，可能有尚未修复的网络安全问题，在1.0正式版发布前，请不要将其部署到生产环境中
-> - **注意:** picoclaw最近合并了大量PRs，近期版本可能内存占用较大(10~20MB)，我们将在功能较为收敛后进行资源占用优化.
+> - **注意:** PicoClaw 正在初期的快速功能开发阶段，可能有尚未修复的网络安全问题，在 1.0 正式版发布前，请不要将其部署到生产环境中。
+> - **注意:** PicoClaw 最近合并了大量 PR，近期版本可能内存占用较大 (10~20MB)，我们将在功能较为收敛后进行资源占用优化。
 
-## 📢 新闻 (News)
+## 📢 新闻
 
-2026-02-16 🎉 PicoClaw 在一周内突破了12K star! 感谢大家的关注！PicoClaw 的成长速度超乎我们预期. 由于PR数量的快速膨胀，我们亟需社区开发者参与维护. 我们需要的志愿者角色和roadmap已经发布到了[这里](docs/ROADMAP.md), 期待你的参与！
+2026-03-17 🚀 **v0.2.3 发布！** 系统托盘 UI（Windows & Linux）、子 Agent 状态查询 (`spawn_status`)、实验性 Gateway 热重载、Cron 安全门控，以及 2 项安全修复。PicoClaw 已达 **25K ⭐**！
 
-2026-02-13 🎉 **PicoClaw 在 4 天内突破 5000 Stars！** 感谢社区的支持！由于正值中国春节假期，PR 和 Issue 涌入较多，我们正在利用这段时间敲定 **项目路线图 (Roadmap)** 并组建 **开发者群组**，以便加速 PicoClaw 的开发。
-🚀 **行动号召：** 请在 GitHub Discussions 中提交您的功能请求 (Feature Requests)。我们将在接下来的周会上进行审查和优先级排序。
+2026-03-09 🎉 **v0.2.1 — 史上最大更新！** MCP 协议支持、4 个新频道 (Matrix/IRC/WeCom/Discord Proxy)、3 个新 Provider (Kimi/Minimax/Avian)、视觉管线、JSONL 记忆存储、模型路由。
 
-2026-02-09 🎉 **PicoClaw 正式发布！** 仅用 1 天构建，旨在将 AI Agent 带入 10 美元硬件与 <10MB 内存的世界。🦐 PicoClaw（皮皮虾），我们走！
+2026-02-28 📦 **v0.2.0** 发布，支持 Docker Compose 和 Web UI 启动器。
+
+2026-02-26 🎉 PicoClaw 仅 17 天突破 **20K Stars**！频道自动编排和能力接口上线。
+
+<details>
+<summary>更早的新闻...</summary>
+
+2026-02-16 🎉 PicoClaw 一周内突破 12K Stars！社区维护者角色和 [路线图](ROADMAP.md) 正式发布。
+
+2026-02-13 🎉 PicoClaw 4 天内突破 5000 Stars！项目路线图和开发者群组筹建中。
+
+2026-02-09 🎉 **PicoClaw 正式发布！** 仅用 1 天构建，将 AI Agent 带入 $10 硬件与 <10MB 内存的世界。🦐 皮皮虾，我们走！
+
+</details>
 
 ## ✨ 特性
 
-🪶 **超轻量级**: 核心功能内存占用 <10MB — 比 Clawdbot 小 99%。
+🪶 **超轻量级**: 核心功能内存占用 <10MB — 比 OpenClaw 小 99%。*
 
-💰 **极低成本**: 高效到足以在 10 美元的硬件上运行 — 比 Mac mini 便宜 98%。
+💰 **极低成本**: 高效到足以在 $10 的硬件上运行 — 比 Mac mini 便宜 98%。
 
 ⚡️ **闪电启动**: 启动速度快 400 倍，即使在 0.6GHz 单核处理器上也能在 1 秒内启动。
 
-🌍 **真正可移植**: 跨 RISC-V、ARM 和 x86 架构的单二进制文件，一键运行！
+🌍 **真正可移植**: 跨 RISC-V、ARM、MIPS 和 x86 架构的单二进制文件，一键运行！
 
-🤖 **AI 自举**: 纯 Go 语言原生实现 — 95% 的核心代码由 Agent 生成，并经由“人机回环 (Human-in-the-loop)”微调。
+🤖 **AI 自举**: 纯 Go 语言原生实现 — 95% 的核心代码由 Agent 生成，并经由"人机回环"微调。
+
+🔌 **MCP 支持**: 原生 [Model Context Protocol](https://modelcontextprotocol.io/) 集成 — 连接任意 MCP 服务器扩展 Agent 能力。
+
+👁️ **视觉管线**: 直接向 Agent 发送图片和文件 — 自动 base64 编码对接多模态 LLM。
+
+🧠 **智能路由**: 基于规则的模型路由 — 简单查询走轻量模型，节省 API 成本。
+
+_*近期版本因快速合并 PR 可能占用 10–20MB，资源优化已列入计划。启动速度对比基于 0.8GHz 单核实测（见下方对比表）。_
+
+<div align="center">
 
 |                                | OpenClaw      | NanoBot                  | **PicoClaw**                           |
 | ------------------------------ | ------------- | ------------------------ | -------------------------------------- |
 | **语言**                       | TypeScript    | Python                   | **Go**                                 |
-| **RAM**                        | >1GB          | >100MB                   | **< 10MB**                             |
+| **RAM**                        | >1GB          | >100MB                   | **< 10MB***                            |
 | **启动时间**</br>(0.8GHz core) | >500s         | >30s                     | **<1s**                                |
 | **成本**                       | Mac Mini $599 | 大多数 Linux 开发板 ~$50 | **任意 Linux 开发板**</br>**低至 $10** |
 
 <img src="assets/compare.jpg" alt="PicoClaw" width="512">
 
+</div>
+
+> 📋 **[硬件兼容列表](docs/zh/hardware-compatibility.md)** — 查看所有已测试的板卡，从 $5 RISC-V 到树莓派到安卓手机。你的板卡没在列表中？欢迎提交 PR！
+
+<p align="center">
+<img src="assets/hardware-banner.jpg" alt="PicoClaw Hardware Compatibility" width="100%">
+</p>
+
 ## 🦾 演示
 
 ### 🛠️ 标准助手工作流
@@ -102,43 +136,29 @@
 </tr>
 </table>
 
-### 📱 在手机上轻松运行
-
-picoclaw 可以将你10年前的老旧手机废物利用，变身成为你的AI助理！快速指南:
-
-1. 先去应用商店下载安装Termux
-2. 打开后执行指令
-
-```bash
-# 注意: 下面的v0.1.1 可以换为你实际看到的最新版本
-wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
-chmod +x picoclaw-linux-arm64
-pkg install proot
-termux-chroot ./picoclaw-linux-arm64 onboard
-```
-
-然后跟随下面的“快速开始”章节继续配置picoclaw即可使用！  
-<img src="assets/termux.jpg" alt="PicoClaw" width="512">
-
 ### 🐜 创新的低占用部署
 
 PicoClaw 几乎可以部署在任何 Linux 设备上！
 
-- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(网口) 或 W(WiFi6) 版本，用于极简家庭助手。
-- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html)，或 $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html)，用于自动化服务器运维。
-- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) 或 $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera)，用于智能监控。
+- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(网口) 或 W(WiFi6) 版本，用于极简家庭助手
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html)，或 $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html)，用于自动化服务器运维
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) 或 $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera)，用于智能监控
 
-[https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4](https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4)
+<https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4>
 
 🌟 更多部署案例敬请期待！
 
 ## 📦 安装
 
-### 使用预编译二进制文件安装
+### 从 picoclaw.io 下载（推荐）
 
-从 [Release 页面](https://github.com/sipeed/picoclaw/releases) 下载适用于您平台的固件。
+访问 **[picoclaw.io](https://picoclaw.io)** — 官网自动检测你的平台，提供一键下载，无需手动选择架构。
 
-### 从源码安装（获取最新特性，开发推荐）
+### 下载预编译二进制文件
+
+也可以从 [GitHub Releases](https://github.com/sipeed/picoclaw/releases) 页面手动下载对应平台的二进制文件。
+
+### 从源码构建（开发用）
 
 ```bash
 git clone https://github.com/sipeed/picoclaw.git
@@ -146,704 +166,418 @@ git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 make deps
 
-# 构建（无需安装）
+# 构建核心二进制文件
 make build
 
+# 构建 Web UI Launcher（WebUI 模式必需）
+make build-launcher
+
 # 为多平台构建
 make build-all
 
+# 为 Raspberry Pi Zero 2 W 构建（32位: make build-linux-arm; 64位: make build-linux-arm64）
+make build-pi-zero
+
 # 构建并安装
 make install
-
 ```
 
-## 🐳 Docker Compose
+**Raspberry Pi Zero 2 W:** 请使用与系统匹配的二进制文件：32 位 Raspberry Pi OS → `make build-linux-arm`；64 位 → `make build-linux-arm64`。或运行 `make build-pi-zero` 同时构建两者。
 
-您也可以使用 Docker Compose 运行 PicoClaw，无需在本地安装任何环境。
+## 🚀 快速开始
+
+### 🌐 WebUI Launcher（推荐桌面用户）
+
+WebUI Launcher 提供基于浏览器的配置与聊天界面，是最简单的上手方式——无需命令行知识。
+
+**方式一：双击启动（桌面）**
+
+从 [picoclaw.io](https://picoclaw.io) 下载后，双击 `picoclaw-launcher`（Windows 上为 `picoclaw-launcher.exe`），浏览器将自动打开 `http://localhost:18800`。
+
+**方式二：命令行**
 
 ```bash
-# 1. 克隆仓库
+picoclaw-launcher
+# 在浏览器中打开 http://localhost:18800
+```
+
+> [!TIP]
+> **远程访问 / Docker / 虚拟机：** 添加 `-public` 参数以监听所有网络接口：
+> ```bash
+> picoclaw-launcher -public
+> ```
+
+<p align="center">
+<img src="assets/launcher-webui.jpg" alt="WebUI Launcher" width="600">
+</p>
+
+**开始使用：**
+
+打开 WebUI，然后：**1)** 配置 Provider（填入 LLM API Key）-> **2)** 配置 Channel（如 Telegram）-> **3)** 启动 Gateway -> **4)** 开始聊天！
+
+详细 WebUI 文档请参阅 [docs.picoclaw.io](https://docs.picoclaw.io)。
+
+<details>
+<summary><b>Docker（备选方案）</b></summary>
+
+```bash
+# 1. 克隆本仓库
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
 
-# 2. 首次运行 — 自动生成 docker/data/config.json 后退出
-docker compose -f docker/docker-compose.yml --profile gateway up
-# 容器打印 "First-run setup complete." 后自动停止
+# 2. 首次运行——自动生成 docker/data/config.json 后退出
+#    （仅在 config.json 和 workspace/ 均不存在时触发）
+docker compose -f docker/docker-compose.yml --profile launcher up
+# 容器打印 "First-run setup complete." 后停止。
 
-# 3. 填写 API Key 等配置
-vim docker/data/config.json   # 设置 provider API key、Bot Token 等
+# 3. 填写 API Key
+vim docker/data/config.json
 
-# 4. 正式启动
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+# 4. 启动
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+# 打开 http://localhost:18800
 ```
 
-> [!TIP]
-> **Docker 用户**: 默认情况下, Gateway 监听 `127.0.0.1`，该端口不会暴露到容器外。如果需要通过端口映射访问健康检查接口，请在环境变量中设置 `PICOCLAW_GATEWAY_HOST=0.0.0.0` 或修改 `config.json`。
+> **Docker / 虚拟机用户：** Gateway 默认监听 `127.0.0.1`。设置 `PICOCLAW_GATEWAY_HOST=0.0.0.0` 或使用 `-public` 参数以允许从宿主机访问。
 
 ```bash
-# 5. 查看日志
-docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+# 查看日志
+docker compose -f docker/docker-compose.yml logs -f
 
-# 6. 停止
-docker compose -f docker/docker-compose.yml --profile gateway down
-```
+# 停止
+docker compose -f docker/docker-compose.yml --profile launcher down
 
-### Agent 模式 (一次性运行)
-
-```bash
-# 提问
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 等于几？"
-
-# 交互模式
-docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
-```
-
-### 更新镜像
-
-```bash
+# 更新
 docker compose -f docker/docker-compose.yml pull
-docker compose -f docker/docker-compose.yml --profile gateway up -d
+docker compose -f docker/docker-compose.yml --profile launcher up -d
 ```
 
-### 🚀 快速开始
+</details>
 
-> [!TIP]
-> 在 `~/.picoclaw/config.json` 中设置您的 API Key。
-> 获取 API Key: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu (智谱)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)
-> 网络搜索是 **可选的** - 获取免费的 [Tavily API](https://tavily.com) (每月 1000 次免费查询) 或 [Brave Search API](https://brave.com/search/api) (每月 2000 次免费查询)
+### 💻 TUI Launcher（推荐无头环境 / SSH）
 
-**1. 初始化 (Initialize)**
+TUI（终端 UI）Launcher 提供功能完整的终端配置与管理界面，适合服务器、树莓派等无显示器环境。
+
+```bash
+picoclaw-launcher-tui
+```
+
+<p align="center">
+<img src="assets/launcher-tui.jpg" alt="TUI Launcher" width="600">
+</p>
+
+**开始使用：**
+
+通过 TUI 菜单：**1)** 配置 Provider -> **2)** 配置 Channel -> **3)** 启动 Gateway -> **4)** 开始聊天！
+
+详细 TUI 文档请参阅 [docs.picoclaw.io](https://docs.picoclaw.io)。
+
+### 📱 Android
+
+让你十年前的旧手机焕发新生！将它变成你的 AI 助手。
+
+**方式一：Termux（现已可用）**
+
+1. 安装 [Termux](https://github.com/termux/termux-app)（可从 [GitHub Releases](https://github.com/termux/termux-app/releases) 下载，或在 F-Droid / Google Play 中搜索）
+2. 执行以下命令：
+
+```bash
+# 从 Release 页面下载最新版本
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+pkg install proot
+termux-chroot ./picoclaw onboard   # chroot 提供标准 Linux 文件系统布局
+```
+
+然后跟随下面的"Terminal Launcher"章节继续配置。
+
+<img src="assets/termux.jpg" alt="PicoClaw on Termux" width="512">
+
+**方式二：APK 安装（即将推出）**
+
+内置 WebUI 的独立 Android APK 正在开发中，敬请期待！
+
+<details>
+<summary><b>Terminal Launcher（适用于资源受限环境）</b></summary>
+
+对于只有 `picoclaw` 核心二进制文件的极简环境（无 Launcher UI），可通过命令行和 JSON 配置文件完成所有配置。
+
+**1. 初始化**
 
 ```bash
 picoclaw onboard
-
 ```
 
-**2. 配置 (Configure)** (`~/.picoclaw/config.json`)
+此命令会创建 `~/.picoclaw/config.json` 和工作区目录。
+
+**2. 配置** (`~/.picoclaw/config.json`)
 
 ```json
 {
   "agents": {
     "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "model_name": "gpt4",
-      "max_tokens": 8192,
-      "temperature": 0.7,
-      "max_tool_iterations": 20
+      "model_name": "gpt-5.4"
     }
   },
   "model_list": [
     {
-      "model_name": "gpt4",
-      "model": "openai/gpt-5.2",
-      "api_key": "your-api-key",
-      "request_timeout": 300
-    },
-    {
-      "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
-      "api_key": "your-anthropic-key"
-    }
-  ],
-  "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "YOUR_BRAVE_API_KEY",
-        "max_results": 5
-      },
-      "tavily": {
-        "enabled": false,
-        "api_key": "YOUR_TAVILY_API_KEY",
-        "max_results": 5
-      }
-    },
-    "cron": {
-      "exec_timeout_minutes": 5
-    }
-  }
-}
-```
-
-> **新功能**: `model_list` 配置格式支持零代码添加 provider。详见[模型配置](#模型配置-model_list)章节。
-> `request_timeout` 为可选项，单位为秒。若省略或设置为 `<= 0`，PicoClaw 使用默认超时（120 秒）。
-
-**3. 获取 API Key**
-
-* **LLM 提供商**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
-* **网络搜索** (可选): [Tavily](https://tavily.com) - 专为 AI Agent 优化 (1000 请求/月) · [Brave Search](https://brave.com/search/api) - 提供免费层级 (2000 请求/月)
-
-> **注意**: 完整的配置模板请参考 `config.example.json`。
-
-**4. 对话 (Chat)**
-
-```bash
-picoclaw agent -m "2+2 等于几？"
-
-```
-
-就是这样！您在 2 分钟内就拥有了一个可工作的 AI 助手。
-
----
-
-## 💬 聊天应用集成 (Chat Apps)
-
-PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方。
-
-> **注意**: 所有 Webhook 类渠道（LINE、WeCom 等）均挂载在同一个 Gateway HTTP 服务器上（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`），无需为每个渠道单独配置端口。注意：飞书（Feishu）使用 WebSocket/SDK 模式，不通过该共享 HTTP webhook 服务器接收消息。
-
-### 核心渠道
-
-| 渠道                 | 设置难度    | 特性说明                                  | 文档链接                                                                                                        |
-| -------------------- | ----------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| **Telegram**         | ⭐ 简单     | 推荐，支持语音转文字，长轮询无需公网      | [查看文档](docs/channels/telegram/README.zh.md)                                                                 |
-| **Discord**          | ⭐ 简单     | Socket Mode，支持群组/私信，Bot 生态成熟  | [查看文档](docs/channels/discord/README.zh.md)                                                                  |
-| **Slack**            | ⭐ 简单     | **Socket Mode** (无需公网 IP)，企业级支持 | [查看文档](docs/channels/slack/README.zh.md)                                                                    |
-| **QQ**               | ⭐⭐ 中等   | 官方机器人 API，适合国内社群              | [查看文档](docs/channels/qq/README.zh.md)                                                                       |
-| **钉钉 (DingTalk)**  | ⭐⭐ 中等   | Stream 模式无需公网，企业办公首选         | [查看文档](docs/channels/dingtalk/README.zh.md)                                                                 |
-| **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 支持群机器人(Webhook)和自建应用(API)      | [Bot 文档](docs/channels/wecom/wecom_bot/README.zh.md) / [App 文档](docs/channels/wecom/wecom_app/README.zh.md) |
-| **飞书 (Feishu)**    | ⭐⭐⭐ 较难 | 企业级协作，功能丰富                      | [查看文档](docs/channels/feishu/README.zh.md)                                                                   |
-| **Line**             | ⭐⭐⭐ 较难 | 需要 HTTPS Webhook                        | [查看文档](docs/channels/line/README.zh.md)                                                                     |
-| **OneBot**           | ⭐⭐ 中等   | 兼容 NapCat/Go-CQHTTP，社区生态丰富       | [查看文档](docs/channels/onebot/README.zh.md)                                                                   |
-| **MaixCam**          | ⭐ 简单     | 专为 AI 摄像头设计的硬件集成通道          | [查看文档](docs/channels/maixcam/README.zh.md)                                                                  |
-
-## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> 加入 Agent 社交网络
-
-只需通过 CLI 或任何集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。
-
-\*\*阅读 `https://clawdchat.ai/skill.md` 并按照说明加入 [ClawdChat.ai](https://clawdchat.ai)
-
-## ⚙️ 配置详解
-
-配置文件路径: `~/.picoclaw/config.json`
-
-### 环境变量
-
-你可以使用环境变量覆盖默认路径。这对于便携安装、容器化部署或将 picoclaw 作为系统服务运行非常有用。这些变量是独立的，控制不同的路径。
-
-| 变量              | 描述                                                                                                                             | 默认路径                  |
-|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
-| `PICOCLAW_CONFIG` | 覆盖配置文件的路径。这直接告诉 picoclaw 加载哪个 `config.json`，忽略所有其他位置。 | `~/.picoclaw/config.json` |
-| `PICOCLAW_HOME`   | 覆盖 picoclaw 数据根目录。这会更改 `workspace` 和其他数据目录的默认位置。          | `~/.picoclaw`             |
-
-**示例：**
-
-```bash
-# 使用特定的配置文件运行 picoclaw
-# 工作区路径将从该配置文件中读取
-PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
-
-# 在 /opt/picoclaw 中存储所有数据运行 picoclaw
-# 配置将从默认的 ~/.picoclaw/config.json 加载
-# 工作区将在 /opt/picoclaw/workspace 创建
-PICOCLAW_HOME=/opt/picoclaw picoclaw agent
-
-# 同时使用两者进行完全自定义设置
-PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
-```
-
-### 工作区布局 (Workspace Layout)
-
-PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/workspace`）：
-
-```
-~/.picoclaw/workspace/
-├── sessions/          # 对话会话和历史
-├── memory/           # 长期记忆 (MEMORY.md)
-├── state/            # 持久化状态 (最后一次频道等)
-├── cron/             # 定时任务数据库
-├── skills/           # 自定义技能
-├── AGENTS.md         # Agent 行为指南
-├── HEARTBEAT.md      # 周期性任务提示词 (每 30 分钟检查一次)
-├── IDENTITY.md       # Agent 身份设定
-├── SOUL.md           # Agent 灵魂/性格
-├── TOOLS.md          # 工具描述
-└── USER.md           # 用户偏好
-
-```
-
-### 心跳 / 周期性任务 (Heartbeat)
-
-PicoClaw 可以自动执行周期性任务。在工作区创建 `HEARTBEAT.md` 文件：
-
-```markdown
-# Periodic Tasks
-
-- Check my email for important messages
-- Review my calendar for upcoming events
-- Check the weather forecast
-```
-
-Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具执行任务。
-
-#### 使用 Spawn 的异步任务
-
-对于耗时较长的任务（网络搜索、API 调用），使用 `spawn` 工具创建一个 **子 Agent (subagent)**：
-
-```markdown
-# Periodic Tasks
-
-## Quick Tasks (respond directly)
-
-- Report current time
-
-## Long Tasks (use spawn for async)
-
-- Search the web for AI news and summarize
-- Check email and report important messages
-```
-
-**关键行为：**
-
-| 特性             | 描述                                     |
-| ---------------- | ---------------------------------------- |
-| **spawn**        | 创建异步子 Agent，不阻塞主心跳进程       |
-| **独立上下文**   | 子 Agent 拥有独立上下文，无会话历史      |
-| **message tool** | 子 Agent 通过 message 工具直接与用户通信 |
-| **非阻塞**       | spawn 后，心跳继续处理下一个任务         |
-
-#### 子 Agent 通信原理
-
-```
-心跳触发 (Heartbeat triggers)
-    ↓
-Agent 读取 HEARTBEAT.md
-    ↓
-对于长任务: spawn 子 Agent
-    ↓                           ↓
-继续下一个任务               子 Agent 独立工作
-    ↓                           ↓
-所有任务完成                 子 Agent 使用 "message" 工具
-    ↓                           ↓
-响应 HEARTBEAT_OK            用户直接收到结果
-
-```
-
-子 Agent 可以访问工具（message, web_search 等），并且无需通过主 Agent 即可独立与用户通信。
-
-**配置：**
-
-```json
-{
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
-  }
-}
-```
-
-| 选项       | 默认值 | 描述                         |
-| ---------- | ------ | ---------------------------- |
-| `enabled`  | `true` | 启用/禁用心跳                |
-| `interval` | `30`   | 检查间隔，单位分钟 (最小: 5) |
-
-**环境变量:**
-
-- `PICOCLAW_HEARTBEAT_ENABLED=false` 禁用
-- `PICOCLAW_HEARTBEAT_INTERVAL=60` 更改间隔
-
-### 提供商 (Providers)
-
-> [!NOTE]
-> Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，Telegram 语音消息将被自动转录为文字。
-
-| 提供商               | 用途                         | 获取 API Key                                                         |
-| -------------------- | ---------------------------- | -------------------------------------------------------------------- |
-| `gemini`             | LLM (Gemini 直连)            | [aistudio.google.com](https://aistudio.google.com)                   |
-| `zhipu`              | LLM (智谱直连)               | [bigmodel.cn](bigmodel.cn)                                           |
-| `openrouter(待测试)` | LLM (推荐，可访问所有模型)   | [openrouter.ai](https://openrouter.ai)                               |
-| `anthropic(待测试)`  | LLM (Claude 直连)            | [console.anthropic.com](https://console.anthropic.com)               |
-| `openai(待测试)`     | LLM (GPT 直连)               | [platform.openai.com](https://platform.openai.com)                   |
-| `deepseek(待测试)`   | LLM (DeepSeek 直连)          | [platform.deepseek.com](https://platform.deepseek.com)               |
-| `qwen`               | LLM (通义千问)               | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
-| `groq`               | LLM + **语音转录** (Whisper) | [console.groq.com](https://console.groq.com)                         |
-| `cerebras`           | LLM (Cerebras 直连)          | [cerebras.ai](https://cerebras.ai)                                   |
-
-### 模型配置 (model_list)
-
-> **新功能！** PicoClaw 现在采用**以模型为中心**的配置方式。只需使用 `厂商/模型` 格式（如 `zhipu/glm-4.7`）即可添加新的 provider——**无需修改任何代码！**
-
-该设计同时支持**多 Agent 场景**，提供灵活的 Provider 选择：
-
-- **不同 Agent 使用不同 Provider**：每个 Agent 可以使用自己的 LLM provider
-- **模型回退（Fallback）**：配置主模型和备用模型，提高可靠性
-- **负载均衡**：在多个 API 端点之间分配请求
-- **集中化配置**：在一个地方管理所有 provider
-
-#### 📋 所有支持的厂商
-
-| 厂商                | `model` 前缀      | 默认 API Base                                       | 协议      | 获取 API Key                                                      |
-| ------------------- | ----------------- | --------------------------------------------------- | --------- | ----------------------------------------------------------------- |
-| **OpenAI**          | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [获取密钥](https://platform.openai.com)                           |
-| **Anthropic**       | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [获取密钥](https://console.anthropic.com)                         |
-| **智谱 AI (GLM)**   | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [获取密钥](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
-| **DeepSeek**        | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [获取密钥](https://platform.deepseek.com)                         |
-| **Google Gemini**   | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI    | [获取密钥](https://aistudio.google.com/api-keys)                  |
-| **Groq**            | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [获取密钥](https://console.groq.com)                              |
-| **Moonshot**        | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [获取密钥](https://platform.moonshot.cn)                          |
-| **通义千问 (Qwen)** | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [获取密钥](https://dashscope.console.aliyun.com)                  |
-| **NVIDIA**          | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [获取密钥](https://build.nvidia.com)                              |
-| **Ollama**          | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | 本地（无需密钥）                                                  |
-| **OpenRouter**      | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [获取密钥](https://openrouter.ai/keys)                            |
-| **VLLM**            | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | 本地                                                              |
-| **Cerebras**        | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [获取密钥](https://cerebras.ai)                                   |
-| **火山引擎**        | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [获取密钥](https://console.volcengine.com)                        |
-| **神算云**          | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                 |
-| **Antigravity**     | `antigravity/`    | Google Cloud                                        | 自定义    | 仅 OAuth                                                          |
-| **GitHub Copilot**  | `github-copilot/` | `localhost:4321`                                    | gRPC      | -                                                                 |
-
-#### 基础配置示例
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_key": "sk-your-openai-key"
-    },
-    {
-      "model_name": "claude-sonnet-4.6",
-      "model": "anthropic/claude-sonnet-4.6",
-      "api_key": "sk-ant-your-key"
-    },
-    {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-zhipu-key"
-    }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "gpt-5.2"
-    }
-  }
-}
-```
-
-#### 各厂商配置示例
-
-**OpenAI**
-
-```json
-{
-  "model_name": "gpt-5.2",
-  "model": "openai/gpt-5.2",
-  "api_key": "sk-..."
-}
-```
-
-**智谱 AI (GLM)**
-
-```json
-{
-  "model_name": "glm-4.7",
-  "model": "zhipu/glm-4.7",
-  "api_key": "your-key"
-}
-```
-
-**DeepSeek**
-
-```json
-{
-  "model_name": "deepseek-chat",
-  "model": "deepseek/deepseek-chat",
-  "api_key": "sk-..."
-}
-```
-
-**Anthropic (使用 OAuth)**
-
-```json
-{
-  "model_name": "claude-sonnet-4.6",
-  "model": "anthropic/claude-sonnet-4.6",
-  "auth_method": "oauth"
-}
-```
-
-> 运行 `picoclaw auth login --provider anthropic` 来设置 OAuth 凭证。
-
-**Ollama (本地)**
-
-```json
-{
-  "model_name": "llama3",
-  "model": "ollama/llama3"
-}
-```
-
-**自定义代理/API**
-
-```json
-{
-  "model_name": "my-custom-model",
-  "model": "openai/custom-model",
-  "api_base": "https://my-proxy.com/v1",
-  "api_key": "sk-...",
-  "request_timeout": 300
-}
-```
-
-#### 负载均衡
-
-为同一个模型名称配置多个端点——PicoClaw 会自动在它们之间轮询：
-
-```json
-{
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_base": "https://api1.example.com/v1",
-      "api_key": "sk-key1"
-    },
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "api_base": "https://api2.example.com/v1",
-      "api_key": "sk-key2"
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-api-key"
     }
   ]
 }
 ```
 
-#### 从旧的 `providers` 配置迁移
+> 完整配置模板请参阅仓库中的 `config/config.example.json`。
 
-旧的 `providers` 配置格式**已弃用**，但为向后兼容仍支持。
+**3. 开始聊天**
 
-**旧配置（已弃用）：**
+```bash
+# 单次提问
+picoclaw agent -m "What is 2+2?"
 
-```json
-{
-  "providers": {
-    "zhipu": {
-      "api_key": "your-key",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  },
-  "agents": {
-    "defaults": {
-      "provider": "zhipu",
-      "model": "glm-4.7"
-    }
-  }
-}
+# 交互式对话模式
+picoclaw agent
+
+# 启动 Gateway 以接入聊天应用
+picoclaw gateway
 ```
 
-**新配置（推荐）：**
+</details>
 
+## 🔌 Providers (LLM)
+
+PicoClaw 通过 `model_list` 配置支持 30+ LLM Provider，使用 `协议/模型` 格式：
+
+| Provider | 协议 | API Key | 备注 |
+|----------|------|---------|------|
+| [OpenAI](https://platform.openai.com/api-keys) | `openai/` | 必填 | GPT-5.4、GPT-4o、o3 等 |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `anthropic/` | 必填 | Claude Opus 4.6、Sonnet 4.6 等 |
+| [Google Gemini](https://aistudio.google.com/apikey) | `gemini/` | 必填 | Gemini 3 Flash、2.5 Pro 等 |
+| [OpenRouter](https://openrouter.ai/keys) | `openrouter/` | 必填 | 200+ 模型，统一 API |
+| [智谱 (GLM)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) | `zhipu/` | 必填 | GLM-4.7、GLM-5 等 |
+| [DeepSeek](https://platform.deepseek.com/api_keys) | `deepseek/` | 必填 | DeepSeek-V3、DeepSeek-R1 |
+| [火山引擎](https://console.volcengine.com) | `volcengine/` | 必填 | 豆包、Ark 系列模型 |
+| [Qwen](https://dashscope.console.aliyun.com/apiKey) | `qwen/` | 必填 | Qwen3、Qwen-Max 等 |
+| [Groq](https://console.groq.com/keys) | `groq/` | 必填 | 快速推理（Llama、Mixtral） |
+| [Moonshot (Kimi)](https://platform.moonshot.cn/console/api-keys) | `moonshot/` | 必填 | Kimi 系列模型 |
+| [Minimax](https://platform.minimaxi.com/user-center/basic-information/interface-key) | `minimax/` | 必填 | MiniMax 系列模型 |
+| [Mistral](https://console.mistral.ai/api-keys) | `mistral/` | 必填 | Mistral Large、Codestral |
+| [NVIDIA NIM](https://build.nvidia.com/) | `nvidia/` | 必填 | NVIDIA 托管模型 |
+| [Cerebras](https://cloud.cerebras.ai/) | `cerebras/` | 必填 | 快速推理 |
+| [Novita AI](https://novita.ai/) | `novita/` | 必填 | 多种开源模型 |
+| [Ollama](https://ollama.com/) | `ollama/` | 无需 | 本地模型，自托管 |
+| [vLLM](https://docs.vllm.ai/) | `vllm/` | 无需 | 本地部署，兼容 OpenAI |
+| [LiteLLM](https://docs.litellm.ai/) | `litellm/` | 视情况 | 100+ Provider 代理 |
+| [Azure OpenAI](https://portal.azure.com/) | `azure/` | 必填 | 企业级 Azure 部署 |
+| [GitHub Copilot](https://github.com/features/copilot) | `github-copilot/` | OAuth | 设备码登录 |
+| [Antigravity](https://console.cloud.google.com/) | `antigravity/` | OAuth | Google Cloud AI |
+
+<details>
+<summary><b>本地部署（Ollama、vLLM 等）</b></summary>
+
+**Ollama:**
 ```json
 {
   "model_list": [
     {
-      "model_name": "glm-4.7",
-      "model": "zhipu/glm-4.7",
-      "api_key": "your-key"
+      "model_name": "local-llama",
+      "model": "ollama/llama3.1:8b",
+      "api_base": "http://localhost:11434/v1"
     }
-  ],
-  "agents": {
-    "defaults": {
-      "model": "glm-4.7"
-    }
-  }
+  ]
 }
 ```
 
-详细的迁移指南请参考 [docs/migration/model-list-migration.md](docs/migration/model-list-migration.md)。
-
-<details>
-<summary><b>智谱 (Zhipu) 配置示例</b></summary>
-
-**1. 获取 API key 和 base URL**
-
-- 获取 [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
-
-**2. 配置**
-
+**vLLM:**
 ```json
 {
-  "agents": {
-    "defaults": {
-      "workspace": "~/.picoclaw/workspace",
-      "model": "glm-4.7",
-      "max_tokens": 8192,
-      "temperature": 0.7,
-      "max_tool_iterations": 20
+  "model_list": [
+    {
+      "model_name": "local-vllm",
+      "model": "vllm/your-model",
+      "api_base": "http://localhost:8000/v1"
     }
-  },
-  "providers": {
-    "zhipu": {
-      "api_key": "Your API Key",
-      "api_base": "https://open.bigmodel.cn/api/paas/v4"
-    }
-  }
+  ]
 }
 ```
 
-**3. 运行**
+完整 Provider 配置详情请参阅 [Providers & Models](docs/zh/providers.md)。
+
+</details>
+
+## 💬 Channels（聊天应用）
+
+通过 17+ 消息平台与你的 PicoClaw 对话：
+
+| Channel | 配置难度 | 协议 | 文档 |
+|---------|----------|------|------|
+| **Telegram** | 简单（bot token） | 长轮询 | [指南](docs/channels/telegram/README.zh.md) |
+| **Discord** | 简单（bot token + intents） | WebSocket | [指南](docs/channels/discord/README.zh.md) |
+| **WhatsApp** | 简单（扫码或 bridge URL） | 原生 / Bridge | [指南](docs/zh/chat-apps.md#whatsapp) |
+| **微信 (Weixin)** | 简单（扫码登录） | iLink API | [指南](docs/zh/chat-apps.md#weixin) |
+| **QQ** | 简单（AppID + AppSecret） | WebSocket | [指南](docs/channels/qq/README.zh.md) |
+| **Slack** | 简单（bot + app token） | Socket Mode | [指南](docs/channels/slack/README.zh.md) |
+| **Matrix** | 中等（homeserver + token） | Sync API | [指南](docs/channels/matrix/README.zh.md) |
+| **钉钉** | 中等（client credentials） | Stream | [指南](docs/channels/dingtalk/README.zh.md) |
+| **飞书 / Lark** | 中等（App ID + Secret） | WebSocket/SDK | [指南](docs/channels/feishu/README.zh.md) |
+| **LINE** | 中等（credentials + webhook） | Webhook | [指南](docs/channels/line/README.zh.md) |
+| **企业微信机器人** | 中等（webhook URL） | Webhook | [指南](docs/channels/wecom/wecom_bot/README.zh.md) |
+| **企业微信应用** | 中等（corp credentials） | Webhook | [指南](docs/channels/wecom/wecom_app/README.zh.md) |
+| **企业微信 AI 机器人** | 中等（token + AES key） | WebSocket / Webhook | [指南](docs/channels/wecom/wecom_aibot/README.zh.md) |
+| **IRC** | 中等（server + nick） | IRC 协议 | [指南](docs/zh/chat-apps.md#irc) |
+| **OneBot** | 中等（WebSocket URL） | OneBot v11 | [指南](docs/channels/onebot/README.zh.md) |
+| **MaixCam** | 简单（启用即可） | TCP socket | [指南](docs/channels/maixcam/README.zh.md) |
+| **Pico** | 简单（启用即可） | 原生协议 | 内置 |
+| **Pico Client** | 简单（WebSocket URL） | WebSocket | 内置 |
+
+> 所有基于 Webhook 的 Channel 共用同一个 Gateway HTTP 服务器（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`）。飞书使用 WebSocket/SDK 模式，不使用共享 HTTP 服务器。
+
+详细 Channel 配置说明请参阅 [聊天应用配置](docs/zh/chat-apps.md)。
+
+## 🔧 Tools
+
+### 🔍 网络搜索
+
+PicoClaw 可以搜索网络以提供最新信息。在 `tools.web` 中配置：
+
+| 搜索引擎 | API Key | 免费额度 | 链接 |
+|---------|---------|---------|------|
+| [百度搜索](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5) | 必填 | 1000 次/天 | AI 搜索，国内首选 |
+| [Tavily](https://tavily.com) | 必填 | 1000 次/月 | 专为 AI Agent 优化 |
+| [GLM Search](https://open.bigmodel.cn/) | 必填 | 视情况 | 智谱网络搜索 |
+| DuckDuckGo | 无需 | 无限制 | 内置备用（国内访问困难） |
+| [Perplexity](https://www.perplexity.ai) | 必填 | 付费 | AI 驱动搜索（国内访问困难） |
+| [Brave Search](https://brave.com/search/api) | 必填 | 2000 次/月 | 快速且注重隐私（国内访问困难） |
+| [SearXNG](https://github.com/searxng/searxng) | 无需 | 自托管 | 免费元搜索引擎 |
+
+### ⚙️ 其他工具
+
+PicoClaw 内置文件操作、代码执行、定时任务等工具。详情请参阅 [工具配置](docs/zh/tools_configuration.md)。
+
+## 🎯 Skills
+
+Skills 是扩展 Agent 能力的模块化插件，从工作区的 `SKILL.md` 文件加载。
+
+**从 ClawHub 安装 Skills：**
 
 ```bash
-picoclaw agent -m "你好"
-
+picoclaw skills search "web scraping"
+picoclaw skills install <skill-name>
 ```
 
-</details>
-
-<details>
-<summary><b>完整配置示例</b></summary>
+**配置 ClawHub token**（可选，用于提高速率限制）：
 
+在 `config.json` 中添加：
 ```json
 {
-  "agents": {
-    "defaults": {
-      "model": "anthropic/claude-opus-4-5"
-    }
-  },
-  "providers": {
-    "openrouter": {
-      "api_key": "sk-or-v1-xxx"
-    },
-    "groq": {
-      "api_key": "gsk_xxx"
-    }
-  },
-  "channels": {
-    "telegram": {
-      "enabled": true,
-      "token": "123456:ABC...",
-      "allow_from": ["123456789"]
-    },
-    "discord": {
-      "enabled": true,
-      "token": "",
-      "allow_from": [""]
-    },
-    "whatsapp": {
-      "enabled": false
-    },
-    "feishu": {
-      "enabled": false,
-      "app_id": "cli_xxx",
-      "app_secret": "xxx",
-      "encrypt_key": "",
-      "verification_token": "",
-      "allow_from": []
-    },
-    "qq": {
-      "enabled": false,
-      "app_id": "",
-      "app_secret": "",
-      "allow_from": []
-    }
-  },
   "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "YOUR_BRAVE_API_KEY",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "auth_token": "your-clawhub-token"
+        }
       }
-    },
-    "cron": {
-      "exec_timeout_minutes": 5
     }
-  },
-  "heartbeat": {
-    "enabled": true,
-    "interval": 30
   }
 }
 ```
 
-</details>
+更多详情请参阅 [工具配置 - Skills](docs/zh/tools_configuration.md#skills-tool)。
 
-## CLI 命令行参考
+## 🔗 MCP (Model Context Protocol)
 
-| 命令                      | 描述               |
-| ------------------------- | ------------------ |
-| `picoclaw onboard`        | 初始化配置和工作区 |
-| `picoclaw agent -m "..."` | 与 Agent 对话      |
-| `picoclaw agent`          | 交互式聊天模式     |
-| `picoclaw gateway`        | 启动网关 (Gateway) |
-| `picoclaw status`         | 显示状态           |
-| `picoclaw cron list`      | 列出所有定时任务   |
-| `picoclaw cron add ...`   | 添加定时任务       |
+PicoClaw 原生支持 [MCP](https://modelcontextprotocol.io/) — 连接任意 MCP 服务器，通过外部工具和数据源扩展 Agent 能力。
 
-### 定时任务 / 提醒 (Scheduled Tasks)
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+        }
+      }
+    }
+  }
+}
+```
+
+完整 MCP 配置（stdio、SSE、HTTP 传输、Tool Discovery）请参阅 [工具配置 - MCP](docs/zh/tools_configuration.md#mcp-tool)。
+
+## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> 加入 Agent 社交网络
+
+通过 CLI 或任何已集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。
+
+**阅读 `https://clawdchat.ai/skill.md` 并按照说明加入 [ClawdChat.ai](https://clawdchat.ai)**
+
+## 🖥️ CLI 命令行参考
+
+| 命令                       | 说明                   |
+| ------------------------- | ---------------------- |
+| `picoclaw onboard`        | 初始化配置与工作区       |
+| `picoclaw auth weixin` | 扫码连接微信个人号 |
+| `picoclaw agent -m "..."` | 与 Agent 对话           |
+| `picoclaw agent`          | 交互式对话模式           |
+| `picoclaw gateway`        | 启动网关                |
+| `picoclaw status`         | 查看状态                |
+| `picoclaw version`        | 查看版本信息             |
+| `picoclaw model`          | 查看或切换默认模型       |
+| `picoclaw cron list`      | 列出所有定时任务         |
+| `picoclaw cron add ...`   | 添加定时任务             |
+| `picoclaw cron disable`   | 禁用定时任务             |
+| `picoclaw cron remove`    | 删除定时任务             |
+| `picoclaw skills list`    | 列出已安装 Skills        |
+| `picoclaw skills install` | 安装 Skill              |
+| `picoclaw migrate`        | 从旧版本迁移数据         |
+| `picoclaw auth login`     | 认证 Provider           |
+
+### ⏰ 定时任务 / 提醒
 
 PicoClaw 通过 `cron` 工具支持定时提醒和重复任务：
 
-- **一次性提醒**: "Remind me in 10 minutes" (10分钟后提醒我) → 10分钟后触发一次
-- **重复任务**: "Remind me every 2 hours" (每2小时提醒我) → 每2小时触发
-- **Cron 表达式**: "Remind me at 9am daily" (每天上午9点提醒我) → 使用 cron 表达式
+* **一次性提醒**: "10分钟后提醒我" → 10分钟后触发一次
+* **重复任务**: "每2小时提醒我" → 每2小时触发
+* **Cron 表达式**: "每天上午9点提醒我" → 使用 cron 表达式
 
-任务存储在 `~/.picoclaw/workspace/cron/` 中并自动处理。
+## 📚 文档
 
-## 🤝 贡献与路线图 (Roadmap)
+详细指南请参阅以下文档，README 仅涵盖快速入门。
+
+| 主题 | 说明 |
+|------|------|
+| 🐳 [Docker 与快速开始](docs/zh/docker.md) | Docker Compose 配置、Launcher/Agent 模式、快速开始 |
+| 💬 [聊天应用配置](docs/zh/chat-apps.md) | 全部 17+ Channel 配置指南 |
+| ⚙️ [配置指南](docs/zh/configuration.md) | 环境变量、工作区布局、安全沙箱 |
+| 🔌 [提供商与模型配置](docs/zh/providers.md) | 30+ LLM Provider、模型路由、model_list 配置 |
+| 🔄 [异步任务与 Spawn](docs/zh/spawn-tasks.md) | 快速任务、长任务与 Spawn、异步子 Agent 编排 |
+| 🪝 [Hook 系统](docs/hooks/README.zh.md) | 事件驱动 Hook：观察者、拦截器、审批 Hook |
+| 🎯 [Steering](docs/steering.md) | 在工具调用间向运行中的 Agent 注入消息 |
+| 🔀 [SubTurn](docs/subturn.md) | 子 Agent 协调、并发控制、生命周期管理 |
+| 🐛 [疑难解答](docs/zh/troubleshooting.md) | 常见问题与解决方案 |
+| 🔧 [工具配置](docs/zh/tools_configuration.md) | 工具启用/禁用、执行策略、MCP、Skills |
+| 📋 [硬件兼容列表](docs/zh/hardware-compatibility.md) | 已测试板卡、最低要求 |
+
+## 🤝 贡献与路线图
 
 欢迎提交 PR！代码库刻意保持小巧和可读。🤗
 
-路线图即将发布...
+查看完整的 [社区路线图](https://github.com/sipeed/picoclaw/issues/988) 和 [CONTRIBUTING.md](CONTRIBUTING.md)。
 
 开发者群组正在组建中，入群门槛：至少合并过 1 个 PR。
 
 用户群组：
 
-Discord: [https://discord.gg/V4sAZ9XWpN](https://discord.gg/V4sAZ9XWpN)
+Discord: <https://discord.gg/V4sAZ9XWpN>
 
-<img src="assets/wechat.png" alt="PicoClaw" width="512">
+WeChat:
+<img src="assets/wechat.png" alt="WeChat group QR code" width="512">
 
-## 🐛 疑难解答 (Troubleshooting)
 
-### 网络搜索提示 "API 配置问题"
 
-如果您尚未配置搜索 API Key，这是正常的。PicoClaw 会提供手动搜索的帮助链接。
 
-启用网络搜索：
 
-1. 在 [https://tavily.com](https://tavily.com) (1000 次免费) 或 [https://brave.com/search/api](https://brave.com/search/api) 获取免费 API Key (2000 次免费)
-2. 添加到 `~/.picoclaw/config.json`:
-
-```json
-{
-  "tools": {
-    "web": {
-      "brave": {
-        "enabled": false,
-        "api_key": "YOUR_BRAVE_API_KEY",
-        "max_results": 5
-      },
-      "duckduckgo": {
-        "enabled": true,
-        "max_results": 5
-      }
-    }
-  }
-}
-```
-
-### 遇到内容过滤错误 (Content Filtering Errors)
-
-某些提供商（如智谱）有严格的内容过滤。尝试改写您的问题或使用其他模型。
-
-### Telegram bot 提示 "Conflict: terminated by other getUpdates"
-
-这表示有另一个机器人实例正在运行。请确保同一时间只有一个 `picoclaw gateway` 进程在运行。
-
----
-
-## 📝 API Key 对比
-
-| 服务 | 免费层级 | 适用场景 |
-| --- | --- | --- |
-| **OpenRouter** | 200K tokens/月 | 多模型聚合 (Claude, GPT-4 等) |
-| **智谱 (Zhipu)** | 200K tokens/月 | 最适合中国用户 |
-| **Brave Search** | 2000 次查询/月 | 网络搜索功能 |
-| **Tavily** | 1000 次查询/月 | AI Agent 搜索优化 |
-| **Groq** | 提供免费层级 | 极速推理 (Llama, Mixtral) |
diff --git a/assets/hardware-banner.jpg b/assets/hardware-banner.jpg
new file mode 100644
index 000000000..f9a1190b1
Binary files /dev/null and b/assets/hardware-banner.jpg differ
diff --git a/assets/launcher-tui.jpg b/assets/launcher-tui.jpg
new file mode 100644
index 000000000..cf5e8ea4d
Binary files /dev/null and b/assets/launcher-tui.jpg differ
diff --git a/assets/launcher-webui.jpg b/assets/launcher-webui.jpg
new file mode 100644
index 000000000..9e7c699b2
Binary files /dev/null and b/assets/launcher-webui.jpg differ
diff --git a/assets/logo.webp b/assets/logo.webp
new file mode 100644
index 000000000..9333f7e1b
Binary files /dev/null and b/assets/logo.webp differ
diff --git a/assets/wechat.png b/assets/wechat.png
index 1c0b88295..effb4dab9 100644
Binary files a/assets/wechat.png and b/assets/wechat.png differ
diff --git a/cmd/picoclaw-launcher-tui/config/config.go b/cmd/picoclaw-launcher-tui/config/config.go
new file mode 100644
index 000000000..227b9fa3d
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/config/config.go
@@ -0,0 +1,236 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+// Package config provides types and I/O for ~/.picoclaw/tui.toml.
+package config
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/BurntSushi/toml"
+
+	"github.com/sipeed/picoclaw/pkg/fileutil"
+)
+
+// DefaultConfigPath returns the default path to the tui.toml config file.
+func DefaultConfigPath() string {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		home = "."
+	}
+	return filepath.Join(home, ".picoclaw", "tui.toml")
+}
+
+// TUIConfig is the top-level structure of ~/.picoclaw/tui.toml.
+type TUIConfig struct {
+	Version  string   `toml:"version"`
+	Model    Model    `toml:"model"`
+	Provider Provider `toml:"provider"`
+}
+
+type Model struct {
+	Type string `toml:"type"` // "provider" (default) | "manual"
+}
+
+type Provider struct {
+	Schemes []Scheme        `toml:"schemes"`
+	Users   []User          `toml:"users"`
+	Current ProviderCurrent `toml:"current"`
+}
+
+type Scheme struct {
+	Name    string `toml:"name"`    // unique key
+	BaseURL string `toml:"baseURL"` // required
+	Type    string `toml:"type"`    // "openai-compatible" (default) | "anthropic"
+}
+
+type User struct {
+	Name   string `toml:"name"`
+	Scheme string `toml:"scheme"` // references Scheme.Name; (Name+Scheme) is unique
+	Type   string `toml:"type"`   // "key" (default) | "OAuth"
+	Key    string `toml:"key"`
+}
+
+type ProviderCurrent struct {
+	Scheme string `toml:"scheme"` // references Scheme.Name
+	User   string `toml:"user"`   // references User.Name where User.Scheme == Scheme
+	Model  string `toml:"model"`  // from GET <baseURL>/models
+}
+
+// DefaultConfig returns a minimal valid TUIConfig.
+func DefaultConfig() *TUIConfig {
+	return &TUIConfig{
+		Version: "1.0",
+		Model:   Model{Type: "provider"},
+		Provider: Provider{
+			Schemes: []Scheme{},
+			Users:   []User{},
+			Current: ProviderCurrent{},
+		},
+	}
+}
+
+// Load reads the TUI config from path. Returns a default config if the file does not exist.
+func Load(path string) (*TUIConfig, error) {
+	data, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return DefaultConfig(), nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("failed to read config file %q: %w", path, err)
+	}
+
+	cfg := DefaultConfig()
+	if _, err := toml.Decode(string(data), cfg); err != nil {
+		return nil, fmt.Errorf("failed to parse config file %q: %w", path, err)
+	}
+
+	applyDefaults(cfg)
+	return cfg, nil
+}
+
+// Save writes cfg to path atomically (safe for flash / SD storage).
+func Save(path string, cfg *TUIConfig) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return fmt.Errorf("failed to create config directory: %w", err)
+	}
+	var buf bytes.Buffer
+	enc := toml.NewEncoder(&buf)
+	if err := enc.Encode(cfg); err != nil {
+		return fmt.Errorf("failed to encode config: %w", err)
+	}
+	if err := fileutil.WriteFileAtomic(path, buf.Bytes(), 0o600); err != nil {
+		return fmt.Errorf("failed to write config file %q: %w", path, err)
+	}
+	return nil
+}
+
+func applyDefaults(cfg *TUIConfig) {
+	if cfg.Version == "" {
+		cfg.Version = "1.0"
+	}
+	if cfg.Model.Type == "" {
+		cfg.Model.Type = "provider"
+	}
+	for i := range cfg.Provider.Schemes {
+		if cfg.Provider.Schemes[i].Type == "" {
+			cfg.Provider.Schemes[i].Type = "openai-compatible"
+		}
+	}
+	for i := range cfg.Provider.Users {
+		if cfg.Provider.Users[i].Type == "" {
+			cfg.Provider.Users[i].Type = "key"
+		}
+	}
+}
+
+// SchemeByName returns the first Scheme whose Name matches, or nil.
+func (p *Provider) SchemeByName(name string) *Scheme {
+	for i := range p.Schemes {
+		if p.Schemes[i].Name == name {
+			return &p.Schemes[i]
+		}
+	}
+	return nil
+}
+
+// UsersForScheme returns all users whose Scheme field matches schemeName.
+func (p *Provider) UsersForScheme(schemeName string) []User {
+	var out []User
+	for _, u := range p.Users {
+		if u.Scheme == schemeName {
+			out = append(out, u)
+		}
+	}
+	return out
+}
+
+// SyncSelectedModelToMainConfig syncs the currently selected model to ~/.picoclaw/config.json
+// Adds/replaces a "tui-prefer" model entry and sets it as the default model.
+// Preserves all other existing fields in the config file unchanged.
+func SyncSelectedModelToMainConfig(scheme Scheme, user User, modelID string) error {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		home = "."
+	}
+	mainConfigPath := filepath.Join(home, ".picoclaw", "config.json")
+
+	var cfg map[string]any
+	if data, readErr := os.ReadFile(mainConfigPath); readErr == nil {
+		if unmarshalErr := json.Unmarshal(data, &cfg); unmarshalErr != nil {
+			cfg = make(map[string]any)
+		}
+	} else {
+		cfg = make(map[string]any)
+	}
+
+	if _, ok := cfg["agents"]; !ok {
+		cfg["agents"] = make(map[string]any)
+	}
+	agents, ok := cfg["agents"].(map[string]any)
+	if ok {
+		if _, ok := agents["defaults"]; !ok {
+			agents["defaults"] = make(map[string]any)
+		}
+		defaults, ok := agents["defaults"].(map[string]any)
+		if ok {
+			defaults["model"] = "tui-prefer"
+		}
+	}
+
+	tuiModel := map[string]any{
+		"model_name": "tui-prefer",
+		"model":      modelID,
+		"api_key":    user.Key,
+		"api_base":   scheme.BaseURL,
+	}
+
+	modelList := []any{}
+	if ml, ok := cfg["model_list"].([]any); ok {
+		modelList = ml
+	}
+
+	found := false
+	for i, m := range modelList {
+		if entry, ok := m.(map[string]any); ok {
+			if name, ok := entry["model_name"].(string); ok && name == "tui-prefer" {
+				modelList[i] = tuiModel
+				found = true
+				break
+			}
+		}
+	}
+	if !found {
+		modelList = append(modelList, tuiModel)
+	}
+	cfg["model_list"] = modelList
+
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		return err
+	}
+
+	if err := os.MkdirAll(filepath.Dir(mainConfigPath), 0o700); err != nil {
+		return err
+	}
+
+	return os.WriteFile(mainConfigPath, data, 0o600)
+}
+
+func (cfg *TUIConfig) CurrentModelLabel() string {
+	cur := cfg.Provider.Current
+	if cur.Model == "" {
+		return "(not configured)"
+	}
+	label := cur.Scheme
+	if label != "" {
+		label += " / "
+	}
+	return label + cur.Model
+}
diff --git a/cmd/picoclaw-launcher-tui/internal/config/store.go b/cmd/picoclaw-launcher-tui/internal/config/store.go
deleted file mode 100644
index 0236de19f..000000000
--- a/cmd/picoclaw-launcher-tui/internal/config/store.go
+++ /dev/null
@@ -1,49 +0,0 @@
-package configstore
-
-import (
-	"errors"
-	"os"
-	"path/filepath"
-
-	picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
-)
-
-const (
-	configDirName  = ".picoclaw"
-	configFileName = "config.json"
-)
-
-func ConfigPath() (string, error) {
-	dir, err := ConfigDir()
-	if err != nil {
-		return "", err
-	}
-	return filepath.Join(dir, configFileName), nil
-}
-
-func ConfigDir() (string, error) {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return "", err
-	}
-	return filepath.Join(home, configDirName), nil
-}
-
-func Load() (*picoclawconfig.Config, error) {
-	path, err := ConfigPath()
-	if err != nil {
-		return nil, err
-	}
-	return picoclawconfig.LoadConfig(path)
-}
-
-func Save(cfg *picoclawconfig.Config) error {
-	if cfg == nil {
-		return errors.New("config is nil")
-	}
-	path, err := ConfigPath()
-	if err != nil {
-		return err
-	}
-	return picoclawconfig.SaveConfig(path, cfg)
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/app.go b/cmd/picoclaw-launcher-tui/internal/ui/app.go
deleted file mode 100644
index 4947d6aea..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/app.go
+++ /dev/null
@@ -1,506 +0,0 @@
-package ui
-
-import (
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	configstore "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/internal/config"
-	picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
-)
-
-type appState struct {
-	app         *tview.Application
-	pages       *tview.Pages
-	stack       []string
-	config      *picoclawconfig.Config
-	configPath  string
-	gatewayCmd  *exec.Cmd
-	menus       map[string]*Menu
-	original    []byte
-	hasOriginal bool
-	backupPath  string
-	dirty       bool
-	logPath     string
-}
-
-func Run() error {
-	applyStyles()
-	cfg, err := configstore.Load()
-	if err != nil {
-		return err
-	}
-	path, err := configstore.ConfigPath()
-	if err != nil {
-		return err
-	}
-
-	if cfg == nil {
-		cfg = picoclawconfig.DefaultConfig()
-	}
-
-	originalData, hasOriginal := loadOriginalConfig(path)
-	backupPath := path + ".bak"
-	if hasOriginal {
-		_ = writeBackupConfig(backupPath, originalData)
-	}
-
-	logPath := filepath.Join(filepath.Dir(path), "gateway.log")
-	state := &appState{
-		app:         tview.NewApplication(),
-		pages:       tview.NewPages(),
-		config:      cfg,
-		configPath:  path,
-		menus:       map[string]*Menu{},
-		original:    originalData,
-		hasOriginal: hasOriginal,
-		backupPath:  backupPath,
-		logPath:     logPath,
-	}
-
-	state.push("main", state.mainMenu())
-
-	root := tview.NewFlex().SetDirection(tview.FlexRow)
-	root.AddItem(bannerView(), 6, 0, false)
-	root.AddItem(state.pages, 0, 1, true)
-
-	if err := state.app.SetRoot(root, true).EnableMouse(false).Run(); err != nil {
-		return err
-	}
-	return nil
-}
-
-func (s *appState) push(name string, primitive tview.Primitive) {
-	s.pages.AddPage(name, primitive, true, true)
-	s.stack = append(s.stack, name)
-	s.pages.SwitchToPage(name)
-	if menu, ok := primitive.(*Menu); ok {
-		s.menus[name] = menu
-	}
-}
-
-func (s *appState) pop() {
-	if len(s.stack) == 0 {
-		return
-	}
-	last := s.stack[len(s.stack)-1]
-	s.pages.RemovePage(last)
-	s.stack = s.stack[:len(s.stack)-1]
-	if len(s.stack) == 0 {
-		s.app.Stop()
-		return
-	}
-	current := s.stack[len(s.stack)-1]
-	s.pages.SwitchToPage(current)
-	if menu, ok := s.menus[current]; ok {
-		s.refreshMenu(current, menu)
-	}
-}
-
-func (s *appState) mainMenu() tview.Primitive {
-	menu := NewMenu("Config Menu", nil)
-	refreshMainMenu(menu, s)
-	menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		switch event.Key() {
-		case tcell.KeyEsc:
-			s.requestExit()
-			return nil
-		}
-		if event.Rune() == 'q' {
-			s.requestExit()
-			return nil
-		}
-		return event
-	})
-
-	return menu
-}
-
-func (s *appState) refreshMenu(name string, menu *Menu) {
-	switch name {
-	case "main":
-		refreshMainMenu(menu, s)
-	case "model":
-		refreshModelMenuFromState(menu, s)
-	case "channel":
-		refreshChannelMenuFromState(menu, s)
-	}
-}
-
-func refreshMainMenuIfPresent(s *appState) {
-	if menu, ok := s.menus["main"]; ok {
-		refreshMainMenu(menu, s)
-	}
-}
-
-func refreshMainMenu(menu *Menu, s *appState) {
-	selectedModel := s.selectedModelName()
-	modelReady := selectedModel != ""
-	channelReady := s.hasEnabledChannel()
-	gatewayRunning := s.gatewayCmd != nil || s.isGatewayRunning()
-
-	gatewayLabel := "Start Gateway"
-	gatewayDescription := "Launch gateway for channels"
-	if gatewayRunning {
-		gatewayLabel = "Stop Gateway"
-		gatewayDescription = "Gateway running"
-	}
-
-	items := []MenuItem{
-		{
-			Label:       rootModelLabel(selectedModel),
-			Description: rootModelDescription(selectedModel),
-			Action: func() {
-				s.push("model", s.modelMenu())
-			},
-			MainColor: func() *tcell.Color {
-				if modelReady {
-					return nil
-				}
-				color := tcell.ColorGray
-				return &color
-			}(),
-		},
-		{
-			Label:       rootChannelLabel(channelReady),
-			Description: rootChannelDescription(channelReady),
-			Action: func() {
-				s.push("channel", s.channelMenu())
-			},
-			MainColor: func() *tcell.Color {
-				if channelReady {
-					return nil
-				}
-				color := tcell.ColorGray
-				return &color
-			}(),
-		},
-		{
-			Label:       "Start Talk",
-			Description: "Open picoclaw agent in terminal",
-			Action: func() {
-				s.requestStartTalk()
-			},
-			Disabled: !modelReady,
-		},
-		{
-			Label:       gatewayLabel,
-			Description: gatewayDescription,
-			Action: func() {
-				if gatewayRunning {
-					s.stopGateway()
-				} else {
-					s.requestStartGateway()
-				}
-				refreshMainMenu(menu, s)
-			},
-			Disabled: !gatewayRunning && (!modelReady || !channelReady),
-		},
-		{
-			Label:       "View Gateway Log",
-			Description: "Open gateway.log",
-			Action: func() {
-				s.viewGatewayLog()
-			},
-		},
-		{
-			Label:       "Exit",
-			Description: "Exit the TUI",
-			Action: func() {
-				s.requestExit()
-			},
-		},
-	}
-	menu.applyItems(items)
-}
-
-func (s *appState) applyChangesValidated() bool {
-	if err := s.config.ValidateModelList(); err != nil {
-		s.showMessage("Validation failed", err.Error())
-		return false
-	}
-	if err := s.validateAgentModel(); err != nil {
-		s.showMessage("Validation failed", err.Error())
-		return false
-	}
-	if err := configstore.Save(s.config); err != nil {
-		s.showMessage("Save failed", err.Error())
-		return false
-	}
-	if data, err := os.ReadFile(s.configPath); err == nil {
-		s.original = data
-		s.hasOriginal = true
-		_ = writeBackupConfig(s.backupPath, data)
-	}
-	return true
-}
-
-func (s *appState) requestExit() {
-	if s.dirty {
-		s.confirmApplyOrDiscard(func() {
-			s.app.Stop()
-		}, func() {
-			s.discardChanges()
-			s.app.Stop()
-		})
-		return
-	}
-	s.app.Stop()
-}
-
-func (s *appState) requestStartTalk() {
-	if s.dirty {
-		s.confirmApplyOrDiscard(func() {
-			s.startTalk()
-		}, func() {
-			s.startTalk()
-		})
-		return
-	}
-	s.startTalk()
-}
-
-func (s *appState) requestStartGateway() {
-	if s.dirty {
-		s.confirmApplyOrDiscard(func() {
-			s.startGateway()
-		}, func() {
-			s.startGateway()
-		})
-		return
-	}
-	s.startGateway()
-}
-
-func (s *appState) viewGatewayLog() {
-	data, err := os.ReadFile(s.logPath)
-	if err != nil {
-		s.showMessage("Log not found", "gateway.log not found")
-		return
-	}
-	text := tview.NewTextView()
-	text.SetBorder(true).SetTitle("Gateway Log")
-	text.SetText(string(data))
-	text.SetDoneFunc(func(key tcell.Key) {
-		s.pages.RemovePage("log")
-	})
-	text.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEsc {
-			s.pages.RemovePage("log")
-			return nil
-		}
-		return event
-	})
-	s.pages.AddPage("log", text, true, true)
-}
-
-func (s *appState) selectedModelName() string {
-	modelName := strings.TrimSpace(s.config.Agents.Defaults.Model)
-	if modelName == "" {
-		return ""
-	}
-	if !s.isActiveModelValid() {
-		return ""
-	}
-	return modelName
-}
-
-func rootModelLabel(selected string) string {
-	if selected == "" {
-		return "Model (no model selected)"
-	}
-	return "Model (" + selected + ")"
-}
-
-func rootModelDescription(selected string) string {
-	if selected == "" {
-		return "no model selected"
-	}
-	return "selected"
-}
-
-func rootChannelLabel(valid bool) string {
-	if !valid {
-		return "Channel (no channel enabled)"
-	}
-	return "Channel"
-}
-
-func rootChannelDescription(valid bool) string {
-	if !valid {
-		return "no channel enabled"
-	}
-	return "enabled"
-}
-
-func (s *appState) startTalk() {
-	if !s.isActiveModelValid() {
-		s.showMessage("Model required", "Select a valid model before starting talk")
-		return
-	}
-	if !s.applyChangesValidated() {
-		return
-	}
-	s.app.Suspend(func() {
-		cmd := exec.Command("picoclaw", "agent")
-		cmd.Stdin = os.Stdin
-		cmd.Stdout = os.Stdout
-		cmd.Stderr = os.Stderr
-		_ = cmd.Run()
-	})
-}
-
-func (s *appState) startGateway() {
-	if !s.isActiveModelValid() {
-		s.showMessage("Model required", "Select a valid model before starting gateway")
-		return
-	}
-	if !s.hasEnabledChannel() {
-		s.showMessage("Channel required", "Enable at least one channel before starting gateway")
-		return
-	}
-	if !s.applyChangesValidated() {
-		return
-	}
-	_ = stopGatewayProcess()
-	cmd := exec.Command("picoclaw", "gateway")
-	logFile, err := os.OpenFile(s.logPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
-	if err != nil {
-		s.showMessage("Gateway failed", err.Error())
-		return
-	}
-	cmd.Stdout = logFile
-	cmd.Stderr = logFile
-	if err := cmd.Start(); err != nil {
-		s.showMessage("Gateway failed", err.Error())
-		_ = logFile.Close()
-		return
-	}
-	_ = logFile.Close()
-	s.gatewayCmd = cmd
-}
-
-func (s *appState) stopGateway() {
-	_ = stopGatewayProcess()
-	if s.gatewayCmd != nil && s.gatewayCmd.Process != nil {
-		_ = s.gatewayCmd.Process.Kill()
-	}
-	s.gatewayCmd = nil
-}
-
-func (s *appState) isGatewayRunning() bool {
-	return isGatewayProcessRunning()
-}
-
-func (s *appState) validateAgentModel() error {
-	modelName := strings.TrimSpace(s.config.Agents.Defaults.Model)
-	if modelName == "" {
-		return nil
-	}
-	_, err := s.config.GetModelConfig(modelName)
-	return err
-}
-
-func (s *appState) isActiveModelValid() bool {
-	modelName := strings.TrimSpace(s.config.Agents.Defaults.Model)
-	if modelName == "" {
-		return false
-	}
-	cfg, err := s.config.GetModelConfig(modelName)
-	if err != nil {
-		return false
-	}
-	hasKey := strings.TrimSpace(cfg.APIKey) != "" || strings.TrimSpace(cfg.AuthMethod) == "oauth"
-	hasModel := strings.TrimSpace(cfg.Model) != ""
-	return hasKey && hasModel
-}
-
-func (s *appState) hasEnabledChannel() bool {
-	c := s.config.Channels
-	return c.Telegram.Enabled || c.Discord.Enabled || c.QQ.Enabled || c.MaixCam.Enabled ||
-		c.WhatsApp.Enabled || c.Feishu.Enabled || c.DingTalk.Enabled || c.Slack.Enabled ||
-		c.LINE.Enabled || c.OneBot.Enabled || c.WeCom.Enabled || c.WeComApp.Enabled
-}
-
-func (s *appState) confirmApplyOrDiscard(onApply func(), onDiscard func()) {
-	if s.pages.HasPage("apply") {
-		return
-	}
-	modal := tview.NewModal().
-		SetText("Apply changes or discard before continuing?").
-		AddButtons([]string{"Cancel", "Discard", "Apply"}).
-		SetDoneFunc(func(buttonIndex int, buttonLabel string) {
-			s.pages.RemovePage("apply")
-			switch buttonLabel {
-			case "Discard":
-				s.discardChanges()
-				if onDiscard != nil {
-					onDiscard()
-				}
-			case "Apply":
-				if s.applyChangesValidated() {
-					s.dirty = false
-					if onApply != nil {
-						onApply()
-					}
-				}
-			}
-		})
-	modal.SetBorder(true)
-	s.pages.AddPage("apply", modal, true, true)
-}
-
-func (s *appState) discardChanges() {
-	if s.hasOriginal {
-		_ = writeOriginalConfig(s.configPath, s.original)
-	} else {
-		_ = os.Remove(s.configPath)
-	}
-	_ = os.Remove(s.backupPath)
-	if cfg, err := configstore.Load(); err == nil && cfg != nil {
-		s.config = cfg
-	}
-	s.dirty = false
-	refreshMainMenuIfPresent(s)
-}
-
-func (s *appState) showMessage(title, message string) {
-	if s.pages.HasPage("message") {
-		return
-	}
-	modal := tview.NewModal().
-		SetText(strings.TrimSpace(message)).
-		AddButtons([]string{"OK"}).
-		SetDoneFunc(func(_ int, _ string) {
-			s.pages.RemovePage("message")
-		})
-	modal.SetTitle(title).SetBorder(true)
-	modal.SetBackgroundColor(tview.Styles.ContrastBackgroundColor)
-	modal.SetTextColor(tview.Styles.PrimaryTextColor)
-	modal.SetButtonBackgroundColor(tcell.NewRGBColor(112, 102, 255))
-	modal.SetButtonTextColor(tview.Styles.PrimaryTextColor)
-	s.pages.AddPage("message", modal, true, true)
-}
-
-func loadOriginalConfig(path string) ([]byte, bool) {
-	data, err := os.ReadFile(path)
-	if err != nil {
-		if os.IsNotExist(err) {
-			return nil, false
-		}
-		return nil, false
-	}
-	return data, true
-}
-
-func writeOriginalConfig(path string, data []byte) error {
-	return os.WriteFile(path, data, 0o600)
-}
-
-func writeBackupConfig(path string, data []byte) error {
-	return os.WriteFile(path, data, 0o600)
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/channel.go b/cmd/picoclaw-launcher-tui/internal/ui/channel.go
deleted file mode 100644
index ad9171424..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/channel.go
+++ /dev/null
@@ -1,574 +0,0 @@
-package ui
-
-import (
-	"fmt"
-	"strings"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
-)
-
-func (s *appState) channelMenu() tview.Primitive {
-	items := []MenuItem{
-		{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
-		channelItem(
-			"Telegram",
-			"Telegram bot settings",
-			s.config.Channels.Telegram.Enabled,
-			func() { s.push("channel-telegram", s.telegramForm()) },
-		),
-		channelItem(
-			"Discord",
-			"Discord bot settings",
-			s.config.Channels.Discord.Enabled,
-			func() { s.push("channel-discord", s.discordForm()) },
-		),
-		channelItem(
-			"QQ",
-			"QQ bot settings",
-			s.config.Channels.QQ.Enabled,
-			func() { s.push("channel-qq", s.qqForm()) },
-		),
-		channelItem(
-			"MaixCam",
-			"MaixCam gateway",
-			s.config.Channels.MaixCam.Enabled,
-			func() { s.push("channel-maixcam", s.maixcamForm()) },
-		),
-		channelItem(
-			"WhatsApp",
-			"WhatsApp bridge",
-			s.config.Channels.WhatsApp.Enabled,
-			func() { s.push("channel-whatsapp", s.whatsappForm()) },
-		),
-		channelItem(
-			"Feishu",
-			"Feishu bot settings",
-			s.config.Channels.Feishu.Enabled,
-			func() { s.push("channel-feishu", s.feishuForm()) },
-		),
-		channelItem(
-			"DingTalk",
-			"DingTalk bot settings",
-			s.config.Channels.DingTalk.Enabled,
-			func() { s.push("channel-dingtalk", s.dingtalkForm()) },
-		),
-		channelItem(
-			"Slack",
-			"Slack bot settings",
-			s.config.Channels.Slack.Enabled,
-			func() { s.push("channel-slack", s.slackForm()) },
-		),
-		channelItem(
-			"LINE",
-			"LINE bot settings",
-			s.config.Channels.LINE.Enabled,
-			func() { s.push("channel-line", s.lineForm()) },
-		),
-		channelItem(
-			"OneBot",
-			"OneBot settings",
-			s.config.Channels.OneBot.Enabled,
-			func() { s.push("channel-onebot", s.onebotForm()) },
-		),
-		channelItem(
-			"WeCom",
-			"WeCom bot settings",
-			s.config.Channels.WeCom.Enabled,
-			func() { s.push("channel-wecom", s.wecomForm()) },
-		),
-		channelItem(
-			"WeCom App",
-			"WeCom App settings",
-			s.config.Channels.WeComApp.Enabled,
-			func() { s.push("channel-wecomapp", s.wecomAppForm()) },
-		),
-	}
-
-	menu := NewMenu("Channels", items)
-	menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEsc {
-			s.pop()
-			return nil
-		}
-		if event.Rune() == 'q' {
-			s.pop()
-			return nil
-		}
-		return event
-	})
-	return menu
-}
-
-func refreshChannelMenuFromState(menu *Menu, s *appState) {
-	items := []MenuItem{
-		{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
-		channelItem(
-			"Telegram",
-			"Telegram bot settings",
-			s.config.Channels.Telegram.Enabled,
-			func() { s.push("channel-telegram", s.telegramForm()) },
-		),
-		channelItem(
-			"Discord",
-			"Discord bot settings",
-			s.config.Channels.Discord.Enabled,
-			func() { s.push("channel-discord", s.discordForm()) },
-		),
-		channelItem(
-			"QQ",
-			"QQ bot settings",
-			s.config.Channels.QQ.Enabled,
-			func() { s.push("channel-qq", s.qqForm()) },
-		),
-		channelItem(
-			"MaixCam",
-			"MaixCam gateway",
-			s.config.Channels.MaixCam.Enabled,
-			func() { s.push("channel-maixcam", s.maixcamForm()) },
-		),
-		channelItem(
-			"WhatsApp",
-			"WhatsApp bridge",
-			s.config.Channels.WhatsApp.Enabled,
-			func() { s.push("channel-whatsapp", s.whatsappForm()) },
-		),
-		channelItem(
-			"Feishu",
-			"Feishu bot settings",
-			s.config.Channels.Feishu.Enabled,
-			func() { s.push("channel-feishu", s.feishuForm()) },
-		),
-		channelItem(
-			"DingTalk",
-			"DingTalk bot settings",
-			s.config.Channels.DingTalk.Enabled,
-			func() { s.push("channel-dingtalk", s.dingtalkForm()) },
-		),
-		channelItem(
-			"Slack",
-			"Slack bot settings",
-			s.config.Channels.Slack.Enabled,
-			func() { s.push("channel-slack", s.slackForm()) },
-		),
-		channelItem(
-			"LINE",
-			"LINE bot settings",
-			s.config.Channels.LINE.Enabled,
-			func() { s.push("channel-line", s.lineForm()) },
-		),
-		channelItem(
-			"OneBot",
-			"OneBot settings",
-			s.config.Channels.OneBot.Enabled,
-			func() { s.push("channel-onebot", s.onebotForm()) },
-		),
-		channelItem(
-			"WeCom",
-			"WeCom bot settings",
-			s.config.Channels.WeCom.Enabled,
-			func() { s.push("channel-wecom", s.wecomForm()) },
-		),
-		channelItem(
-			"WeCom App",
-			"WeCom App settings",
-			s.config.Channels.WeComApp.Enabled,
-			func() { s.push("channel-wecomapp", s.wecomAppForm()) },
-		),
-	}
-	menu.applyItems(items)
-}
-
-func (s *appState) telegramForm() tview.Primitive {
-	cfg := &s.config.Channels.Telegram
-	form := baseChannelForm("Telegram", cfg.Enabled, func(v bool) {
-		cfg.Enabled = v
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["channel"]; ok {
-			refreshChannelMenuFromState(menu, s)
-		}
-	})
-	form.AddInputField("Token", cfg.Token, 128, nil, func(text string) {
-		cfg.Token = strings.TrimSpace(text)
-	})
-	form.AddInputField("Proxy", cfg.Proxy, 128, nil, func(text string) {
-		cfg.Proxy = strings.TrimSpace(text)
-	})
-	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
-		cfg.AllowFrom = splitCSV(text)
-	})
-	return wrapWithBack(form, s)
-}
-
-func (s *appState) discordForm() tview.Primitive {
-	cfg := &s.config.Channels.Discord
-	form := baseChannelForm("Discord", cfg.Enabled, func(v bool) {
-		cfg.Enabled = v
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["channel"]; ok {
-			refreshChannelMenuFromState(menu, s)
-		}
-	})
-	form.AddInputField("Token", cfg.Token, 128, nil, func(text string) {
-		cfg.Token = strings.TrimSpace(text)
-	})
-	form.AddCheckbox("Mention Only", cfg.MentionOnly, func(checked bool) {
-		cfg.MentionOnly = checked
-	})
-	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
-		cfg.AllowFrom = splitCSV(text)
-	})
-	return wrapWithBack(form, s)
-}
-
-func (s *appState) qqForm() tview.Primitive {
-	cfg := &s.config.Channels.QQ
-	form := baseChannelForm("QQ", cfg.Enabled, func(v bool) {
-		cfg.Enabled = v
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["channel"]; ok {
-			refreshChannelMenuFromState(menu, s)
-		}
-	})
-	form.AddInputField("App ID", cfg.AppID, 64, nil, func(text string) {
-		cfg.AppID = strings.TrimSpace(text)
-	})
-	form.AddInputField("App Secret", cfg.AppSecret, 128, nil, func(text string) {
-		cfg.AppSecret = strings.TrimSpace(text)
-	})
-	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
-		cfg.AllowFrom = splitCSV(text)
-	})
-	return wrapWithBack(form, s)
-}
-
-func (s *appState) maixcamForm() tview.Primitive {
-	cfg := &s.config.Channels.MaixCam
-	form := baseChannelForm("MaixCam", cfg.Enabled, func(v bool) {
-		cfg.Enabled = v
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["channel"]; ok {
-			refreshChannelMenuFromState(menu, s)
-		}
-	})
-	form.AddInputField("Host", cfg.Host, 64, nil, func(text string) {
-		cfg.Host = strings.TrimSpace(text)
-	})
-	addIntField(form, "Port", cfg.Port, func(value int) { cfg.Port = value })
-	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
-		cfg.AllowFrom = splitCSV(text)
-	})
-	return wrapWithBack(form, s)
-}
-
-func (s *appState) whatsappForm() tview.Primitive {
-	cfg := &s.config.Channels.WhatsApp
-	form := baseChannelForm("WhatsApp", cfg.Enabled, func(v bool) {
-		cfg.Enabled = v
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["channel"]; ok {
-			refreshChannelMenuFromState(menu, s)
-		}
-	})
-	form.AddInputField("Bridge URL", cfg.BridgeURL, 128, nil, func(text string) {
-		cfg.BridgeURL = strings.TrimSpace(text)
-	})
-	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
-		cfg.AllowFrom = splitCSV(text)
-	})
-	return wrapWithBack(form, s)
-}
-
-func (s *appState) feishuForm() tview.Primitive {
-	cfg := &s.config.Channels.Feishu
-	form := baseChannelForm("Feishu", cfg.Enabled, func(v bool) {
-		cfg.Enabled = v
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["channel"]; ok {
-			refreshChannelMenuFromState(menu, s)
-		}
-	})
-	form.AddInputField("App ID", cfg.AppID, 64, nil, func(text string) {
-		cfg.AppID = strings.TrimSpace(text)
-	})
-	form.AddInputField("App Secret", cfg.AppSecret, 128, nil, func(text string) {
-		cfg.AppSecret = strings.TrimSpace(text)
-	})
-	form.AddInputField("Encrypt Key", cfg.EncryptKey, 128, nil, func(text string) {
-		cfg.EncryptKey = strings.TrimSpace(text)
-	})
-	form.AddInputField("Verification Token", cfg.VerificationToken, 128, nil, func(text string) {
-		cfg.VerificationToken = strings.TrimSpace(text)
-	})
-	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
-		cfg.AllowFrom = splitCSV(text)
-	})
-	return wrapWithBack(form, s)
-}
-
-func (s *appState) dingtalkForm() tview.Primitive {
-	cfg := &s.config.Channels.DingTalk
-	form := baseChannelForm("DingTalk", cfg.Enabled, func(v bool) {
-		cfg.Enabled = v
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["channel"]; ok {
-			refreshChannelMenuFromState(menu, s)
-		}
-	})
-	form.AddInputField("Client ID", cfg.ClientID, 64, nil, func(text string) {
-		cfg.ClientID = strings.TrimSpace(text)
-	})
-	form.AddInputField("Client Secret", cfg.ClientSecret, 128, nil, func(text string) {
-		cfg.ClientSecret = strings.TrimSpace(text)
-	})
-	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
-		cfg.AllowFrom = splitCSV(text)
-	})
-	return wrapWithBack(form, s)
-}
-
-func (s *appState) slackForm() tview.Primitive {
-	cfg := &s.config.Channels.Slack
-	form := baseChannelForm("Slack", cfg.Enabled, func(v bool) {
-		cfg.Enabled = v
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["channel"]; ok {
-			refreshChannelMenuFromState(menu, s)
-		}
-	})
-	form.AddInputField("Bot Token", cfg.BotToken, 128, nil, func(text string) {
-		cfg.BotToken = strings.TrimSpace(text)
-	})
-	form.AddInputField("App Token", cfg.AppToken, 128, nil, func(text string) {
-		cfg.AppToken = strings.TrimSpace(text)
-	})
-	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
-		cfg.AllowFrom = splitCSV(text)
-	})
-	return wrapWithBack(form, s)
-}
-
-func (s *appState) lineForm() tview.Primitive {
-	cfg := &s.config.Channels.LINE
-	form := baseChannelForm("LINE", cfg.Enabled, func(v bool) {
-		cfg.Enabled = v
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["channel"]; ok {
-			refreshChannelMenuFromState(menu, s)
-		}
-	})
-	form.AddInputField("Channel Secret", cfg.ChannelSecret, 128, nil, func(text string) {
-		cfg.ChannelSecret = strings.TrimSpace(text)
-	})
-	form.AddInputField("Channel Access Token", cfg.ChannelAccessToken, 128, nil, func(text string) {
-		cfg.ChannelAccessToken = strings.TrimSpace(text)
-	})
-	form.AddInputField("Webhook Host", cfg.WebhookHost, 64, nil, func(text string) {
-		cfg.WebhookHost = strings.TrimSpace(text)
-	})
-	addIntField(form, "Webhook Port", cfg.WebhookPort, func(value int) { cfg.WebhookPort = value })
-	form.AddInputField("Webhook Path", cfg.WebhookPath, 64, nil, func(text string) {
-		cfg.WebhookPath = strings.TrimSpace(text)
-	})
-	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
-		cfg.AllowFrom = splitCSV(text)
-	})
-	return wrapWithBack(form, s)
-}
-
-func (s *appState) onebotForm() tview.Primitive {
-	cfg := &s.config.Channels.OneBot
-	form := baseChannelForm("OneBot", cfg.Enabled, func(v bool) {
-		cfg.Enabled = v
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["channel"]; ok {
-			refreshChannelMenuFromState(menu, s)
-		}
-	})
-	form.AddInputField("WS URL", cfg.WSUrl, 128, nil, func(text string) {
-		cfg.WSUrl = strings.TrimSpace(text)
-	})
-	form.AddInputField("Access Token", cfg.AccessToken, 128, nil, func(text string) {
-		cfg.AccessToken = strings.TrimSpace(text)
-	})
-	addIntField(
-		form,
-		"Reconnect Interval",
-		cfg.ReconnectInterval,
-		func(value int) { cfg.ReconnectInterval = value },
-	)
-	form.AddInputField(
-		"Group Trigger Prefix",
-		strings.Join(cfg.GroupTriggerPrefix, ","),
-		128,
-		nil,
-		func(text string) {
-			cfg.GroupTriggerPrefix = splitCSV(text)
-		},
-	)
-	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
-		cfg.AllowFrom = splitCSV(text)
-	})
-	return wrapWithBack(form, s)
-}
-
-func (s *appState) wecomForm() tview.Primitive {
-	cfg := &s.config.Channels.WeCom
-	form := baseChannelForm("WeCom", cfg.Enabled, func(v bool) {
-		cfg.Enabled = v
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["channel"]; ok {
-			refreshChannelMenuFromState(menu, s)
-		}
-	})
-	form.AddInputField("Token", cfg.Token, 128, nil, func(text string) {
-		cfg.Token = strings.TrimSpace(text)
-	})
-	form.AddInputField("Encoding AES Key", cfg.EncodingAESKey, 128, nil, func(text string) {
-		cfg.EncodingAESKey = strings.TrimSpace(text)
-	})
-	form.AddInputField("Webhook URL", cfg.WebhookURL, 128, nil, func(text string) {
-		cfg.WebhookURL = strings.TrimSpace(text)
-	})
-	form.AddInputField("Webhook Host", cfg.WebhookHost, 64, nil, func(text string) {
-		cfg.WebhookHost = strings.TrimSpace(text)
-	})
-	addIntField(form, "Webhook Port", cfg.WebhookPort, func(value int) { cfg.WebhookPort = value })
-	form.AddInputField("Webhook Path", cfg.WebhookPath, 64, nil, func(text string) {
-		cfg.WebhookPath = strings.TrimSpace(text)
-	})
-	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
-		cfg.AllowFrom = splitCSV(text)
-	})
-	addIntField(
-		form,
-		"Reply Timeout",
-		cfg.ReplyTimeout,
-		func(value int) { cfg.ReplyTimeout = value },
-	)
-	return wrapWithBack(form, s)
-}
-
-func (s *appState) wecomAppForm() tview.Primitive {
-	cfg := &s.config.Channels.WeComApp
-	form := baseChannelForm("WeCom App", cfg.Enabled, func(v bool) {
-		cfg.Enabled = v
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["channel"]; ok {
-			refreshChannelMenuFromState(menu, s)
-		}
-	})
-	form.AddInputField("Corp ID", cfg.CorpID, 64, nil, func(text string) {
-		cfg.CorpID = strings.TrimSpace(text)
-	})
-	form.AddInputField("Corp Secret", cfg.CorpSecret, 128, nil, func(text string) {
-		cfg.CorpSecret = strings.TrimSpace(text)
-	})
-	addInt64Field(form, "Agent ID", cfg.AgentID, func(value int64) { cfg.AgentID = value })
-	form.AddInputField("Token", cfg.Token, 128, nil, func(text string) {
-		cfg.Token = strings.TrimSpace(text)
-	})
-	form.AddInputField("Encoding AES Key", cfg.EncodingAESKey, 128, nil, func(text string) {
-		cfg.EncodingAESKey = strings.TrimSpace(text)
-	})
-	form.AddInputField("Webhook Host", cfg.WebhookHost, 64, nil, func(text string) {
-		cfg.WebhookHost = strings.TrimSpace(text)
-	})
-	addIntField(form, "Webhook Port", cfg.WebhookPort, func(value int) { cfg.WebhookPort = value })
-	form.AddInputField("Webhook Path", cfg.WebhookPath, 64, nil, func(text string) {
-		cfg.WebhookPath = strings.TrimSpace(text)
-	})
-	form.AddInputField("Allow From", strings.Join(cfg.AllowFrom, ","), 128, nil, func(text string) {
-		cfg.AllowFrom = splitCSV(text)
-	})
-	addIntField(
-		form,
-		"Reply Timeout",
-		cfg.ReplyTimeout,
-		func(value int) { cfg.ReplyTimeout = value },
-	)
-	return wrapWithBack(form, s)
-}
-
-func baseChannelForm(title string, enabled bool, onEnabled func(bool)) *tview.Form {
-	form := tview.NewForm()
-	form.SetBorder(true).SetTitle(fmt.Sprintf("Channel: %s", title))
-	form.SetButtonBackgroundColor(tcell.NewRGBColor(80, 250, 123))
-	form.SetButtonTextColor(tcell.NewRGBColor(12, 13, 22))
-	form.AddCheckbox("Enabled", enabled, func(checked bool) {
-		onEnabled(checked)
-	})
-	return form
-}
-
-func wrapWithBack(form *tview.Form, s *appState) tview.Primitive {
-	form.AddButton("Back", func() {
-		s.pop()
-	})
-	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEsc {
-			s.pop()
-			return nil
-		}
-		return event
-	})
-	return form
-}
-
-func splitCSV(input string) picoclawconfig.FlexibleStringSlice {
-	parts := strings.Split(strings.TrimSpace(input), ",")
-	cleaned := make([]string, 0, len(parts))
-	for _, part := range parts {
-		value := strings.TrimSpace(part)
-		if value == "" {
-			continue
-		}
-		cleaned = append(cleaned, value)
-	}
-	return cleaned
-}
-
-func addIntField(form *tview.Form, label string, value int, onChange func(int)) {
-	form.AddInputField(label, fmt.Sprintf("%d", value), 16, nil, func(text string) {
-		var parsed int
-		if _, err := fmt.Sscanf(strings.TrimSpace(text), "%d", &parsed); err == nil {
-			onChange(parsed)
-		}
-	})
-}
-
-func addInt64Field(form *tview.Form, label string, value int64, onChange func(int64)) {
-	form.AddInputField(label, fmt.Sprintf("%d", value), 16, nil, func(text string) {
-		var parsed int64
-		if _, err := fmt.Sscanf(strings.TrimSpace(text), "%d", &parsed); err == nil {
-			onChange(parsed)
-		}
-	})
-}
-
-func channelItem(label, description string, enabled bool, action MenuAction) MenuItem {
-	item := MenuItem{
-		Label:       label,
-		Description: description,
-		Action:      action,
-	}
-	if !enabled {
-		color := tcell.ColorGray
-		item.MainColor = &color
-	}
-	return item
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/gateway_posix.go b/cmd/picoclaw-launcher-tui/internal/ui/gateway_posix.go
deleted file mode 100644
index bc874f7f2..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/gateway_posix.go
+++ /dev/null
@@ -1,16 +0,0 @@
-//go:build !windows
-// +build !windows
-
-package ui
-
-import "os/exec"
-
-func isGatewayProcessRunning() bool {
-	cmd := exec.Command("sh", "-c", "pgrep -f 'picoclaw\\s+gateway' >/dev/null 2>&1")
-	return cmd.Run() == nil
-}
-
-func stopGatewayProcess() error {
-	cmd := exec.Command("sh", "-c", "pkill -f 'picoclaw\\s+gateway' >/dev/null 2>&1")
-	return cmd.Run()
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/gateway_windows.go b/cmd/picoclaw-launcher-tui/internal/ui/gateway_windows.go
deleted file mode 100644
index 7067a5c13..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/gateway_windows.go
+++ /dev/null
@@ -1,16 +0,0 @@
-//go:build windows
-// +build windows
-
-package ui
-
-import "os/exec"
-
-func isGatewayProcessRunning() bool {
-	cmd := exec.Command("tasklist", "/FI", "IMAGENAME eq picoclaw.exe")
-	return cmd.Run() == nil
-}
-
-func stopGatewayProcess() error {
-	cmd := exec.Command("taskkill", "/F", "/IM", "picoclaw.exe")
-	return cmd.Run()
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/menu.go b/cmd/picoclaw-launcher-tui/internal/ui/menu.go
deleted file mode 100644
index 9f2132c5a..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/menu.go
+++ /dev/null
@@ -1,72 +0,0 @@
-package ui
-
-import (
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-)
-
-type MenuAction func()
-
-type MenuItem struct {
-	Label       string
-	Description string
-	Action      MenuAction
-	Disabled    bool
-	MainColor   *tcell.Color
-	DescColor   *tcell.Color
-}
-
-type Menu struct {
-	*tview.Table
-	items []MenuItem
-}
-
-func NewMenu(title string, items []MenuItem) *Menu {
-	table := tview.NewTable().SetSelectable(true, false)
-	table.SetBorder(true).SetTitle(title)
-	table.SetBorders(false)
-	menu := &Menu{Table: table, items: items}
-	menu.applyItems(items)
-	menu.SetSelectedFunc(func(row, _ int) {
-		if row < 0 || row >= len(menu.items) {
-			return
-		}
-		item := menu.items[row]
-		if item.Disabled || item.Action == nil {
-			return
-		}
-		item.Action()
-	})
-	menu.SetSelectedStyle(
-		tcell.StyleDefault.Foreground(tview.Styles.InverseTextColor).
-			Background(tcell.NewRGBColor(189, 147, 249)),
-	)
-	return menu
-}
-
-func (m *Menu) applyItems(items []MenuItem) {
-	m.items = items
-	m.Clear()
-	for row, item := range items {
-		label := item.Label
-		if item.Disabled && label != "" {
-			label = label + " (disabled)"
-		}
-		left := tview.NewTableCell(label)
-		right := tview.NewTableCell(item.Description).SetAlign(tview.AlignRight)
-		if item.MainColor != nil {
-			left.SetTextColor(*item.MainColor)
-		}
-		if item.DescColor != nil {
-			right.SetTextColor(*item.DescColor)
-		} else {
-			right.SetTextColor(tview.Styles.TertiaryTextColor)
-		}
-		if item.Disabled {
-			left.SetTextColor(tcell.ColorGray)
-			right.SetTextColor(tcell.ColorGray)
-		}
-		m.SetCell(row, 0, left)
-		m.SetCell(row, 1, right)
-	}
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/model.go b/cmd/picoclaw-launcher-tui/internal/ui/model.go
deleted file mode 100644
index ba91f5b09..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/model.go
+++ /dev/null
@@ -1,343 +0,0 @@
-package ui
-
-import (
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-	"time"
-
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-
-	picoclawconfig "github.com/sipeed/picoclaw/pkg/config"
-)
-
-func (s *appState) modelMenu() tview.Primitive {
-	items := make([]MenuItem, 0, 2+len(s.config.ModelList))
-	items = append(items,
-		MenuItem{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
-		MenuItem{
-			Label:       "Add model",
-			Description: "Append a new model entry",
-			Action: func() {
-				s.addModel(
-					picoclawconfig.ModelConfig{ModelName: "new-model", Model: "openai/gpt-5.2"},
-				)
-				s.push(
-					fmt.Sprintf("model-%d", len(s.config.ModelList)-1),
-					s.modelForm(len(s.config.ModelList)-1),
-				)
-			},
-		},
-	)
-	currentModel := strings.TrimSpace(s.config.Agents.Defaults.Model)
-	for i := range s.config.ModelList {
-		index := i
-		model := s.config.ModelList[i]
-		isValid := isModelValid(model)
-		desc := model.APIBase
-		if desc == "" {
-			desc = model.AuthMethod
-		}
-		if desc == "" {
-			desc = "api_key required"
-		}
-		label := fmt.Sprintf("%s (%s)", model.ModelName, model.Model)
-		if model.ModelName == currentModel && currentModel != "" {
-			label = "* " + label
-		}
-		isSelected := model.ModelName == currentModel && currentModel != ""
-		items = append(items, MenuItem{
-			Label:       label,
-			Description: desc,
-			MainColor:   modelStatusColor(isValid, isSelected),
-			Action: func() {
-				s.push(fmt.Sprintf("model-%d", index), s.modelForm(index))
-			},
-		})
-	}
-
-	menu := NewMenu("Models", items)
-	menu.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEsc {
-			s.pop()
-			return nil
-		}
-		if event.Rune() == 'q' {
-			s.pop()
-			return nil
-		}
-		if event.Rune() == ' ' {
-			row, _ := menu.GetSelection()
-			if row > 0 && row <= len(s.config.ModelList) {
-				model := s.config.ModelList[row-1]
-				if !isModelValid(model) {
-					s.showMessage(
-						"Invalid model",
-						"Select a model with api_key or oauth auth_method",
-					)
-					return nil
-				}
-				s.config.Agents.Defaults.Model = model.ModelName
-				s.dirty = true
-				refreshModelMenu(menu, s.config.Agents.Defaults.Model, s.config.ModelList)
-				refreshMainMenuIfPresent(s)
-			}
-			return nil
-		}
-		return event
-	})
-	return menu
-}
-
-func (s *appState) modelForm(index int) tview.Primitive {
-	model := &s.config.ModelList[index]
-	form := tview.NewForm()
-	form.SetBorder(true).SetTitle(fmt.Sprintf("Model: %s", model.ModelName))
-	form.SetButtonBackgroundColor(tcell.NewRGBColor(80, 250, 123))
-	form.SetButtonTextColor(tcell.NewRGBColor(12, 13, 22))
-
-	addInput(form, "Model Name", model.ModelName, func(value string) {
-		model.ModelName = value
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["model"]; ok {
-			refreshModelMenuFromState(menu, s)
-		}
-	})
-	addInput(form, "Model", model.Model, func(value string) {
-		model.Model = value
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["model"]; ok {
-			refreshModelMenuFromState(menu, s)
-		}
-	})
-	addInput(form, "API Base", model.APIBase, func(value string) {
-		model.APIBase = value
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["model"]; ok {
-			refreshModelMenuFromState(menu, s)
-		}
-	})
-	addInput(form, "API Key", model.APIKey, func(value string) {
-		model.APIKey = value
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["model"]; ok {
-			refreshModelMenuFromState(menu, s)
-		}
-	})
-	addInput(form, "Proxy", model.Proxy, func(value string) {
-		model.Proxy = value
-	})
-	addInput(form, "Auth Method", model.AuthMethod, func(value string) {
-		model.AuthMethod = value
-		s.dirty = true
-		refreshMainMenuIfPresent(s)
-		if menu, ok := s.menus["model"]; ok {
-			refreshModelMenuFromState(menu, s)
-		}
-	})
-	addInput(form, "Connect Mode", model.ConnectMode, func(value string) {
-		model.ConnectMode = value
-	})
-	addInput(form, "Workspace", model.Workspace, func(value string) {
-		model.Workspace = value
-	})
-	addInput(form, "Max Tokens Field", model.MaxTokensField, func(value string) {
-		model.MaxTokensField = value
-	})
-	addIntInput(form, "RPM", model.RPM, func(value int) {
-		model.RPM = value
-	})
-	addIntInput(form, "Request Timeout", model.RequestTimeout, func(value int) {
-		model.RequestTimeout = value
-	})
-
-	form.AddButton("Delete", func() {
-		s.deleteModel(index)
-	})
-	form.AddButton("Test", func() {
-		s.testModel(model)
-	})
-	form.AddButton("Back", func() {
-		s.pop()
-	})
-
-	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
-		if event.Key() == tcell.KeyEsc {
-			s.pop()
-			return nil
-		}
-		return event
-	})
-	return form
-}
-
-func addInput(form *tview.Form, label, value string, onChange func(string)) {
-	form.AddInputField(label, value, 128, nil, func(text string) {
-		onChange(strings.TrimSpace(text))
-	})
-}
-
-func addIntInput(form *tview.Form, label string, value int, onChange func(int)) {
-	form.AddInputField(label, fmt.Sprintf("%d", value), 16, nil, func(text string) {
-		var parsed int
-		if _, err := fmt.Sscanf(strings.TrimSpace(text), "%d", &parsed); err == nil {
-			onChange(parsed)
-		}
-	})
-}
-
-func (s *appState) addModel(model picoclawconfig.ModelConfig) {
-	s.config.ModelList = append(s.config.ModelList, model)
-}
-
-func (s *appState) deleteModel(index int) {
-	if index < 0 || index >= len(s.config.ModelList) {
-		return
-	}
-	s.config.ModelList = append(s.config.ModelList[:index], s.config.ModelList[index+1:]...)
-	s.pop()
-}
-
-func modelStatusColor(valid bool, selected bool) *tcell.Color {
-	if valid {
-		color := tview.Styles.PrimaryTextColor
-		return &color
-	}
-	color := tcell.ColorGray
-	return &color
-}
-
-func refreshModelMenu(menu *Menu, currentModel string, models []picoclawconfig.ModelConfig) {
-	for i, model := range models {
-		row := i + 1
-		label := fmt.Sprintf("%s (%s)", model.ModelName, model.Model)
-		isValid := isModelValid(model)
-		if model.ModelName == currentModel && currentModel != "" {
-			label = "* " + label
-		}
-		cell := menu.GetCell(row, 0)
-		if cell != nil {
-			cell.SetText(label)
-			isSelected := model.ModelName == currentModel && currentModel != ""
-			color := modelStatusColor(isValid, isSelected)
-			if color != nil {
-				cell.SetTextColor(*color)
-			}
-		}
-	}
-}
-
-func refreshModelMenuFromState(menu *Menu, s *appState) {
-	items := make([]MenuItem, 0, 2+len(s.config.ModelList))
-	items = append(items,
-		MenuItem{Label: "Back", Description: "Return to main menu", Action: func() { s.pop() }},
-		MenuItem{
-			Label:       "Add model",
-			Description: "Append a new model entry",
-			Action: func() {
-				s.addModel(
-					picoclawconfig.ModelConfig{ModelName: "new-model", Model: "openai/gpt-5.2"},
-				)
-				s.push(
-					fmt.Sprintf("model-%d", len(s.config.ModelList)-1),
-					s.modelForm(len(s.config.ModelList)-1),
-				)
-			},
-		},
-	)
-	currentModel := strings.TrimSpace(s.config.Agents.Defaults.Model)
-	for i := range s.config.ModelList {
-		index := i
-		model := s.config.ModelList[i]
-		isValid := isModelValid(model)
-		desc := model.APIBase
-		if desc == "" {
-			desc = model.AuthMethod
-		}
-		if desc == "" {
-			desc = "api_key required"
-		}
-		label := fmt.Sprintf("%s (%s)", model.ModelName, model.Model)
-		if model.ModelName == currentModel && currentModel != "" {
-			label = "* " + label
-		}
-		isSelected := model.ModelName == currentModel && currentModel != ""
-		items = append(items, MenuItem{
-			Label:       label,
-			Description: desc,
-			MainColor:   modelStatusColor(isValid, isSelected),
-			Action: func() {
-				s.push(fmt.Sprintf("model-%d", index), s.modelForm(index))
-			},
-		})
-	}
-	menu.applyItems(items)
-}
-
-func isModelValid(model picoclawconfig.ModelConfig) bool {
-	hasKey := strings.TrimSpace(model.APIKey) != "" ||
-		strings.TrimSpace(model.AuthMethod) == "oauth"
-	hasModel := strings.TrimSpace(model.Model) != ""
-	return hasKey && hasModel
-}
-
-func (s *appState) testModel(model *picoclawconfig.ModelConfig) {
-	if model == nil {
-		return
-	}
-	if strings.TrimSpace(model.APIKey) == "" {
-		s.showMessage("Missing API Key", "Set api_key before testing")
-		return
-	}
-	base := strings.TrimSpace(model.APIBase)
-	if base == "" {
-		s.showMessage("Missing API Base", "Set api_base before testing")
-		return
-	}
-	modelID := strings.TrimSpace(model.Model)
-	if modelID == "" {
-		s.showMessage("Missing Model", "Set model before testing")
-		return
-	}
-	if !strings.HasPrefix(modelID, "openai/") {
-		s.showMessage("Unsupported model", "Only openai/* models are supported for test")
-		return
-	}
-	modelName := strings.TrimPrefix(modelID, "openai/")
-	endpoint := strings.TrimRight(base, "/") + "/chat/completions"
-
-	payload := fmt.Sprintf(
-		`{"model":"%s","messages":[{"role":"user","content":"ping"}],"max_tokens":1}`,
-		modelName,
-	)
-	client := &http.Client{Timeout: 10 * time.Second}
-	request, err := http.NewRequest("POST", endpoint, strings.NewReader(payload))
-	if err != nil {
-		s.showMessage("Test failed", err.Error())
-		return
-	}
-	request.Header.Set("Content-Type", "application/json")
-	request.Header.Set("Authorization", "Bearer "+strings.TrimSpace(model.APIKey))
-
-	resp, err := client.Do(request)
-	if err != nil {
-		s.showMessage("Test failed", err.Error())
-		return
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode >= 200 && resp.StatusCode < 300 {
-		s.showMessage("Test OK", resp.Status)
-		return
-	}
-	body, _ := io.ReadAll(io.LimitReader(resp.Body, 2048))
-	s.showMessage(
-		"Test failed",
-		fmt.Sprintf("%s: %s", resp.Status, strings.TrimSpace(string(body))),
-	)
-}
diff --git a/cmd/picoclaw-launcher-tui/internal/ui/style.go b/cmd/picoclaw-launcher-tui/internal/ui/style.go
deleted file mode 100644
index ff4f8b1a8..000000000
--- a/cmd/picoclaw-launcher-tui/internal/ui/style.go
+++ /dev/null
@@ -1,37 +0,0 @@
-package ui
-
-import (
-	"github.com/gdamore/tcell/v2"
-	"github.com/rivo/tview"
-)
-
-func applyStyles() {
-	tview.Styles.PrimitiveBackgroundColor = tcell.NewRGBColor(12, 13, 22)
-	tview.Styles.ContrastBackgroundColor = tcell.NewRGBColor(34, 19, 53)
-	tview.Styles.MoreContrastBackgroundColor = tcell.NewRGBColor(18, 18, 32)
-	tview.Styles.BorderColor = tcell.NewRGBColor(112, 102, 255)
-	tview.Styles.TitleColor = tcell.NewRGBColor(255, 121, 198)
-	tview.Styles.GraphicsColor = tcell.NewRGBColor(139, 233, 253)
-	tview.Styles.PrimaryTextColor = tcell.NewRGBColor(241, 250, 255)
-	tview.Styles.SecondaryTextColor = tcell.NewRGBColor(80, 250, 123)
-	tview.Styles.TertiaryTextColor = tcell.NewRGBColor(139, 233, 253)
-	tview.Styles.InverseTextColor = tcell.NewRGBColor(12, 13, 22)
-	tview.Styles.ContrastSecondaryTextColor = tcell.NewRGBColor(189, 147, 249)
-}
-
-func bannerView() *tview.TextView {
-	text := tview.NewTextView()
-	text.SetDynamicColors(true)
-	text.SetTextAlign(tview.AlignCenter)
-	text.SetBackgroundColor(tview.Styles.PrimitiveBackgroundColor)
-	text.SetText(
-		"[::b][#84aaff]██████╗ ██╗ ██████╗ ██████╗  ██████╗██╗      █████╗ ██╗    ██╗\n" +
-			"[#84aaff]██╔══██╗██║██╔════╝██╔═══██╗██╔════╝██║     ██╔══██╗██║    ██║\n" +
-			"[#84aaff]██████╔╝██║██║     ██║   ██║██║     ██║     ███████║██║ █╗ ██║\n" +
-			"[#84aaff]██╔═══╝ ██║██║     ██║   ██║██║     ██║     ██╔══██║██║███╗██║\n" +
-			"[#84aaff]██║     ██║╚██████╗╚██████╔╝╚██████╗███████╗██║  ██║╚███╔███╔╝\n" +
-			"[#84aaff]╚═╝     ╚═╝ ╚═════╝ ╚═════╝  ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝",
-	)
-	text.SetBorder(false)
-	return text
-}
diff --git a/cmd/picoclaw-launcher-tui/main.go b/cmd/picoclaw-launcher-tui/main.go
index 0e8cce415..3cb7110c1 100644
--- a/cmd/picoclaw-launcher-tui/main.go
+++ b/cmd/picoclaw-launcher-tui/main.go
@@ -1,15 +1,48 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
 package main
 
 import (
 	"fmt"
 	"os"
+	"os/exec"
+	"path/filepath"
 
-	"github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/internal/ui"
+	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
+	"github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/ui"
 )
 
 func main() {
-	if err := ui.Run(); err != nil {
-		fmt.Fprintln(os.Stderr, err)
+	configPath := tuicfg.DefaultConfigPath()
+	if len(os.Args) > 1 {
+		configPath = os.Args[1]
+	}
+
+	configDir := filepath.Dir(configPath)
+	if _, err := os.Stat(configDir); os.IsNotExist(err) {
+		cmd := exec.Command("picoclaw", "onboard")
+		cmd.Stdin = os.Stdin
+		cmd.Stdout = os.Stdout
+		cmd.Stderr = os.Stderr
+		_ = cmd.Run()
+	}
+
+	cfg, err := tuicfg.Load(configPath)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "picoclaw-launcher-tui: %v\n", err)
+		os.Exit(1)
+	}
+
+	app := ui.New(cfg, configPath)
+	// Bind model selection hook to sync to main config
+	app.OnModelSelected = func(scheme tuicfg.Scheme, user tuicfg.User, modelID string) {
+		_ = tuicfg.SyncSelectedModelToMainConfig(scheme, user, modelID)
+	}
+	if err := app.Run(); err != nil {
+		fmt.Fprintf(os.Stderr, "picoclaw-launcher-tui: %v\n", err)
 		os.Exit(1)
 	}
 }
diff --git a/cmd/picoclaw-launcher-tui/ui/app.go b/cmd/picoclaw-launcher-tui/ui/app.go
new file mode 100644
index 000000000..a65693b01
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/app.go
@@ -0,0 +1,325 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+	"fmt"
+	"sync"
+
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+
+	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
+)
+
+// App is the root TUI application.
+type App struct {
+	tapp           *tview.Application
+	pages          *tview.Pages
+	pageStack      []string
+	cfg            *tuicfg.TUIConfig
+	configPath     string
+	pageRefreshFns map[string]func()
+	headerModelTV  *tview.TextView
+	modalOpen      map[string]bool
+
+	// OnModelSelected is called when a model is selected in the UI.
+	// Can be nil to disable.
+	OnModelSelected func(scheme tuicfg.Scheme, user tuicfg.User, modelID string)
+
+	modelCache   map[string][]modelEntry
+	modelCacheMu sync.RWMutex
+	refreshMu    sync.Mutex
+}
+
+// cacheKey returns the map key for a (scheme, user) pair.
+func cacheKey(schemeName, userName string) string {
+	return fmt.Sprintf("%s/%s", schemeName, userName)
+}
+
+// cachedModels returns a defensive copy of the cached model list for a user (may be nil).
+func (a *App) cachedModels(schemeName, userName string) []modelEntry {
+	a.modelCacheMu.RLock()
+	defer a.modelCacheMu.RUnlock()
+	entries := a.modelCache[cacheKey(schemeName, userName)]
+	return append([]modelEntry(nil), entries...)
+}
+
+// refreshModelCache fetches models for every user in the config concurrently.
+// Serialized by refreshMu so concurrent calls don't race on the cache map.
+// When all fetches complete it calls onDone via QueueUpdateDraw.
+func (a *App) refreshModelCache(onDone func()) {
+	go func() {
+		a.refreshMu.Lock()
+		defer a.refreshMu.Unlock()
+
+		users := a.cfg.Provider.Users
+		schemes := a.cfg.Provider.Schemes
+
+		schemeURL := make(map[string]string, len(schemes))
+		for _, s := range schemes {
+			schemeURL[s.Name] = s.BaseURL
+		}
+
+		var wg sync.WaitGroup
+		for _, u := range users {
+			baseURL, ok := schemeURL[u.Scheme]
+			if !ok || baseURL == "" {
+				continue
+			}
+			if u.Key == "" {
+				a.modelCacheMu.Lock()
+				if a.modelCache == nil {
+					a.modelCache = make(map[string][]modelEntry)
+				}
+				a.modelCache[cacheKey(u.Scheme, u.Name)] = nil
+				a.modelCacheMu.Unlock()
+				continue
+			}
+			wg.Add(1)
+			bURL := baseURL
+			go func() {
+				defer wg.Done()
+				entries, err := fetchModels(bURL, u.Key)
+				a.modelCacheMu.Lock()
+				if a.modelCache == nil {
+					a.modelCache = make(map[string][]modelEntry)
+				}
+				if err != nil || len(entries) == 0 {
+					a.modelCache[cacheKey(u.Scheme, u.Name)] = nil
+				} else {
+					a.modelCache[cacheKey(u.Scheme, u.Name)] = entries
+				}
+				a.modelCacheMu.Unlock()
+			}()
+		}
+		wg.Wait()
+
+		if onDone != nil {
+			a.tapp.QueueUpdateDraw(onDone)
+		}
+	}()
+}
+
+// New creates and wires up the TUI application.
+func New(cfg *tuicfg.TUIConfig, configPath string) *App {
+	// Cyberpunk Theme Colors
+	// Dark background
+	tview.Styles.PrimitiveBackgroundColor = tcell.NewHexColor(0x050510) // Deep Void
+	tview.Styles.ContrastBackgroundColor = tcell.NewHexColor(0x1a1a2e)  // Dark Indigo
+	tview.Styles.MoreContrastBackgroundColor = tcell.NewHexColor(0x2a2a40)
+
+	// Borders and Titles
+	tview.Styles.BorderColor = tcell.NewHexColor(0x00f0ff)   // Neon Cyan
+	tview.Styles.TitleColor = tcell.NewHexColor(0x00f0ff)    // Neon Cyan
+	tview.Styles.GraphicsColor = tcell.NewHexColor(0xff00ff) // Neon Magenta
+
+	// Text
+	tview.Styles.PrimaryTextColor = tcell.NewHexColor(0xe0e0e0)           // Off-white
+	tview.Styles.SecondaryTextColor = tcell.NewHexColor(0x00f0ff)         // Neon Cyan
+	tview.Styles.TertiaryTextColor = tcell.NewHexColor(0x39ff14)          // Neon Lime
+	tview.Styles.InverseTextColor = tcell.NewHexColor(0x000000)           // Black
+	tview.Styles.ContrastSecondaryTextColor = tcell.NewHexColor(0xff00ff) // Neon Magenta
+
+	a := &App{
+		tapp:           tview.NewApplication(),
+		pages:          tview.NewPages(),
+		pageStack:      []string{},
+		cfg:            cfg,
+		configPath:     configPath,
+		pageRefreshFns: make(map[string]func()),
+		modalOpen:      make(map[string]bool),
+	}
+
+	a.tapp.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEscape {
+			if len(a.modalOpen) > 0 {
+				return event
+			}
+			return a.goBack()
+		}
+		return event
+	})
+
+	a.buildPages()
+	return a
+}
+
+// Run starts the TUI event loop.
+func (a *App) Run() error {
+	return a.tapp.SetRoot(a.pages, true).EnableMouse(true).Run()
+}
+
+func (a *App) buildPages() {
+	a.pages.AddPage("home", a.newHomePage(), true, true)
+	a.pageStack = []string{"home"}
+}
+
+func (a *App) navigateTo(name string, page tview.Primitive) {
+	a.pages.RemovePage(name)
+	a.pages.AddPage(name, page, true, false)
+	a.pageStack = append(a.pageStack, name)
+	a.pages.SwitchToPage(name)
+}
+
+func (a *App) goBack() *tcell.EventKey {
+	if len(a.pageStack) <= 1 {
+		return nil
+	}
+	popped := a.pageStack[len(a.pageStack)-1]
+	a.pageStack = a.pageStack[:len(a.pageStack)-1]
+	a.pages.RemovePage(popped)
+	prev := a.pageStack[len(a.pageStack)-1]
+	if fn, ok := a.pageRefreshFns[prev]; ok {
+		fn()
+	}
+	if prev == "home" && a.headerModelTV != nil {
+		a.headerModelTV.SetText(a.cfg.CurrentModelLabel() + "  ")
+	}
+	a.pages.SwitchToPage(prev)
+	return nil
+}
+
+func (a *App) showModal(name string, primitive tview.Primitive) {
+	a.modalOpen[name] = true
+	a.pages.AddPage(name, primitive, true, true)
+}
+
+func (a *App) hideModal(name string) {
+	delete(a.modalOpen, name)
+	a.pages.HidePage(name)
+	a.pages.RemovePage(name)
+}
+
+func (a *App) save() {
+	if err := tuicfg.Save(a.configPath, a.cfg); err != nil {
+		a.showError("save failed: " + err.Error())
+	}
+}
+
+func (a *App) showError(msg string) {
+	modal := tview.NewModal().
+		SetText(" [red::b]ERROR[-::-]\n\n" + msg).
+		AddButtons([]string{"OK"}).
+		SetDoneFunc(func(_ int, _ string) {
+			a.hideModal("error")
+		})
+	// Cyberpunk Modal Style
+	modal.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))       // Deep Indigo
+	modal.SetTextColor(tcell.NewHexColor(0xffffff))             // White
+	modal.SetButtonBackgroundColor(tcell.NewHexColor(0xff2a2a)) // Neon Red
+	modal.SetButtonTextColor(tcell.NewHexColor(0xffffff))       // White
+	a.showModal("error", modal)
+}
+
+func (a *App) confirmDelete(label string, onConfirm func()) {
+	modal := tview.NewModal().
+		SetText(" [red::b]DELETE WARNING[-::-]\n\nDelete " + label + "?\n[gray]This action cannot be undone.[-]").
+		AddButtons([]string{"Delete", "Cancel"}).
+		SetDoneFunc(func(_ int, buttonLabel string) {
+			a.hideModal("confirm-delete")
+			if buttonLabel == "Delete" {
+				onConfirm()
+			}
+		})
+	// Cyberpunk Modal Style
+	modal.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))       // Deep Indigo
+	modal.SetTextColor(tcell.NewHexColor(0xffffff))             // White
+	modal.SetButtonBackgroundColor(tcell.NewHexColor(0xff2a2a)) // Neon Red for danger
+	modal.SetButtonTextColor(tcell.NewHexColor(0xffffff))       // White
+	a.showModal("confirm-delete", modal)
+}
+
+func centeredForm(form *tview.Form, widthPct, height int) tview.Primitive {
+	return tview.NewFlex().
+		AddItem(tview.NewBox(), 0, 1, false).
+		AddItem(tview.NewFlex().SetDirection(tview.FlexRow).
+			AddItem(tview.NewBox(), 0, 1, false).
+			AddItem(form, height, 1, true).
+			AddItem(tview.NewBox(), 0, 1, false), 0, widthPct, true).
+		AddItem(tview.NewBox(), 0, 1, false)
+}
+
+func hintBar(text string) *tview.TextView {
+	tv := tview.NewTextView().
+		SetText(text).
+		SetDynamicColors(true).
+		SetTextAlign(tview.AlignCenter).
+		SetTextColor(tcell.NewHexColor(0x00f0ff)) // Neon Cyan
+	tv.SetBackgroundColor(tcell.NewHexColor(0x2a2a40)) // Darker Indigo
+	return tv
+}
+
+func (a *App) buildShell(pageID string, content tview.Primitive, hint string) tview.Primitive {
+	var modelTV *tview.TextView
+	if pageID == "home" {
+		if a.headerModelTV == nil {
+			a.headerModelTV = tview.NewTextView()
+			a.headerModelTV.SetTextAlign(tview.AlignRight).
+				SetTextColor(tcell.NewHexColor(0x39ff14)). // Neon Lime
+				SetDynamicColors(true).
+				SetBackgroundColor(tcell.NewHexColor(0x050510))
+		}
+		modelTV = a.headerModelTV
+		modelTV.SetText("MODEL: " + a.cfg.CurrentModelLabel() + " ")
+	} else {
+		modelTV = tview.NewTextView()
+		modelTV.SetBackgroundColor(tcell.NewHexColor(0x050510))
+	}
+
+	headerLeft := tview.NewTextView().
+		SetText(" [#ff00ff::b]///[#00f0ff] PICOCLAW LAUNCHER [#ff00ff]///").
+		SetDynamicColors(true).
+		SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+	header := tview.NewFlex().
+		AddItem(headerLeft, 0, 1, false).
+		AddItem(modelTV, 0, 1, false)
+
+	sidebar := tview.NewTextView().
+		SetDynamicColors(true).
+		SetWrap(false)
+	sidebar.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e)) // Deep Indigo
+
+	// Cyberpunk Sidebar Styling
+	activePrefix := "[#39ff14::b]>> " // Neon Lime arrow
+	activeSuffix := "[-]"
+	inactivePrefix := "[#808080]   "
+	inactiveSuffix := "[-]"
+
+	sbText := "\n\n" // Top padding
+
+	menuItem := func(id, label string) string {
+		if pageID == id {
+			return activePrefix + label + activeSuffix + "\n\n"
+		}
+		return inactivePrefix + label + inactiveSuffix + "\n\n"
+	}
+
+	sbText += menuItem("home", "HOME")
+	sbText += menuItem("schemes", "SCHEMES")
+	sbText += menuItem("users", "USERS")
+	sbText += menuItem("models", "MODELS")
+	sbText += menuItem("channels", "CHANNELS")
+	sbText += menuItem("gateway", "GATEWAY")
+
+	sidebar.SetText(sbText)
+
+	footer := hintBar(hint)
+
+	grid := tview.NewGrid().
+		SetRows(1, 0, 1).
+		SetColumns(20, 0). // Slightly wider sidebar
+		AddItem(header, 0, 0, 1, 2, 0, 0, false).
+		AddItem(sidebar, 1, 0, 1, 1, 0, 0, false).
+		AddItem(content, 1, 1, 1, 1, 0, 0, true).
+		AddItem(footer, 2, 0, 1, 2, 0, 0, false)
+
+	// Add a border around the content area if possible, or ensure content has its own border
+	// grid.SetBorders(false) // Grid borders usually look bad, handled by components
+
+	return grid
+}
diff --git a/cmd/picoclaw-launcher-tui/ui/channels.go b/cmd/picoclaw-launcher-tui/ui/channels.go
new file mode 100644
index 000000000..c976f1fcd
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/channels.go
@@ -0,0 +1,202 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strconv"
+
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+)
+
+func (a *App) newChannelsPage() tview.Primitive {
+	list := tview.NewList()
+	list.SetBorder(true).
+		SetTitle(" [#00f0ff::b] COMMUNICATION CHANNELS ").
+		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
+		SetBorderColor(tcell.NewHexColor(0x00f0ff))
+	list.SetMainTextColor(tcell.NewHexColor(0xe0e0e0))
+	list.SetSecondaryTextColor(tcell.NewHexColor(0x808080))
+	list.SetSelectedStyle(
+		tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0x050510)),
+	)
+	list.SetHighlightFullLine(true)
+	list.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+	rebuild := func() {
+		sel := list.GetCurrentItem()
+		list.Clear()
+
+		home, err := os.UserHomeDir()
+		if err != nil {
+			home = "."
+		}
+		configPath := filepath.Join(home, ".picoclaw", "config.json")
+
+		var cfg map[string]any
+		if data, err := os.ReadFile(configPath); err == nil {
+			_ = json.Unmarshal(data, &cfg)
+		}
+
+		if chRaw, ok := cfg["channels"].(map[string]any); ok {
+			for name, ch := range chRaw {
+				chMap, ok := ch.(map[string]any)
+				enabled := "disabled"
+				if ok {
+					if e, ok := chMap["enabled"].(bool); ok && e {
+						enabled = "enabled"
+					}
+				}
+				list.AddItem(name, fmt.Sprintf("Status: %s", enabled), 0, func() {
+					a.showChannelEditForm(configPath, name, chMap)
+				})
+			}
+		}
+
+		if sel >= 0 && sel < list.GetItemCount() {
+			list.SetCurrentItem(sel)
+		}
+	}
+	rebuild()
+
+	a.pageRefreshFns["channels"] = rebuild
+
+	list.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEscape {
+			return a.goBack()
+		}
+		return event
+	})
+
+	return a.buildShell("channels", list, " [#ff00ff]Enter:[-] edit  [#ff2a2a]ESC:[-] back ")
+}
+
+func (a *App) showChannelEditForm(configPath, channelName string, existing map[string]any) {
+	form := tview.NewForm()
+	form.SetBorder(true).
+		SetTitle(" [::b]EDIT CHANNEL ").
+		SetTitleColor(tcell.NewHexColor(0x39ff14)).
+		SetBorderColor(tcell.NewHexColor(0x00f0ff))
+	form.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))
+	form.SetFieldBackgroundColor(tcell.NewHexColor(0x050510))
+	form.SetFieldTextColor(tcell.NewHexColor(0x00f0ff))
+	form.SetLabelColor(tcell.NewHexColor(0xe0e0e0))
+	form.SetButtonBackgroundColor(tcell.NewHexColor(0xff00ff))
+	form.SetButtonTextColor(tcell.NewHexColor(0xffffff))
+
+	fields := make(map[string]*tview.InputField)
+	var nameField *tview.InputField
+
+	if channelName == "" {
+		nameField = tview.NewInputField().
+			SetLabel("Channel Name").
+			SetText("").
+			SetFieldWidth(28)
+		form.AddFormItem(nameField)
+	}
+
+	for k, v := range existing {
+		if reflect.ValueOf(v).Kind() == reflect.Map || reflect.ValueOf(v).Kind() == reflect.Slice {
+			continue
+		}
+		valStr := fmt.Sprintf("%v", v)
+		field := tview.NewInputField().
+			SetLabel(k).
+			SetText(valStr).
+			SetFieldWidth(28)
+		form.AddFormItem(field)
+		fields[k] = field
+	}
+
+	form.AddButton("SAVE", func() {
+		var cfg map[string]any
+		if data, err := os.ReadFile(configPath); err == nil {
+			if err := json.Unmarshal(data, &cfg); err != nil {
+				cfg = make(map[string]any)
+			}
+		} else {
+			cfg = make(map[string]any)
+		}
+
+		if _, ok := cfg["channels"]; !ok {
+			cfg["channels"] = make(map[string]any)
+		}
+		channels, ok := cfg["channels"].(map[string]any)
+		if !ok {
+			channels = make(map[string]any)
+			cfg["channels"] = channels
+		}
+
+		finalName := channelName
+		if channelName == "" {
+			if nameField == nil || nameField.GetText() == "" {
+				a.showError("Channel name is required")
+				return
+			}
+			finalName = nameField.GetText()
+		}
+
+		updated := make(map[string]any)
+		if existing != nil {
+			for k, v := range existing {
+				updated[k] = v
+			}
+		}
+		for k, field := range fields {
+			val := field.GetText()
+			if val == "true" {
+				updated[k] = true
+			} else if val == "false" {
+				updated[k] = false
+			} else if num, err := strconv.Atoi(val); err == nil {
+				updated[k] = num
+			} else {
+				updated[k] = val
+			}
+		}
+
+		if channelName != "" && finalName != channelName {
+			delete(channels, channelName)
+		}
+		channels[finalName] = updated
+
+		data, err := json.MarshalIndent(cfg, "", "  ")
+		if err != nil {
+			a.showError(fmt.Sprintf("Failed to save config: %v", err))
+			return
+		}
+		if err := os.MkdirAll(filepath.Dir(configPath), 0o700); err != nil {
+			a.showError(fmt.Sprintf("Failed to create config directory: %v", err))
+			return
+		}
+		if err := os.WriteFile(configPath, data, 0o600); err != nil {
+			a.showError(fmt.Sprintf("Failed to write config: %v", err))
+			return
+		}
+
+		a.hideModal("channel-edit")
+		a.goBack()
+	})
+
+	form.AddButton("CANCEL", func() {
+		a.hideModal("channel-edit")
+	})
+
+	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEscape {
+			a.hideModal("channel-edit")
+			return nil
+		}
+		return event
+	})
+
+	a.showModal("channel-edit", centeredForm(form, 4, 20))
+}
diff --git a/cmd/picoclaw-launcher-tui/ui/gateway.go b/cmd/picoclaw-launcher-tui/ui/gateway.go
new file mode 100644
index 000000000..1138c12db
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/gateway.go
@@ -0,0 +1,261 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+)
+
+const pidFileName = "gateway.pid"
+
+type gatewayStatus struct {
+	running bool
+	pid     int
+}
+
+func getPidPath() string {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		home = "."
+	}
+	return filepath.Join(home, ".picoclaw", pidFileName)
+}
+
+func isProcessRunning(pid int) bool {
+	if runtime.GOOS == "windows" {
+		cmd := exec.Command("tasklist", "/FI", fmt.Sprintf("PID eq %d", pid))
+		output, err := cmd.Output()
+		if err != nil {
+			return false
+		}
+		return strings.Contains(string(output), strconv.Itoa(pid))
+	} else if runtime.GOOS == "darwin" {
+		cmd := exec.Command("ps", "aux")
+		output, err := cmd.Output()
+		if err != nil {
+			return false
+		}
+		return strings.Contains(string(output), fmt.Sprintf(" %d ", pid))
+	}
+	// Linux
+	_, err := os.Stat(fmt.Sprintf("/proc/%d", pid))
+	return err == nil
+}
+
+func getGatewayStatus() gatewayStatus {
+	pidPath := getPidPath()
+	data, err := os.ReadFile(pidPath)
+	if err != nil {
+		return gatewayStatus{running: false}
+	}
+	pid, err := strconv.Atoi(strings.TrimSpace(string(data)))
+	if err != nil {
+		return gatewayStatus{running: false}
+	}
+	if !isProcessRunning(pid) {
+		os.Remove(pidPath)
+		return gatewayStatus{running: false}
+	}
+	return gatewayStatus{
+		running: true,
+		pid:     pid,
+	}
+}
+
+func startGateway() error {
+	status := getGatewayStatus()
+	if status.running {
+		return fmt.Errorf("gateway is already running (PID: %d)", status.pid)
+	}
+
+	pidPath := getPidPath()
+	var cmd *exec.Cmd
+
+	if runtime.GOOS == "windows" {
+		cmd = exec.Command("cmd", "/C", "start /B picoclaw gateway > NUL 2>&1")
+	} else {
+		cmd = exec.Command("sh", "-c", "nohup picoclaw gateway > /dev/null 2>&1 & echo $! > "+pidPath)
+	}
+
+	err := cmd.Start()
+	if err != nil {
+		return err
+	}
+
+	time.Sleep(1 * time.Second)
+
+	if runtime.GOOS == "windows" {
+		cmd := exec.Command(
+			"wmic",
+			"process",
+			"where",
+			"name='picoclaw.exe' and commandline like '%gateway%'",
+			"get",
+			"processid",
+		)
+		output, err := cmd.Output()
+		if err != nil {
+			return fmt.Errorf("failed to get gateway PID: %w", err)
+		}
+		lines := strings.Split(string(output), "\n")
+		for _, line := range lines[1:] {
+			line = strings.TrimSpace(line)
+			if line == "" {
+				continue
+			}
+			pid, err := strconv.Atoi(line)
+			if err == nil {
+				os.WriteFile(pidPath, []byte(strconv.Itoa(pid)), 0o600)
+				break
+			}
+		}
+	}
+
+	status = getGatewayStatus()
+	if !status.running {
+		return fmt.Errorf("failed to start gateway")
+	}
+	return nil
+}
+
+func stopGateway() error {
+	status := getGatewayStatus()
+	if !status.running {
+		return fmt.Errorf("gateway is not running")
+	}
+
+	var err error
+	if runtime.GOOS == "windows" {
+		err = exec.Command("taskkill", "/F", "/PID", strconv.Itoa(status.pid)).Run()
+	} else {
+		err = exec.Command("kill", "-9", strconv.Itoa(status.pid)).Run()
+	}
+	if err != nil {
+		return err
+	}
+
+	// 多次尝试确认进程已停止
+	for i := 0; i < 5; i++ {
+		if !isProcessRunning(status.pid) {
+			break
+		}
+		time.Sleep(200 * time.Millisecond)
+	}
+
+	os.Remove(getPidPath())
+	return nil
+}
+
+func (a *App) newGatewayPage() tview.Primitive {
+	flex := tview.NewFlex().SetDirection(tview.FlexRow)
+	flex.SetBorder(true).
+		SetTitle(" [#00f0ff::b] GATEWAY MANAGEMENT ").
+		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
+		SetBorderColor(tcell.NewHexColor(0x00f0ff))
+	flex.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+	statusTV := tview.NewTextView().
+		SetDynamicColors(true).
+		SetTextAlign(tview.AlignCenter).
+		SetText("Checking status...")
+	statusTV.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+	var updateStatus func()
+
+	// 使用List作为按钮，保证显示和交互正常
+	buttons := tview.NewList()
+	buttons.SetBackgroundColor(tcell.NewHexColor(0x050510))
+	buttons.SetMainTextColor(tcell.ColorWhite)
+	buttons.SetSelectedBackgroundColor(tcell.NewHexColor(0xff00ff))
+	buttons.SetSelectedTextColor(tcell.ColorBlack)
+
+	buttons.AddItem(" [lime]START[white]   ", "", 0, func() {
+		if !getGatewayStatus().running {
+			err := startGateway()
+			if err != nil {
+				a.showError(err.Error())
+			}
+			updateStatus()
+		}
+	})
+	buttons.AddItem(" [red]STOP[white]    ", "", 0, func() {
+		if getGatewayStatus().running {
+			err := stopGateway()
+			if err != nil {
+				a.showError(err.Error())
+			}
+			updateStatus()
+		}
+	})
+
+	buttonFlex := tview.NewFlex().SetDirection(tview.FlexColumn)
+	buttonFlex.
+		AddItem(tview.NewBox(), 0, 1, false).
+		AddItem(buttons, 20, 1, true).
+		AddItem(tview.NewBox(), 0, 1, false)
+
+	flex.
+		AddItem(tview.NewBox(), 0, 1, false).
+		AddItem(statusTV, 3, 1, false).
+		AddItem(tview.NewBox(), 0, 1, false).
+		AddItem(buttonFlex, 4, 1, true).
+		AddItem(tview.NewBox(), 0, 1, false)
+
+	updateStatus = func() {
+		status := getGatewayStatus()
+		if status.running {
+			statusTV.SetText(fmt.Sprintf("[#39ff14::b]GATEWAY RUNNING[-]\n\nPID: %d", status.pid))
+			buttons.SetItemText(0, " [gray]START[white]   ", "")
+			buttons.SetItemText(1, " [red]STOP[white]    ", "")
+		} else {
+			statusTV.SetText("[#ff2a2a::b]GATEWAY STOPPED[-]\n\nPID: N/A")
+			buttons.SetItemText(0, " [lime]START[white]   ", "")
+			buttons.SetItemText(1, " [gray]STOP[white]    ", "")
+		}
+	}
+
+	updateStatus()
+
+	done := make(chan struct{})
+	go func() {
+		ticker := time.NewTicker(2 * time.Second)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ticker.C:
+				a.tapp.QueueUpdateDraw(updateStatus)
+			case <-done:
+				return
+			}
+		}
+	}()
+
+	originalInputCapture := flex.GetInputCapture()
+	flex.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEscape {
+			close(done)
+			return a.goBack()
+		}
+		if originalInputCapture != nil {
+			return originalInputCapture(event)
+		}
+		return event
+	})
+
+	a.pageRefreshFns["gateway"] = updateStatus
+
+	return a.buildShell("gateway", flex, " [#39ff14]Enter:[-] select  [#ff2a2a]ESC:[-] back ")
+}
diff --git a/cmd/picoclaw-launcher-tui/ui/home.go b/cmd/picoclaw-launcher-tui/ui/home.go
new file mode 100644
index 000000000..74a7769cf
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/home.go
@@ -0,0 +1,70 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+	"os"
+	"os/exec"
+
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+)
+
+func (a *App) newHomePage() tview.Primitive {
+	list := tview.NewList()
+	list.SetBorder(true).
+		SetTitle(" [#00f0ff::b] ACTIVE CONFIGURATION ").
+		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
+		SetBorderColor(tcell.NewHexColor(0x00f0ff))
+	list.SetMainTextColor(tcell.NewHexColor(0xe0e0e0))
+	list.SetSecondaryTextColor(tcell.NewHexColor(0x808080))
+	list.SetSelectedStyle(
+		tcell.StyleDefault.Background(tcell.NewHexColor(0x39ff14)).Foreground(tcell.NewHexColor(0x050510)),
+	)
+	list.SetHighlightFullLine(true)
+	list.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+	rebuildList := func() {
+		sel := list.GetCurrentItem()
+		list.Clear()
+		list.AddItem("MODEL: "+a.cfg.CurrentModelLabel(), "Select to configure AI model", 'm', func() {
+			a.navigateTo("schemes", a.newSchemesPage())
+		})
+		list.AddItem(
+			"CHANNELS: Configure communication channels",
+			"Manage Telegram/Discord/WeChat channels",
+			'n',
+			func() {
+				a.navigateTo("channels", a.newChannelsPage())
+			},
+		)
+		list.AddItem("GATEWAY MANAGEMENT", "Manage PicoClaw gateway daemon", 'g', func() {
+			a.navigateTo("gateway", a.newGatewayPage())
+		})
+		list.AddItem("CHAT: Start AI agent chat", "Launch interactive chat session", 'c', func() {
+			a.tapp.Suspend(func() {
+				cmd := exec.Command("picoclaw", "agent")
+				cmd.Stdin = os.Stdin
+				cmd.Stdout = os.Stdout
+				cmd.Stderr = os.Stderr
+				_ = cmd.Run()
+			})
+		})
+		list.AddItem("QUIT SYSTEM", "Exit PicoClaw Launcher", 'q', func() { a.tapp.Stop() })
+		if sel >= 0 && sel < list.GetItemCount() {
+			list.SetCurrentItem(sel)
+		}
+	}
+	rebuildList()
+
+	a.pageRefreshFns["home"] = rebuildList
+
+	return a.buildShell(
+		"home",
+		list,
+		" [#00f0ff]m:[-] model  [#00f0ff]n:[-] channels  [#00f0ff]g:[-] gateway  [#00f0ff]c:[-] chat  [#ff2a2a]q:[-] quit ",
+	)
+}
diff --git a/cmd/picoclaw-launcher-tui/ui/models.go b/cmd/picoclaw-launcher-tui/ui/models.go
new file mode 100644
index 000000000..20e5f0182
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/models.go
@@ -0,0 +1,200 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+
+	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
+)
+
+type modelsAPIResponse struct {
+	Data []modelEntry `json:"data"`
+}
+
+type modelEntry struct {
+	ID          string `json:"id"`
+	Name        string `json:"name"`
+	Description string `json:"description"`
+}
+
+func (a *App) newModelsPage(schemeName, userName, baseURL string) tview.Primitive {
+	table := tview.NewTable().
+		SetBorders(false).
+		SetSelectable(true, false).
+		SetFixed(0, 0)
+	table.SetBorder(true).
+		SetTitle(fmt.Sprintf(" [#00f0ff::b] MODELS · %s / %s ", schemeName, userName)).
+		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
+		SetBorderColor(tcell.NewHexColor(0x00f0ff))
+	table.SetSelectedStyle(
+		tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0xffffff)),
+	)
+	table.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+	var modelIDs []string
+
+	status := tview.NewTextView().
+		SetTextAlign(tview.AlignCenter).
+		SetDynamicColors(true).
+		SetText("[#ffff00]FETCHING MODELS...[-]")
+	status.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+	flex := tview.NewFlex().
+		SetDirection(tview.FlexRow).
+		AddItem(status, 1, 0, false).
+		AddItem(table, 0, 1, false)
+
+	apiKey := a.resolveKey(schemeName, userName)
+
+	go func() {
+		var entries []modelEntry
+		var err error
+		if apiKey == "" {
+			err = fmt.Errorf("key is required")
+		} else {
+			entries, err = fetchModels(baseURL, apiKey)
+		}
+
+		a.modelCacheMu.Lock()
+		if a.modelCache == nil {
+			a.modelCache = make(map[string][]modelEntry)
+		}
+		if err == nil && len(entries) > 0 {
+			a.modelCache[cacheKey(schemeName, userName)] = entries
+		} else {
+			a.modelCache[cacheKey(schemeName, userName)] = nil
+		}
+		a.modelCacheMu.Unlock()
+
+		a.tapp.QueueUpdateDraw(func() {
+			if err != nil {
+				status.SetText(fmt.Sprintf("[#ff2a2a]ERROR: %s[-]", err.Error()))
+				table.SetCell(0, 0, tview.NewTableCell(" (failed to load models)"))
+				a.tapp.SetFocus(table)
+				return
+			}
+			if len(entries) == 0 {
+				status.SetText("[#ff2a2a]NO MODELS RETURNED[-]")
+				table.SetCell(0, 0, tview.NewTableCell(" (no models available)"))
+				a.tapp.SetFocus(table)
+				return
+			}
+
+			status.SetText(fmt.Sprintf("[#39ff14]%d MODEL(S) LOADED[-]", len(entries)))
+			for i, m := range entries {
+				modelIDs = append(modelIDs, m.ID)
+				table.SetCell(i, 0,
+					tview.NewTableCell(fmt.Sprintf("%3d", i+1)).
+						SetAlign(tview.AlignRight).
+						SetTextColor(tcell.NewHexColor(0x808080)).
+						SetSelectable(false),
+				)
+				table.SetCell(i, 1,
+					tview.NewTableCell(" "+m.ID).
+						SetAlign(tview.AlignLeft).
+						SetExpansion(1).
+						SetTextColor(tcell.NewHexColor(0xe0e0e0)),
+				)
+			}
+			a.tapp.SetFocus(table)
+		})
+	}()
+
+	table.SetSelectedFunc(func(row, _ int) {
+		if row < 0 || row >= len(modelIDs) {
+			return
+		}
+		a.cfg.Provider.Current = tuicfg.ProviderCurrent{
+			Scheme: schemeName,
+			User:   userName,
+			Model:  modelIDs[row],
+		}
+		a.save()
+
+		// Trigger model selected callback if set
+		if a.OnModelSelected != nil && a.cfg.Model.Type == "provider" {
+			scheme := a.cfg.Provider.SchemeByName(schemeName)
+			if scheme == nil {
+				a.goBack()
+				return
+			}
+			var user tuicfg.User
+			for _, u := range a.cfg.Provider.Users {
+				if u.Scheme == schemeName && u.Name == userName {
+					user = u
+					break
+				}
+			}
+			a.OnModelSelected(*scheme, user, modelIDs[row])
+		}
+
+		a.goBack()
+	})
+
+	return a.buildShell("models", flex, " [#39ff14]Enter:[-] select  [#ff00ff]ESC:[-] back ")
+}
+
+func (a *App) resolveKey(schemeName, userName string) string {
+	for _, u := range a.cfg.Provider.Users {
+		if u.Scheme == schemeName && u.Name == userName {
+			return u.Key
+		}
+	}
+	return ""
+}
+
+func fetchModels(baseURL, apiKey string) ([]modelEntry, error) {
+	url := strings.TrimRight(baseURL, "/") + "/models"
+
+	client := &http.Client{Timeout: 15 * time.Second}
+	req, err := http.NewRequest(http.MethodGet, url, nil)
+	if err != nil {
+		return nil, fmt.Errorf("build request: %w", err)
+	}
+	if apiKey != "" {
+		req.Header.Set("Authorization", "Bearer "+apiKey)
+	}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
+		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+	}
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("read response: %w", err)
+	}
+
+	var result modelsAPIResponse
+	if err := json.Unmarshal(body, &result); err == nil && len(result.Data) > 0 {
+		return result.Data, nil
+	}
+
+	var arr []modelEntry
+	if err := json.Unmarshal(body, &arr); err == nil {
+		return arr, nil
+	}
+
+	return nil, fmt.Errorf(
+		"decode response: unrecognized shape: %s",
+		strings.TrimSpace(string(body[:min(len(body), 256)])),
+	)
+}
diff --git a/cmd/picoclaw-launcher-tui/ui/schemes.go b/cmd/picoclaw-launcher-tui/ui/schemes.go
new file mode 100644
index 000000000..e38d7fa86
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/schemes.go
@@ -0,0 +1,252 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+	"fmt"
+
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+
+	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
+)
+
+func (a *App) newSchemesPage() tview.Primitive {
+	table := tview.NewTable().
+		SetBorders(false).
+		SetSelectable(true, false)
+	table.SetBorder(true).
+		SetTitle(" [#00f0ff::b] PROVIDER SCHEMES ").
+		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
+		SetBorderColor(tcell.NewHexColor(0x00f0ff))
+	table.SetSelectedStyle(
+		tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0xffffff)),
+	)
+	table.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+	rowToIdx := func(row int) int { return row / 2 }
+
+	selectedSchemeName := func() string {
+		row, _ := table.GetSelection()
+		idx := rowToIdx(row)
+		schemes := a.cfg.Provider.Schemes
+		if idx >= 0 && idx < len(schemes) {
+			return schemes[idx].Name
+		}
+		return ""
+	}
+
+	rebuild := func() {
+		selName := selectedSchemeName()
+		table.Clear()
+		schemes := a.cfg.Provider.Schemes
+		for i, s := range schemes {
+			nameRow := i * 2
+			detailRow := nameRow + 1
+
+			table.SetCell(nameRow, 0,
+				tview.NewTableCell(" "+s.Name).
+					SetTextColor(tcell.NewHexColor(0xe0e0e0)).
+					SetExpansion(1).
+					SetSelectable(true),
+			)
+
+			users := a.cfg.Provider.UsersForScheme(s.Name)
+			n := len(users)
+			m := 0
+			for _, u := range users {
+				if models := a.cachedModels(s.Name, u.Name); len(models) > 0 {
+					m++
+				}
+			}
+			table.SetCell(detailRow, 0,
+				tview.NewTableCell(fmt.Sprintf("  [#808080](%d/%d) %s", m, n, s.BaseURL)).
+					SetTextColor(tcell.NewHexColor(0x808080)).
+					SetExpansion(1).
+					SetSelectable(false),
+			)
+			table.SetCell(detailRow, 1,
+				tview.NewTableCell("[#00f0ff]"+s.Type+"  ").
+					SetAlign(tview.AlignRight).
+					SetSelectable(false),
+			)
+		}
+		if selName != "" {
+			for i, s := range schemes {
+				if s.Name == selName {
+					table.Select(i*2, 0)
+					return
+				}
+			}
+		}
+		if table.GetRowCount() > 0 {
+			table.Select(0, 0)
+		}
+	}
+	rebuild()
+
+	a.refreshModelCache(rebuild)
+	a.pageRefreshFns["schemes"] = func() { a.refreshModelCache(rebuild) }
+
+	table.SetSelectedFunc(func(row, _ int) {
+		idx := rowToIdx(row)
+		schemes := a.cfg.Provider.Schemes
+		if idx < 0 || idx >= len(schemes) {
+			return
+		}
+		name := schemes[idx].Name
+		a.navigateTo("users", a.newUsersPage(name))
+	})
+
+	table.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		row, _ := table.GetSelection()
+		idx := rowToIdx(row)
+		schemes := a.cfg.Provider.Schemes
+		switch event.Rune() {
+		case 'a':
+			a.showSchemeForm(nil, func(s tuicfg.Scheme) {
+				a.cfg.Provider.Schemes = append(a.cfg.Provider.Schemes, s)
+				a.save()
+				a.refreshModelCache(rebuild)
+			})
+			return nil
+		case 'e':
+			if idx < 0 || idx >= len(schemes) {
+				return nil
+			}
+			origName := schemes[idx].Name
+			orig := schemes[idx]
+			a.showSchemeForm(&orig, func(s tuicfg.Scheme) {
+				current := a.cfg.Provider.Schemes
+				for i, sc := range current {
+					if sc.Name == origName {
+						a.cfg.Provider.Schemes[i] = s
+						break
+					}
+				}
+				a.save()
+				a.refreshModelCache(func() {
+					rebuild()
+					for i, sc := range a.cfg.Provider.Schemes {
+						if sc.Name == s.Name {
+							table.Select(i*2, 0)
+							break
+						}
+					}
+				})
+			})
+			return nil
+		case 'd':
+			if idx < 0 || idx >= len(schemes) {
+				return nil
+			}
+			name := schemes[idx].Name
+			a.confirmDelete(fmt.Sprintf("scheme %q", name), func() {
+				current := a.cfg.Provider.Schemes
+				newSchemes := make([]tuicfg.Scheme, 0, len(current))
+				for _, sc := range current {
+					if sc.Name != name {
+						newSchemes = append(newSchemes, sc)
+					}
+				}
+				a.cfg.Provider.Schemes = newSchemes
+
+				existing := a.cfg.Provider.Users
+				filtered := make([]tuicfg.User, 0, len(existing))
+				for _, u := range existing {
+					if u.Scheme != name {
+						filtered = append(filtered, u)
+					}
+				}
+				a.cfg.Provider.Users = filtered
+
+				a.save()
+				a.refreshModelCache(rebuild)
+			})
+			return nil
+		}
+		return event
+	})
+
+	return a.buildShell(
+		"schemes",
+		table,
+		" [#00f0ff]a:[-] add  [#00f0ff]e:[-] edit  [#ff2a2a]d:[-] delete  [#39ff14]Enter:[-] open  [#ff00ff]ESC:[-] back ",
+	)
+}
+
+func (a *App) showSchemeForm(existing *tuicfg.Scheme, onSave func(tuicfg.Scheme)) {
+	name := ""
+	baseURL := ""
+	schemeType := "openai-compatible"
+	title := " ADD SCHEME "
+
+	if existing != nil {
+		name = existing.Name
+		baseURL = existing.BaseURL
+		schemeType = existing.Type
+		title = " EDIT SCHEME "
+	}
+
+	typeOptions := []string{"openai-compatible", "anthropic"}
+	typeIdx := 0
+	for i, t := range typeOptions {
+		if t == schemeType {
+			typeIdx = i
+			break
+		}
+	}
+
+	form := tview.NewForm()
+
+	form.
+		AddInputField("Name", name, 20, nil, func(text string) { name = text }).
+		AddInputField("Base URL", baseURL, 28, nil, func(text string) { baseURL = text }).
+		AddDropDown("Type", typeOptions, typeIdx, func(option string, _ int) { schemeType = option }).
+		AddButton("SAVE", func() {
+			if name == "" {
+				a.showError("Name is required")
+				return
+			}
+			if baseURL == "" {
+				a.showError("Base URL is required")
+				return
+			}
+			if existing == nil {
+				for _, s := range a.cfg.Provider.Schemes {
+					if s.Name == name {
+						a.showError(fmt.Sprintf("Scheme name %q already exists", name))
+						return
+					}
+				}
+			}
+			a.hideModal("scheme-form")
+			onSave(tuicfg.Scheme{Name: name, BaseURL: baseURL, Type: schemeType})
+		}).
+		AddButton("CANCEL", func() {
+			a.hideModal("scheme-form")
+		})
+
+	form.SetBorder(true).
+		SetTitle(" [::b]" + title + " ").
+		SetTitleColor(tcell.NewHexColor(0x39ff14)).
+		SetBorderColor(tcell.NewHexColor(0x00f0ff))
+	form.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))
+	form.SetFieldBackgroundColor(tcell.NewHexColor(0x050510))
+	form.SetFieldTextColor(tcell.NewHexColor(0x00f0ff))
+	form.SetLabelColor(tcell.NewHexColor(0xe0e0e0))
+	form.SetButtonBackgroundColor(tcell.NewHexColor(0xff00ff))
+	form.SetButtonTextColor(tcell.NewHexColor(0xffffff))
+	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEscape {
+			a.hideModal("scheme-form")
+			return nil
+		}
+		return event
+	})
+
+	a.showModal("scheme-form", centeredForm(form, 4, 12))
+}
diff --git a/cmd/picoclaw-launcher-tui/ui/users.go b/cmd/picoclaw-launcher-tui/ui/users.go
new file mode 100644
index 000000000..b00fc8982
--- /dev/null
+++ b/cmd/picoclaw-launcher-tui/ui/users.go
@@ -0,0 +1,261 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package ui
+
+import (
+	"fmt"
+
+	"github.com/gdamore/tcell/v2"
+	"github.com/rivo/tview"
+
+	tuicfg "github.com/sipeed/picoclaw/cmd/picoclaw-launcher-tui/config"
+)
+
+func (a *App) newUsersPage(schemeName string) tview.Primitive {
+	table := tview.NewTable().
+		SetBorders(false).
+		SetSelectable(true, false)
+	table.SetBorder(true).
+		SetTitle(fmt.Sprintf(" [#00f0ff::b] USERS · %s ", schemeName)).
+		SetTitleColor(tcell.NewHexColor(0x00f0ff)).
+		SetBorderColor(tcell.NewHexColor(0x00f0ff))
+	table.SetSelectedStyle(
+		tcell.StyleDefault.Background(tcell.NewHexColor(0xff00ff)).Foreground(tcell.NewHexColor(0xffffff)),
+	)
+	table.SetBackgroundColor(tcell.NewHexColor(0x050510))
+
+	visibleUsers := func() []tuicfg.User {
+		var out []tuicfg.User
+		for _, u := range a.cfg.Provider.Users {
+			if u.Scheme == schemeName {
+				out = append(out, u)
+			}
+		}
+		return out
+	}
+
+	findUserGlobalIdx := func(userName string) int {
+		for i, u := range a.cfg.Provider.Users {
+			if u.Scheme == schemeName && u.Name == userName {
+				return i
+			}
+		}
+		return -1
+	}
+
+	rowToVisIdx := func(row int) int { return row / 2 }
+
+	selectedUserName := func() string {
+		row, _ := table.GetSelection()
+		users := visibleUsers()
+		visIdx := rowToVisIdx(row)
+		if visIdx >= 0 && visIdx < len(users) {
+			return users[visIdx].Name
+		}
+		return ""
+	}
+
+	rebuild := func() {
+		selName := selectedUserName()
+		table.Clear()
+		users := visibleUsers()
+		for i, u := range users {
+			nameRow := i * 2
+			detailRow := nameRow + 1
+
+			table.SetCell(nameRow, 0,
+				tview.NewTableCell(" "+u.Name).
+					SetTextColor(tcell.NewHexColor(0xe0e0e0)).
+					SetExpansion(1).
+					SetSelectable(true),
+			)
+			table.SetCell(nameRow, 1,
+				tview.NewTableCell("").
+					SetSelectable(false),
+			)
+
+			models := a.cachedModels(schemeName, u.Name)
+			var detailText string
+			if len(models) > 0 {
+				detailText = fmt.Sprintf("  [#39ff14]%d models available[-]", len(models))
+			} else {
+				detailText = "  [#ff2a2a]Inactive / No Access[-]"
+			}
+			table.SetCell(detailRow, 0,
+				tview.NewTableCell(detailText).
+					SetTextColor(tcell.NewHexColor(0x808080)).
+					SetExpansion(1).
+					SetSelectable(false),
+			)
+			table.SetCell(detailRow, 1,
+				tview.NewTableCell("[#00f0ff]"+u.Type+"  ").
+					SetAlign(tview.AlignRight).
+					SetSelectable(false),
+			)
+		}
+		if selName != "" {
+			for i, u := range users {
+				if u.Name == selName {
+					table.Select(i*2, 0)
+					return
+				}
+			}
+		}
+		if table.GetRowCount() > 0 {
+			table.Select(0, 0)
+		}
+	}
+	rebuild()
+
+	a.refreshModelCache(rebuild)
+	a.pageRefreshFns["users"] = func() { a.refreshModelCache(rebuild) }
+
+	table.SetSelectedFunc(func(row, _ int) {
+		visIdx := rowToVisIdx(row)
+		users := visibleUsers()
+		if visIdx < 0 || visIdx >= len(users) {
+			return
+		}
+		uName := users[visIdx].Name
+		scheme := a.cfg.Provider.SchemeByName(schemeName)
+		if scheme == nil {
+			a.showError(fmt.Sprintf("Scheme %q not found", schemeName))
+			return
+		}
+		a.navigateTo("models", a.newModelsPage(schemeName, uName, scheme.BaseURL))
+	})
+
+	table.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		row, _ := table.GetSelection()
+		visIdx := rowToVisIdx(row)
+		users := visibleUsers()
+		switch event.Rune() {
+		case 'a':
+			a.showUserForm(schemeName, nil, func(u tuicfg.User) {
+				a.cfg.Provider.Users = append(a.cfg.Provider.Users, u)
+				a.save()
+				a.refreshModelCache(rebuild)
+			})
+			return nil
+		case 'e':
+			if visIdx < 0 || visIdx >= len(users) {
+				return nil
+			}
+			origName := users[visIdx].Name
+			orig := a.cfg.Provider.Users[findUserGlobalIdx(origName)]
+			a.showUserForm(schemeName, &orig, func(u tuicfg.User) {
+				cfgIdx := findUserGlobalIdx(origName)
+				if cfgIdx < 0 {
+					a.showError(fmt.Sprintf("User %q no longer exists", origName))
+					return
+				}
+				a.cfg.Provider.Users[cfgIdx] = u
+				a.save()
+				a.refreshModelCache(func() {
+					rebuild()
+					for i, usr := range visibleUsers() {
+						if usr.Name == u.Name {
+							table.Select(i*2, 0)
+							break
+						}
+					}
+				})
+			})
+			return nil
+		case 'd':
+			if visIdx < 0 || visIdx >= len(users) {
+				return nil
+			}
+			uName := users[visIdx].Name
+			a.confirmDelete(fmt.Sprintf("user %q", uName), func() {
+				cfgIdx := findUserGlobalIdx(uName)
+				if cfgIdx < 0 {
+					return
+				}
+				all := a.cfg.Provider.Users
+				a.cfg.Provider.Users = append(all[:cfgIdx], all[cfgIdx+1:]...)
+				a.save()
+				a.refreshModelCache(rebuild)
+			})
+			return nil
+		}
+		return event
+	})
+
+	return a.buildShell(
+		"users",
+		table,
+		" [#00f0ff]a:[-] add  [#00f0ff]e:[-] edit  [#ff2a2a]d:[-] delete  [#39ff14]Enter:[-] models  [#ff00ff]ESC:[-] back ",
+	)
+}
+
+func (a *App) showUserForm(schemeName string, existing *tuicfg.User, onSave func(tuicfg.User)) {
+	name := ""
+	userType := "key"
+	key := ""
+	title := " ADD USER "
+
+	if existing != nil {
+		name = existing.Name
+		userType = existing.Type
+		key = existing.Key
+		title = " EDIT USER "
+	}
+
+	typeOptions := []string{"key", "OAuth"}
+	typeIdx := 0
+	for i, t := range typeOptions {
+		if t == userType {
+			typeIdx = i
+			break
+		}
+	}
+
+	form := tview.NewForm()
+	form.
+		AddInputField("Name", name, 20, nil, func(text string) { name = text }).
+		AddDropDown("Type", typeOptions, typeIdx, func(option string, _ int) { userType = option }).
+		AddPasswordField("Key", key, 28, '*', func(text string) { key = text }).
+		AddButton("SAVE", func() {
+			if name == "" {
+				a.showError("Name is required")
+				return
+			}
+			if existing == nil {
+				for _, u := range a.cfg.Provider.Users {
+					if u.Scheme == schemeName && u.Name == name {
+						a.showError(fmt.Sprintf("User name %q already exists for this scheme", name))
+						return
+					}
+				}
+			}
+			a.hideModal("user-form")
+			onSave(tuicfg.User{Name: name, Scheme: schemeName, Type: userType, Key: key})
+		}).
+		AddButton("CANCEL", func() {
+			a.hideModal("user-form")
+		})
+
+	form.SetBorder(true).
+		SetTitle(" [::b]" + title + " ").
+		SetTitleColor(tcell.NewHexColor(0x39ff14)).
+		SetBorderColor(tcell.NewHexColor(0x00f0ff))
+	form.SetBackgroundColor(tcell.NewHexColor(0x1a1a2e))
+	form.SetFieldBackgroundColor(tcell.NewHexColor(0x050510))
+	form.SetFieldTextColor(tcell.NewHexColor(0x00f0ff))
+	form.SetLabelColor(tcell.NewHexColor(0xe0e0e0))
+	form.SetButtonBackgroundColor(tcell.NewHexColor(0xff00ff))
+	form.SetButtonTextColor(tcell.NewHexColor(0xffffff))
+	form.SetInputCapture(func(event *tcell.EventKey) *tcell.EventKey {
+		if event.Key() == tcell.KeyEscape {
+			a.hideModal("user-form")
+			return nil
+		}
+		return event
+	})
+
+	a.showModal("user-form", centeredForm(form, 4, 13))
+}
diff --git a/cmd/picoclaw-launcher/README.md b/cmd/picoclaw-launcher/README.md
deleted file mode 100644
index 641279bb1..000000000
--- a/cmd/picoclaw-launcher/README.md
+++ /dev/null
@@ -1,290 +0,0 @@
-# PicoClaw Launcher
-
-> [!WARNING]
-> This project is a temporary solution and will be refactored in the future to provide a complete web service. Therefore, the APIs in this directory are not stable.
-
-A standalone launcher for PicoClaw, providing visual JSON editing and OAuth provider authentication management.
-
-## Features
-
-- 📝 **Config Editor** — Sidebar-based settings UI with model management, channel configuration forms, and a raw JSON editor
-- 🤖 **Model Management** — Model card grid with availability status (grayed out without API key), primary model selection, add/edit/delete with required/optional field separation
-- 📡 **Channel Configuration** — Form-based settings for 12 channel types (Telegram, Discord, Slack, WeCom, DingTalk, Feishu, LINE, WhatsApp, QQ, OneBot, MaixCAM, etc.) with documentation links
-- 🔐 **Provider Auth** — Login to OpenAI (Device Code), Anthropic (API Token), Google Antigravity (Browser OAuth)
-- 🌐 **Embedded Frontend** — Compiles to a single binary with no external dependencies
-- 🌍 **i18n** — Chinese/English language switching with browser auto-detection
-- 🎨 **Theme** — Light / Dark / System theme toggle with localStorage persistence
-
-## Quick Start
-
-```bash
-# Build
-go build -o picoclaw-launcher ./cmd/picoclaw-launcher/
-
-# Run with default config path (~/.picoclaw/config.json)
-./picoclaw-launcher
-
-# Specify a config file
-./picoclaw-launcher ./config.json
-
-# Allow LAN access
-./picoclaw-launcher -public
-```
-
-Open `http://localhost:18800` in your browser.
-
-## CLI Options
-
-```
-Usage: picoclaw-config [options] [config.json]
-
-Arguments:
-  config.json    Path to the configuration file (default: ~/.picoclaw/config.json)
-
-Options:
-  -public        Listen on all interfaces (0.0.0.0), allowing access from other devices
-```
-
-## API Reference
-
-Base URL: `http://localhost:18800`
-
----
-
-### Static Files
-
-#### GET /
-
-Serves the embedded frontend (`index.html`).
-
----
-
-### Config API
-
-#### GET /api/config
-
-Reads the current configuration file.
-
-**Response** `200 OK`
-
-```json
-{
-  "config": { ... },
-  "path": "/Users/xiao/.picoclaw/config.json"
-}
-```
-
----
-
-#### PUT /api/config
-
-Saves the configuration. The request body must be a complete Config JSON object.
-
-**Request Body** — `application/json`
-
-```json
-{
-  "agents": { "defaults": { "model_name": "gpt-5.2" } },
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "auth_method": "oauth"
-    }
-  ]
-}
-```
-
-**Response** `200 OK`
-
-```json
-{ "status": "ok" }
-```
-
-**Error** `400 Bad Request` — Invalid JSON
-
----
-
-### Auth API
-
-#### GET /api/auth/status
-
-Returns the authentication status of all providers and any in-progress device code login.
-
-**Response** `200 OK`
-
-```json
-{
-  "providers": [
-    {
-      "provider": "openai",
-      "auth_method": "oauth",
-      "status": "active",
-      "account_id": "user-xxx",
-      "expires_at": "2026-03-01T00:00:00Z"
-    }
-  ],
-  "pending_device": {
-    "provider": "openai",
-    "status": "pending",
-    "device_url": "https://auth.openai.com/activate",
-    "user_code": "ABCD-1234"
-  }
-}
-```
-
-`status` values: `active` | `expired` | `needs_refresh`
-
-`pending_device` is only present when a device code login is in progress.
-
----
-
-#### POST /api/auth/login
-
-Initiates a provider login.
-
-**Request Body** — `application/json`
-
-```json
-{ "provider": "openai" }
-```
-
-Supported `provider` values: `openai` | `anthropic` | `google-antigravity`
-
-##### OpenAI (Device Code Flow)
-
-Returns device code info. The server polls for completion in the background.
-
-```json
-{
-  "status": "pending",
-  "device_url": "https://auth.openai.com/activate",
-  "user_code": "ABCD-1234",
-  "message": "Open the URL and enter the code to authenticate."
-}
-```
-
-The user opens `device_url` in a browser and enters `user_code`. Once authenticated, `GET /api/auth/status` will show `pending_device.status` as `success`.
-
-##### Anthropic (API Token)
-
-Requires a `token` field in the request:
-
-```json
-{ "provider": "anthropic", "token": "sk-ant-xxx" }
-```
-
-**Response:**
-
-```json
-{ "status": "success", "message": "Anthropic token saved" }
-```
-
-##### Google Antigravity (Browser OAuth)
-
-Returns an authorization URL for the frontend to open in a new tab:
-
-```json
-{
-  "status": "redirect",
-  "auth_url": "https://accounts.google.com/o/oauth2/auth?...",
-  "message": "Open the URL to authenticate with Google."
-}
-```
-
-After authentication, Google redirects to `GET /auth/callback`, which saves the credentials and redirects back to the picoclaw-config UI.
-
----
-
-#### POST /api/auth/logout
-
-Logs out from a provider.
-
-**Request Body** — `application/json`
-
-```json
-{ "provider": "openai" }
-```
-
-Omit or leave `provider` empty to log out from all providers.
-
-**Response** `200 OK`
-
-```json
-{ "status": "ok" }
-```
-
----
-
-#### GET /auth/callback
-
-OAuth browser callback endpoint (used by Google Antigravity). Called by the OAuth provider's redirect — **not invoked directly by the frontend**.
-
-**Query Parameters:**
-- `state` — OAuth state for CSRF validation
-- `code` — Authorization code
-
-On success, redirects to `/#auth`.
-
-
-### Process API
-
-#### GET /api/process/status
-
-Gets the running status of the `picoclaw gateway` process.
-
-**Response** `200 OK` (Running)
-
-```json
-{
-  "process_status": "running",
-  "status": "ok",
-  "uptime": "1.010814s"
-}
-```
-
-**Response** `200 OK` (Stopped)
-
-```json
-{
-  "process_status": "stopped",
-  "error": "Get \"http://localhost:18790/health\": dial tcp [::1]:18790: connect: connection refused"
-}
-```
-
----
-
-#### POST /api/process/start
-
-Starts the `picoclaw gateway` process in the background.
-
-**Response** `200 OK`
-
-```json
-{
-  "status": "ok",
-  "pid": 12345
-}
-```
-
----
-
-#### POST /api/process/stop
-
-Stops the running `picoclaw gateway` process.
-
-**Response** `200 OK`
-
-```json
-{
-  "status": "ok"
-}
-```
-
----
-
-## Testing
-
-```bash
-go test -v ./cmd/picoclaw-launcher/
-```
diff --git a/cmd/picoclaw-launcher/README.zh.md b/cmd/picoclaw-launcher/README.zh.md
deleted file mode 100644
index 320de75a5..000000000
--- a/cmd/picoclaw-launcher/README.zh.md
+++ /dev/null
@@ -1,287 +0,0 @@
-# PicoClaw Launcher
-
-> [!WARNING]
-> 该项目属于临时解决方案，后续会重构并提供完整的 Web 服务，因此该目录下的接口并不稳定。
-
-PicoClaw 的独立启动器，提供可视化 JSON 配置编辑和 OAuth Provider 认证管理。
-
-## 功能
-
-- 📝 **配置编辑** — 侧边栏式设置 UI，支持模型管理、通道配置表单和原始 JSON 编辑器
-- 🤖 **模型管理** — 模型卡片网格，可用性状态显示（无 API Key 时灰色），主模型选择，增删改查，必填/选填字段分离
-- 📡 **通道配置** — 12 种通道类型（Telegram、Discord、Slack、企业微信、钉钉、飞书、LINE、WhatsApp、QQ、OneBot、MaixCAM 等）的表单化配置，附带文档链接
-- 🔐 **Provider 认证** — 支持 OpenAI (Device Code)、Anthropic (API Token)、Google Antigravity (Browser OAuth) 登录
-- 🌐 **嵌入式前端** — 编译为单一二进制文件，无需额外依赖
-- 🌍 **国际化** — 中英文切换，首次访问自动检测浏览器语言
-- 🎨 **主题** — 亮色 / 暗色 / 跟随系统，偏好保存在 localStorage
-
-## 快速开始
-
-```bash
-# 编译
-go build -o picoclaw-launcher ./cmd/picoclaw-launcher/
-
-# 运行（使用默认配置路径 ~/.picoclaw/config.json）
-./picoclaw-launcher
-
-# 指定配置文件
-./picoclaw-launcher ./config.json
-
-# 允许局域网访问
-./picoclaw-launcher -public
-```
-
-启动后在浏览器中打开 `http://localhost:18800`。
-
-## 命令行参数
-
-```
-Usage: picoclaw-launcher [options] [config.json]
-
-Arguments:
-  config.json    配置文件路径（默认: ~/.picoclaw/config.json）
-
-Options:
-  -public        监听所有网络接口（0.0.0.0），允许局域网设备访问
-```
-
-## API 文档
-
-Base URL: `http://localhost:18800`
-
-### 静态文件
-
-#### GET /
-
-提供嵌入式前端页面（`index.html`）。
-
----
-
-### Config API
-
-#### GET /api/config
-
-读取当前配置文件内容。
-
-**Response** `200 OK`
-
-```json
-{
-  "config": { ... },
-  "path": "/Users/xiao/.picoclaw/config.json"
-}
-```
-
----
-
-#### PUT /api/config
-
-保存配置。请求体为完整的 Config JSON。
-
-**Request Body** — `application/json`
-
-```json
-{
-  "agents": { "defaults": { "model_name": "gpt-5.2" } },
-  "model_list": [
-    {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
-      "auth_method": "oauth"
-    }
-  ]
-}
-```
-
-**Response** `200 OK`
-
-```json
-{ "status": "ok" }
-```
-
-**Error** `400 Bad Request` — 无效 JSON
-
----
-
-### Auth API
-
-#### GET /api/auth/status
-
-获取所有 Provider 的认证状态和进行中的 Device Code 登录信息。
-
-**Response** `200 OK`
-
-```json
-{
-  "providers": [
-    {
-      "provider": "openai",
-      "auth_method": "oauth",
-      "status": "active",
-      "account_id": "user-xxx",
-      "expires_at": "2026-03-01T00:00:00Z"
-    }
-  ],
-  "pending_device": {
-    "provider": "openai",
-    "status": "pending",
-    "device_url": "https://auth.openai.com/activate",
-    "user_code": "ABCD-1234"
-  }
-}
-```
-
-`status` 可选值: `active` | `expired` | `needs_refresh`
-
-`pending_device` 仅在有进行中的 Device Code 登录时返回。
-
----
-
-#### POST /api/auth/login
-
-发起 Provider 登录。
-
-**Request Body** — `application/json`
-
-```json
-{ "provider": "openai" }
-```
-
-支持的 `provider` 值: `openai` | `anthropic` | `google-antigravity`
-
-##### OpenAI (Device Code Flow)
-
-返回 Device Code 信息，后台自动轮询认证结果：
-
-```json
-{
-  "status": "pending",
-  "device_url": "https://auth.openai.com/activate",
-  "user_code": "ABCD-1234",
-  "message": "Open the URL and enter the code to authenticate."
-}
-```
-
-用户在浏览器中打开 `device_url` 并输入 `user_code`。认证完成后通过 `GET /api/auth/status` 的 `pending_device.status` 变为 `success` 通知前端。
-
-##### Anthropic (API Token)
-
-需在请求中附带 token：
-
-```json
-{ "provider": "anthropic", "token": "sk-ant-xxx" }
-```
-
-**Response:**
-
-```json
-{ "status": "success", "message": "Anthropic token saved" }
-```
-
-##### Google Antigravity (Browser OAuth)
-
-返回授权 URL，前端打开新标签页：
-
-```json
-{
-  "status": "redirect",
-  "auth_url": "https://accounts.google.com/o/oauth2/auth?...",
-  "message": "Open the URL to authenticate with Google."
-}
-```
-
-认证完成后 Google 回调至 `GET /auth/callback`，自动保存凭据并重定向回 picoclaw-config 页面。
-
----
-
-#### POST /api/auth/logout
-
-登出 Provider。
-
-**Request Body** — `application/json`
-
-```json
-{ "provider": "openai" }
-```
-
-传空字符串或省略 `provider` 则登出所有 Provider。
-
-**Response** `200 OK`
-
-```json
-{ "status": "ok" }
-```
-
----
-
-#### GET /auth/callback
-
-OAuth Browser 回调端点（Google Antigravity 专用），由 OAuth Provider 重定向调用，**非前端直接使用**。
-
-**Query Parameters:**
-- `state` — OAuth state 校验
-- `code` — 授权码
-
-认证成功后重定向到 `/#auth`。
-
-### Process API
-
-#### GET /api/process/status
-
-获取 `picoclaw gateway` 进程的运行状态。
-
-**Response** `200 OK` (运行中)
-
-```json
-{
-  "process_status": "running",
-  "status": "ok",
-  "uptime": "1.010814s"
-}
-```
-
-**Response** `200 OK` (未运行)
-
-```json
-{
-  "process_status": "stopped",
-  "error": "Get \"http://localhost:18790/health\": dial tcp [::1]:18790: connect: connection refused"
-}
-```
-
----
-
-#### POST /api/process/start
-
-在后台启动 `picoclaw gateway` 进程。
-
-**Response** `200 OK`
-
-```json
-{
-  "status": "ok",
-  "pid": 12345
-}
-```
-
----
-
-#### POST /api/process/stop
-
-停止正在运行的 `picoclaw gateway` 进程。
-
-**Response** `200 OK`
-
-```json
-{
-  "status": "ok"
-}
-```
-
----
-
-## 测试
-
-```bash
-go test -v ./cmd/picoclaw-launcher/
-```
diff --git a/cmd/picoclaw-launcher/internal/server/auth_config.go b/cmd/picoclaw-launcher/internal/server/auth_config.go
deleted file mode 100644
index f75e8fff0..000000000
--- a/cmd/picoclaw-launcher/internal/server/auth_config.go
+++ /dev/null
@@ -1,147 +0,0 @@
-package server
-
-import (
-	"log"
-	"strings"
-
-	"github.com/sipeed/picoclaw/pkg/auth"
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-// updateConfigAfterLogin updates config.json after a successful provider login.
-func updateConfigAfterLogin(configPath, provider string, cred *auth.AuthCredential) {
-	cfg, err := config.LoadConfig(configPath)
-	if err != nil {
-		log.Printf("Warning: could not load config to update auth_method: %v", err)
-		return
-	}
-
-	switch provider {
-	case "openai":
-		cfg.Providers.OpenAI.AuthMethod = "oauth"
-		found := false
-		for i := range cfg.ModelList {
-			if isOpenAIModel(cfg.ModelList[i].Model) {
-				cfg.ModelList[i].AuthMethod = "oauth"
-				found = true
-				break
-			}
-		}
-		if !found {
-			cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
-				ModelName:  "gpt-5.2",
-				Model:      "openai/gpt-5.2",
-				AuthMethod: "oauth",
-			})
-		}
-		cfg.Agents.Defaults.ModelName = "gpt-5.2"
-
-	case "anthropic":
-		cfg.Providers.Anthropic.AuthMethod = "token"
-		found := false
-		for i := range cfg.ModelList {
-			if isAnthropicModel(cfg.ModelList[i].Model) {
-				cfg.ModelList[i].AuthMethod = "token"
-				found = true
-				break
-			}
-		}
-		if !found {
-			cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
-				ModelName:  "claude-sonnet-4.6",
-				Model:      "anthropic/claude-sonnet-4.6",
-				AuthMethod: "token",
-			})
-		}
-		cfg.Agents.Defaults.ModelName = "claude-sonnet-4.6"
-
-	case "google-antigravity":
-		cfg.Providers.Antigravity.AuthMethod = "oauth"
-		found := false
-		for i := range cfg.ModelList {
-			if isAntigravityModel(cfg.ModelList[i].Model) {
-				cfg.ModelList[i].AuthMethod = "oauth"
-				found = true
-				break
-			}
-		}
-		if !found {
-			cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
-				ModelName:  "gemini-flash",
-				Model:      "antigravity/gemini-3-flash",
-				AuthMethod: "oauth",
-			})
-		}
-		cfg.Agents.Defaults.ModelName = "gemini-flash"
-	}
-
-	if err := config.SaveConfig(configPath, cfg); err != nil {
-		log.Printf("Warning: could not update config: %v", err)
-	}
-}
-
-// clearAuthMethodInConfig clears auth_method for a specific provider in config.json.
-func clearAuthMethodInConfig(configPath, provider string) {
-	cfg, err := config.LoadConfig(configPath)
-	if err != nil {
-		return
-	}
-
-	for i := range cfg.ModelList {
-		switch provider {
-		case "openai":
-			if isOpenAIModel(cfg.ModelList[i].Model) {
-				cfg.ModelList[i].AuthMethod = ""
-			}
-		case "anthropic":
-			if isAnthropicModel(cfg.ModelList[i].Model) {
-				cfg.ModelList[i].AuthMethod = ""
-			}
-		case "google-antigravity", "antigravity":
-			if isAntigravityModel(cfg.ModelList[i].Model) {
-				cfg.ModelList[i].AuthMethod = ""
-			}
-		}
-	}
-
-	switch provider {
-	case "openai":
-		cfg.Providers.OpenAI.AuthMethod = ""
-	case "anthropic":
-		cfg.Providers.Anthropic.AuthMethod = ""
-	case "google-antigravity", "antigravity":
-		cfg.Providers.Antigravity.AuthMethod = ""
-	}
-
-	config.SaveConfig(configPath, cfg)
-}
-
-// clearAllAuthMethodsInConfig clears auth_method for all providers in config.json.
-func clearAllAuthMethodsInConfig(configPath string) {
-	cfg, err := config.LoadConfig(configPath)
-	if err != nil {
-		return
-	}
-	for i := range cfg.ModelList {
-		cfg.ModelList[i].AuthMethod = ""
-	}
-	cfg.Providers.OpenAI.AuthMethod = ""
-	cfg.Providers.Anthropic.AuthMethod = ""
-	cfg.Providers.Antigravity.AuthMethod = ""
-	config.SaveConfig(configPath, cfg)
-}
-
-// ── Model identification helpers ─────────────────────────────────
-
-func isOpenAIModel(model string) bool {
-	return model == "openai" || strings.HasPrefix(model, "openai/")
-}
-
-func isAnthropicModel(model string) bool {
-	return model == "anthropic" || strings.HasPrefix(model, "anthropic/")
-}
-
-func isAntigravityModel(model string) bool {
-	return model == "antigravity" || model == "google-antigravity" ||
-		strings.HasPrefix(model, "antigravity/") || strings.HasPrefix(model, "google-antigravity/")
-}
diff --git a/cmd/picoclaw-launcher/internal/server/auth_config_test.go b/cmd/picoclaw-launcher/internal/server/auth_config_test.go
deleted file mode 100644
index 92158d011..000000000
--- a/cmd/picoclaw-launcher/internal/server/auth_config_test.go
+++ /dev/null
@@ -1,222 +0,0 @@
-package server
-
-import (
-	"path/filepath"
-	"testing"
-
-	"github.com/sipeed/picoclaw/pkg/auth"
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-// ── Model identification helpers ─────────────────────────────────
-
-func TestIsOpenAIModel(t *testing.T) {
-	tests := []struct {
-		model string
-		want  bool
-	}{
-		{"openai", true},
-		{"openai/gpt-4o", true},
-		{"openai/gpt-5.2", true},
-		{"anthropic", false},
-		{"anthropic/claude-sonnet-4.6", false},
-		{"openai-compatible", false},
-		{"", false},
-	}
-	for _, tt := range tests {
-		if got := isOpenAIModel(tt.model); got != tt.want {
-			t.Errorf("isOpenAIModel(%q) = %v, want %v", tt.model, got, tt.want)
-		}
-	}
-}
-
-func TestIsAnthropicModel(t *testing.T) {
-	tests := []struct {
-		model string
-		want  bool
-	}{
-		{"anthropic", true},
-		{"anthropic/claude-sonnet-4.6", true},
-		{"openai", false},
-		{"openai/gpt-4o", false},
-		{"", false},
-	}
-	for _, tt := range tests {
-		if got := isAnthropicModel(tt.model); got != tt.want {
-			t.Errorf("isAnthropicModel(%q) = %v, want %v", tt.model, got, tt.want)
-		}
-	}
-}
-
-func TestIsAntigravityModel(t *testing.T) {
-	tests := []struct {
-		model string
-		want  bool
-	}{
-		{"antigravity", true},
-		{"google-antigravity", true},
-		{"antigravity/gemini-3-flash", true},
-		{"google-antigravity/gemini-3-flash", true},
-		{"openai", false},
-		{"antigravity-custom", false},
-		{"", false},
-	}
-	for _, tt := range tests {
-		if got := isAntigravityModel(tt.model); got != tt.want {
-			t.Errorf("isAntigravityModel(%q) = %v, want %v", tt.model, got, tt.want)
-		}
-	}
-}
-
-// ── Config update helpers ────────────────────────────────────────
-
-func writeTempConfigViaSave(t *testing.T, cfg *config.Config) string {
-	t.Helper()
-	dir := t.TempDir()
-	path := filepath.Join(dir, "config.json")
-	if err := config.SaveConfig(path, cfg); err != nil {
-		t.Fatalf("save config: %v", err)
-	}
-	return path
-}
-
-func loadTempConfig(t *testing.T, path string) *config.Config {
-	t.Helper()
-	cfg, err := config.LoadConfig(path)
-	if err != nil {
-		t.Fatalf("load config: %v", err)
-	}
-	return cfg
-}
-
-func TestUpdateConfigAfterLogin_OpenAI_ExistingModel(t *testing.T) {
-	cfg := &config.Config{
-		ModelList: []config.ModelConfig{
-			{ModelName: "gpt-4o", Model: "openai/gpt-4o"},
-		},
-	}
-	path := writeTempConfigViaSave(t, cfg)
-
-	cred := &auth.AuthCredential{AuthMethod: "oauth"}
-	updateConfigAfterLogin(path, "openai", cred)
-
-	result := loadTempConfig(t, path)
-
-	// Model-level auth_method persists through serialization
-	if len(result.ModelList) != 1 {
-		t.Fatalf("expected 1 model, got %d", len(result.ModelList))
-	}
-	if result.ModelList[0].AuthMethod != "oauth" {
-		t.Errorf("expected model auth_method=oauth, got %q", result.ModelList[0].AuthMethod)
-	}
-}
-
-func TestUpdateConfigAfterLogin_OpenAI_NoExistingModel(t *testing.T) {
-	cfg := &config.Config{
-		ModelList: []config.ModelConfig{
-			{ModelName: "claude", Model: "anthropic/claude-sonnet-4.6"},
-		},
-	}
-	path := writeTempConfigViaSave(t, cfg)
-
-	cred := &auth.AuthCredential{AuthMethod: "oauth"}
-	updateConfigAfterLogin(path, "openai", cred)
-
-	result := loadTempConfig(t, path)
-
-	if len(result.ModelList) != 2 {
-		t.Fatalf("expected 2 models (original + added), got %d", len(result.ModelList))
-	}
-	if result.ModelList[1].Model != "openai/gpt-5.2" {
-		t.Errorf("expected added model openai/gpt-5.2, got %q", result.ModelList[1].Model)
-	}
-	if result.Agents.Defaults.ModelName != "gpt-5.2" {
-		t.Errorf("expected default model_name=gpt-5.2, got %q", result.Agents.Defaults.ModelName)
-	}
-}
-
-func TestUpdateConfigAfterLogin_Anthropic(t *testing.T) {
-	cfg := &config.Config{}
-	path := writeTempConfigViaSave(t, cfg)
-
-	cred := &auth.AuthCredential{AuthMethod: "token"}
-	updateConfigAfterLogin(path, "anthropic", cred)
-
-	result := loadTempConfig(t, path)
-
-	// Model should be added with correct auth_method
-	if len(result.ModelList) != 1 {
-		t.Fatalf("expected 1 model added, got %d", len(result.ModelList))
-	}
-	if result.ModelList[0].Model != "anthropic/claude-sonnet-4.6" {
-		t.Errorf("expected model anthropic/claude-sonnet-4.6, got %q", result.ModelList[0].Model)
-	}
-	if result.ModelList[0].AuthMethod != "token" {
-		t.Errorf("expected model auth_method=token, got %q", result.ModelList[0].AuthMethod)
-	}
-}
-
-func TestUpdateConfigAfterLogin_GoogleAntigravity(t *testing.T) {
-	cfg := &config.Config{}
-	path := writeTempConfigViaSave(t, cfg)
-
-	cred := &auth.AuthCredential{AuthMethod: "oauth"}
-	updateConfigAfterLogin(path, "google-antigravity", cred)
-
-	result := loadTempConfig(t, path)
-
-	// Model should be added with correct auth_method
-	if len(result.ModelList) != 1 {
-		t.Fatalf("expected 1 model added, got %d", len(result.ModelList))
-	}
-	if result.ModelList[0].Model != "antigravity/gemini-3-flash" {
-		t.Errorf("expected model antigravity/gemini-3-flash, got %q", result.ModelList[0].Model)
-	}
-	if result.ModelList[0].AuthMethod != "oauth" {
-		t.Errorf("expected model auth_method=oauth, got %q", result.ModelList[0].AuthMethod)
-	}
-}
-
-func TestClearAuthMethodInConfig(t *testing.T) {
-	cfg := &config.Config{
-		ModelList: []config.ModelConfig{
-			{ModelName: "gpt-4o", Model: "openai/gpt-4o", AuthMethod: "oauth"},
-			{ModelName: "claude", Model: "anthropic/claude-sonnet-4.6", AuthMethod: "token"},
-		},
-	}
-	path := writeTempConfigViaSave(t, cfg)
-
-	clearAuthMethodInConfig(path, "openai")
-
-	result := loadTempConfig(t, path)
-
-	// Openai model auth_method should be cleared
-	if result.ModelList[0].AuthMethod != "" {
-		t.Errorf("expected openai model auth_method cleared, got %q", result.ModelList[0].AuthMethod)
-	}
-	// Anthropic model should be unchanged
-	if result.ModelList[1].AuthMethod != "token" {
-		t.Errorf("expected anthropic model auth_method unchanged, got %q", result.ModelList[1].AuthMethod)
-	}
-}
-
-func TestClearAllAuthMethodsInConfig(t *testing.T) {
-	cfg := &config.Config{
-		ModelList: []config.ModelConfig{
-			{ModelName: "gpt-4o", Model: "openai/gpt-4o", AuthMethod: "oauth"},
-			{ModelName: "claude", Model: "anthropic/claude-sonnet-4.6", AuthMethod: "token"},
-			{ModelName: "gemini", Model: "antigravity/gemini-3-flash", AuthMethod: "oauth"},
-		},
-	}
-	path := writeTempConfigViaSave(t, cfg)
-
-	clearAllAuthMethodsInConfig(path)
-
-	result := loadTempConfig(t, path)
-
-	for i, m := range result.ModelList {
-		if m.AuthMethod != "" {
-			t.Errorf("model[%d] auth_method not cleared, got %q", i, m.AuthMethod)
-		}
-	}
-}
diff --git a/cmd/picoclaw-launcher/internal/server/auth_handlers.go b/cmd/picoclaw-launcher/internal/server/auth_handlers.go
deleted file mode 100644
index 1e9b8be0a..000000000
--- a/cmd/picoclaw-launcher/internal/server/auth_handlers.go
+++ /dev/null
@@ -1,312 +0,0 @@
-package server
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"log"
-	"net/http"
-	"sync"
-	"time"
-
-	"github.com/sipeed/picoclaw/pkg/auth"
-	"github.com/sipeed/picoclaw/pkg/providers"
-)
-
-// oauthSession stores in-flight OAuth state for browser-based flows.
-type oauthSession struct {
-	Provider    string
-	PKCE        auth.PKCECodes
-	State       string
-	RedirectURI string
-	OAuthCfg    auth.OAuthProviderConfig
-	ConfigPath  string
-}
-
-// deviceCodeSession stores in-flight device code flow state.
-type deviceCodeSession struct {
-	mu         sync.Mutex
-	Provider   string
-	Info       *auth.DeviceCodeInfo
-	OAuthCfg   auth.OAuthProviderConfig
-	ConfigPath string
-	Status     string // "pending", "success", "error"
-	Error      string
-	Done       bool
-}
-
-var (
-	oauthSessions   = map[string]*oauthSession{} // keyed by state
-	oauthSessionsMu sync.Mutex
-
-	activeDeviceSession   *deviceCodeSession
-	activeDeviceSessionMu sync.Mutex
-)
-
-// handleOpenAILogin starts the OpenAI device code flow and returns device code info to the frontend.
-func handleOpenAILogin(w http.ResponseWriter, configPath string) {
-	// Check if there's already a pending device code session
-	activeDeviceSessionMu.Lock()
-	if activeDeviceSession != nil {
-		activeDeviceSession.mu.Lock()
-		if !activeDeviceSession.Done {
-			resp := map[string]any{
-				"status":     "pending",
-				"device_url": activeDeviceSession.Info.VerifyURL,
-				"user_code":  activeDeviceSession.Info.UserCode,
-				"message":    "Device code flow already in progress. Enter the code in your browser.",
-			}
-			activeDeviceSession.mu.Unlock()
-			activeDeviceSessionMu.Unlock()
-			w.Header().Set("Content-Type", "application/json")
-			json.NewEncoder(w).Encode(resp)
-			return
-		}
-		activeDeviceSession.mu.Unlock()
-	}
-	activeDeviceSessionMu.Unlock()
-
-	// Request a device code
-	oauthCfg := auth.OpenAIOAuthConfig()
-	info, err := auth.RequestDeviceCode(oauthCfg)
-	if err != nil {
-		http.Error(w, fmt.Sprintf("Failed to request device code: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	session := &deviceCodeSession{
-		Provider:   "openai",
-		Info:       info,
-		OAuthCfg:   oauthCfg,
-		ConfigPath: configPath,
-		Status:     "pending",
-	}
-
-	activeDeviceSessionMu.Lock()
-	activeDeviceSession = session
-	activeDeviceSessionMu.Unlock()
-
-	// Start background polling
-	go func() {
-		deadline := time.After(15 * time.Minute)
-		ticker := time.NewTicker(time.Duration(info.Interval) * time.Second)
-		defer ticker.Stop()
-
-		for {
-			select {
-			case <-deadline:
-				session.mu.Lock()
-				session.Status = "error"
-				session.Error = "Authentication timed out after 15 minutes"
-				session.Done = true
-				session.mu.Unlock()
-				return
-			case <-ticker.C:
-				cred, err := auth.PollDeviceCodeOnce(oauthCfg, info.DeviceAuthID, info.UserCode)
-				if err != nil {
-					continue // Still pending
-				}
-				if cred != nil {
-					if saveErr := auth.SetCredential("openai", cred); saveErr != nil {
-						session.mu.Lock()
-						session.Status = "error"
-						session.Error = saveErr.Error()
-						session.Done = true
-						session.mu.Unlock()
-						return
-					}
-					updateConfigAfterLogin(configPath, "openai", cred)
-					session.mu.Lock()
-					session.Status = "success"
-					session.Done = true
-					session.mu.Unlock()
-					log.Printf("OpenAI device code login successful (account: %s)", cred.AccountID)
-					return
-				}
-			}
-		}
-	}()
-
-	// Return device code info to frontend
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]any{
-		"status":     "pending",
-		"device_url": info.VerifyURL,
-		"user_code":  info.UserCode,
-		"message":    "Open the URL and enter the code to authenticate.",
-	})
-}
-
-// handleAnthropicLogin saves a pasted API token for Anthropic.
-func handleAnthropicLogin(w http.ResponseWriter, token, configPath string) {
-	if token == "" {
-		http.Error(w, "Token is required for Anthropic login", http.StatusBadRequest)
-		return
-	}
-
-	cred := &auth.AuthCredential{
-		AccessToken: token,
-		Provider:    "anthropic",
-		AuthMethod:  "token",
-	}
-
-	if err := auth.SetCredential("anthropic", cred); err != nil {
-		http.Error(w, fmt.Sprintf("Failed to save credentials: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	updateConfigAfterLogin(configPath, "anthropic", cred)
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]string{
-		"status":  "success",
-		"message": "Anthropic token saved",
-	})
-}
-
-// handleGoogleAntigravityLogin generates a PKCE + auth URL and returns it to the frontend.
-func handleGoogleAntigravityLogin(w http.ResponseWriter, r *http.Request, configPath string) {
-	oauthCfg := auth.GoogleAntigravityOAuthConfig()
-
-	pkce, err := auth.GeneratePKCE()
-	if err != nil {
-		http.Error(w, fmt.Sprintf("Failed to generate PKCE: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	state, err := auth.GenerateState()
-	if err != nil {
-		http.Error(w, fmt.Sprintf("Failed to generate state: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	// Build redirect URI pointing to picoclaw-launcher's own callback
-	scheme := "http"
-	redirectURI := fmt.Sprintf("%s://%s/auth/callback", scheme, r.Host)
-
-	authURL := auth.BuildAuthorizeURL(oauthCfg, pkce, state, redirectURI)
-
-	// Store session for callback
-	oauthSessionsMu.Lock()
-	oauthSessions[state] = &oauthSession{
-		Provider:    "google-antigravity",
-		PKCE:        pkce,
-		State:       state,
-		RedirectURI: redirectURI,
-		OAuthCfg:    oauthCfg,
-		ConfigPath:  configPath,
-	}
-	oauthSessionsMu.Unlock()
-
-	// Clean up stale sessions after 10 minutes
-	go func() {
-		time.Sleep(10 * time.Minute)
-		oauthSessionsMu.Lock()
-		delete(oauthSessions, state)
-		oauthSessionsMu.Unlock()
-	}()
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]string{
-		"status":   "redirect",
-		"auth_url": authURL,
-		"message":  "Open the URL to authenticate with Google.",
-	})
-}
-
-// handleOAuthCallback processes the OAuth callback from Google Antigravity.
-func handleOAuthCallback(w http.ResponseWriter, r *http.Request) {
-	state := r.URL.Query().Get("state")
-	code := r.URL.Query().Get("code")
-
-	oauthSessionsMu.Lock()
-	session, ok := oauthSessions[state]
-	if ok {
-		delete(oauthSessions, state)
-	}
-	oauthSessionsMu.Unlock()
-
-	if !ok {
-		http.Error(w, "Invalid or expired OAuth state", http.StatusBadRequest)
-		return
-	}
-
-	if code == "" {
-		errMsg := r.URL.Query().Get("error")
-		w.Header().Set("Content-Type", "text/html")
-		fmt.Fprintf(
-			w,
-			`<html><body><h2>Authentication failed</h2><p>%s</p><p>You can close this window.</p></body></html>`,
-			errMsg,
-		)
-		return
-	}
-
-	cred, err := auth.ExchangeCodeForTokens(session.OAuthCfg, code, session.PKCE.CodeVerifier, session.RedirectURI)
-	if err != nil {
-		w.Header().Set("Content-Type", "text/html")
-		fmt.Fprintf(
-			w,
-			`<html><body><h2>Authentication failed</h2><p>%s</p><p>You can close this window.</p></body></html>`,
-			err.Error(),
-		)
-		return
-	}
-
-	cred.Provider = session.Provider
-
-	// Fetch user info for Google Antigravity
-	if session.Provider == "google-antigravity" {
-		if email, err := fetchGoogleUserEmail(cred.AccessToken); err == nil {
-			cred.Email = email
-		}
-		if projectID, err := providers.FetchAntigravityProjectID(cred.AccessToken); err == nil {
-			cred.ProjectID = projectID
-		}
-	}
-
-	if err := auth.SetCredential(session.Provider, cred); err != nil {
-		w.Header().Set("Content-Type", "text/html")
-		fmt.Fprintf(w, `<html><body><h2>Failed to save credentials</h2><p>%s</p></body></html>`, err.Error())
-		return
-	}
-
-	updateConfigAfterLogin(session.ConfigPath, session.Provider, cred)
-
-	// Redirect back to picoclaw-launcher UI
-	w.Header().Set("Content-Type", "text/html")
-	fmt.Fprintf(w, `<html><body>
-		<h2>Authentication successful!</h2>
-		<p>Redirecting back to Config Editor...</p>
-		<script>setTimeout(function(){ window.location.href = '/#auth'; }, 1000);</script>
-	</body></html>`)
-}
-
-// fetchGoogleUserEmail retrieves the user's email from Google's userinfo endpoint.
-func fetchGoogleUserEmail(accessToken string) (string, error) {
-	req, err := http.NewRequest("GET", "https://www.googleapis.com/oauth2/v2/userinfo", nil)
-	if err != nil {
-		return "", err
-	}
-	req.Header.Set("Authorization", "Bearer "+accessToken)
-
-	client := &http.Client{Timeout: 10 * time.Second}
-	resp, err := client.Do(req)
-	if err != nil {
-		return "", err
-	}
-	defer resp.Body.Close()
-
-	body, _ := io.ReadAll(resp.Body)
-	if resp.StatusCode != http.StatusOK {
-		return "", fmt.Errorf("userinfo request failed: %s", string(body))
-	}
-
-	var userInfo struct {
-		Email string `json:"email"`
-	}
-	if err := json.Unmarshal(body, &userInfo); err != nil {
-		return "", err
-	}
-	return userInfo.Email, nil
-}
diff --git a/cmd/picoclaw-launcher/internal/server/logbuffer_test.go b/cmd/picoclaw-launcher/internal/server/logbuffer_test.go
deleted file mode 100644
index dc525be16..000000000
--- a/cmd/picoclaw-launcher/internal/server/logbuffer_test.go
+++ /dev/null
@@ -1,116 +0,0 @@
-package server
-
-import (
-	"fmt"
-	"sync"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-)
-
-func TestLogBuffer_Basic(t *testing.T) {
-	buf := NewLogBuffer(5)
-
-	// Empty buffer
-	lines, total, runID := buf.LinesSince(0)
-	assert.Nil(t, lines)
-	assert.Equal(t, 0, total)
-	assert.Equal(t, 0, runID)
-
-	// Append some lines
-	buf.Append("line1")
-	buf.Append("line2")
-	buf.Append("line3")
-
-	lines, total, runID = buf.LinesSince(0)
-	assert.Equal(t, []string{"line1", "line2", "line3"}, lines)
-	assert.Equal(t, 3, total)
-	assert.Equal(t, 0, runID)
-
-	// Incremental read
-	lines, total, _ = buf.LinesSince(2)
-	assert.Equal(t, []string{"line3"}, lines)
-	assert.Equal(t, 3, total)
-
-	// No new lines
-	lines, total, _ = buf.LinesSince(3)
-	assert.Nil(t, lines)
-	assert.Equal(t, 3, total)
-}
-
-func TestLogBuffer_Wrap(t *testing.T) {
-	buf := NewLogBuffer(3)
-
-	buf.Append("a")
-	buf.Append("b")
-	buf.Append("c")
-	buf.Append("d") // evicts "a"
-	buf.Append("e") // evicts "b"
-
-	lines, total, _ := buf.LinesSince(0)
-	assert.Equal(t, []string{"c", "d", "e"}, lines)
-	assert.Equal(t, 5, total)
-
-	// Incremental after wrap
-	lines, total, _ = buf.LinesSince(3)
-	assert.Equal(t, []string{"d", "e"}, lines)
-	assert.Equal(t, 5, total)
-
-	// Offset too old (before buffer start), get all buffered
-	lines, total, _ = buf.LinesSince(1)
-	assert.Equal(t, []string{"c", "d", "e"}, lines)
-	assert.Equal(t, 5, total)
-}
-
-func TestLogBuffer_Reset(t *testing.T) {
-	buf := NewLogBuffer(5)
-
-	buf.Append("before")
-	assert.Equal(t, 0, buf.RunID())
-
-	buf.Reset()
-	assert.Equal(t, 1, buf.RunID())
-	assert.Equal(t, 0, buf.Total())
-
-	lines, total, runID := buf.LinesSince(0)
-	assert.Nil(t, lines)
-	assert.Equal(t, 0, total)
-	assert.Equal(t, 1, runID)
-
-	buf.Append("after")
-	lines, total, runID = buf.LinesSince(0)
-	assert.Equal(t, []string{"after"}, lines)
-	assert.Equal(t, 1, total)
-	assert.Equal(t, 1, runID)
-}
-
-func TestLogBuffer_Concurrent(t *testing.T) {
-	buf := NewLogBuffer(100)
-	var wg sync.WaitGroup
-
-	// 10 writers
-	for i := range 10 {
-		wg.Add(1)
-		go func(id int) {
-			defer wg.Done()
-			for j := range 50 {
-				buf.Append(fmt.Sprintf("writer-%d-line-%d", id, j))
-			}
-		}(i)
-	}
-
-	// 5 readers
-	for range 5 {
-		wg.Add(1)
-		go func() {
-			defer wg.Done()
-			for range 100 {
-				buf.LinesSince(0)
-			}
-		}()
-	}
-
-	wg.Wait()
-
-	assert.Equal(t, 500, buf.Total())
-}
diff --git a/cmd/picoclaw-launcher/internal/server/process.go b/cmd/picoclaw-launcher/internal/server/process.go
deleted file mode 100644
index bc2129bf5..000000000
--- a/cmd/picoclaw-launcher/internal/server/process.go
+++ /dev/null
@@ -1,232 +0,0 @@
-package server
-
-import (
-	"bufio"
-	"encoding/json"
-	"fmt"
-	"io"
-	"log"
-	"net"
-	"net/http"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"runtime"
-	"strconv"
-	"time"
-
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-// gatewayLogs stores captured stdout/stderr from the gateway process launched by the launcher.
-var gatewayLogs = NewLogBuffer(200)
-
-// RegisterProcessAPI registers endpoints to start, stop and check status of the picoclaw gateway.
-func RegisterProcessAPI(mux *http.ServeMux, absPath string) {
-	mux.HandleFunc("GET /api/process/status", func(w http.ResponseWriter, r *http.Request) {
-		handleStatusGateway(w, r, absPath)
-	})
-	mux.HandleFunc("POST /api/process/start", handleStartGateway)
-	mux.HandleFunc("POST /api/process/stop", handleStopGateway)
-}
-
-func handleStartGateway(w http.ResponseWriter, r *http.Request) {
-	// Locate picoclaw executable:
-	// 1. Try same directory as current executable
-	// 2. Fallback to just "picoclaw" (relies on $PATH)
-	execPath := "picoclaw"
-
-	if exe, err := os.Executable(); err == nil {
-		dir := filepath.Dir(exe)
-		candidate := filepath.Join(dir, "picoclaw")
-		if runtime.GOOS == "windows" {
-			candidate += ".exe"
-		}
-
-		if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
-			execPath = candidate
-		}
-	}
-
-	cmd := exec.Command(execPath, "gateway")
-
-	stdoutPipe, err := cmd.StdoutPipe()
-	if err != nil {
-		log.Printf("Failed to create stdout pipe: %v\n", err)
-		http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	stderrPipe, err := cmd.StderrPipe()
-	if err != nil {
-		log.Printf("Failed to create stderr pipe: %v\n", err)
-		http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	// Clear old logs and increment runID before starting
-	gatewayLogs.Reset()
-
-	if err := cmd.Start(); err != nil {
-		log.Printf("Failed to start picoclaw gateway: %v\n", err)
-		http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
-		return
-	}
-
-	// Read stdout and stderr into the log buffer
-	go scanPipe(stdoutPipe, gatewayLogs)
-	go scanPipe(stderrPipe, gatewayLogs)
-
-	// Wait for the process to exit in the background to avoid zombies
-	go func() {
-		if err := cmd.Wait(); err != nil {
-			log.Printf("Gateway process exited: %v\n", err)
-		}
-	}()
-
-	log.Printf("Started picoclaw gateway (PID: %d) from %s\n", cmd.Process.Pid, execPath)
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]any{
-		"status": "ok",
-		"pid":    cmd.Process.Pid,
-	})
-}
-
-// scanPipe reads lines from r and appends them to buf. It returns when r reaches EOF.
-func scanPipe(r io.Reader, buf *LogBuffer) {
-	scanner := bufio.NewScanner(r)
-	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024) // up to 1MB per line
-
-	for scanner.Scan() {
-		buf.Append(scanner.Text())
-	}
-}
-
-func handleStopGateway(w http.ResponseWriter, r *http.Request) {
-	var err error
-	if runtime.GOOS == "windows" {
-		// Kill via taskkill finding picoclaw.exe (though it might kill this config tool if it's named picoclaw-launcher.exe...? No, /IM does exact match usually, but just to be safe let's stop exactly picoclaw.exe)
-		// Alternatively, we use powershell to kill processes with commandline containing 'gateway'
-		psCmd := `Get-WmiObject Win32_Process | Where-Object { $_.CommandLine -match 'picoclaw.*gateway' } | ForEach-Object { Stop-Process $_.ProcessId -Force }`
-		err = exec.Command("powershell", "-Command", psCmd).Run()
-	} else {
-		// Linux/macOS
-		err = exec.Command("pkill", "-f", "picoclaw gateway").Run()
-	}
-
-	if err != nil {
-		log.Printf("Warning: Failed to stop gateway (perhaps not running?): %v\n", err)
-		// We still return 200 OK because pkill returns an error if no process was found
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]any{
-			"status": "ok", // or "not_found"
-			"msg":    "Stop command executed, but returned error (process might not be running).",
-			"error":  err.Error(),
-		})
-		return
-	}
-
-	log.Printf("Stopped picoclaw gateway processes.\n")
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(map[string]string{
-		"status": "ok",
-	})
-}
-
-func handleStatusGateway(w http.ResponseWriter, r *http.Request, absPath string) {
-	cfg, cfgErr := config.LoadConfig(absPath)
-	host := "127.0.0.1"
-	port := 18790
-	if cfgErr == nil && cfg != nil {
-		if cfg.Gateway.Host != "" && cfg.Gateway.Host != "0.0.0.0" {
-			host = cfg.Gateway.Host
-		}
-		if cfg.Gateway.Port != 0 {
-			port = cfg.Gateway.Port
-		}
-	}
-
-	url := fmt.Sprintf("http://%s/health", net.JoinHostPort(host, strconv.Itoa(port)))
-	client := http.Client{Timeout: 2 * time.Second}
-	resp, err := client.Get(url)
-
-	// Build the response data map
-	data := map[string]any{}
-
-	if err != nil {
-		data["process_status"] = "stopped"
-		data["error"] = err.Error()
-	} else {
-		defer resp.Body.Close()
-
-		if resp.StatusCode != http.StatusOK {
-			data["process_status"] = "error"
-			data["status_code"] = resp.StatusCode
-		} else {
-			var healthData map[string]any
-			if decErr := json.NewDecoder(resp.Body).Decode(&healthData); decErr != nil {
-				data["process_status"] = "error"
-				data["error"] = "invalid response from gateway"
-			} else {
-				// Gateway is running and responded properly — merge health data
-				for k, v := range healthData {
-					data[k] = v
-				}
-				data["process_status"] = "running"
-			}
-		}
-	}
-
-	// Append log data from the buffer
-	appendLogData(r, data)
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(data)
-}
-
-// appendLogData reads log_offset and log_run_id query params from the request and
-// populates the response data map with incremental log lines.
-func appendLogData(r *http.Request, data map[string]any) {
-	clientOffset := 0
-	clientRunID := -1
-
-	if v := r.URL.Query().Get("log_offset"); v != "" {
-		if n, err := strconv.Atoi(v); err == nil {
-			clientOffset = n
-		}
-	}
-
-	if v := r.URL.Query().Get("log_run_id"); v != "" {
-		if n, err := strconv.Atoi(v); err == nil {
-			clientRunID = n
-		}
-	}
-
-	runID := gatewayLogs.RunID()
-
-	// If runID is 0 (never reset = never launched from this launcher), report no source
-	if runID == 0 {
-		data["logs"] = []string{}
-		data["log_total"] = 0
-		data["log_run_id"] = 0
-		data["log_source"] = "none"
-		return
-	}
-
-	// If the client's runID doesn't match, send all buffered lines (gateway restarted)
-	offset := clientOffset
-	if clientRunID != runID {
-		offset = 0
-	}
-
-	lines, total, runID := gatewayLogs.LinesSince(offset)
-	if lines == nil {
-		lines = []string{}
-	}
-
-	data["logs"] = lines
-	data["log_total"] = total
-	data["log_run_id"] = runID
-	data["log_source"] = "launcher"
-}
diff --git a/cmd/picoclaw-launcher/internal/server/server.go b/cmd/picoclaw-launcher/internal/server/server.go
deleted file mode 100644
index 4fc68f04c..000000000
--- a/cmd/picoclaw-launcher/internal/server/server.go
+++ /dev/null
@@ -1,196 +0,0 @@
-package server
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-	"log"
-	"net/http"
-	"time"
-
-	"github.com/sipeed/picoclaw/pkg/auth"
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-const DefaultPort = "18800"
-
-// providerStatus represents the auth status of a single provider in API responses.
-type providerStatus struct {
-	Provider   string `json:"provider"`
-	AuthMethod string `json:"auth_method"`
-	Status     string `json:"status"`
-	AccountID  string `json:"account_id,omitempty"`
-	Email      string `json:"email,omitempty"`
-	ProjectID  string `json:"project_id,omitempty"`
-	ExpiresAt  string `json:"expires_at,omitempty"`
-}
-
-// ── Route registration ───────────────────────────────────────────
-
-func RegisterConfigAPI(mux *http.ServeMux, absPath string) {
-	// GET /api/config — read config
-	mux.HandleFunc("GET /api/config", func(w http.ResponseWriter, r *http.Request) {
-		cfg, err := config.LoadConfig(absPath)
-		if err != nil {
-			http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
-			return
-		}
-		w.Header().Set("Content-Type", "application/json")
-		resp := map[string]any{
-			"config": cfg,
-			"path":   absPath,
-		}
-		enc := json.NewEncoder(w)
-		enc.SetIndent("", "  ")
-		if err := enc.Encode(resp); err != nil {
-			log.Printf("Failed to encode response: %v", err)
-		}
-	})
-
-	// PUT /api/config — save config
-	mux.HandleFunc("PUT /api/config", func(w http.ResponseWriter, r *http.Request) {
-		body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
-		if err != nil {
-			http.Error(w, "Failed to read request body", http.StatusBadRequest)
-			return
-		}
-		defer r.Body.Close()
-
-		var cfg config.Config
-		if err := json.Unmarshal(body, &cfg); err != nil {
-			http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
-			return
-		}
-
-		if err := config.SaveConfig(absPath, &cfg); err != nil {
-			http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
-			return
-		}
-
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
-	})
-}
-
-func RegisterAuthAPI(mux *http.ServeMux, absPath string) {
-	// GET /api/auth/status — all authenticated providers + pending login state
-	mux.HandleFunc("GET /api/auth/status", func(w http.ResponseWriter, r *http.Request) {
-		store, err := auth.LoadStore()
-		if err != nil {
-			http.Error(w, fmt.Sprintf("Failed to load auth store: %v", err), http.StatusInternalServerError)
-			return
-		}
-
-		result := []providerStatus{}
-		for name, cred := range store.Credentials {
-			status := "active"
-			if cred.IsExpired() {
-				status = "expired"
-			} else if cred.NeedsRefresh() {
-				status = "needs_refresh"
-			}
-			ps := providerStatus{
-				Provider:   name,
-				AuthMethod: cred.AuthMethod,
-				Status:     status,
-				AccountID:  cred.AccountID,
-				Email:      cred.Email,
-				ProjectID:  cred.ProjectID,
-			}
-			if !cred.ExpiresAt.IsZero() {
-				ps.ExpiresAt = cred.ExpiresAt.Format(time.RFC3339)
-			}
-			result = append(result, ps)
-		}
-
-		// Include pending device code state
-		var pendingDevice map[string]any
-		activeDeviceSessionMu.Lock()
-		if activeDeviceSession != nil {
-			activeDeviceSession.mu.Lock()
-			pendingDevice = map[string]any{
-				"provider":   activeDeviceSession.Provider,
-				"status":     activeDeviceSession.Status,
-				"device_url": activeDeviceSession.Info.VerifyURL,
-				"user_code":  activeDeviceSession.Info.UserCode,
-			}
-			if activeDeviceSession.Error != "" {
-				pendingDevice["error"] = activeDeviceSession.Error
-			}
-			if activeDeviceSession.Done {
-				activeDeviceSession.mu.Unlock()
-				activeDeviceSession = nil
-			} else {
-				activeDeviceSession.mu.Unlock()
-			}
-		}
-		activeDeviceSessionMu.Unlock()
-
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]any{
-			"providers":      result,
-			"pending_device": pendingDevice,
-		})
-	})
-
-	// POST /api/auth/login — initiate provider login
-	mux.HandleFunc("POST /api/auth/login", func(w http.ResponseWriter, r *http.Request) {
-		var req struct {
-			Provider string `json:"provider"`
-			Token    string `json:"token,omitempty"`
-		}
-		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-			http.Error(w, "Invalid request body", http.StatusBadRequest)
-			return
-		}
-
-		switch req.Provider {
-		case "openai":
-			handleOpenAILogin(w, absPath)
-		case "anthropic":
-			handleAnthropicLogin(w, req.Token, absPath)
-		case "google-antigravity", "antigravity":
-			handleGoogleAntigravityLogin(w, r, absPath)
-		default:
-			http.Error(
-				w,
-				fmt.Sprintf(
-					"Unsupported provider: %s (supported: openai, anthropic, google-antigravity)",
-					req.Provider,
-				),
-				http.StatusBadRequest,
-			)
-		}
-	})
-
-	// POST /api/auth/logout — logout a provider
-	mux.HandleFunc("POST /api/auth/logout", func(w http.ResponseWriter, r *http.Request) {
-		var req struct {
-			Provider string `json:"provider"`
-		}
-		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
-			http.Error(w, "Invalid request body", http.StatusBadRequest)
-			return
-		}
-
-		if req.Provider == "" {
-			if err := auth.DeleteAllCredentials(); err != nil {
-				http.Error(w, fmt.Sprintf("Failed to logout: %v", err), http.StatusInternalServerError)
-				return
-			}
-			clearAllAuthMethodsInConfig(absPath)
-		} else {
-			if err := auth.DeleteCredential(req.Provider); err != nil {
-				http.Error(w, fmt.Sprintf("Failed to logout: %v", err), http.StatusInternalServerError)
-				return
-			}
-			clearAuthMethodInConfig(absPath, req.Provider)
-		}
-
-		w.Header().Set("Content-Type", "application/json")
-		json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
-	})
-
-	// GET /auth/callback — OAuth browser callback for Google Antigravity
-	mux.HandleFunc("GET /auth/callback", handleOAuthCallback)
-}
diff --git a/cmd/picoclaw-launcher/internal/server/server_test.go b/cmd/picoclaw-launcher/internal/server/server_test.go
deleted file mode 100644
index c87e93d8c..000000000
--- a/cmd/picoclaw-launcher/internal/server/server_test.go
+++ /dev/null
@@ -1,247 +0,0 @@
-package server
-
-import (
-	"encoding/json"
-	"net/http"
-	"net/http/httptest"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-// ── Config API tests ─────────────────────────────────────────────
-
-func setupConfigMux(t *testing.T, cfg *config.Config) (*http.ServeMux, string) {
-	t.Helper()
-	dir := t.TempDir()
-	path := filepath.Join(dir, "config.json")
-	data, err := json.MarshalIndent(cfg, "", "  ")
-	if err != nil {
-		t.Fatalf("marshal config: %v", err)
-	}
-	if err := os.WriteFile(path, data, 0o600); err != nil {
-		t.Fatalf("write config: %v", err)
-	}
-
-	mux := http.NewServeMux()
-	RegisterConfigAPI(mux, path)
-	RegisterAuthAPI(mux, path)
-	return mux, path
-}
-
-func TestGetConfig(t *testing.T) {
-	cfg := &config.Config{
-		ModelList: []config.ModelConfig{
-			{ModelName: "gpt-4o", Model: "openai/gpt-4o"},
-		},
-	}
-	mux, path := setupConfigMux(t, cfg)
-
-	req := httptest.NewRequest("GET", "/api/config", nil)
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusOK {
-		t.Fatalf("GET /api/config: expected 200, got %d: %s", w.Code, w.Body.String())
-	}
-
-	var resp struct {
-		Config config.Config `json:"config"`
-		Path   string        `json:"path"`
-	}
-	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
-		t.Fatalf("decode response: %v", err)
-	}
-
-	if resp.Path != path {
-		t.Errorf("expected path %q, got %q", path, resp.Path)
-	}
-	if len(resp.Config.ModelList) != 1 {
-		t.Errorf("expected 1 model, got %d", len(resp.Config.ModelList))
-	}
-}
-
-func TestGetConfig_MissingFile_ReturnsDefault(t *testing.T) {
-	mux := http.NewServeMux()
-	RegisterConfigAPI(mux, "/tmp/nonexistent-picoclaw-launcher-test/config.json")
-
-	req := httptest.NewRequest("GET", "/api/config", nil)
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	// LoadConfig returns a default empty config when file is missing
-	if w.Code != http.StatusOK {
-		t.Errorf("expected 200 for missing file (default config), got %d", w.Code)
-	}
-}
-
-func TestPutConfig(t *testing.T) {
-	cfg := &config.Config{}
-	mux, path := setupConfigMux(t, cfg)
-
-	newCfg := config.Config{
-		ModelList: []config.ModelConfig{
-			{ModelName: "claude", Model: "anthropic/claude-sonnet-4.6", AuthMethod: "token"},
-		},
-	}
-	body, _ := json.Marshal(newCfg)
-
-	req := httptest.NewRequest("PUT", "/api/config", strings.NewReader(string(body)))
-	req.Header.Set("Content-Type", "application/json")
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusOK {
-		t.Fatalf("PUT /api/config: expected 200, got %d: %s", w.Code, w.Body.String())
-	}
-
-	saved, err := config.LoadConfig(path)
-	if err != nil {
-		t.Fatalf("load saved config: %v", err)
-	}
-	if len(saved.ModelList) != 1 {
-		t.Fatalf("expected 1 model saved, got %d", len(saved.ModelList))
-	}
-	if saved.ModelList[0].Model != "anthropic/claude-sonnet-4.6" {
-		t.Errorf("expected model anthropic/claude-sonnet-4.6, got %q", saved.ModelList[0].Model)
-	}
-}
-
-func TestPutConfig_InvalidJSON(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	req := httptest.NewRequest("PUT", "/api/config", strings.NewReader("{invalid"))
-	req.Header.Set("Content-Type", "application/json")
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("expected 400 for invalid JSON, got %d", w.Code)
-	}
-}
-
-// ── Auth API tests ───────────────────────────────────────────────
-
-func TestAuthStatus(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	req := httptest.NewRequest("GET", "/api/auth/status", nil)
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusOK {
-		t.Fatalf("GET /api/auth/status: expected 200, got %d: %s", w.Code, w.Body.String())
-	}
-
-	var resp struct {
-		Providers     []providerStatus `json:"providers"`
-		PendingDevice map[string]any   `json:"pending_device"`
-	}
-	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
-		t.Fatalf("decode response: %v", err)
-	}
-
-	// providers should be a non-nil list (could be empty)
-	if resp.Providers == nil {
-		t.Error("providers should not be nil")
-	}
-}
-
-func TestAuthLogin_UnsupportedProvider(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	body := `{"provider": "unsupported"}`
-	req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader(body))
-	req.Header.Set("Content-Type", "application/json")
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("expected 400 for unsupported provider, got %d", w.Code)
-	}
-}
-
-func TestAuthLogin_AnthropicNoToken(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	body := `{"provider": "anthropic"}`
-	req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader(body))
-	req.Header.Set("Content-Type", "application/json")
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("expected 400 for anthropic without token, got %d", w.Code)
-	}
-}
-
-func TestAuthLogin_InvalidBody(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	req := httptest.NewRequest("POST", "/api/auth/login", strings.NewReader("{bad"))
-	req.Header.Set("Content-Type", "application/json")
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("expected 400 for invalid JSON body, got %d", w.Code)
-	}
-}
-
-func TestAuthLogout_InvalidBody(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	req := httptest.NewRequest("POST", "/api/auth/logout", strings.NewReader("{bad"))
-	req.Header.Set("Content-Type", "application/json")
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("expected 400 for invalid body, got %d", w.Code)
-	}
-}
-
-func TestOAuthCallback_InvalidState(t *testing.T) {
-	cfg := &config.Config{}
-	mux, _ := setupConfigMux(t, cfg)
-
-	req := httptest.NewRequest("GET", "/auth/callback?state=invalid&code=test", nil)
-	w := httptest.NewRecorder()
-	mux.ServeHTTP(w, req)
-
-	if w.Code != http.StatusBadRequest {
-		t.Errorf("expected 400 for invalid state, got %d", w.Code)
-	}
-}
-
-// ── Utility tests ────────────────────────────────────────────────
-
-func TestDefaultConfigPath(t *testing.T) {
-	path := DefaultConfigPath()
-	if path == "" {
-		t.Error("defaultConfigPath should not return empty")
-	}
-	if !strings.HasSuffix(path, filepath.Join(".picoclaw", "config.json")) {
-		t.Errorf("expected path ending with .picoclaw/config.json, got %q", path)
-	}
-}
-
-func TestGetLocalIP(t *testing.T) {
-	// Just ensure it doesn't panic; IP may or may not be available
-	ip := GetLocalIP()
-	if ip != "" {
-		// If returned, should look like an IP
-		if !strings.Contains(ip, ".") {
-			t.Errorf("getLocalIP returned non-IPv4 looking string: %q", ip)
-		}
-	}
-}
diff --git a/cmd/picoclaw-launcher/internal/server/utils.go b/cmd/picoclaw-launcher/internal/server/utils.go
deleted file mode 100644
index a46adbece..000000000
--- a/cmd/picoclaw-launcher/internal/server/utils.go
+++ /dev/null
@@ -1,28 +0,0 @@
-package server
-
-import (
-	"net"
-	"os"
-	"path/filepath"
-)
-
-func DefaultConfigPath() string {
-	home, err := os.UserHomeDir()
-	if err != nil {
-		return "config.json"
-	}
-	return filepath.Join(home, ".picoclaw", "config.json")
-}
-
-func GetLocalIP() string {
-	addrs, err := net.InterfaceAddrs()
-	if err != nil {
-		return ""
-	}
-	for _, a := range addrs {
-		if ipnet, ok := a.(*net.IPNet); ok && !ipnet.IP.IsLoopback() && ipnet.IP.To4() != nil {
-			return ipnet.IP.String()
-		}
-	}
-	return ""
-}
diff --git a/cmd/picoclaw-launcher/internal/ui/index.html b/cmd/picoclaw-launcher/internal/ui/index.html
deleted file mode 100644
index 93893fd75..000000000
--- a/cmd/picoclaw-launcher/internal/ui/index.html
+++ /dev/null
@@ -1,1999 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-
-<head>
-    <script>
-    // Apply theme before paint to avoid flash
-    (function(){
-        var s = localStorage.getItem('picoclaw-theme') || 'system';
-        var t = s === 'system' ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : s;
-        document.documentElement.setAttribute('data-theme', t);
-    })();
-    </script>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>PicoClaw Config</title>
-    <meta name="description" content="PicoClaw configuration editor">
-    <link rel="preconnect" href="https://fonts.googleapis.com">
-    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap"
-          rel="stylesheet">
-    <style>
-        *, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }
-
-        :root {
-            --radius: 12px;
-            --transition: 200ms cubic-bezier(0.4, 0, 0.2, 1);
-            --sidebar-w: 220px;
-        }
-
-        /* Dark theme (default) */
-        [data-theme="dark"] {
-            --bg-primary: #0f1117;
-            --bg-secondary: #161822;
-            --bg-elevated: #1c1f2e;
-            --bg-editor: #12141e;
-            --border: #2a2d3e;
-            --border-focus: #6366f1;
-            --text-primary: #e2e8f0;
-            --text-secondary: #94a3b8;
-            --text-muted: #64748b;
-            --accent: #6366f1;
-            --accent-hover: #818cf8;
-            --accent-glow: rgba(99, 102, 241, 0.15);
-            --success: #22c55e;
-            --success-bg: rgba(34, 197, 94, 0.1);
-            --error: #ef4444;
-            --error-bg: rgba(239, 68, 68, 0.1);
-            --warning: #f59e0b;
-            --warning-bg: rgba(245, 158, 11, 0.1);
-            --link: #818cf8;
-        }
-
-        /* Light theme */
-        [data-theme="light"] {
-            --bg-primary: #f8f9fb;
-            --bg-secondary: #ffffff;
-            --bg-elevated: #f1f3f5;
-            --bg-editor: #ffffff;
-            --border: #d5d9e0;
-            --border-focus: #6366f1;
-            --text-primary: #1a1d2e;
-            --text-secondary: #4b5563;
-            --text-muted: #8892a4;
-            --accent: #6366f1;
-            --accent-hover: #4f46e5;
-            --accent-glow: rgba(99, 102, 241, 0.12);
-            --success: #16a34a;
-            --success-bg: rgba(22, 163, 74, 0.08);
-            --error: #dc2626;
-            --error-bg: rgba(220, 38, 38, 0.08);
-            --warning: #d97706;
-            --warning-bg: rgba(217, 119, 6, 0.08);
-            --link: #4f46e5;
-        }
-
-        body {
-            font-family: 'Inter', -apple-system, BlinkMacSystemFont, sans-serif;
-            background: var(--bg-primary);
-            color: var(--text-primary);
-            min-height: 100vh;
-            display: flex;
-            flex-direction: column;
-        }
-
-        /* ── Header ─────────────────────────────────── */
-        .header {
-            background: var(--bg-secondary);
-            border-bottom: 1px solid var(--border);
-            padding: 12px 24px;
-            display: flex;
-            align-items: center;
-            justify-content: space-between;
-            position: sticky;
-            top: 0;
-            z-index: 100;
-            backdrop-filter: blur(12px);
-            gap: 16px;
-        }
-        .header-left {
-            display: flex;
-            align-items: center;
-            gap: 12px;
-            flex-shrink: 0;
-        }
-        .logo {
-            width: 32px; height: 32px;
-            background: linear-gradient(135deg, var(--accent), #a78bfa);
-            border-radius: 8px;
-            display: flex; align-items: center; justify-content: center;
-            font-size: 16px; font-weight: 700; color: #fff;
-            box-shadow: 0 2px 12px var(--accent-glow);
-        }
-        .header h1 {
-            font-size: 16px; font-weight: 600; letter-spacing: -0.02em; white-space: nowrap;
-        }
-        .header h1 span { color: var(--text-muted); font-weight: 400; margin-left: 6px; font-size: 13px; }
-
-        .header-center { flex: 1; display: flex; justify-content: center; align-items: center; }
-        .header-right { display: flex; align-items: center; gap: 10px; flex-shrink: 0; }
-
-        /* Language switcher */
-        .lang-btn {
-            font-family: 'Inter', sans-serif; font-size: 12px; font-weight: 500;
-            padding: 5px 10px; border-radius: 6px;
-            border: 1px solid var(--border); background: var(--bg-elevated);
-            color: var(--text-secondary); cursor: pointer;
-            transition: all var(--transition);
-        }
-        .lang-btn:hover { border-color: var(--text-muted); color: var(--text-primary); }
-
-        /* Buttons */
-        .btn {
-            font-family: 'Inter', sans-serif; font-size: 13px; font-weight: 500;
-            padding: 7px 16px; border-radius: 8px;
-            border: 1px solid var(--border); background: var(--bg-elevated);
-            color: var(--text-primary); cursor: pointer;
-            transition: all var(--transition);
-            display: inline-flex; align-items: center; gap: 6px; white-space: nowrap;
-        }
-        .btn:hover { border-color: var(--text-muted); background: var(--bg-secondary); transform: translateY(-1px); }
-        .btn:active { transform: translateY(0); }
-        .btn-primary { background: var(--accent); border-color: var(--accent); color: #fff; box-shadow: 0 2px 8px var(--accent-glow); }
-        .btn-primary:hover { background: var(--accent-hover); border-color: var(--accent-hover); }
-        .btn-sm { padding: 5px 12px; font-size: 12px; }
-        .btn-danger { border-color: rgba(239, 68, 68, 0.3); color: var(--error); }
-        .btn-danger:hover { background: var(--error-bg); border-color: var(--error); }
-        .btn-success { border-color: rgba(34, 197, 94, 0.3); color: var(--success); }
-        .btn-success:hover { background: var(--success-bg); border-color: var(--success); }
-        .btn-run { background: var(--success); border-color: var(--success); color: #fff; }
-        .btn-run:hover { background: #16a34a; }
-        .btn-process { padding: 8px 28px; font-size: 14px; font-weight: 600; border-radius: 10px; letter-spacing: 0.01em; }
-        .btn-process .btn-spinner {
-            width: 14px; height: 14px; border: 2px solid rgba(255,255,255,0.3);
-            border-top-color: #fff; border-radius: 50%;
-            animation: spin 0.7s linear infinite; display: inline-block;
-        }
-        .process-hint { font-size: 12px; color: var(--text-muted); margin-left: 10px; white-space: nowrap; }
-        .btn-stop { background: var(--error); border-color: var(--error); color: #fff; }
-        .btn-stop:hover { background: #dc2626; }
-        .btn:disabled { opacity: 0.5; cursor: not-allowed; transform: none !important; }
-        .btn .icon { font-size: 14px; }
-
-        /* ── Toast notifications ────────────────────── */
-        .toast-container {
-            position: fixed; top: 60px; left: 50%; transform: translateX(-50%);
-            z-index: 300; display: flex; flex-direction: column; align-items: center; gap: 8px;
-            pointer-events: none;
-        }
-        .toast {
-            font-size: 13px; font-weight: 500; padding: 10px 20px;
-            border-radius: 10px; display: inline-flex; align-items: center; gap: 6px;
-            pointer-events: auto; box-shadow: 0 4px 20px rgba(0,0,0,0.25);
-            animation: toastIn 300ms ease-out;
-            transition: opacity 300ms ease;
-        }
-        .toast.success { background: var(--success-bg); color: var(--success); border: 1px solid rgba(34, 197, 94, 0.3); backdrop-filter: blur(8px); }
-        .toast.error { background: var(--error-bg); color: var(--error); border: 1px solid rgba(239, 68, 68, 0.3); backdrop-filter: blur(8px); }
-        .toast.fade-out { opacity: 0; }
-        @keyframes toastIn { from { opacity: 0; transform: translateY(-12px); } to { opacity: 1; transform: translateY(0); } }
-
-        /* ── Layout ──────────────────────────────────── */
-        .main { flex: 1; display: flex; flex-direction: column; overflow: hidden; }
-
-        /* Settings layout */
-        .settings-layout { display: flex; flex: 1; overflow: hidden; }
-
-        /* Sidebar */
-        .sidebar {
-            width: var(--sidebar-w); flex-shrink: 0;
-            background: var(--bg-secondary); border-right: 1px solid var(--border);
-            overflow-y: auto; padding: 12px 0;
-        }
-        .sidebar-group { margin-bottom: 4px; }
-        .sidebar-group-title {
-            font-size: 11px; font-weight: 600; text-transform: uppercase;
-            letter-spacing: 0.06em; color: var(--text-muted);
-            padding: 8px 16px 4px; cursor: pointer;
-            display: flex; align-items: center; justify-content: space-between;
-            user-select: none;
-        }
-        .sidebar-group-title:hover { color: var(--text-secondary); }
-        .sidebar-group-title .arrow {
-            font-size: 10px; transition: transform var(--transition);
-        }
-        .sidebar-group.collapsed .arrow { transform: rotate(-90deg); }
-        .sidebar-group.collapsed .sidebar-items { display: none; }
-        .sidebar-item {
-            font-size: 13px; padding: 6px 16px 6px 28px;
-            color: var(--text-secondary); cursor: pointer;
-            transition: all var(--transition); border-left: 2px solid transparent;
-        }
-        .sidebar-item:hover { background: var(--bg-elevated); color: var(--text-primary); }
-        .sidebar-item.active {
-            background: var(--accent-glow); color: var(--accent-hover);
-            border-left-color: var(--accent);
-        }
-        .sidebar-divider { height: 1px; background: var(--border); margin: 8px 16px; }
-        .sidebar-item.standalone {
-            padding-left: 16px; font-weight: 500; color: var(--text-muted);
-        }
-
-        /* Content area */
-        .content { flex: 1; overflow-y: auto; padding: 24px; }
-        .content-panel { display: none; }
-        .content-panel.active { display: block; }
-
-        .panel-title { font-size: 18px; font-weight: 600; margin-bottom: 4px; }
-        .panel-desc { font-size: 13px; color: var(--text-muted); margin-bottom: 20px; }
-        .panel-desc a.doc-link {
-            color: var(--link, var(--accent-hover)); font-weight: 500;
-            text-decoration: none; border-bottom: 1px dashed var(--link, var(--accent-hover));
-            padding-bottom: 1px; transition: opacity var(--transition);
-        }
-        .panel-desc a.doc-link:hover { opacity: 0.8; }
-
-        /* Theme toggle */
-        .theme-btn {
-            font-family: 'Inter', sans-serif; font-size: 14px;
-            width: 32px; height: 32px; border-radius: 6px;
-            border: 1px solid var(--border); background: var(--bg-elevated);
-            color: var(--text-secondary); cursor: pointer;
-            transition: all var(--transition);
-            display: flex; align-items: center; justify-content: center;
-            line-height: 1;
-        }
-        .theme-btn:hover { border-color: var(--text-muted); color: var(--text-primary); }
-
-        /* ── Model cards ─────────────────────────────── */
-        .model-grid {
-            display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
-            gap: 12px; margin-bottom: 16px;
-        }
-        .model-card {
-            background: var(--bg-secondary); border: 1px solid var(--border);
-            border-radius: var(--radius); padding: 16px;
-            transition: border-color var(--transition), opacity var(--transition);
-            position: relative;
-        }
-        .model-card:hover { border-color: var(--text-muted); }
-        .model-card.unavailable { opacity: 0.45; }
-        .model-card.unavailable:hover { opacity: 0.65; }
-        .model-card-head { display: flex; align-items: center; justify-content: space-between; margin-bottom: 10px; }
-        .model-name { font-size: 14px; font-weight: 600; display: flex; align-items: center; gap: 8px; }
-        .model-protocol {
-            font-size: 11px; font-family: 'JetBrains Mono', monospace;
-            color: var(--text-muted); background: var(--bg-elevated);
-            padding: 2px 6px; border-radius: 4px;
-        }
-        .badge-primary {
-            font-size: 10px; font-weight: 600; padding: 2px 8px; border-radius: 20px;
-            background: var(--accent-glow); color: var(--accent-hover);
-            border: 1px solid rgba(99, 102, 241, 0.3); text-transform: uppercase;
-        }
-        .badge-nokey {
-            font-size: 10px; font-weight: 600; padding: 2px 8px; border-radius: 20px;
-            background: var(--bg-elevated); color: var(--text-muted);
-            border: 1px solid var(--border);
-        }
-        .model-detail { font-size: 12px; color: var(--text-muted); margin-bottom: 3px; word-break: break-all; }
-        .model-detail strong { color: var(--text-secondary); font-weight: 500; }
-        .model-actions { margin-top: 12px; display: flex; gap: 6px; flex-wrap: wrap; }
-
-        /* ── Model edit modal ────────────────────────── */
-        .modal-overlay {
-            position: fixed; inset: 0; background: rgba(0,0,0,0.6);
-            z-index: 200; display: flex; align-items: center; justify-content: center;
-            opacity: 0; pointer-events: none; transition: opacity var(--transition);
-        }
-        .modal-overlay.active { opacity: 1; pointer-events: auto; }
-        .modal {
-            background: var(--bg-secondary); border: 1px solid var(--border);
-            border-radius: var(--radius); padding: 24px; width: 480px; max-width: 90vw;
-            max-height: 80vh; overflow-y: auto;
-        }
-        .modal-title { font-size: 16px; font-weight: 600; margin-bottom: 16px; }
-        .modal-actions { margin-top: 20px; display: flex; gap: 8px; justify-content: flex-end; }
-
-        /* Collapsible optional fields */
-        .collapsible-header {
-            font-size: 12px; font-weight: 500; color: var(--text-muted);
-            cursor: pointer; user-select: none;
-            display: flex; align-items: center; gap: 6px;
-            padding: 8px 0; margin-top: 4px;
-            border-top: 1px solid var(--border);
-        }
-        .collapsible-header:hover { color: var(--text-secondary); }
-        .collapsible-header .arrow {
-            font-size: 10px; transition: transform var(--transition);
-        }
-        .collapsible-header.open .arrow { transform: rotate(90deg); }
-        .collapsible-body { display: none; }
-        .collapsible-body.open { display: block; }
-
-        /* ── Form fields ─────────────────────────────── */
-        .form-group { margin-bottom: 16px; }
-        .form-label {
-            font-size: 12px; font-weight: 500; color: var(--text-secondary);
-            margin-bottom: 6px; display: block;
-        }
-        .form-input {
-            width: 100%; font-family: 'JetBrains Mono', monospace; font-size: 13px;
-            padding: 8px 12px; border-radius: 8px;
-            border: 1px solid var(--border); background: var(--bg-editor);
-            color: var(--text-primary); outline: none;
-            transition: border-color var(--transition);
-        }
-        .form-input:focus { border-color: var(--border-focus); }
-        .form-input::placeholder { color: var(--text-muted); }
-        .form-input-number { width: 120px; }
-        .form-hint { font-size: 11px; color: var(--text-muted); margin-top: 4px; }
-
-        /* Toggle switch */
-        .toggle-row { display: flex; align-items: center; gap: 10px; margin-bottom: 16px; }
-        .toggle {
-            width: 40px; height: 22px; border-radius: 11px;
-            background: var(--border); cursor: pointer;
-            position: relative; transition: background var(--transition);
-            flex-shrink: 0;
-        }
-        .toggle.on { background: var(--accent); }
-        .toggle::after {
-            content: ''; position: absolute; top: 3px; left: 3px;
-            width: 16px; height: 16px; border-radius: 50%;
-            background: #fff; transition: transform var(--transition);
-        }
-        .toggle.on::after { transform: translateX(18px); }
-        .toggle-label { font-size: 13px; font-weight: 500; }
-
-        /* Array editor */
-        .array-editor { display: flex; flex-direction: column; gap: 6px; }
-        .array-row { display: flex; gap: 6px; align-items: center; }
-        .array-row .form-input { flex: 1; }
-        .array-add { font-size: 12px; color: var(--accent); cursor: pointer; padding: 4px 0; }
-        .array-add:hover { color: var(--accent-hover); }
-
-        /* Channel form */
-        .channel-form { max-width: 560px; }
-        .form-section-title {
-            font-size: 13px; font-weight: 600; color: var(--text-secondary);
-            margin: 20px 0 12px; padding-bottom: 6px;
-            border-bottom: 1px solid var(--border);
-        }
-        .form-section-title:first-child { margin-top: 0; }
-
-        /* ── Auth panel ──────────────────────────────── */
-        .provider-grid {
-            display: grid; grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
-            gap: 14px;
-        }
-        .provider-card {
-            background: var(--bg-secondary); border: 1px solid var(--border);
-            border-radius: var(--radius); padding: 18px;
-            transition: border-color var(--transition);
-        }
-        .provider-card:hover { border-color: var(--text-muted); }
-        .provider-card-header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 12px; }
-        .provider-name { font-size: 14px; font-weight: 600; display: flex; align-items: center; gap: 8px; }
-        .provider-badge {
-            font-size: 10px; font-weight: 600; padding: 2px 8px; border-radius: 20px;
-            text-transform: uppercase; letter-spacing: 0.05em;
-        }
-        .badge-active { background: var(--success-bg); color: var(--success); border: 1px solid rgba(34, 197, 94, 0.2); }
-        .badge-expired { background: var(--error-bg); color: var(--error); border: 1px solid rgba(239, 68, 68, 0.2); }
-        .badge-pending { background: var(--warning-bg); color: var(--warning); border: 1px solid rgba(245, 158, 11, 0.2); }
-        .badge-none { background: var(--bg-elevated); color: var(--text-muted); border: 1px solid var(--border); }
-        .provider-detail { font-size: 12px; color: var(--text-muted); margin-bottom: 4px; }
-        .provider-detail strong { color: var(--text-secondary); font-weight: 500; }
-        .provider-actions { margin-top: 12px; display: flex; gap: 8px; }
-        .device-code-box {
-            background: var(--bg-elevated); border: 1px solid var(--border);
-            border-radius: 8px; padding: 14px; margin-top: 10px; text-align: center;
-        }
-        .device-code-box .code {
-            font-family: 'JetBrains Mono', monospace; font-size: 22px; font-weight: 700;
-            color: var(--accent-hover); letter-spacing: 0.1em; margin: 8px 0;
-        }
-        .device-code-box .url { font-size: 12px; color: var(--text-secondary); word-break: break-all; }
-        .device-code-box .url a { color: var(--accent-hover); text-decoration: none; }
-        .device-code-box .url a:hover { text-decoration: underline; }
-        .device-code-box .hint { font-size: 11px; color: var(--text-muted); margin-top: 8px; }
-        .token-input-group { display: flex; gap: 8px; margin-top: 10px; }
-        .token-input-group input {
-            flex: 1; font-family: 'JetBrains Mono', monospace; font-size: 12px;
-            padding: 8px 12px; border-radius: 8px; border: 1px solid var(--border);
-            background: var(--bg-editor); color: var(--text-primary); outline: none;
-            transition: border-color var(--transition);
-        }
-        .token-input-group input:focus { border-color: var(--border-focus); }
-
-        /* ── Raw JSON editor ─────────────────────────── */
-        .editor-header { display: flex; align-items: center; justify-content: space-between; margin-bottom: 12px; }
-        .editor-label { font-size: 12px; font-weight: 500; color: var(--text-muted); text-transform: uppercase; letter-spacing: 0.06em; }
-        .file-path {
-            font-family: 'JetBrains Mono', monospace; font-size: 12px; color: var(--text-muted);
-            background: var(--bg-elevated); padding: 4px 10px; border-radius: 6px; border: 1px solid var(--border);
-        }
-        .editor-toolbar { display: flex; gap: 8px; margin-bottom: 12px; }
-        .editor-wrapper {
-            flex: 1; position: relative; border: 1px solid var(--border);
-            border-radius: var(--radius); overflow: hidden;
-            transition: border-color var(--transition), box-shadow var(--transition);
-            min-height: 400px;
-        }
-        .editor-wrapper:focus-within { border-color: var(--border-focus); box-shadow: 0 0 0 3px var(--accent-glow); }
-        .editor-wrapper.error { border-color: var(--error); box-shadow: 0 0 0 3px var(--error-bg); }
-        #editor {
-            width: 100%; height: 100%; min-height: 400px; resize: vertical;
-            background: var(--bg-editor); color: var(--text-primary);
-            font-family: 'JetBrains Mono', monospace; font-size: 13px; line-height: 1.65;
-            padding: 16px 20px; border: none; outline: none;
-            tab-size: 2; white-space: pre; overflow: auto;
-        }
-        .loading-overlay {
-            position: absolute; inset: 0; background: rgba(15, 17, 23, 0.85);
-            display: flex; align-items: center; justify-content: center;
-            z-index: 10; backdrop-filter: blur(4px);
-            opacity: 0; pointer-events: none; transition: opacity var(--transition);
-        }
-        .loading-overlay.active { opacity: 1; pointer-events: auto; }
-        .spinner {
-            width: 28px; height: 28px; border: 3px solid var(--border);
-            border-top-color: var(--accent); border-radius: 50%;
-            animation: spin 0.7s linear infinite;
-        }
-        @keyframes spin { to { transform: rotate(360deg); } }
-
-        /* ── Log panel ──────────────────────────────── */
-        .log-toolbar {
-            display: flex; align-items: center; justify-content: space-between;
-            margin-bottom: 12px; gap: 8px;
-        }
-        .log-toolbar-right { display: flex; align-items: center; gap: 12px; }
-        .log-autoscroll { display: flex; align-items: center; gap: 6px; font-size: 12px; color: var(--text-secondary); cursor: pointer; user-select: none; }
-        .log-autoscroll input { accent-color: var(--accent); cursor: pointer; }
-        .log-container {
-            background: var(--bg-editor); border: 1px solid var(--border);
-            border-radius: var(--radius); overflow: hidden; position: relative;
-            min-height: 300px; max-height: calc(100vh - 260px);
-            display: flex; flex-direction: column;
-        }
-        .log-output {
-            flex: 1; overflow-y: auto; padding: 16px 20px;
-            font-family: 'JetBrains Mono', monospace; font-size: 12px; line-height: 1.7;
-            color: var(--text-primary); white-space: pre-wrap; word-break: break-all;
-            margin: 0;
-        }
-        .log-placeholder {
-            color: var(--text-muted); font-style: italic;
-            font-family: 'Inter', sans-serif; font-size: 13px;
-        }
-
-        /* ── Footer ──────────────────────────────────── */
-        .footer {
-            padding: 10px 24px; border-top: 1px solid var(--border);
-            font-size: 12px; color: var(--text-muted);
-            display: flex; align-items: center; justify-content: space-between;
-            flex-shrink: 0;
-        }
-
-        /* ── Responsive ──────────────────────────────── */
-        @media (max-width: 768px) {
-            :root { --sidebar-w: 180px; }
-            .header { padding: 10px 16px; flex-wrap: wrap; gap: 8px; }
-            .header h1 span { display: none; }
-            .content { padding: 16px; }
-        }
-        @media (max-width: 640px) {
-            .settings-layout { flex-direction: column; }
-            .sidebar {
-                width: 100%; border-right: none; border-bottom: 1px solid var(--border);
-                max-height: 200px; padding: 8px 0;
-            }
-            .model-grid { grid-template-columns: 1fr; }
-            .provider-grid { grid-template-columns: 1fr; }
-        }
-    </style>
-</head>
-
-<body>
-
-<header class="header">
-    <div class="header-left">
-        <div class="logo">P</div>
-        <h1>PicoClaw <span>Config</span></h1>
-    </div>
-    <div class="header-center">
-        <button class="btn btn-run btn-process" id="btnRunStop" disabled>
-            <span class="icon" id="btnRunStopIcon">&#9654;</span> <span id="btnRunStopText" data-i18n="start">Start</span>
-        </button>
-        <span class="process-hint" id="processHint"></span>
-    </div>
-    <div class="header-right">
-        <button class="theme-btn" id="btnTheme" onclick="cycleTheme()" title="Toggle theme"></button>
-        <button class="lang-btn" id="btnLang" onclick="toggleLang()">EN</button>
-    </div>
-</header>
-
-<div class="toast-container" id="toastContainer"></div>
-
-<main class="main">
-        <div class="settings-layout">
-            <!-- Sidebar -->
-            <nav class="sidebar" id="sidebar">
-                <div class="sidebar-group" data-group="providers">
-                    <div class="sidebar-group-title" onclick="toggleGroup(this)">
-                        <span data-i18n="sidebar.providers">Providers</span> <span class="arrow">&#9662;</span>
-                    </div>
-                    <div class="sidebar-items">
-                        <div class="sidebar-item active" data-panel="panelModels" data-i18n="sidebar.models">Models</div>
-                        <div class="sidebar-item" data-panel="panelAuth" data-i18n="sidebar.auth">Auth</div>
-                    </div>
-                </div>
-                <div class="sidebar-group" data-group="channels">
-                    <div class="sidebar-group-title" onclick="toggleGroup(this)">
-                        <span data-i18n="sidebar.channels">Channels</span> <span class="arrow">&#9662;</span>
-                    </div>
-                    <div class="sidebar-items">
-                        <div class="sidebar-item" data-panel="panelCh_telegram">Telegram</div>
-                        <div class="sidebar-item" data-panel="panelCh_discord">Discord</div>
-                        <div class="sidebar-item" data-panel="panelCh_slack">Slack</div>
-                        <div class="sidebar-item" data-panel="panelCh_wecom">WeCom</div>
-                        <div class="sidebar-item" data-panel="panelCh_wecom_app">WeCom App</div>
-                        <div class="sidebar-item" data-panel="panelCh_dingtalk">DingTalk</div>
-                        <div class="sidebar-item" data-panel="panelCh_feishu" data-i18n="sidebar.feishu">Feishu</div>
-                        <div class="sidebar-item" data-panel="panelCh_line">LINE</div>
-                        <div class="sidebar-item" data-panel="panelCh_whatsapp">WhatsApp</div>
-                        <div class="sidebar-item" data-panel="panelCh_qq">QQ</div>
-                        <div class="sidebar-item" data-panel="panelCh_onebot">OneBot</div>
-                        <div class="sidebar-item" data-panel="panelCh_maixcam">MaixCAM</div>
-                    </div>
-                </div>
-                <div class="sidebar-divider"></div>
-                <div class="sidebar-item standalone" data-panel="panelLogs" data-i18n="sidebar.logs">Logs</div>
-                <div class="sidebar-item standalone" data-panel="panelRawJson" data-i18n="sidebar.rawjson">Raw JSON</div>
-            </nav>
-
-            <!-- Content -->
-            <div class="content" id="contentArea">
-                <div class="content-panel active" id="panelModels">
-                    <div class="panel-title" data-i18n="models.title">Models</div>
-                    <div class="panel-desc" data-i18n="models.desc">Manage LLM model configurations. Models without an API key are grayed out. Only available models can be set as primary.</div>
-                    <div style="margin-bottom: 14px;">
-                        <button class="btn btn-sm btn-primary" onclick="showAddModelModal()" data-i18n="models.add">+ Add Model</button>
-                    </div>
-                    <div class="model-grid" id="modelGrid"></div>
-                </div>
-
-                <div class="content-panel" id="panelAuth">
-                    <div class="panel-title" data-i18n="auth.title">Provider Authentication</div>
-                    <div class="panel-desc" id="authDesc"></div>
-                    <div class="provider-grid" id="providerGrid">
-                        <div class="provider-card" id="card-openai">
-                            <div class="provider-card-header">
-                                <span class="provider-name">OpenAI</span>
-                                <span class="provider-badge badge-none" id="badge-openai" data-i18n="auth.notLoggedIn">Not logged in</span>
-                            </div>
-                            <div id="details-openai"></div>
-                            <div class="provider-actions" id="actions-openai">
-                                <button class="btn btn-sm btn-primary" onclick="loginProvider('openai')" data-i18n="auth.loginDevice">Login (Device Code)</button>
-                            </div>
-                        </div>
-                        <div class="provider-card" id="card-anthropic">
-                            <div class="provider-card-header">
-                                <span class="provider-name">Anthropic</span>
-                                <span class="provider-badge badge-none" id="badge-anthropic" data-i18n="auth.notLoggedIn">Not logged in</span>
-                            </div>
-                            <div id="details-anthropic"></div>
-                            <div class="provider-actions" id="actions-anthropic">
-                                <button class="btn btn-sm btn-primary" onclick="showTokenInput('anthropic')" data-i18n="auth.loginToken">Login (API Token)</button>
-                            </div>
-                        </div>
-                        <div class="provider-card" id="card-google-antigravity">
-                            <div class="provider-card-header">
-                                <span class="provider-name">Google Antigravity</span>
-                                <span class="provider-badge badge-none" id="badge-google-antigravity" data-i18n="auth.notLoggedIn">Not logged in</span>
-                            </div>
-                            <div id="details-google-antigravity"></div>
-                            <div class="provider-actions" id="actions-google-antigravity">
-                                <button class="btn btn-sm btn-primary" onclick="loginProvider('google-antigravity')" data-i18n="auth.loginOAuth">Login (Browser OAuth)</button>
-                            </div>
-                        </div>
-                    </div>
-                </div>
-
-                <!-- Channel Panels -->
-                <div class="content-panel" id="panelCh_telegram"></div>
-                <div class="content-panel" id="panelCh_discord"></div>
-                <div class="content-panel" id="panelCh_slack"></div>
-                <div class="content-panel" id="panelCh_wecom"></div>
-                <div class="content-panel" id="panelCh_wecom_app"></div>
-                <div class="content-panel" id="panelCh_dingtalk"></div>
-                <div class="content-panel" id="panelCh_feishu"></div>
-                <div class="content-panel" id="panelCh_line"></div>
-                <div class="content-panel" id="panelCh_whatsapp"></div>
-                <div class="content-panel" id="panelCh_qq"></div>
-                <div class="content-panel" id="panelCh_onebot"></div>
-                <div class="content-panel" id="panelCh_maixcam"></div>
-
-                <!-- Logs Panel -->
-                <div class="content-panel" id="panelLogs">
-                    <div class="panel-title" data-i18n="logs.title">Gateway Logs</div>
-                    <div class="panel-desc" data-i18n="logs.desc">Real-time output from the gateway process.</div>
-                    <div class="log-toolbar">
-                        <div>
-                            <button class="btn btn-sm" onclick="clearLogDisplay()" data-i18n="logs.clear">Clear Display</button>
-                        </div>
-                        <div class="log-toolbar-right">
-                            <label class="log-autoscroll">
-                                <input type="checkbox" id="logAutoScrollCb" checked onchange="logAutoScrollEnabled=this.checked">
-                                <span data-i18n="logs.autoScroll">Auto-scroll</span>
-                            </label>
-                        </div>
-                    </div>
-                    <div class="log-container">
-                        <pre class="log-output" id="logOutput"><span class="log-placeholder" id="logPlaceholder" data-i18n="logs.noLogs">No logs available. Start the gateway to see output here.</span></pre>
-                    </div>
-                </div>
-
-                <!-- Raw JSON Panel -->
-                <div class="content-panel" id="panelRawJson">
-                    <div class="panel-title" data-i18n="raw.title">Raw JSON</div>
-                    <div class="panel-desc" data-i18n="raw.desc">Directly edit the configuration file.</div>
-                    <div class="editor-header">
-                        <span class="editor-label">config.json</span>
-                        <span class="file-path" id="filePath">-</span>
-                    </div>
-                    <div class="editor-toolbar">
-                        <button class="btn btn-sm" id="btnReload" onclick="loadConfig()">
-                            <span class="icon">&#8635;</span> <span data-i18n="raw.reload">Reload</span>
-                        </button>
-                        <button class="btn btn-sm" id="btnFormat" onclick="formatJson()">
-                            <span class="icon">{ }</span> <span data-i18n="raw.format">Format</span>
-                        </button>
-                        <button class="btn btn-sm btn-primary" id="btnSave" onclick="saveRawConfig()" data-i18n="save">Save</button>
-                    </div>
-                    <div class="editor-wrapper" id="editorWrapper">
-                        <textarea id="editor" spellcheck="false"></textarea>
-                        <div class="loading-overlay" id="loading">
-                            <div class="spinner"></div>
-                        </div>
-                    </div>
-                </div>
-            </div>
-        </div>
-</main>
-
-<!-- Model Edit Modal -->
-<div class="modal-overlay" id="modelModal">
-    <div class="modal">
-        <div class="modal-title" id="modalTitle"></div>
-        <div id="modalBody"></div>
-        <div class="modal-actions">
-            <button class="btn btn-sm" onclick="closeModelModal()" data-i18n="cancel">Cancel</button>
-            <button class="btn btn-sm btn-primary" id="modalSaveBtn" onclick="saveModelFromModal()" data-i18n="save">Save</button>
-        </div>
-    </div>
-</div>
-
-<footer class="footer">
-    <span>PicoClaw Config</span>
-    <span id="jsonStatus">-</span>
-</footer>
-
-<script>
-// ── Theme ───────────────────────────────────────────
-const themeIcons = { light: '\u2600\uFE0F', dark: '\uD83C\uDF19', system: '\uD83D\uDCBB' };
-const themeOrder = ['system', 'light', 'dark'];
-let currentThemeSetting = localStorage.getItem('picoclaw-theme') || 'system';
-
-function getSystemTheme() {
-    return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
-}
-function applyTheme() {
-    const resolved = currentThemeSetting === 'system' ? getSystemTheme() : currentThemeSetting;
-    document.documentElement.setAttribute('data-theme', resolved);
-    const btn = document.getElementById('btnTheme');
-    if (btn) btn.textContent = themeIcons[currentThemeSetting];
-}
-function cycleTheme() {
-    const idx = themeOrder.indexOf(currentThemeSetting);
-    currentThemeSetting = themeOrder[(idx + 1) % themeOrder.length];
-    localStorage.setItem('picoclaw-theme', currentThemeSetting);
-    applyTheme();
-}
-// Listen for system theme changes
-window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', () => {
-    if (currentThemeSetting === 'system') applyTheme();
-});
-// Apply immediately to avoid flash
-applyTheme();
-
-// ── i18n ────────────────────────────────────────────
-const i18nData = {
-    en: {
-        // Header & global
-        'start': 'Start',
-        'stop': 'Stop',
-        'save': 'Save',
-        'cancel': 'Cancel',
-        'edit': 'Edit',
-        'delete': 'Delete',
-        'enabled': 'Enabled',
-        'comingSoon': 'Coming soon',
-        // Sidebar
-        'sidebar.providers': 'Providers',
-        'sidebar.models': 'Models',
-        'sidebar.auth': 'Auth',
-        'sidebar.channels': 'Channels',
-        'sidebar.feishu': 'Feishu',
-        'sidebar.logs': 'Logs',
-        'sidebar.rawjson': 'Raw JSON',
-        // Models
-        'models.title': 'Models',
-        'models.desc': 'Manage LLM model configurations. Models without an API key are grayed out. Only available models can be set as primary.',
-        'models.add': '+ Add Custom Model',
-        'models.noModels': 'No models configured.',
-        'models.primary': 'Primary',
-        'models.noKey': 'No Key',
-        'models.setPrimary': 'Set Primary',
-        'models.editModel': 'Edit Model',
-        'models.addModel': 'Add Model',
-        'models.advancedOptions': 'Advanced Options',
-        'models.deleteConfirm': 'Delete model "{name}"?',
-        'models.requiredFields': 'Model Name and Model ID are required',
-        // Model fields
-        'field.modelName': 'Model Name',
-        'field.modelId': 'Model ID',
-        'field.modelIdHint': 'Format: protocol/model-id',
-        'field.apiKey': 'API Key',
-        'field.apiBase': 'API Base',
-        'field.proxy': 'Proxy',
-        'field.authMethod': 'Auth Method',
-        'field.connectMode': 'Connect Mode',
-        'field.workspace': 'Workspace',
-        'field.rpm': 'RPM Limit',
-        'field.requestTimeout': 'Request Timeout (s)',
-        // Auth
-        'auth.title': 'Provider Authentication',
-        'auth.desc': 'Login to providers using OAuth or API tokens. Credentials are stored locally in <code style="font-family:\'JetBrains Mono\',monospace;font-size:12px;background:var(--bg-elevated);padding:2px 6px;border-radius:4px;">~/.picoclaw/auth.json</code>.',
-        'auth.notLoggedIn': 'Not logged in',
-        'auth.active': 'Active',
-        'auth.expired': 'Expired',
-        'auth.needsRefresh': 'Needs Refresh',
-        'auth.authenticating': 'Authenticating...',
-        'auth.loginDevice': 'Login (Device Code)',
-        'auth.loginToken': 'Login (API Token)',
-        'auth.loginOAuth': 'Login (Browser OAuth)',
-        'auth.logout': 'Logout',
-        'auth.retry': 'Retry',
-        'auth.waiting': 'Waiting...',
-        'auth.pasteKey': 'Paste your API key here...',
-        'auth.step1': 'Step 1: Click the link below',
-        'auth.step2': 'Step 2: Enter this code',
-        'auth.step3': 'Step 3: Complete auth in browser, this page updates automatically',
-        'auth.method': 'Method',
-        'auth.email': 'Email',
-        'auth.account': 'Account',
-        'auth.project': 'Project',
-        'auth.expires': 'Expires',
-        // Channel
-        'ch.configure': 'Configure {name} channel settings.',
-        'ch.docLink': 'Configuration Guide',
-        'ch.accessControl': 'Access Control',
-        'ch.allowFrom': 'Allow From (User IDs)',
-        'ch.addItem': '+ Add',
-        'ch.mentionOnly': 'Mention Only',
-        'ch.mentionOnlyHint': 'Only respond when mentioned',
-        'ch.groupTrigger': 'Group Trigger Prefixes',
-        // Logs
-        'logs.title': 'Gateway Logs',
-        'logs.desc': 'Real-time output from the gateway process.',
-        'logs.clear': 'Clear Display',
-        'logs.autoScroll': 'Auto-scroll',
-        'logs.noLogs': 'No logs available. Start the gateway to see output here.',
-        'logs.noCapture': 'Logs are not available. The gateway was not started from this launcher.',
-        // Raw JSON
-        'raw.title': 'Raw JSON',
-        'raw.desc': 'Directly edit the configuration file.',
-        'raw.reload': 'Reload',
-        'raw.format': 'Format',
-        // Status messages
-        'status.configLoaded': 'Config loaded',
-        'status.configSaved': 'Config saved',
-        'status.loadFailed': 'Load failed',
-        'status.saveFailed': 'Save failed',
-        'status.formatted': 'Formatted',
-        'status.invalidJson': 'Invalid JSON, please fix before saving',
-        'status.jsonValid': 'JSON valid',
-        'status.jsonInvalid': 'JSON invalid',
-        'status.saved': '{name} saved',
-        'status.tokenEmpty': 'Token cannot be empty',
-        'status.tokenSaved': 'Token saved for {name}',
-        'status.loggedOut': 'Logged out from {name}',
-        'status.loginFailed': 'Login failed',
-        'status.logoutFailed': 'Logout failed',
-        'status.openingBrowser': 'Opening browser for authentication...',
-        'status.loginStarted': 'Login started...',
-        'status.loginSuccess': 'Login successful!',
-        // Process
-        'process.running': 'Service running',
-        'process.notRunning': 'Service not running',
-        'process.starting': 'Starting gateway...',
-        'process.started': 'Gateway started',
-        'process.startFailed': 'Failed to start gateway',
-        'process.stopping': 'Stopping gateway...',
-        'process.stopped': 'Gateway stopped',
-        'process.stopFailed': 'Failed to stop gateway',
-        'process.needModel': 'At least one model with API key is required',
-        'process.needChannel': 'At least one channel must be enabled',
-        'process.checkLogs': 'Check Logs for details',
-        'process.needBoth': 'Need model with API key and enabled channel to start',
-    },
-    zh: {
-        'start': '\u542F\u52A8',
-        'stop': '\u505C\u6B62',
-        'save': '\u4FDD\u5B58',
-        'cancel': '\u53D6\u6D88',
-        'edit': '\u7F16\u8F91',
-        'delete': '\u5220\u9664',
-        'enabled': '\u542F\u7528',
-        'comingSoon': '\u5373\u5C06\u63A8\u51FA',
-        'sidebar.providers': '\u63D0\u4F9B\u5546',
-        'sidebar.models': '\u6A21\u578B',
-        'sidebar.auth': '\u8BA4\u8BC1',
-        'sidebar.channels': '\u901A\u9053',
-        'sidebar.feishu': '\u98DE\u4E66',
-        'sidebar.logs': '\u65E5\u5FD7',
-        'sidebar.rawjson': '\u539F\u59CB JSON',
-        'models.title': '\u6A21\u578B',
-        'models.desc': '\u7BA1\u7406 LLM \u6A21\u578B\u914D\u7F6E\u3002\u6CA1\u6709 API Key \u7684\u6A21\u578B\u663E\u793A\u4E3A\u7070\u8272\u3002\u53EA\u6709\u53EF\u7528\u6A21\u578B\u624D\u80FD\u8BBE\u4E3A\u4E3B\u6A21\u578B\u3002',
-        'models.add': '+ \u6DFB\u52A0\u81EA\u5B9A\u4E49\u6A21\u578B',
-        'models.noModels': '\u6682\u65E0\u6A21\u578B\u914D\u7F6E\u3002',
-        'models.primary': '\u4E3B\u6A21\u578B',
-        'models.noKey': '\u65E0 Key',
-        'models.setPrimary': '\u8BBE\u4E3A\u4E3B\u6A21\u578B',
-        'models.editModel': '\u7F16\u8F91\u6A21\u578B',
-        'models.addModel': '\u6DFB\u52A0\u6A21\u578B',
-        'models.advancedOptions': '\u9AD8\u7EA7\u9009\u9879',
-        'models.deleteConfirm': '\u786E\u5B9A\u5220\u9664\u6A21\u578B\u201C{name}\u201D\uFF1F',
-        'models.requiredFields': '\u6A21\u578B\u540D\u79F0\u548C\u6A21\u578B ID \u4E3A\u5FC5\u586B\u9879',
-        'field.modelName': '\u6A21\u578B\u540D\u79F0',
-        'field.modelId': '\u6A21\u578B ID',
-        'field.modelIdHint': '\u683C\u5F0F\uFF1A\u534F\u8BAE/\u6A21\u578B\u6807\u8BC6',
-        'field.apiKey': 'API Key',
-        'field.apiBase': 'API \u5730\u5740',
-        'field.proxy': '\u4EE3\u7406',
-        'field.authMethod': '\u8BA4\u8BC1\u65B9\u5F0F',
-        'field.connectMode': '\u8FDE\u63A5\u6A21\u5F0F',
-        'field.workspace': '\u5DE5\u4F5C\u533A',
-        'field.rpm': 'RPM \u9650\u5236',
-        'field.requestTimeout': '\u8BF7\u6C42\u8D85\u65F6 (\u79D2)',
-        'auth.title': '\u63D0\u4F9B\u5546\u8BA4\u8BC1',
-        'auth.desc': '\u901A\u8FC7 OAuth \u6216 API Token \u767B\u5F55\u63D0\u4F9B\u5546\u3002\u51ED\u8BC1\u5B58\u50A8\u5728\u672C\u5730 <code style="font-family:\'JetBrains Mono\',monospace;font-size:12px;background:var(--bg-elevated);padding:2px 6px;border-radius:4px;">~/.picoclaw/auth.json</code>\u3002',
-        'auth.notLoggedIn': '\u672A\u767B\u5F55',
-        'auth.active': '\u5DF2\u6FC0\u6D3B',
-        'auth.expired': '\u5DF2\u8FC7\u671F',
-        'auth.needsRefresh': '\u9700\u8981\u5237\u65B0',
-        'auth.authenticating': '\u8BA4\u8BC1\u4E2D...',
-        'auth.loginDevice': '\u767B\u5F55 (\u8BBE\u5907\u7801)',
-        'auth.loginToken': '\u767B\u5F55 (API Token)',
-        'auth.loginOAuth': '\u767B\u5F55 (\u6D4F\u89C8\u5668 OAuth)',
-        'auth.logout': '\u767B\u51FA',
-        'auth.retry': '\u91CD\u8BD5',
-        'auth.waiting': '\u7B49\u5F85\u4E2D...',
-        'auth.pasteKey': '\u8BF7\u7C98\u8D34 API Key...',
-        'auth.step1': '\u7B2C 1 \u6B65\uFF1A\u70B9\u51FB\u4E0B\u65B9\u94FE\u63A5',
-        'auth.step2': '\u7B2C 2 \u6B65\uFF1A\u8F93\u5165\u4EE5\u4E0B\u4EE3\u7801',
-        'auth.step3': '\u7B2C 3 \u6B65\uFF1A\u5728\u6D4F\u89C8\u5668\u4E2D\u5B8C\u6210\u8BA4\u8BC1\uFF0C\u672C\u9875\u9762\u4F1A\u81EA\u52A8\u66F4\u65B0',
-        'auth.method': '\u65B9\u5F0F',
-        'auth.email': '\u90AE\u7BB1',
-        'auth.account': '\u8D26\u53F7',
-        'auth.project': '\u9879\u76EE',
-        'auth.expires': '\u8FC7\u671F\u65F6\u95F4',
-        'ch.configure': '\u914D\u7F6E {name} \u901A\u9053\u8BBE\u7F6E\u3002',
-        'ch.docLink': '\u914D\u7F6E\u6307\u5357',
-        'ch.accessControl': '\u8BBF\u95EE\u63A7\u5236',
-        'ch.allowFrom': '\u5141\u8BB8\u7684\u7528\u6237 ID',
-        'ch.addItem': '+ \u6DFB\u52A0',
-        'ch.mentionOnly': '\u4EC5\u63D0\u53CA\u65F6\u54CD\u5E94',
-        'ch.mentionOnlyHint': '\u53EA\u5728\u88AB @\u63D0\u53CA\u65F6\u56DE\u590D',
-        'ch.groupTrigger': '\u7FA4\u804A\u89E6\u53D1\u524D\u7F00',
-        'logs.title': 'Gateway \u65E5\u5FD7',
-        'logs.desc': 'Gateway \u8FDB\u7A0B\u7684\u5B9E\u65F6\u8F93\u51FA\u3002',
-        'logs.clear': '\u6E05\u9664\u663E\u793A',
-        'logs.autoScroll': '\u81EA\u52A8\u6EDA\u52A8',
-        'logs.noLogs': '\u6682\u65E0\u65E5\u5FD7\u3002\u542F\u52A8 Gateway \u540E\u53EF\u5728\u6B64\u67E5\u770B\u8F93\u51FA\u3002',
-        'logs.noCapture': '\u65E5\u5FD7\u4E0D\u53EF\u7528\u3002Gateway \u4E0D\u662F\u901A\u8FC7\u6B64\u542F\u52A8\u5668\u542F\u52A8\u7684\u3002',
-        'raw.title': '\u539F\u59CB JSON',
-        'raw.desc': '\u76F4\u63A5\u7F16\u8F91\u914D\u7F6E\u6587\u4EF6\u3002',
-        'raw.reload': '\u91CD\u65B0\u52A0\u8F7D',
-        'raw.format': '\u683C\u5F0F\u5316',
-        'status.configLoaded': '\u914D\u7F6E\u5DF2\u52A0\u8F7D',
-        'status.configSaved': '\u914D\u7F6E\u5DF2\u4FDD\u5B58',
-        'status.loadFailed': '\u52A0\u8F7D\u5931\u8D25',
-        'status.saveFailed': '\u4FDD\u5B58\u5931\u8D25',
-        'status.formatted': '\u5DF2\u683C\u5F0F\u5316',
-        'status.invalidJson': 'JSON \u683C\u5F0F\u65E0\u6548\uFF0C\u8BF7\u4FEE\u6B63\u540E\u518D\u4FDD\u5B58',
-        'status.jsonValid': 'JSON \u6709\u6548',
-        'status.jsonInvalid': 'JSON \u65E0\u6548',
-        'status.saved': '{name} \u5DF2\u4FDD\u5B58',
-        'status.tokenEmpty': 'Token \u4E0D\u80FD\u4E3A\u7A7A',
-        'status.tokenSaved': '\u5DF2\u4FDD\u5B58 {name} \u7684 Token',
-        'status.loggedOut': '\u5DF2\u4ECE {name} \u767B\u51FA',
-        'status.loginFailed': '\u767B\u5F55\u5931\u8D25',
-        'status.logoutFailed': '\u767B\u51FA\u5931\u8D25',
-        'status.openingBrowser': '\u6B63\u5728\u6253\u5F00\u6D4F\u89C8\u5668\u8FDB\u884C\u8BA4\u8BC1...',
-        'status.loginStarted': '\u767B\u5F55\u5DF2\u542F\u52A8...',
-        'status.loginSuccess': '\u767B\u5F55\u6210\u529F\uFF01',
-        'process.running': '\u670D\u52A1\u5DF2\u542F\u52A8',
-        'process.notRunning': '\u670D\u52A1\u672A\u542F\u52A8',
-        'process.starting': '\u6B63\u5728\u542F\u52A8 Gateway...',
-        'process.started': 'Gateway \u5DF2\u542F\u52A8',
-        'process.startFailed': 'Gateway \u542F\u52A8\u5931\u8D25',
-        'process.stopping': '\u6B63\u5728\u505C\u6B62 Gateway...',
-        'process.stopped': 'Gateway \u5DF2\u505C\u6B62',
-        'process.stopFailed': 'Gateway \u505C\u6B62\u5931\u8D25',
-        'process.needModel': '\u81F3\u5C11\u9700\u8981\u4E00\u4E2A\u914D\u7F6E\u4E86 API Key \u7684\u6A21\u578B',
-        'process.needChannel': '\u81F3\u5C11\u9700\u8981\u542F\u7528\u4E00\u4E2A\u901A\u9053',
-        'process.checkLogs': '\u8BF7\u67E5\u770B\u65E5\u5FD7\u4E86\u89E3\u8BE6\u60C5',
-        'process.needBoth': '\u9700\u8981\u914D\u7F6E\u6A21\u578B\u548C\u542F\u7528\u901A\u9053\u624D\u80FD\u542F\u52A8',
-    }
-};
-
-let currentLang = localStorage.getItem('picoclaw-lang') || (navigator.language.startsWith('zh') ? 'zh' : 'en');
-
-function t(key, params) {
-    let s = (i18nData[currentLang] && i18nData[currentLang][key]) || i18nData.en[key] || key;
-    if (params) {
-        Object.keys(params).forEach(k => { s = s.replace('{' + k + '}', params[k]); });
-    }
-    return s;
-}
-
-function applyI18n() {
-    document.querySelectorAll('[data-i18n]').forEach(el => {
-        const key = el.dataset.i18n;
-        const val = t(key);
-        if (el.tagName === 'INPUT' || el.tagName === 'TEXTAREA') {
-            el.placeholder = val;
-        } else {
-            el.textContent = val;
-        }
-    });
-    document.getElementById('authDesc').innerHTML = t('auth.desc');
-    document.getElementById('btnLang').textContent = currentLang === 'en' ? 'EN' : '\u4E2D';
-    document.documentElement.lang = currentLang === 'zh' ? 'zh-CN' : 'en';
-}
-
-function toggleLang() {
-    currentLang = currentLang === 'en' ? 'zh' : 'en';
-    localStorage.setItem('picoclaw-lang', currentLang);
-    applyI18n();
-    // Re-render process button text
-    updateRunStopButton(gatewayRunning);
-    // Re-render dynamic panels
-    renderModels();
-    const activePanel = document.querySelector('.content-panel.active');
-    if (activePanel) {
-        const id = activePanel.id;
-        if (id === 'panelAuth') loadAuthStatus();
-        if (id.startsWith('panelCh_')) renderChannelForm(id.replace('panelCh_', ''));
-    }
-}
-
-// ── State ───────────────────────────────────────────
-let configData = null;
-let configPath = '';
-let authPollTimer = null;
-let editingModelIndex = -1;
-
-// ── Channel schemas ─────────────────────────────────
-const channelSchemas = {
-    telegram: {
-        title: 'Telegram', configKey: 'telegram', docSlug: 'telegram',
-        fields: [
-            { key: 'token', label: 'Bot Token', type: 'password', placeholder: 'Telegram bot token from @BotFather' },
-            { key: 'proxy', label: 'Proxy', type: 'text', placeholder: 'http://proxy:port' },
-        ]
-    },
-    discord: {
-        title: 'Discord', configKey: 'discord', docSlug: 'discord',
-        fields: [
-            { key: 'token', label: 'Bot Token', type: 'password', placeholder: 'Discord bot token' },
-            { key: 'mention_only', label: 'ch.mentionOnly', type: 'toggle', hint: 'ch.mentionOnlyHint', i18nLabel: true },
-        ]
-    },
-    slack: {
-        title: 'Slack', configKey: 'slack', docSlug: 'slack',
-        fields: [
-            { key: 'bot_token', label: 'Bot Token', type: 'password', placeholder: 'xoxb-...' },
-            { key: 'app_token', label: 'App Token', type: 'password', placeholder: 'xapp-...' },
-        ]
-    },
-    wecom: {
-        title: 'WeCom (Bot)', configKey: 'wecom', docSlug: 'wecom-bot',
-        fields: [
-            { key: 'token', label: 'Token', type: 'password', placeholder: 'Verification token' },
-            { key: 'encoding_aes_key', label: 'Encoding AES Key', type: 'password', placeholder: '43-char AES key' },
-            { key: 'webhook_url', label: 'Webhook URL', type: 'text', placeholder: 'https://qyapi.weixin.qq.com/...' },
-            { key: 'webhook_host', label: 'Webhook Host', type: 'text', placeholder: '0.0.0.0' },
-            { key: 'webhook_port', label: 'Webhook Port', type: 'number', placeholder: '18793' },
-            { key: 'webhook_path', label: 'Webhook Path', type: 'text', placeholder: '/webhook/wecom' },
-            { key: 'reply_timeout', label: 'Reply Timeout (s)', type: 'number', placeholder: '5' },
-        ]
-    },
-    wecom_app: {
-        title: 'WeCom (App)', configKey: 'wecom_app', docSlug: 'wecom-app',
-        fields: [
-            { key: 'corp_id', label: 'Corp ID', type: 'text', placeholder: 'Corporation ID' },
-            { key: 'corp_secret', label: 'Corp Secret', type: 'password', placeholder: 'Corporation secret' },
-            { key: 'agent_id', label: 'Agent ID', type: 'number', placeholder: 'Agent ID (number)' },
-            { key: 'token', label: 'Token', type: 'password', placeholder: 'Verification token' },
-            { key: 'encoding_aes_key', label: 'Encoding AES Key', type: 'password', placeholder: '43-char AES key' },
-            { key: 'webhook_host', label: 'Webhook Host', type: 'text', placeholder: '0.0.0.0' },
-            { key: 'webhook_port', label: 'Webhook Port', type: 'number', placeholder: '18792' },
-            { key: 'webhook_path', label: 'Webhook Path', type: 'text', placeholder: '/webhook/wecom-app' },
-            { key: 'reply_timeout', label: 'Reply Timeout (s)', type: 'number', placeholder: '5' },
-        ]
-    },
-    dingtalk: {
-        title: 'DingTalk', configKey: 'dingtalk', docSlug: 'dingtalk',
-        fields: [
-            { key: 'client_id', label: 'Client ID', type: 'text', placeholder: 'App key / Client ID' },
-            { key: 'client_secret', label: 'Client Secret', type: 'password', placeholder: 'App secret' },
-        ]
-    },
-    feishu: {
-        title: 'Feishu', configKey: 'feishu', docSlug: 'feishu',
-        fields: [
-            { key: 'app_id', label: 'App ID', type: 'text', placeholder: 'Feishu app ID' },
-            { key: 'app_secret', label: 'App Secret', type: 'password', placeholder: 'Feishu app secret' },
-            { key: 'encrypt_key', label: 'Encrypt Key', type: 'password', placeholder: 'Event encrypt key' },
-            { key: 'verification_token', label: 'Verification Token', type: 'password', placeholder: 'Event verification token' },
-        ]
-    },
-    line: {
-        title: 'LINE', configKey: 'line', docSlug: 'line',
-        fields: [
-            { key: 'channel_secret', label: 'Channel Secret', type: 'password', placeholder: 'LINE channel secret' },
-            { key: 'channel_access_token', label: 'Channel Access Token', type: 'password', placeholder: 'LINE channel access token' },
-            { key: 'webhook_host', label: 'Webhook Host', type: 'text', placeholder: '0.0.0.0' },
-            { key: 'webhook_port', label: 'Webhook Port', type: 'number', placeholder: '18791' },
-            { key: 'webhook_path', label: 'Webhook Path', type: 'text', placeholder: '/webhook/line' },
-        ]
-    },
-    whatsapp: {
-        title: 'WhatsApp', configKey: 'whatsapp', docSlug: null,
-        fields: [
-            { key: 'bridge_url', label: 'Bridge URL', type: 'text', placeholder: 'ws://localhost:3001' },
-        ]
-    },
-    qq: {
-        title: 'QQ', configKey: 'qq', docSlug: 'qq',
-        fields: [
-            { key: 'app_id', label: 'App ID', type: 'text', placeholder: 'QQ bot App ID' },
-            { key: 'app_secret', label: 'App Secret', type: 'password', placeholder: 'QQ bot App Secret' },
-        ]
-    },
-    onebot: {
-        title: 'OneBot', configKey: 'onebot', docSlug: 'onebot',
-        fields: [
-            { key: 'ws_url', label: 'WebSocket URL', type: 'text', placeholder: 'ws://127.0.0.1:3001' },
-            { key: 'access_token', label: 'Access Token', type: 'password', placeholder: 'Access token' },
-            { key: 'reconnect_interval', label: 'Reconnect Interval (s)', type: 'number', placeholder: '5' },
-            { key: 'group_trigger_prefix', label: 'ch.groupTrigger', type: 'array', placeholder: 'Trigger word', i18nLabel: true },
-        ]
-    },
-    maixcam: {
-        title: 'MaixCAM', configKey: 'maixcam', docSlug: 'maixcam',
-        fields: [
-            { key: 'host', label: 'Host', type: 'text', placeholder: '0.0.0.0' },
-            { key: 'port', label: 'Port', type: 'number', placeholder: '18790' },
-        ]
-    },
-};
-
-// ── Sidebar ─────────────────────────────────────────
-function toggleGroup(el) {
-    el.parentElement.classList.toggle('collapsed');
-}
-
-document.querySelectorAll('.sidebar-item').forEach(item => {
-    item.addEventListener('click', () => {
-        document.querySelectorAll('.sidebar-item').forEach(i => i.classList.remove('active'));
-        item.classList.add('active');
-        const panelId = item.dataset.panel;
-        document.querySelectorAll('.content-panel').forEach(p => p.classList.remove('active'));
-        const panel = document.getElementById(panelId);
-        if (panel) panel.classList.add('active');
-
-        if (panelId === 'panelModels') renderModels();
-        if (panelId === 'panelAuth') loadAuthStatus();
-        if (panelId === 'panelRawJson') syncEditorFromConfig();
-        if (panelId.startsWith('panelCh_')) {
-            renderChannelForm(panelId.replace('panelCh_', ''));
-        }
-    });
-});
-
-// ── Status messages ─────────────────────────────────
-function showStatus(text, type) {
-    const container = document.getElementById('toastContainer');
-    const toast = document.createElement('div');
-    toast.className = 'toast ' + type;
-    toast.textContent = (type === 'success' ? '\u2713 ' : '\u2717 ') + text;
-    container.appendChild(toast);
-    setTimeout(() => {
-        toast.classList.add('fade-out');
-        setTimeout(() => toast.remove(), 300);
-    }, 3000);
-}
-
-// ── Config API ──────────────────────────────────────
-async function loadConfig() {
-    try {
-        const res = await fetch('/api/config');
-        if (!res.ok) throw new Error('HTTP ' + res.status + ': ' + (await res.text()));
-        const data = await res.json();
-        configData = data.config;
-        configPath = data.path || '';
-        document.getElementById('filePath').textContent = configPath || '-';
-        renderModels();
-        if (!pendingAction) updateRunStopButton(gatewayRunning);
-    } catch (e) {
-        showStatus(t('status.loadFailed') + ': ' + e.message, 'error');
-    }
-}
-
-async function saveConfig() {
-    if (!configData) return;
-    try {
-        const res = await fetch('/api/config', {
-            method: 'PUT',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(configData),
-        });
-        if (!res.ok) throw new Error('HTTP ' + res.status + ': ' + (await res.text()));
-        showStatus(t('status.configSaved'), 'success');
-    } catch (e) {
-        showStatus(t('status.saveFailed') + ': ' + e.message, 'error');
-    }
-    // Refresh start button state after config changes
-    if (!pendingAction) updateRunStopButton(gatewayRunning);
-}
-
-// ── Raw JSON editor ─────────────────────────────────
-function syncEditorFromConfig() {
-    const editor = document.getElementById('editor');
-    if (configData) editor.value = JSON.stringify(configData, null, 2);
-    document.getElementById('filePath').textContent = configPath || '-';
-    validateJson();
-}
-
-async function saveRawConfig() {
-    const obj = validateJson();
-    if (obj === null) { showStatus(t('status.invalidJson'), 'error'); return; }
-    configData = obj;
-    await saveConfig();
-    document.getElementById('editor').value = JSON.stringify(configData, null, 2);
-}
-
-function formatJson() {
-    const obj = validateJson();
-    if (obj !== null) {
-        document.getElementById('editor').value = JSON.stringify(obj, null, 2);
-        showStatus(t('status.formatted'), 'success');
-    }
-}
-
-function validateJson() {
-    const editor = document.getElementById('editor');
-    const jsonStatus = document.getElementById('jsonStatus');
-    const editorWrap = document.getElementById('editorWrapper');
-    const val = editor.value.trim();
-    if (!val) { jsonStatus.textContent = '-'; editorWrap.classList.remove('error'); return null; }
-    try {
-        const obj = JSON.parse(val);
-        jsonStatus.textContent = '\u2713 ' + t('status.jsonValid');
-        jsonStatus.style.color = 'var(--success)';
-        editorWrap.classList.remove('error');
-        return obj;
-    } catch (e) {
-        jsonStatus.textContent = '\u2717 ' + t('status.jsonInvalid') + ': ' + e.message;
-        jsonStatus.style.color = 'var(--error)';
-        editorWrap.classList.add('error');
-        return null;
-    }
-}
-
-document.getElementById('editor').addEventListener('input', validateJson);
-document.addEventListener('keydown', (e) => {
-    if ((e.ctrlKey || e.metaKey) && e.key === 's') {
-        e.preventDefault();
-        if (document.getElementById('panelRawJson').classList.contains('active')) saveRawConfig();
-        else saveConfig();
-    }
-});
-
-// ── Models Panel ────────────────────────────────────
-function renderModels() {
-    const grid = document.getElementById('modelGrid');
-    if (!configData || !configData.model_list) {
-        grid.innerHTML = `<div style="color:var(--text-muted);font-size:13px;">${t('models.noModels')}</div>`;
-        return;
-    }
-
-    const primaryModelName = (configData.agents && configData.agents.defaults)
-        ? (configData.agents.defaults.model_name || configData.agents.defaults.model || '')
-        : '';
-
-    // Build index array sorted: primary first, then the rest in original order
-    const indices = configData.model_list.map((_, i) => i);
-    indices.sort((a, b) => {
-        const ap = configData.model_list[a].model_name === primaryModelName ? 0 : 1;
-        const bp = configData.model_list[b].model_name === primaryModelName ? 0 : 1;
-        return ap !== bp ? ap - bp : a - b;
-    });
-
-    const isModelAvailable = isModelAvailableGlobal;
-
-    let html = '';
-    indices.forEach(idx => {
-        const m = configData.model_list[idx];
-        const available = isModelAvailable(m);
-        const isPrimary = m.model_name === primaryModelName;
-        const protocol = m.model ? m.model.split('/')[0] : '';
-
-        html += `<div class="model-card ${available ? '' : 'unavailable'}">`;
-        html += `<div class="model-card-head">`;
-        html += `<div class="model-name">${esc(m.model_name)}`;
-        if (protocol) html += ` <span class="model-protocol">${esc(protocol)}</span>`;
-        html += `</div>`;
-        if (isPrimary) html += `<span class="badge-primary">${t('models.primary')}</span>`;
-        else if (!available) html += `<span class="badge-nokey">${t('models.noKey')}</span>`;
-        html += `</div>`;
-
-        html += `<div class="model-detail"><strong>Model:</strong> ${esc(m.model || '-')}</div>`;
-        if (m.api_base) html += `<div class="model-detail"><strong>API Base:</strong> ${esc(m.api_base)}</div>`;
-        if (m.api_key) html += `<div class="model-detail"><strong>API Key:</strong> ${maskKey(m.api_key)}</div>`;
-        if (m.auth_method) html += `<div class="model-detail"><strong>Auth:</strong> ${esc(m.auth_method)}</div>`;
-        if (m.proxy) html += `<div class="model-detail"><strong>Proxy:</strong> ${esc(m.proxy)}</div>`;
-
-        html += `<div class="model-actions">`;
-        html += `<button class="btn btn-sm" onclick="showEditModelModal(${idx})">${t('edit')}</button>`;
-        if (available && !isPrimary) {
-            html += `<button class="btn btn-sm btn-success" onclick="setPrimaryModel(${idx})">${t('models.setPrimary')}</button>`;
-        }
-        html += `<button class="btn btn-sm btn-danger" onclick="deleteModel(${idx})">${t('delete')}</button>`;
-        html += `</div></div>`;
-    });
-    grid.innerHTML = html;
-}
-
-function setPrimaryModel(idx) {
-    if (!configData || !configData.model_list[idx]) return;
-    if (!configData.agents) configData.agents = {};
-    if (!configData.agents.defaults) configData.agents.defaults = {};
-    configData.agents.defaults.model_name = configData.model_list[idx].model_name;
-    saveConfig().then(renderModels);
-}
-
-function deleteModel(idx) {
-    if (!configData || !configData.model_list) return;
-    const name = configData.model_list[idx].model_name;
-    if (!confirm(t('models.deleteConfirm', { name }))) return;
-    configData.model_list.splice(idx, 1);
-    saveConfig().then(renderModels);
-}
-
-// ── Model Modal ─────────────────────────────────────
-const modelFieldsRequired = [
-    { key: 'model_name', labelKey: 'field.modelName', type: 'text', placeholder: 'e.g. gpt-4o', required: true },
-    { key: 'model', labelKey: 'field.modelId', type: 'text', placeholder: 'e.g. openai/gpt-4o', required: true, hintKey: 'field.modelIdHint' },
-    { key: 'api_key', labelKey: 'field.apiKey', type: 'password', placeholder: 'API key' },
-    { key: 'api_base', labelKey: 'field.apiBase', type: 'text', placeholder: 'https://api.openai.com/v1' },
-];
-const modelFieldsOptional = [
-    { key: 'proxy', labelKey: 'field.proxy', type: 'text', placeholder: 'http://proxy:port' },
-    { key: 'auth_method', labelKey: 'field.authMethod', type: 'text', placeholder: 'oauth / token' },
-    { key: 'connect_mode', labelKey: 'field.connectMode', type: 'text', placeholder: 'stdio / grpc' },
-    { key: 'workspace', labelKey: 'field.workspace', type: 'text', placeholder: 'Workspace path' },
-    { key: 'rpm', labelKey: 'field.rpm', type: 'number', placeholder: 'RPM' },
-    { key: 'request_timeout', labelKey: 'field.requestTimeout', type: 'number', placeholder: 'Seconds' },
-];
-const modelFields = [...modelFieldsRequired, ...modelFieldsOptional];
-
-function showEditModelModal(idx) {
-    editingModelIndex = idx;
-    const m = configData.model_list[idx];
-    document.getElementById('modalTitle').textContent = t('models.editModel') + ': ' + m.model_name;
-    renderModalBody(m);
-    document.getElementById('modelModal').classList.add('active');
-}
-
-function showAddModelModal() {
-    editingModelIndex = -1;
-    document.getElementById('modalTitle').textContent = t('models.addModel');
-    renderModalBody({});
-    document.getElementById('modelModal').classList.add('active');
-}
-
-function closeModelModal() {
-    document.getElementById('modelModal').classList.remove('active');
-}
-
-function renderModalBody(data) {
-    const hasOptionalValues = modelFieldsOptional.some(f => {
-        const v = data[f.key];
-        return v !== undefined && v !== null && v !== '' && v !== 0;
-    });
-
-    function renderField(f) {
-        const val = data[f.key] !== undefined && data[f.key] !== null ? data[f.key] : '';
-        const label = t(f.labelKey);
-        let h = `<div class="form-group">`;
-        h += `<label class="form-label">${label}${f.required ? ' *' : ''}</label>`;
-        h += `<input class="form-input ${f.type === 'number' ? 'form-input-number' : ''}" `;
-        h += `type="${f.type === 'password' ? 'password' : f.type === 'number' ? 'number' : 'text'}" `;
-        h += `data-field="${f.key}" value="${esc(String(val))}" placeholder="${f.placeholder || ''}">`;
-        if (f.hintKey) h += `<div class="form-hint">${t(f.hintKey)}</div>`;
-        h += `</div>`;
-        return h;
-    }
-
-    let html = '';
-    modelFieldsRequired.forEach(f => { html += renderField(f); });
-
-    html += `<div class="collapsible-header" onclick="this.classList.toggle('open');this.nextElementSibling.classList.toggle('open')">`;
-    html += `<span class="arrow">&#9656;</span> ${t('models.advancedOptions')}`;
-    html += `</div>`;
-    html += `<div class="collapsible-body">`;
-    modelFieldsOptional.forEach(f => { html += renderField(f); });
-    html += `</div>`;
-
-    document.getElementById('modalBody').innerHTML = html;
-}
-
-function saveModelFromModal() {
-    const inputs = document.querySelectorAll('#modalBody input[data-field]');
-    const obj = {};
-    inputs.forEach(input => {
-        const key = input.dataset.field;
-        let val = input.value.trim();
-        if (input.type === 'number' && val) val = parseInt(val, 10) || 0;
-        if (val !== '' && val !== 0) obj[key] = val;
-        else if (key === 'model_name' || key === 'model') obj[key] = val;
-    });
-
-    if (!obj.model_name || !obj.model) {
-        showStatus(t('models.requiredFields'), 'error');
-        return;
-    }
-
-    if (!configData.model_list) configData.model_list = [];
-
-    if (editingModelIndex >= 0) {
-        configData.model_list[editingModelIndex] = { ...configData.model_list[editingModelIndex], ...obj };
-        modelFields.forEach(f => {
-            if (!f.required && (obj[f.key] === '' || obj[f.key] === 0)) {
-                delete configData.model_list[editingModelIndex][f.key];
-            }
-        });
-    } else {
-        configData.model_list.push(obj);
-        // Auto-set as primary model
-        if (!configData.agents) configData.agents = {};
-        if (!configData.agents.defaults) configData.agents.defaults = {};
-        configData.agents.defaults.model_name = obj.model_name;
-    }
-
-    closeModelModal();
-    saveConfig().then(renderModels);
-}
-
-document.getElementById('modelModal').addEventListener('click', function(e) {
-    if (e.target === this) closeModelModal();
-});
-
-// ── Channel Forms ───────────────────────────────────
-function renderChannelForm(chKey) {
-    const schema = channelSchemas[chKey];
-    if (!schema) return;
-    const panel = document.getElementById('panelCh_' + chKey);
-    const chData = (configData && configData.channels && configData.channels[schema.configKey]) || {};
-
-    let html = `<div class="panel-title">${schema.title}</div>`;
-    html += `<div class="panel-desc">${t('ch.configure', { name: schema.title })}`;
-    if (schema.docSlug) {
-        const docBase = currentLang === 'zh' ? 'https://docs.picoclaw.io/zh-Hans/docs/channels/' : 'https://docs.picoclaw.io/docs/channels/';
-        html += ` <a class="doc-link" href="${docBase}${schema.docSlug}" target="_blank" rel="noopener noreferrer">\u{1F4D6} ${t('ch.docLink')}</a>`;
-    }
-    html += `</div>`;
-    html += `<div class="channel-form" id="chForm_${chKey}">`;
-
-    // Enabled toggle
-    html += `<div class="toggle-row">`;
-    html += `<div class="toggle ${chData.enabled ? 'on' : ''}" id="chToggle_${chKey}" onclick="toggleChannelEnabled('${chKey}', this)"></div>`;
-    html += `<span class="toggle-label">${t('enabled')}</span>`;
-    html += `</div>`;
-
-    schema.fields.forEach(f => {
-        const label = f.i18nLabel ? t(f.label) : f.label;
-        if (f.type === 'toggle') {
-            const hint = f.i18nLabel && f.hint ? t(f.hint) : (f.hint || '');
-            html += `<div class="toggle-row">`;
-            html += `<div class="toggle ${chData[f.key] ? 'on' : ''}" data-chfield="${f.key}" onclick="this.classList.toggle('on')"></div>`;
-            html += `<span class="toggle-label">${label}</span>`;
-            if (hint) html += `<span class="form-hint" style="margin-left:8px;">${hint}</span>`;
-            html += `</div>`;
-        } else if (f.type === 'array') {
-            const arr = chData[f.key] || [];
-            html += `<div class="form-group">`;
-            html += `<label class="form-label">${label}</label>`;
-            html += `<div class="array-editor" data-chfield="${f.key}" data-placeholder="${f.placeholder || ''}">`;
-            arr.forEach(v => {
-                html += `<div class="array-row">`;
-                html += `<input class="form-input" type="text" value="${esc(String(v))}" placeholder="${f.placeholder || ''}">`;
-                html += `<button class="btn btn-sm btn-danger" onclick="removeArrayRow(this)">&times;</button>`;
-                html += `</div>`;
-            });
-            html += `<div class="array-add" onclick="addArrayRow(this.parentElement)">${t('ch.addItem')}</div>`;
-            html += `</div></div>`;
-        } else {
-            const val = chData[f.key] !== undefined && chData[f.key] !== null ? chData[f.key] : '';
-            html += `<div class="form-group">`;
-            html += `<label class="form-label">${label}</label>`;
-            html += `<input class="form-input ${f.type === 'number' ? 'form-input-number' : ''}" `;
-            html += `type="${f.type === 'password' ? 'password' : f.type === 'number' ? 'number' : 'text'}" `;
-            html += `data-chfield="${f.key}" value="${esc(String(val))}" placeholder="${f.placeholder || ''}">`;
-            html += `</div>`;
-        }
-    });
-
-    // Allow from
-    const allowFrom = chData.allow_from || [];
-    html += `<div class="form-section-title">${t('ch.accessControl')}</div>`;
-    html += `<div class="form-group">`;
-    html += `<label class="form-label">${t('ch.allowFrom')}</label>`;
-    html += `<div class="array-editor" data-chfield="allow_from" data-placeholder="User / Chat ID">`;
-    allowFrom.forEach(v => {
-        html += `<div class="array-row">`;
-        html += `<input class="form-input" type="text" value="${esc(String(v))}" placeholder="User / Chat ID">`;
-        html += `<button class="btn btn-sm btn-danger" onclick="removeArrayRow(this)">&times;</button>`;
-        html += `</div>`;
-    });
-    html += `<div class="array-add" onclick="addArrayRow(this.parentElement)">${t('ch.addItem')}</div>`;
-    html += `</div></div>`;
-
-    html += `<div style="margin-top:20px;">`;
-    html += `<button class="btn btn-primary" onclick="saveChannelForm('${chKey}')">${t('save')}</button>`;
-    html += `</div></div>`;
-
-    panel.innerHTML = html;
-}
-
-function toggleChannelEnabled(chKey, el) { el.classList.toggle('on'); }
-
-function addArrayRow(container) {
-    const placeholder = container.dataset.placeholder || '';
-    const addBtn = container.querySelector('.array-add');
-    const row = document.createElement('div');
-    row.className = 'array-row';
-    row.innerHTML = `<input class="form-input" type="text" value="" placeholder="${placeholder}">` +
-        `<button class="btn btn-sm btn-danger" onclick="removeArrayRow(this)">&times;</button>`;
-    container.insertBefore(row, addBtn);
-    row.querySelector('input').focus();
-}
-
-function removeArrayRow(btn) { btn.parentElement.remove(); }
-
-function saveChannelForm(chKey) {
-    const schema = channelSchemas[chKey];
-    if (!schema || !configData) return;
-
-    if (!configData.channels) configData.channels = {};
-    const chObj = configData.channels[schema.configKey] || {};
-
-    const toggle = document.getElementById('chToggle_' + chKey);
-    chObj.enabled = toggle ? toggle.classList.contains('on') : false;
-
-    const form = document.getElementById('chForm_' + chKey);
-    schema.fields.forEach(f => {
-        if (f.type === 'toggle') {
-            const el = form.querySelector(`[data-chfield="${f.key}"].toggle`);
-            if (el) chObj[f.key] = el.classList.contains('on');
-        } else if (f.type === 'array') {
-            const container = form.querySelector(`.array-editor[data-chfield="${f.key}"]`);
-            if (container) {
-                const vals = [];
-                container.querySelectorAll('.array-row input').forEach(input => {
-                    const v = input.value.trim();
-                    if (v) vals.push(v);
-                });
-                chObj[f.key] = vals;
-            }
-        } else {
-            const input = form.querySelector(`input[data-chfield="${f.key}"]`);
-            if (input) {
-                let val = input.value.trim();
-                if (f.type === 'number' && val) {
-                    val = parseInt(val, 10);
-                    if (isNaN(val)) val = 0;
-                }
-                chObj[f.key] = val === '' ? (f.type === 'number' ? 0 : '') : val;
-            }
-        }
-    });
-
-    const afContainer = form.querySelector('.array-editor[data-chfield="allow_from"]');
-    if (afContainer) {
-        const vals = [];
-        afContainer.querySelectorAll('.array-row input').forEach(input => {
-            const v = input.value.trim();
-            if (v) vals.push(v);
-        });
-        chObj.allow_from = vals;
-    }
-
-    configData.channels[schema.configKey] = chObj;
-    saveConfig().then(() => showStatus(t('status.saved', { name: schema.title }), 'success'));
-}
-
-// ── Auth API ────────────────────────────────────────
-let authProviderMap = {}; // { 'openai': { status: 'active', ... }, ... }
-
-async function loadAuthStatus() {
-    try {
-        const res = await fetch('/api/auth/status');
-        if (!res.ok) return;
-        const data = await res.json();
-        const providers = data.providers || [];
-        authProviderMap = {};
-        providers.forEach(p => { authProviderMap[p.provider] = p; });
-        renderAuthStatus(providers, data.pending_device);
-    } catch (e) {
-        console.error('Failed to load auth status:', e);
-    }
-}
-
-function renderAuthStatus(providersList, pendingDevice) {
-    const providerMap = {};
-    providersList.forEach(p => { providerMap[p.provider] = p; });
-
-    ['openai', 'anthropic', 'google-antigravity'].forEach(name => {
-        const badge = document.getElementById('badge-' + name);
-        const details = document.getElementById('details-' + name);
-        const actions = document.getElementById('actions-' + name);
-        const p = providerMap[name];
-
-        if (p) {
-            const badgeClass = p.status === 'active' ? 'badge-active' :
-                p.status === 'expired' ? 'badge-expired' : 'badge-pending';
-            const badgeText = p.status === 'active' ? t('auth.active') :
-                p.status === 'expired' ? t('auth.expired') : t('auth.needsRefresh');
-            badge.className = 'provider-badge ' + badgeClass;
-            badge.textContent = badgeText;
-
-            let dh = '';
-            if (p.auth_method) dh += `<div class="provider-detail"><strong>${t('auth.method')}:</strong> ${p.auth_method}</div>`;
-            if (p.email) dh += `<div class="provider-detail"><strong>${t('auth.email')}:</strong> ${p.email}</div>`;
-            if (p.account_id) dh += `<div class="provider-detail"><strong>${t('auth.account')}:</strong> ${p.account_id}</div>`;
-            if (p.project_id) dh += `<div class="provider-detail"><strong>${t('auth.project')}:</strong> ${p.project_id}</div>`;
-            if (p.expires_at) {
-                const d = new Date(p.expires_at);
-                dh += `<div class="provider-detail"><strong>${t('auth.expires')}:</strong> ${d.toLocaleString()}</div>`;
-            }
-            details.innerHTML = dh;
-            actions.innerHTML = `<button class="btn btn-sm btn-danger" onclick="logoutProvider('${name}')">${t('auth.logout')}</button>`;
-        } else {
-            badge.className = 'provider-badge badge-none';
-            badge.textContent = t('auth.notLoggedIn');
-            details.innerHTML = '';
-            if (name === 'openai') {
-                actions.innerHTML = `<button class="btn btn-sm btn-primary" onclick="loginProvider('openai')">${t('auth.loginDevice')}</button>`;
-            } else if (name === 'anthropic') {
-                actions.innerHTML = `<button class="btn btn-sm btn-primary" onclick="showTokenInput('anthropic')">${t('auth.loginToken')}</button>`;
-            } else {
-                actions.innerHTML = `<button class="btn btn-sm btn-primary" onclick="loginProvider('google-antigravity')">${t('auth.loginOAuth')}</button>`;
-            }
-        }
-    });
-
-    if (pendingDevice && pendingDevice.status === 'pending') {
-        const name = pendingDevice.provider;
-        const badge = document.getElementById('badge-' + name);
-        const details = document.getElementById('details-' + name);
-        const actions = document.getElementById('actions-' + name);
-        if (badge) { badge.className = 'provider-badge badge-pending'; badge.textContent = t('auth.authenticating'); }
-        if (pendingDevice.device_url && pendingDevice.user_code && details) {
-            details.innerHTML = `
-            <div class="device-code-box">
-              <div class="hint" style="margin-bottom:8px;font-size:12px;">${t('auth.step1')}</div>
-              <div class="url"><a href="${pendingDevice.device_url}" target="_blank">${pendingDevice.device_url} &#8599;</a></div>
-              <div class="hint" style="margin-top:10px;margin-bottom:4px;font-size:12px;">${t('auth.step2')}</div>
-              <div class="code">${pendingDevice.user_code}</div>
-              <div class="hint">${t('auth.step3')}</div>
-            </div>`;
-        }
-        if (pendingDevice.error && details) {
-            details.innerHTML = `<div class="provider-detail" style="color:var(--error)">${pendingDevice.error}</div>`;
-            if (actions) actions.innerHTML = `<button class="btn btn-sm btn-primary" onclick="loginProvider('${name}')">${t('auth.retry')}</button>`;
-        } else if (actions) {
-            actions.innerHTML = `<button class="btn btn-sm" disabled><span class="spinner" style="width:14px;height:14px;border-width:2px;display:inline-block;vertical-align:middle;margin-right:6px;"></span>${t('auth.waiting')}</button>`;
-        }
-        startAuthPolling();
-    } else {
-        stopAuthPolling();
-    }
-}
-
-function startAuthPolling() {
-    stopAuthPolling();
-    authPollTimer = setInterval(() => loadAuthStatus(), 3000);
-}
-
-function stopAuthPolling() {
-    if (authPollTimer) { clearInterval(authPollTimer); authPollTimer = null; }
-}
-
-async function loginProvider(provider) {
-    const actions = document.getElementById('actions-' + provider);
-    const original = actions ? actions.innerHTML : '';
-    if (actions) actions.querySelectorAll('.btn').forEach(b => { b.disabled = true; b.style.opacity = '0.5'; });
-
-    try {
-        const res = await fetch('/api/auth/login', {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ provider }),
-        });
-        if (!res.ok) throw new Error(await res.text());
-        const data = await res.json();
-
-        if (data.status === 'redirect' && data.auth_url) {
-            showStatus(t('status.openingBrowser'), 'success');
-            window.open(data.auth_url, '_blank');
-            if (actions) actions.innerHTML = original;
-            return;
-        }
-        if (data.status === 'pending') {
-            showStatus(data.message || t('status.loginStarted'), 'success');
-            if (data.device_url && data.user_code) {
-                const badge = document.getElementById('badge-' + provider);
-                const details = document.getElementById('details-' + provider);
-                if (badge) { badge.className = 'provider-badge badge-pending'; badge.textContent = t('auth.authenticating'); }
-                if (details) {
-                    details.innerHTML = `
-                    <div class="device-code-box">
-                      <div class="hint" style="margin-bottom:8px;font-size:12px;">${t('auth.step1')}</div>
-                      <div class="url"><a href="${data.device_url}" target="_blank">${data.device_url} &#8599;</a></div>
-                      <div class="hint" style="margin-top:10px;margin-bottom:4px;font-size:12px;">${t('auth.step2')}</div>
-                      <div class="code">${data.user_code}</div>
-                      <div class="hint">${t('auth.step3')}</div>
-                    </div>`;
-                }
-                if (actions) {
-                    actions.innerHTML = `<button class="btn btn-sm" disabled><span class="spinner" style="width:14px;height:14px;border-width:2px;display:inline-block;vertical-align:middle;margin-right:6px;"></span>${t('auth.waiting')}</button>`;
-                }
-            }
-            startAuthPolling();
-        } else if (data.status === 'success') {
-            showStatus(data.message || t('status.loginSuccess'), 'success');
-            loadAuthStatus();
-        }
-    } catch (e) {
-        showStatus(t('status.loginFailed') + ': ' + e.message, 'error');
-        if (actions) actions.innerHTML = original;
-    }
-}
-
-function showTokenInput(provider) {
-    const actions = document.getElementById('actions-' + provider);
-    actions.innerHTML = `
-    <div class="token-input-group">
-      <input type="password" id="tokenInput-${provider}" placeholder="${t('auth.pasteKey')}" />
-      <button class="btn btn-sm btn-primary" onclick="submitToken('${provider}')">${t('save')}</button>
-      <button class="btn btn-sm" onclick="loadAuthStatus()">${t('cancel')}</button>
-    </div>`;
-    document.getElementById('tokenInput-' + provider).focus();
-}
-
-async function submitToken(provider) {
-    const input = document.getElementById('tokenInput-' + provider);
-    const token = input.value.trim();
-    if (!token) { showStatus(t('status.tokenEmpty'), 'error'); return; }
-    try {
-        const res = await fetch('/api/auth/login', {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ provider, token }),
-        });
-        if (!res.ok) throw new Error(await res.text());
-        showStatus(t('status.tokenSaved', { name: provider }), 'success');
-        loadAuthStatus();
-    } catch (e) {
-        showStatus(t('status.loginFailed') + ': ' + e.message, 'error');
-    }
-}
-
-async function logoutProvider(provider) {
-    try {
-        const res = await fetch('/api/auth/logout', {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ provider }),
-        });
-        if (!res.ok) throw new Error(await res.text());
-        showStatus(t('status.loggedOut', { name: provider }), 'success');
-        loadAuthStatus();
-    } catch (e) {
-        showStatus(t('status.logoutFailed') + ': ' + e.message, 'error');
-    }
-}
-
-// ── Process API (Start/Stop/Status) ─────────────────
-let gatewayRunning = false;
-let processPolling = null;
-let pendingAction = null; // { type: 'start'|'stop', retries: 0 }
-const MAX_RETRIES = 10;
-
-function isModelAvailableGlobal(m) {
-    if (m.api_key) return true;
-    if (m.auth_method === 'oauth') {
-        const protocol = m.model ? m.model.split('/')[0] : '';
-        const providerName = protocol === 'google-antigravity' ? 'google-antigravity' : protocol;
-        const authInfo = authProviderMap[providerName];
-        return !!(authInfo && authInfo.status === 'active');
-    }
-    if (m.auth_method) return true;
-    return false;
-}
-
-function checkStartPrereqs() {
-    const primaryModelName = configData && configData.agents && configData.agents.defaults
-        ? (configData.agents.defaults.model_name || '') : '';
-    const hasModel = !!(primaryModelName && configData.model_list &&
-        configData.model_list.some(m => m.model_name === primaryModelName && isModelAvailableGlobal(m)));
-    const hasChannel = configData && configData.channels &&
-        Object.keys(channelSchemas).some(k => {
-            const cfg = configData.channels[channelSchemas[k].configKey];
-            return cfg && cfg.enabled;
-        });
-    return { hasModel, hasChannel, canStart: hasModel && hasChannel };
-}
-
-function updateRunStopButton(running) {
-    gatewayRunning = running;
-    const btn = document.getElementById('btnRunStop');
-    const icon = document.getElementById('btnRunStopIcon');
-    const text = document.getElementById('btnRunStopText');
-    const hint = document.getElementById('processHint');
-    if (running) {
-        btn.disabled = false;
-        btn.className = 'btn btn-stop btn-process';
-        icon.innerHTML = '&#9632;';
-        text.textContent = t('stop');
-        hint.textContent = '(' + t('process.running') + ')';
-        hint.style.color = '';
-    } else {
-        const prereqs = checkStartPrereqs();
-        btn.disabled = !prereqs.canStart;
-        btn.className = 'btn btn-run btn-process';
-        icon.innerHTML = '&#9654;';
-        text.textContent = t('start');
-        if (!prereqs.canStart) {
-            const reason = !prereqs.hasModel && !prereqs.hasChannel ? t('process.needBoth')
-                : !prereqs.hasModel ? t('process.needModel')
-                : t('process.needChannel');
-            hint.textContent = '(' + reason + ')';
-            hint.style.color = 'var(--danger, #e74c3c)';
-        } else {
-            hint.textContent = '(' + t('process.notRunning') + ')';
-            hint.style.color = '';
-        }
-    }
-}
-
-function setButtonLoading(actionType) {
-    const btn = document.getElementById('btnRunStop');
-    const icon = document.getElementById('btnRunStopIcon');
-    const text = document.getElementById('btnRunStopText');
-    const hint = document.getElementById('processHint');
-    btn.disabled = true;
-    btn.className = 'btn btn-process';
-    icon.innerHTML = '<span class="btn-spinner"></span>';
-    text.textContent = actionType === 'start' ? t('process.starting') : t('process.stopping');
-    hint.textContent = '';
-}
-
-async function checkProcessStatus() {
-    let running = false;
-    try {
-        const params = new URLSearchParams({ log_offset: logOffset, log_run_id: logRunID });
-        const res = await fetch('/api/process/status?' + params);
-        if (res.ok) {
-            const data = await res.json();
-            running = data.process_status === 'running';
-            handleLogData(data);
-        }
-    } catch (e) { /* treat as not running */ }
-
-    if (pendingAction) {
-        const expected = pendingAction.type === 'start';
-        if (running === expected) {
-            showStatus(expected ? t('process.started') : t('process.stopped'), 'success');
-            pendingAction = null;
-            restoreNormalPolling();
-            updateRunStopButton(running);
-        } else {
-            pendingAction.retries++;
-            if (pendingAction.retries >= MAX_RETRIES) {
-                let msg = pendingAction.type === 'start' ? t('process.startFailed') : t('process.stopFailed');
-                if (pendingAction.type === 'start') msg += ' — ' + t('process.checkLogs');
-                showStatus(msg, 'error');
-                pendingAction = null;
-                restoreNormalPolling();
-                updateRunStopButton(running);
-            }
-        }
-    } else {
-        updateRunStopButton(running);
-    }
-}
-
-function restoreNormalPolling() {
-    clearInterval(processPolling);
-    processPolling = setInterval(checkProcessStatus, 5000);
-}
-
-async function startGateway() {
-    const prereqs = checkStartPrereqs();
-    if (!prereqs.canStart) {
-        const reason = !prereqs.hasModel && !prereqs.hasChannel ? t('process.needBoth')
-            : !prereqs.hasModel ? t('process.needModel')
-            : t('process.needChannel');
-        showStatus(reason, 'error');
-        return;
-    }
-    setButtonLoading('start');
-    // Set pending BEFORE fetch so polls don't overwrite loading state
-    pendingAction = { type: 'start', retries: 0 };
-    clearInterval(processPolling);
-    processPolling = setInterval(checkProcessStatus, 1000);
-    try {
-        const res = await fetch('/api/process/start', { method: 'POST' });
-        if (!res.ok) throw new Error(await res.text());
-    } catch (e) {
-        showStatus(t('process.startFailed') + ': ' + e.message + ' — ' + t('process.checkLogs'), 'error');
-        pendingAction = null;
-        restoreNormalPolling();
-        updateRunStopButton(false);
-    }
-}
-
-async function stopGateway() {
-    setButtonLoading('stop');
-    pendingAction = { type: 'stop', retries: 0 };
-    clearInterval(processPolling);
-    processPolling = setInterval(checkProcessStatus, 1000);
-    try {
-        const res = await fetch('/api/process/stop', { method: 'POST' });
-        if (!res.ok) throw new Error(await res.text());
-    } catch (e) {
-        showStatus(t('process.stopFailed') + ': ' + e.message, 'error');
-        pendingAction = null;
-        restoreNormalPolling();
-        updateRunStopButton(true);
-    }
-}
-
-document.getElementById('btnRunStop').addEventListener('click', () => {
-    if (gatewayRunning) { stopGateway(); } else { startGateway(); }
-});
-
-// Poll status every 5 seconds
-checkProcessStatus();
-processPolling = setInterval(checkProcessStatus, 5000);
-
-// ── Log Panel ───────────────────────────────────────
-let logOffset = 0;
-let logRunID = -1;
-let logAutoScrollEnabled = true;
-let logHasContent = false;
-
-function handleLogData(data) {
-    const output = document.getElementById('logOutput');
-    const placeholder = document.getElementById('logPlaceholder');
-    if (!output) return;
-
-    const serverRunID = data.log_run_id;
-    const serverSource = data.log_source;
-    const lines = data.logs || [];
-    const total = data.log_total || 0;
-
-    // External gateway (not launched by us) — show appropriate placeholder
-    if (serverSource === 'none') {
-        if (!logHasContent) {
-            if (placeholder) {
-                placeholder.textContent = gatewayRunning ? t('logs.noCapture') : t('logs.noLogs');
-                placeholder.style.display = '';
-            }
-        }
-        return;
-    }
-
-    // Gateway restarted — clear display
-    if (serverRunID !== logRunID && logRunID !== -1) {
-        output.textContent = '';
-        logHasContent = false;
-    }
-    logRunID = serverRunID;
-
-    // Append new lines
-    if (lines.length > 0) {
-        // Hide placeholder
-        if (placeholder) placeholder.style.display = 'none';
-
-        // Remove placeholder node text if it's still the only content
-        if (!logHasContent) {
-            output.textContent = '';
-        }
-
-        output.textContent += lines.join('\n') + '\n';
-        logHasContent = true;
-
-        // Auto-scroll
-        if (logAutoScrollEnabled) {
-            output.scrollTop = output.scrollHeight;
-        }
-    }
-
-    logOffset = total;
-
-    // Show placeholder if we've never had content
-    if (!logHasContent && placeholder) {
-        placeholder.textContent = t('logs.noLogs');
-        placeholder.style.display = '';
-    }
-}
-
-function clearLogDisplay() {
-    const output = document.getElementById('logOutput');
-    const placeholder = document.getElementById('logPlaceholder');
-    if (output) output.textContent = '';
-    logHasContent = false;
-    // Re-add placeholder
-    if (output && placeholder) {
-        output.appendChild(placeholder);
-        placeholder.textContent = t('logs.noLogs');
-        placeholder.style.display = '';
-    }
-    // Keep logOffset/logRunID so we don't re-fetch old lines
-}
-
-// ── Utilities ───────────────────────────────────────
-function esc(s) {
-    const div = document.createElement('div');
-    div.textContent = s;
-    return div.innerHTML;
-}
-
-function maskKey(key) {
-    if (!key || key.length < 8) return '****';
-    return key.substring(0, 4) + '...' + key.substring(key.length - 4);
-}
-
-// ── Init ────────────────────────────────────────────
-applyI18n();
-loadConfig();
-loadAuthStatus().then(() => renderModels());
-
-if (window.location.hash === '#auth') {
-    document.querySelector('[data-panel="panelAuth"]').click();
-    window.location.hash = '';
-}
-</script>
-</body>
-
-</html>
diff --git a/cmd/picoclaw-launcher/main.go b/cmd/picoclaw-launcher/main.go
deleted file mode 100644
index 3323c31a8..000000000
--- a/cmd/picoclaw-launcher/main.go
+++ /dev/null
@@ -1,127 +0,0 @@
-// PicoClaw Launcher - Standalone HTTP service
-//
-// Provides a web-based JSON editor for picoclaw config files,
-// with OAuth provider authentication support.
-//
-// Usage:
-//
-//	go build -o picoclaw-launcher ./cmd/picoclaw-launcher/
-//	./picoclaw-launcher [config.json]
-//	./picoclaw-launcher -public config.json
-
-package main
-
-import (
-	"embed"
-	"flag"
-	"fmt"
-	"io/fs"
-	"log"
-	"net/http"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"runtime"
-	"time"
-
-	"github.com/sipeed/picoclaw/cmd/picoclaw-launcher/internal/server"
-)
-
-//go:embed internal/ui/index.html
-var staticFiles embed.FS
-
-func main() {
-	public := flag.Bool("public", false, "Listen on all interfaces (0.0.0.0) instead of localhost only")
-	flag.Usage = func() {
-		fmt.Fprintf(os.Stderr, "PicoClaw Launcher - A web-based configuration editor\n\n")
-		fmt.Fprintf(os.Stderr, "Usage: %s [options] [config.json]\n\n", os.Args[0])
-		fmt.Fprintf(os.Stderr, "Arguments:\n")
-		fmt.Fprintf(os.Stderr, "  config.json    Path to the configuration file (default: ~/.picoclaw/config.json)\n\n")
-		fmt.Fprintf(os.Stderr, "Options:\n")
-		flag.PrintDefaults()
-		fmt.Fprintf(os.Stderr, "\nExamples:\n")
-		fmt.Fprintf(os.Stderr, "  %s                          Use default config path\n", os.Args[0])
-		fmt.Fprintf(os.Stderr, "  %s ./config.json             Specify a config file\n", os.Args[0])
-		fmt.Fprintf(
-			os.Stderr,
-			"  %s -public ./config.json     Allow access from other devices on the network\n",
-			os.Args[0],
-		)
-	}
-	flag.Parse()
-
-	configPath := server.DefaultConfigPath()
-	if flag.NArg() > 0 {
-		configPath = flag.Arg(0)
-	}
-
-	absPath, err := filepath.Abs(configPath)
-	if err != nil {
-		log.Fatalf("Failed to resolve config path: %v", err)
-	}
-
-	var addr string
-	if *public {
-		addr = "0.0.0.0:" + server.DefaultPort
-	} else {
-		addr = "127.0.0.1:" + server.DefaultPort
-	}
-
-	mux := http.NewServeMux()
-	server.RegisterConfigAPI(mux, absPath)
-	server.RegisterAuthAPI(mux, absPath)
-	server.RegisterProcessAPI(mux, absPath)
-
-	staticFS, err := fs.Sub(staticFiles, "internal/ui")
-	if err != nil {
-		log.Fatalf("Failed to create sub filesystem: %v", err)
-	}
-	mux.Handle("/", http.FileServer(http.FS(staticFS)))
-
-	// Print startup banner
-	fmt.Println("=============================================")
-	fmt.Println("  PicoClaw Launcher")
-	fmt.Println("=============================================")
-	fmt.Printf("  Config file : %s\n", absPath)
-	fmt.Printf("  Listen addr : %s\n\n", addr)
-	fmt.Println("  Open the following URL in your browser")
-	fmt.Println("  to view and edit the configuration:")
-	fmt.Println()
-	fmt.Printf("    >> http://localhost:%s <<\n", server.DefaultPort)
-	if *public {
-		if ip := server.GetLocalIP(); ip != "" {
-			fmt.Printf("    >> http://%s:%s <<\n", ip, server.DefaultPort)
-		}
-	}
-	fmt.Println()
-	// fmt.Println("=============================================")
-
-	go func() {
-		// Wait briefly to ensure the server is ready before opening the browser
-		time.Sleep(500 * time.Millisecond)
-		url := "http://localhost:" + server.DefaultPort
-		if err := openBrowser(url); err != nil {
-			log.Printf("Warning: Failed to auto-open browser: %v\n", err)
-		}
-	}()
-
-	if err := http.ListenAndServe(addr, mux); err != nil {
-		log.Fatalf("Server failed: %v", err)
-	}
-}
-
-// openBrowser automatically opens the given URL in the default browser.
-func openBrowser(url string) error {
-	var err error
-	switch runtime.GOOS {
-	case "linux":
-		err = exec.Command("xdg-open", url).Start()
-	case "windows":
-		err = exec.Command("rundll32", "url.dll,FileProtocolHandler", url).Start()
-	case "darwin":
-		err = exec.Command("open", url).Start()
-	default:
-		err = fmt.Errorf("unsupported platform")
-	}
-	return err
-}
diff --git a/cmd/picoclaw/dns_noresolv.go b/cmd/picoclaw/dns_noresolv.go
new file mode 100644
index 000000000..ba4ae1f4f
--- /dev/null
+++ b/cmd/picoclaw/dns_noresolv.go
@@ -0,0 +1,64 @@
+package main
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"os"
+	"strings"
+	"sync/atomic"
+	"time"
+)
+
+func init() {
+	// 仅在 /etc/resolv.conf 不存在时才覆盖（即 Android 环境）
+	if _, err := os.Stat("/etc/resolv.conf"); err == nil {
+		return
+	}
+
+	// 从环境变量获取 DNS server 列表，多个用 ; 隔开
+	// 例如: PICOCLAW_DNS_SERVER="8.8.8.8:53;1.1.1.1:53;223.5.5.5:53"
+	dnsEnv := os.Getenv("PICOCLAW_DNS_SERVER")
+	if dnsEnv == "" {
+		dnsEnv = "8.8.8.8:53;1.1.1.1:53"
+	}
+
+	var dnsServers []string
+	for _, s := range strings.Split(dnsEnv, ";") {
+		s = strings.TrimSpace(s)
+		if s != "" {
+			// 如果没有带端口号，自动补上 :53
+			if _, _, err := net.SplitHostPort(s); err != nil {
+				s = s + ":53"
+			}
+			dnsServers = append(dnsServers, s)
+		}
+	}
+
+	// 轮询索引，在多个 DNS 服务器之间轮转
+	var idx uint64
+
+	customResolver := &net.Resolver{
+		PreferGo: true,
+		Dial: func(ctx context.Context, network, address string) (net.Conn, error) {
+			d := net.Dialer{Timeout: 5 * time.Second}
+			// Round-robin: 依次尝试不同的 DNS 服务器
+			server := dnsServers[atomic.AddUint64(&idx, 1)%uint64(len(dnsServers))]
+			return d.DialContext(ctx, "udp", server)
+		},
+	}
+
+	// 覆盖全局 DefaultResolver
+	net.DefaultResolver = customResolver
+
+	// 覆盖 http.DefaultTransport 使用自定义 DNS 解析的 DialContext
+	dialer := &net.Dialer{
+		Timeout:   30 * time.Second,
+		KeepAlive: 30 * time.Second,
+		Resolver:  customResolver,
+	}
+
+	if tr, ok := http.DefaultTransport.(*http.Transport); ok {
+		tr.DialContext = dialer.DialContext
+	}
+}
diff --git a/cmd/picoclaw/internal/agent/helpers.go b/cmd/picoclaw/internal/agent/helpers.go
index f754abc65..0af743bb5 100644
--- a/cmd/picoclaw/internal/agent/helpers.go
+++ b/cmd/picoclaw/internal/agent/helpers.go
@@ -9,7 +9,7 @@ import (
 	"path/filepath"
 	"strings"
 
-	"github.com/chzyer/readline"
+	"github.com/ergochat/readline"
 
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/agent"
@@ -23,16 +23,16 @@ func agentCmd(message, sessionKey, model string, debug bool) error {
 		sessionKey = "cli:default"
 	}
 
-	if debug {
-		logger.SetLevel(logger.DEBUG)
-		fmt.Println("🔍 Debug mode enabled")
-	}
-
 	cfg, err := internal.LoadConfig()
 	if err != nil {
 		return fmt.Errorf("error loading config: %w", err)
 	}
 
+	if debug {
+		logger.SetLevel(logger.DEBUG)
+		fmt.Println("🔍 Debug mode enabled")
+	}
+
 	if model != "" {
 		cfg.Agents.Defaults.ModelName = model
 	}
@@ -50,6 +50,7 @@ func agentCmd(message, sessionKey, model string, debug bool) error {
 	msgBus := bus.NewMessageBus()
 	defer msgBus.Close()
 	agentLoop := agent.NewAgentLoop(cfg, msgBus, provider)
+	defer agentLoop.Close()
 
 	// Print agent startup info (only for interactive mode)
 	startupInfo := agentLoop.GetStartupInfo()
diff --git a/cmd/picoclaw/internal/auth/command.go b/cmd/picoclaw/internal/auth/command.go
index 12a0a3a8c..9de083d8d 100644
--- a/cmd/picoclaw/internal/auth/command.go
+++ b/cmd/picoclaw/internal/auth/command.go
@@ -16,6 +16,8 @@ func NewAuthCommand() *cobra.Command {
 		newLogoutCommand(),
 		newStatusCommand(),
 		newModelsCommand(),
+		newWeixinCommand(),
+		newWeComCommand(),
 	)
 
 	return cmd
diff --git a/cmd/picoclaw/internal/auth/command_test.go b/cmd/picoclaw/internal/auth/command_test.go
index 48dc704dd..3c7f2d3d6 100644
--- a/cmd/picoclaw/internal/auth/command_test.go
+++ b/cmd/picoclaw/internal/auth/command_test.go
@@ -32,6 +32,8 @@ func TestNewAuthCommand(t *testing.T) {
 		"logout",
 		"status",
 		"models",
+		"weixin",
+		"wecom",
 	}
 
 	subcommands := cmd.Commands()
diff --git a/cmd/picoclaw/internal/auth/helpers.go b/cmd/picoclaw/internal/auth/helpers.go
index 633ce8740..531cb76aa 100644
--- a/cmd/picoclaw/internal/auth/helpers.go
+++ b/cmd/picoclaw/internal/auth/helpers.go
@@ -1,6 +1,7 @@
 package auth
 
 import (
+	"bufio"
 	"encoding/json"
 	"fmt"
 	"io"
@@ -15,14 +16,17 @@ import (
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
-const supportedProvidersMsg = "supported providers: openai, anthropic, google-antigravity"
+const (
+	supportedProvidersMsg = "supported providers: openai, anthropic, google-antigravity"
+	defaultAnthropicModel = "claude-sonnet-4.6"
+)
 
-func authLoginCmd(provider string, useDeviceCode bool) error {
+func authLoginCmd(provider string, useDeviceCode bool, useOauth bool) error {
 	switch provider {
 	case "openai":
 		return authLoginOpenAI(useDeviceCode)
 	case "anthropic":
-		return authLoginPasteToken(provider)
+		return authLoginAnthropic(useOauth)
 	case "google-antigravity", "antigravity":
 		return authLoginGoogleAntigravity()
 	default:
@@ -52,9 +56,6 @@ func authLoginOpenAI(useDeviceCode bool) error {
 
 	appCfg, err := internal.LoadConfig()
 	if err == nil {
-		// Update Providers (legacy format)
-		appCfg.Providers.OpenAI.AuthMethod = "oauth"
-
 		// Update or add openai in ModelList
 		foundOpenAI := false
 		for i := range appCfg.ModelList {
@@ -67,15 +68,15 @@ func authLoginOpenAI(useDeviceCode bool) error {
 
 		// If no openai in ModelList, add it
 		if !foundOpenAI {
-			appCfg.ModelList = append(appCfg.ModelList, config.ModelConfig{
-				ModelName:  "gpt-5.2",
-				Model:      "openai/gpt-5.2",
+			appCfg.ModelList = append(appCfg.ModelList, &config.ModelConfig{
+				ModelName:  "gpt-5.4",
+				Model:      "openai/gpt-5.4",
 				AuthMethod: "oauth",
 			})
 		}
 
 		// Update default model to use OpenAI
-		appCfg.Agents.Defaults.ModelName = "gpt-5.2"
+		appCfg.Agents.Defaults.ModelName = "gpt-5.4"
 
 		if err = config.SaveConfig(internal.GetConfigPath(), appCfg); err != nil {
 			return fmt.Errorf("could not update config: %w", err)
@@ -86,7 +87,7 @@ func authLoginOpenAI(useDeviceCode bool) error {
 	if cred.AccountID != "" {
 		fmt.Printf("Account: %s\n", cred.AccountID)
 	}
-	fmt.Println("Default model set to: gpt-5.2")
+	fmt.Println("Default model set to: gpt-5.4")
 
 	return nil
 }
@@ -126,9 +127,6 @@ func authLoginGoogleAntigravity() error {
 
 	appCfg, err := internal.LoadConfig()
 	if err == nil {
-		// Update Providers (legacy format, for backward compatibility)
-		appCfg.Providers.Antigravity.AuthMethod = "oauth"
-
 		// Update or add antigravity in ModelList
 		foundAntigravity := false
 		for i := range appCfg.ModelList {
@@ -141,7 +139,7 @@ func authLoginGoogleAntigravity() error {
 
 		// If no antigravity in ModelList, add it
 		if !foundAntigravity {
-			appCfg.ModelList = append(appCfg.ModelList, config.ModelConfig{
+			appCfg.ModelList = append(appCfg.ModelList, &config.ModelConfig{
 				ModelName:  "gemini-flash",
 				Model:      "antigravity/gemini-3-flash",
 				AuthMethod: "oauth",
@@ -163,6 +161,79 @@ func authLoginGoogleAntigravity() error {
 	return nil
 }
 
+func authLoginAnthropic(useOauth bool) error {
+	if useOauth {
+		return authLoginAnthropicSetupToken()
+	}
+
+	fmt.Println("Anthropic login method:")
+	fmt.Println("  1) Setup token (from `claude setup-token`) (Recommended)")
+	fmt.Println("  2) API key (from console.anthropic.com)")
+
+	scanner := bufio.NewScanner(os.Stdin)
+	for {
+		fmt.Print("Choose [1]: ")
+		choice := "1"
+		if scanner.Scan() {
+			text := strings.TrimSpace(scanner.Text())
+			if text != "" {
+				choice = text
+			}
+		}
+
+		switch choice {
+		case "1":
+			return authLoginAnthropicSetupToken()
+		case "2":
+			return authLoginPasteToken("anthropic")
+		default:
+			fmt.Printf("Invalid choice: %s. Please enter 1 or 2.\n", choice)
+		}
+	}
+}
+
+func authLoginAnthropicSetupToken() error {
+	cred, err := auth.LoginSetupToken(os.Stdin)
+	if err != nil {
+		return fmt.Errorf("login failed: %w", err)
+	}
+
+	if err = auth.SetCredential("anthropic", cred); err != nil {
+		return fmt.Errorf("failed to save credentials: %w", err)
+	}
+
+	appCfg, err := internal.LoadConfig()
+	if err == nil {
+		found := false
+		for i := range appCfg.ModelList {
+			if isAnthropicModel(appCfg.ModelList[i].Model) {
+				appCfg.ModelList[i].AuthMethod = "oauth"
+				found = true
+				break
+			}
+		}
+		if !found {
+			appCfg.ModelList = append(appCfg.ModelList, &config.ModelConfig{
+				ModelName:  defaultAnthropicModel,
+				Model:      "anthropic/" + defaultAnthropicModel,
+				AuthMethod: "oauth",
+			})
+			// Only set default model if user has no default configured yet
+			if appCfg.Agents.Defaults.GetModelName() == "" {
+				appCfg.Agents.Defaults.ModelName = defaultAnthropicModel
+			}
+		}
+
+		if err := config.SaveConfig(internal.GetConfigPath(), appCfg); err != nil {
+			return fmt.Errorf("could not update config: %w", err)
+		}
+	}
+
+	fmt.Println("Setup token saved for Anthropic!")
+
+	return nil
+}
+
 func fetchGoogleUserEmail(accessToken string) (string, error) {
 	req, err := http.NewRequest("GET", "https://www.googleapis.com/oauth2/v2/userinfo", nil)
 	if err != nil {
@@ -177,7 +248,10 @@ func fetchGoogleUserEmail(accessToken string) (string, error) {
 	}
 	defer resp.Body.Close()
 
-	body, _ := io.ReadAll(resp.Body)
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("reading userinfo response: %w", err)
+	}
 	if resp.StatusCode != http.StatusOK {
 		return "", fmt.Errorf("userinfo request failed: %s", string(body))
 	}
@@ -205,7 +279,6 @@ func authLoginPasteToken(provider string) error {
 	if err == nil {
 		switch provider {
 		case "anthropic":
-			appCfg.Providers.Anthropic.AuthMethod = "token"
 			// Update ModelList
 			found := false
 			for i := range appCfg.ModelList {
@@ -216,16 +289,14 @@ func authLoginPasteToken(provider string) error {
 				}
 			}
 			if !found {
-				appCfg.ModelList = append(appCfg.ModelList, config.ModelConfig{
-					ModelName:  "claude-sonnet-4.6",
-					Model:      "anthropic/claude-sonnet-4.6",
+				appCfg.ModelList = append(appCfg.ModelList, &config.ModelConfig{
+					ModelName:  defaultAnthropicModel,
+					Model:      "anthropic/" + defaultAnthropicModel,
 					AuthMethod: "token",
 				})
+				appCfg.Agents.Defaults.ModelName = defaultAnthropicModel
 			}
-			// Update default model
-			appCfg.Agents.Defaults.ModelName = "claude-sonnet-4.6"
 		case "openai":
-			appCfg.Providers.OpenAI.AuthMethod = "token"
 			// Update ModelList
 			found := false
 			for i := range appCfg.ModelList {
@@ -236,14 +307,14 @@ func authLoginPasteToken(provider string) error {
 				}
 			}
 			if !found {
-				appCfg.ModelList = append(appCfg.ModelList, config.ModelConfig{
-					ModelName:  "gpt-5.2",
-					Model:      "openai/gpt-5.2",
+				appCfg.ModelList = append(appCfg.ModelList, &config.ModelConfig{
+					ModelName:  "gpt-5.4",
+					Model:      "openai/gpt-5.4",
 					AuthMethod: "token",
 				})
 			}
 			// Update default model
-			appCfg.Agents.Defaults.ModelName = "gpt-5.2"
+			appCfg.Agents.Defaults.ModelName = "gpt-5.4"
 		}
 		if err := config.SaveConfig(internal.GetConfigPath(), appCfg); err != nil {
 			return fmt.Errorf("could not update config: %w", err)
@@ -284,15 +355,6 @@ func authLogoutCmd(provider string) error {
 					}
 				}
 			}
-			// Clear AuthMethod in Providers (legacy)
-			switch provider {
-			case "openai":
-				appCfg.Providers.OpenAI.AuthMethod = ""
-			case "anthropic":
-				appCfg.Providers.Anthropic.AuthMethod = ""
-			case "google-antigravity", "antigravity":
-				appCfg.Providers.Antigravity.AuthMethod = ""
-			}
 			config.SaveConfig(internal.GetConfigPath(), appCfg)
 		}
 
@@ -311,10 +373,6 @@ func authLogoutCmd(provider string) error {
 		for i := range appCfg.ModelList {
 			appCfg.ModelList[i].AuthMethod = ""
 		}
-		// Clear all AuthMethods in Providers (legacy)
-		appCfg.Providers.OpenAI.AuthMethod = ""
-		appCfg.Providers.Anthropic.AuthMethod = ""
-		appCfg.Providers.Antigravity.AuthMethod = ""
 		config.SaveConfig(internal.GetConfigPath(), appCfg)
 	}
 
@@ -360,6 +418,16 @@ func authStatusCmd() error {
 		if !cred.ExpiresAt.IsZero() {
 			fmt.Printf("    Expires: %s\n", cred.ExpiresAt.Format("2006-01-02 15:04"))
 		}
+
+		if provider == "anthropic" && cred.AuthMethod == "oauth" {
+			usage, err := auth.FetchAnthropicUsage(cred.AccessToken)
+			if err != nil {
+				fmt.Printf("    Usage: unavailable (%v)\n", err)
+			} else {
+				fmt.Printf("    Usage (5h):  %.1f%%\n", usage.FiveHourUtilization*100)
+				fmt.Printf("    Usage (7d):  %.1f%%\n", usage.SevenDayUtilization*100)
+			}
+		}
 	}
 
 	return nil
diff --git a/cmd/picoclaw/internal/auth/login.go b/cmd/picoclaw/internal/auth/login.go
index 9a6d28d2f..afbe098aa 100644
--- a/cmd/picoclaw/internal/auth/login.go
+++ b/cmd/picoclaw/internal/auth/login.go
@@ -6,6 +6,7 @@ func newLoginCommand() *cobra.Command {
 	var (
 		provider      string
 		useDeviceCode bool
+		useOauth      bool
 	)
 
 	cmd := &cobra.Command{
@@ -13,12 +14,16 @@ func newLoginCommand() *cobra.Command {
 		Short: "Login via OAuth or paste token",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			return authLoginCmd(provider, useDeviceCode)
+			return authLoginCmd(provider, useDeviceCode, useOauth)
 		},
 	}
 
 	cmd.Flags().StringVarP(&provider, "provider", "p", "", "Provider to login with (openai, anthropic)")
 	cmd.Flags().BoolVar(&useDeviceCode, "device-code", false, "Use device code flow (for headless environments)")
+	cmd.Flags().BoolVar(
+		&useOauth, "setup-token", false,
+		"Use setup-token flow for Anthropic (from `claude setup-token`)",
+	)
 	_ = cmd.MarkFlagRequired("provider")
 
 	return cmd
diff --git a/cmd/picoclaw/internal/auth/wecom.go b/cmd/picoclaw/internal/auth/wecom.go
new file mode 100644
index 000000000..8261f5f80
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/wecom.go
@@ -0,0 +1,407 @@
+package auth
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"runtime"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/mdp/qrterminal/v3"
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+const (
+	wecomQRSourceID          = "picoclaw"
+	wecomQRGenerateEndpoint  = "https://work.weixin.qq.com/ai/qc/generate"
+	wecomQRQueryEndpoint     = "https://work.weixin.qq.com/ai/qc/query_result"
+	wecomQRPageEndpoint      = "https://work.weixin.qq.com/ai/qc/gen"
+	wecomQRHTTPTimeout       = 15 * time.Second
+	wecomQRPollInterval      = 3 * time.Second
+	wecomQRPollTimeout       = 5 * time.Minute
+	wecomDefaultWebSocketURL = "wss://openws.work.weixin.qq.com"
+)
+
+type wecomQRScanner func(context.Context, wecomQRFlowOptions) (wecomQRBotInfo, error)
+
+type wecomQRFlowOptions struct {
+	HTTPClient    *http.Client
+	GenerateURL   string
+	QueryURL      string
+	QRCodePageURL string
+	SourceID      string
+	PollInterval  time.Duration
+	PollTimeout   time.Duration
+	Writer        io.Writer
+}
+
+type wecomQRBotInfo struct {
+	BotID  string
+	Secret string
+}
+
+type wecomQRSession struct {
+	SCode   string
+	AuthURL string
+}
+
+type wecomQRGenerateResponse struct {
+	ErrCode int    `json:"errcode,omitempty"`
+	ErrMsg  string `json:"errmsg,omitempty"`
+	Data    struct {
+		SCode   string `json:"scode"`
+		AuthURL string `json:"auth_url"`
+	} `json:"data"`
+}
+
+type wecomQRQueryResponse struct {
+	ErrCode int    `json:"errcode,omitempty"`
+	ErrMsg  string `json:"errmsg,omitempty"`
+	Data    struct {
+		Status  string `json:"status"`
+		BotInfo struct {
+			BotID  string `json:"botid"`
+			Secret string `json:"secret"`
+		} `json:"bot_info"`
+	} `json:"data"`
+}
+
+func newWeComCommand() *cobra.Command {
+	var timeout time.Duration
+
+	cmd := &cobra.Command{
+		Use:   "wecom",
+		Short: "Scan a WeCom QR code and configure channels.wecom",
+		Args:  cobra.NoArgs,
+		RunE: func(_ *cobra.Command, _ []string) error {
+			return authWeComCmd(timeout)
+		},
+	}
+
+	cmd.Flags().DurationVar(&timeout, "timeout", wecomQRPollTimeout, "How long to wait for QR confirmation")
+
+	return cmd
+}
+
+func authWeComCmd(timeout time.Duration) error {
+	return authWeComCmdWithScanner(context.Background(), os.Stdout, timeout, scanWeComQRCodeInteractive)
+}
+
+func authWeComCmdWithScanner(
+	ctx context.Context,
+	writer io.Writer,
+	timeout time.Duration,
+	scanner wecomQRScanner,
+) error {
+	if scanner == nil {
+		return fmt.Errorf("wecom QR scanner is nil")
+	}
+	if writer == nil {
+		writer = os.Stdout
+	}
+
+	cfg, err := internal.LoadConfig()
+	if err != nil {
+		return fmt.Errorf("failed to load config: %w", err)
+	}
+
+	opts := defaultWeComQRFlowOptions(timeout)
+	opts.Writer = writer
+
+	botInfo, err := scanner(ctx, opts)
+	if err != nil {
+		return err
+	}
+
+	applyWeComAuthResult(cfg, botInfo)
+
+	if saveErr := config.SaveConfig(internal.GetConfigPath(), cfg); saveErr != nil {
+		return fmt.Errorf("failed to save config: %w", saveErr)
+	}
+
+	fmt.Fprintln(writer)
+	fmt.Fprintln(writer, "WeCom connected.")
+	fmt.Fprintf(writer, "Bot ID: %s\n", botInfo.BotID)
+	fmt.Fprintf(writer, "Config: %s\n", internal.GetConfigPath())
+
+	return nil
+}
+
+func defaultWeComQRFlowOptions(timeout time.Duration) wecomQRFlowOptions {
+	if timeout <= 0 {
+		timeout = wecomQRPollTimeout
+	}
+
+	return wecomQRFlowOptions{
+		HTTPClient:    &http.Client{Timeout: wecomQRHTTPTimeout},
+		GenerateURL:   wecomQRGenerateEndpoint,
+		QueryURL:      wecomQRQueryEndpoint,
+		QRCodePageURL: wecomQRPageEndpoint,
+		SourceID:      wecomQRSourceID,
+		PollInterval:  wecomQRPollInterval,
+		PollTimeout:   timeout,
+		Writer:        os.Stdout,
+	}
+}
+
+func applyWeComAuthResult(cfg *config.Config, botInfo wecomQRBotInfo) {
+	cfg.Channels.WeCom.Enabled = true
+	cfg.Channels.WeCom.BotID = botInfo.BotID
+	cfg.Channels.WeCom.SetSecret(botInfo.Secret)
+	if strings.TrimSpace(cfg.Channels.WeCom.WebSocketURL) == "" {
+		cfg.Channels.WeCom.WebSocketURL = wecomDefaultWebSocketURL
+	}
+}
+
+func scanWeComQRCodeInteractive(ctx context.Context, opts wecomQRFlowOptions) (wecomQRBotInfo, error) {
+	opts = normalizeWeComQRFlowOptions(opts)
+
+	fmt.Fprintln(opts.Writer, "Requesting WeCom QR code...")
+
+	session, err := fetchWeComQRCode(ctx, opts)
+	if err != nil {
+		return wecomQRBotInfo{}, err
+	}
+
+	fmt.Fprintln(opts.Writer)
+	fmt.Fprintln(opts.Writer, "=======================================================")
+	fmt.Fprintln(opts.Writer, "Please scan the following QR code with WeCom:")
+	fmt.Fprintln(opts.Writer, "=======================================================")
+	fmt.Fprintln(opts.Writer)
+
+	qrterminal.GenerateWithConfig(session.AuthURL, qrterminal.Config{
+		Level:      qrterminal.L,
+		Writer:     opts.Writer,
+		HalfBlocks: true,
+	})
+
+	pageURL, err := buildWeComQRCodePageURL(opts.QRCodePageURL, opts.SourceID, session.SCode)
+	if err != nil {
+		return wecomQRBotInfo{}, err
+	}
+
+	fmt.Fprintln(opts.Writer)
+	fmt.Fprintf(opts.Writer, "QR Code Link: %s\n", pageURL)
+	fmt.Fprintln(opts.Writer)
+	fmt.Fprintln(opts.Writer, "Waiting for scan...")
+
+	return pollWeComQRCodeResult(ctx, opts, session.SCode)
+}
+
+func normalizeWeComQRFlowOptions(opts wecomQRFlowOptions) wecomQRFlowOptions {
+	if opts.HTTPClient == nil {
+		opts.HTTPClient = &http.Client{Timeout: wecomQRHTTPTimeout}
+	}
+	if strings.TrimSpace(opts.GenerateURL) == "" {
+		opts.GenerateURL = wecomQRGenerateEndpoint
+	}
+	if strings.TrimSpace(opts.QueryURL) == "" {
+		opts.QueryURL = wecomQRQueryEndpoint
+	}
+	if strings.TrimSpace(opts.QRCodePageURL) == "" {
+		opts.QRCodePageURL = wecomQRPageEndpoint
+	}
+	if strings.TrimSpace(opts.SourceID) == "" {
+		opts.SourceID = wecomQRSourceID
+	}
+	if opts.PollInterval <= 0 {
+		opts.PollInterval = wecomQRPollInterval
+	}
+	if opts.PollTimeout <= 0 {
+		opts.PollTimeout = wecomQRPollTimeout
+	}
+	if opts.Writer == nil {
+		opts.Writer = os.Stdout
+	}
+
+	return opts
+}
+
+func fetchWeComQRCode(ctx context.Context, opts wecomQRFlowOptions) (wecomQRSession, error) {
+	generateURL, err := buildWeComQRGenerateURL(opts.GenerateURL, opts.SourceID, wecomPlatformCode())
+	if err != nil {
+		return wecomQRSession{}, err
+	}
+
+	var resp wecomQRGenerateResponse
+	if err := doWeComJSONGet(ctx, opts.HTTPClient, generateURL, &resp); err != nil {
+		return wecomQRSession{}, fmt.Errorf("failed to get WeCom QR code: %w", err)
+	}
+	if resp.ErrCode != 0 {
+		return wecomQRSession{}, fmt.Errorf(
+			"failed to get WeCom QR code: errcode=%d errmsg=%s",
+			resp.ErrCode,
+			resp.ErrMsg,
+		)
+	}
+	if resp.Data.SCode == "" || resp.Data.AuthURL == "" {
+		return wecomQRSession{}, fmt.Errorf("failed to get WeCom QR code: response missing scode or auth_url")
+	}
+
+	return wecomQRSession{
+		SCode:   resp.Data.SCode,
+		AuthURL: resp.Data.AuthURL,
+	}, nil
+}
+
+func pollWeComQRCodeResult(ctx context.Context, opts wecomQRFlowOptions, scode string) (wecomQRBotInfo, error) {
+	if strings.TrimSpace(scode) == "" {
+		return wecomQRBotInfo{}, fmt.Errorf("missing WeCom QR scode")
+	}
+
+	timeoutCtx, cancel := context.WithTimeout(ctx, opts.PollTimeout)
+	defer cancel()
+
+	var scannedPrinted bool
+
+	for {
+		status, err := queryWeComQRCodeStatus(timeoutCtx, opts, scode)
+		if err != nil {
+			if errors.Is(err, context.DeadlineExceeded) || errors.Is(timeoutCtx.Err(), context.DeadlineExceeded) {
+				return wecomQRBotInfo{}, fmt.Errorf("WeCom QR scan timed out after %s", opts.PollTimeout)
+			}
+			return wecomQRBotInfo{}, err
+		}
+
+		switch strings.ToLower(status.Data.Status) {
+		case "success":
+			if status.Data.BotInfo.BotID == "" || status.Data.BotInfo.Secret == "" {
+				return wecomQRBotInfo{}, fmt.Errorf("WeCom QR scan succeeded but bot credentials are missing")
+			}
+			return wecomQRBotInfo{
+				BotID:  status.Data.BotInfo.BotID,
+				Secret: status.Data.BotInfo.Secret,
+			}, nil
+		case "expired":
+			return wecomQRBotInfo{}, fmt.Errorf("WeCom QR code expired, please retry")
+		case "scaned", "scanned":
+			if !scannedPrinted {
+				fmt.Fprintln(opts.Writer, "QR code scanned. Confirm the login in WeCom.")
+				scannedPrinted = true
+			}
+		}
+
+		select {
+		case <-timeoutCtx.Done():
+			if errors.Is(timeoutCtx.Err(), context.DeadlineExceeded) {
+				return wecomQRBotInfo{}, fmt.Errorf("WeCom QR scan timed out after %s", opts.PollTimeout)
+			}
+			return wecomQRBotInfo{}, timeoutCtx.Err()
+		case <-time.After(opts.PollInterval):
+		}
+	}
+}
+
+func queryWeComQRCodeStatus(ctx context.Context, opts wecomQRFlowOptions, scode string) (wecomQRQueryResponse, error) {
+	queryURL, err := buildWeComQRQueryURL(opts.QueryURL, scode)
+	if err != nil {
+		return wecomQRQueryResponse{}, err
+	}
+
+	var resp wecomQRQueryResponse
+	if err := doWeComJSONGet(ctx, opts.HTTPClient, queryURL, &resp); err != nil {
+		return wecomQRQueryResponse{}, fmt.Errorf("failed to query WeCom QR result: %w", err)
+	}
+	if resp.ErrCode != 0 {
+		return wecomQRQueryResponse{}, fmt.Errorf(
+			"failed to query WeCom QR result: errcode=%d errmsg=%s",
+			resp.ErrCode,
+			resp.ErrMsg,
+		)
+	}
+
+	return resp, nil
+}
+
+func buildWeComQRGenerateURL(baseURL, sourceID string, platformCode int) (string, error) {
+	u, err := url.Parse(baseURL)
+	if err != nil {
+		return "", fmt.Errorf("invalid WeCom QR generate URL: %w", err)
+	}
+
+	query := u.Query()
+	query.Set("source", sourceID)
+	query.Set("sourceID", sourceID)
+	query.Set("plat", strconv.Itoa(platformCode))
+	u.RawQuery = query.Encode()
+
+	return u.String(), nil
+}
+
+func buildWeComQRQueryURL(baseURL, scode string) (string, error) {
+	u, err := url.Parse(baseURL)
+	if err != nil {
+		return "", fmt.Errorf("invalid WeCom QR query URL: %w", err)
+	}
+
+	query := u.Query()
+	query.Set("scode", scode)
+	u.RawQuery = query.Encode()
+
+	return u.String(), nil
+}
+
+func buildWeComQRCodePageURL(baseURL, sourceID, scode string) (string, error) {
+	u, err := url.Parse(baseURL)
+	if err != nil {
+		return "", fmt.Errorf("invalid WeCom QR page URL: %w", err)
+	}
+
+	query := u.Query()
+	query.Set("source", sourceID)
+	query.Set("sourceID", sourceID)
+	query.Set("scode", scode)
+	u.RawQuery = query.Encode()
+
+	return u.String(), nil
+}
+
+func doWeComJSONGet(ctx context.Context, client *http.Client, targetURL string, out any) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, targetURL, nil)
+	if err != nil {
+		return err
+	}
+
+	resp, err := client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, readErr := io.ReadAll(io.LimitReader(resp.Body, 8192))
+		if readErr != nil {
+			return fmt.Errorf("unexpected status %s", resp.Status)
+		}
+		return fmt.Errorf("unexpected status %s: %s", resp.Status, strings.TrimSpace(string(body)))
+	}
+
+	if err := json.NewDecoder(resp.Body).Decode(out); err != nil {
+		return fmt.Errorf("decode JSON response: %w", err)
+	}
+
+	return nil
+}
+
+func wecomPlatformCode() int {
+	switch runtime.GOOS {
+	case "darwin":
+		return 1
+	case "windows":
+		return 2
+	case "linux":
+		return 3
+	default:
+		return 0
+	}
+}
diff --git a/cmd/picoclaw/internal/auth/wecom_test.go b/cmd/picoclaw/internal/auth/wecom_test.go
new file mode 100644
index 000000000..c2a4624ae
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/wecom_test.go
@@ -0,0 +1,157 @@
+package auth
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"path/filepath"
+	"strconv"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestNewWeComCommand(t *testing.T) {
+	cmd := newWeComCommand()
+
+	require.NotNil(t, cmd)
+	assert.Equal(t, "wecom", cmd.Use)
+	assert.Equal(t, "Scan a WeCom QR code and configure channels.wecom", cmd.Short)
+	assert.NotNil(t, cmd.Flags().Lookup("timeout"))
+}
+
+func TestBuildWeComQRGenerateURL(t *testing.T) {
+	rawURL, err := buildWeComQRGenerateURL("https://example.com/ai/qc/generate", wecomQRSourceID, 3)
+	require.NoError(t, err)
+
+	parsed, err := url.Parse(rawURL)
+	require.NoError(t, err)
+
+	assert.Equal(t, wecomQRSourceID, parsed.Query().Get("source"))
+	assert.Equal(t, wecomQRSourceID, parsed.Query().Get("sourceID"))
+	assert.Equal(t, "3", parsed.Query().Get("plat"))
+}
+
+func TestBuildWeComQRCodePageURL(t *testing.T) {
+	rawURL, err := buildWeComQRCodePageURL("https://example.com/ai/qc/gen", wecomQRSourceID, "scode-1")
+	require.NoError(t, err)
+
+	parsed, err := url.Parse(rawURL)
+	require.NoError(t, err)
+
+	assert.Equal(t, wecomQRSourceID, parsed.Query().Get("source"))
+	assert.Equal(t, wecomQRSourceID, parsed.Query().Get("sourceID"))
+	assert.Equal(t, "scode-1", parsed.Query().Get("scode"))
+}
+
+func TestFetchWeComQRCode(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/generate", r.URL.Path)
+		assert.Equal(t, wecomQRSourceID, r.URL.Query().Get("source"))
+		assert.Equal(t, wecomQRSourceID, r.URL.Query().Get("sourceID"))
+		assert.Equal(t, strconv.Itoa(wecomPlatformCode()), r.URL.Query().Get("plat"))
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"data":{"scode":"scode-1","auth_url":"https://example.com/qr"}}`))
+	}))
+	defer server.Close()
+
+	opts := normalizeWeComQRFlowOptions(wecomQRFlowOptions{
+		HTTPClient:  server.Client(),
+		GenerateURL: server.URL + "/generate",
+		Writer:      bytes.NewBuffer(nil),
+	})
+
+	session, err := fetchWeComQRCode(context.Background(), opts)
+	require.NoError(t, err)
+	assert.Equal(t, "scode-1", session.SCode)
+	assert.Equal(t, "https://example.com/qr", session.AuthURL)
+}
+
+func TestPollWeComQRCodeResult(t *testing.T) {
+	var calls atomic.Int32
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		call := calls.Add(1)
+		assert.Equal(t, "/query", r.URL.Path)
+		assert.Equal(t, "scode-1", r.URL.Query().Get("scode"))
+		w.Header().Set("Content-Type", "application/json")
+		switch call {
+		case 1:
+			_, _ = w.Write([]byte(`{"data":{"status":"wait"}}`))
+		case 2:
+			_, _ = w.Write([]byte(`{"data":{"status":"scaned"}}`))
+		default:
+			_, _ = w.Write([]byte(`{"data":{"status":"success","bot_info":{"botid":"bot-1","secret":"secret-1"}}}`))
+		}
+	}))
+	defer server.Close()
+
+	var output bytes.Buffer
+	opts := normalizeWeComQRFlowOptions(wecomQRFlowOptions{
+		HTTPClient:   server.Client(),
+		QueryURL:     server.URL + "/query",
+		PollInterval: time.Millisecond,
+		PollTimeout:  time.Second,
+		Writer:       &output,
+	})
+
+	botInfo, err := pollWeComQRCodeResult(context.Background(), opts, "scode-1")
+	require.NoError(t, err)
+	assert.Equal(t, "bot-1", botInfo.BotID)
+	assert.Equal(t, "secret-1", botInfo.Secret)
+	assert.Contains(t, output.String(), "QR code scanned. Confirm the login in WeCom.")
+}
+
+func TestApplyWeComAuthResult(t *testing.T) {
+	cfg := config.DefaultConfig()
+	cfg.Channels.WeCom.WebSocketURL = ""
+
+	applyWeComAuthResult(cfg, wecomQRBotInfo{
+		BotID:  "bot-1",
+		Secret: "secret-1",
+	})
+
+	assert.True(t, cfg.Channels.WeCom.Enabled)
+	assert.Equal(t, "bot-1", cfg.Channels.WeCom.BotID)
+	assert.Equal(t, "secret-1", cfg.Channels.WeCom.Secret())
+	assert.Equal(t, wecomDefaultWebSocketURL, cfg.Channels.WeCom.WebSocketURL)
+}
+
+func TestAuthWeComCmdWithScanner(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+
+	t.Setenv(config.EnvHome, tmpDir)
+	t.Setenv(config.EnvConfig, configPath)
+
+	var output bytes.Buffer
+	err := authWeComCmdWithScanner(
+		context.Background(),
+		&output,
+		time.Second,
+		func(_ context.Context, opts wecomQRFlowOptions) (wecomQRBotInfo, error) {
+			assert.Equal(t, wecomQRSourceID, opts.SourceID)
+			return wecomQRBotInfo{
+				BotID:  "bot-1",
+				Secret: "secret-1",
+			}, nil
+		},
+	)
+	require.NoError(t, err)
+
+	cfg, err := config.LoadConfig(internal.GetConfigPath())
+	require.NoError(t, err)
+	assert.True(t, cfg.Channels.WeCom.Enabled)
+	assert.Equal(t, "bot-1", cfg.Channels.WeCom.BotID)
+	assert.Equal(t, "secret-1", cfg.Channels.WeCom.Secret())
+	assert.Equal(t, wecomDefaultWebSocketURL, cfg.Channels.WeCom.WebSocketURL)
+	assert.Contains(t, output.String(), "WeCom connected.")
+}
diff --git a/cmd/picoclaw/internal/auth/weixin.go b/cmd/picoclaw/internal/auth/weixin.go
new file mode 100644
index 000000000..948a81495
--- /dev/null
+++ b/cmd/picoclaw/internal/auth/weixin.go
@@ -0,0 +1,124 @@
+package auth
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/channels/weixin"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func newWeixinCommand() *cobra.Command {
+	var baseURL string
+	var proxy string
+	var timeout int
+
+	cmd := &cobra.Command{
+		Use:   "weixin",
+		Short: "Connect a WeChat personal account via QR code",
+		Long: `Start the interactive Weixin (WeChat personal) QR code login flow.
+
+A QR code is displayed in the terminal. Scan it with the WeChat mobile app
+to authorize your account. On success, the bot token is saved to the picoclaw
+config so you can start the gateway immediately.
+
+Example:
+  picoclaw auth weixin`,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			return runWeixinOnboard(baseURL, proxy, time.Duration(timeout)*time.Second)
+		},
+	}
+
+	cmd.Flags().StringVar(&baseURL, "base-url", "https://ilinkai.weixin.qq.com/", "iLink API base URL")
+	cmd.Flags().StringVar(&proxy, "proxy", "", "HTTP proxy URL (e.g. http://localhost:7890)")
+	cmd.Flags().IntVar(&timeout, "timeout", 300, "Login timeout in seconds")
+
+	return cmd
+}
+
+func runWeixinOnboard(baseURL, proxy string, timeout time.Duration) error {
+	fmt.Println("Starting Weixin (WeChat personal) login...")
+	fmt.Println()
+
+	botToken, userID, accountID, returnedBaseURL, err := weixin.PerformLoginInteractive(
+		context.Background(),
+		weixin.AuthFlowOpts{
+			BaseURL: baseURL,
+			Timeout: timeout,
+			Proxy:   proxy,
+		},
+	)
+	if err != nil {
+		return fmt.Errorf("login failed: %w", err)
+	}
+
+	fmt.Println()
+	fmt.Println("✅ Login successful!")
+	fmt.Printf("   Account ID : %s\n", accountID)
+	if userID != "" {
+		fmt.Printf("   User ID    : %s\n", userID)
+	}
+	fmt.Println()
+
+	// Prefer the server-returned base URL (may be region-specific)
+	effectiveBaseURL := returnedBaseURL
+	if effectiveBaseURL == "" {
+		effectiveBaseURL = baseURL
+	}
+
+	if err := saveWeixinConfig(botToken, effectiveBaseURL, proxy); err != nil {
+		fmt.Printf("⚠️  Could not auto-save to config: %v\n", err)
+		printManualWeixinConfig(botToken, effectiveBaseURL)
+		return nil
+	}
+
+	fmt.Println("✓ Config updated. Start the gateway with:")
+	fmt.Println()
+	fmt.Println("  picoclaw gateway")
+	fmt.Println()
+	fmt.Println("To restrict which WeChat users can send messages, add their user IDs")
+	fmt.Println("to channels.weixin.allow_from in your config.")
+
+	return nil
+}
+
+// saveWeixinConfig patches channels.weixin in the config and saves it.
+func saveWeixinConfig(token, baseURL, proxy string) error {
+	cfgPath := internal.GetConfigPath()
+
+	cfg, err := config.LoadConfig(cfgPath)
+	if err != nil {
+		return fmt.Errorf("failed to load config: %w", err)
+	}
+
+	cfg.Channels.Weixin.Enabled = true
+	cfg.Channels.Weixin.SetToken(token)
+	const defaultBase = "https://ilinkai.weixin.qq.com/"
+	if baseURL != "" && baseURL != defaultBase {
+		cfg.Channels.Weixin.BaseURL = baseURL
+	}
+	if proxy != "" {
+		cfg.Channels.Weixin.Proxy = proxy
+	}
+
+	return config.SaveConfig(cfgPath, cfg)
+}
+
+func printManualWeixinConfig(token, baseURL string) {
+	fmt.Println()
+	fmt.Println("Add the following to the channels section of your picoclaw config:")
+	fmt.Println()
+	fmt.Println(`  "weixin": {`)
+	fmt.Println(`    "enabled": true,`)
+	fmt.Printf("    \"token\": %q,\n", token)
+	const defaultBase = "https://ilinkai.weixin.qq.com/"
+	if baseURL != "" && baseURL != defaultBase {
+		fmt.Printf("    \"base_url\": %q,\n", baseURL)
+	}
+	fmt.Println(`    "allow_from": []`)
+	fmt.Println(`  }`)
+}
diff --git a/cmd/picoclaw/internal/gateway/command.go b/cmd/picoclaw/internal/gateway/command.go
index 66a56f9ce..7fa588c5c 100644
--- a/cmd/picoclaw/internal/gateway/command.go
+++ b/cmd/picoclaw/internal/gateway/command.go
@@ -1,23 +1,52 @@
 package gateway
 
 import (
+	"fmt"
+
 	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/gateway"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
 func NewGatewayCommand() *cobra.Command {
 	var debug bool
+	var noTruncate bool
+	var allowEmpty bool
 
 	cmd := &cobra.Command{
 		Use:     "gateway",
 		Aliases: []string{"g"},
 		Short:   "Start picoclaw gateway",
 		Args:    cobra.NoArgs,
+		PreRunE: func(_ *cobra.Command, _ []string) error {
+			if noTruncate && !debug {
+				return fmt.Errorf("the --no-truncate option can only be used in conjunction with --debug (-d)")
+			}
+
+			if noTruncate {
+				utils.SetDisableTruncation(true)
+				logger.Info("String truncation is globally disabled via 'no-truncate' flag")
+			}
+
+			return nil
+		},
 		RunE: func(_ *cobra.Command, _ []string) error {
-			return gatewayCmd(debug)
+			return gateway.Run(debug, internal.GetPicoclawHome(), internal.GetConfigPath(), allowEmpty)
 		},
 	}
 
 	cmd.Flags().BoolVarP(&debug, "debug", "d", false, "Enable debug logging")
+	cmd.Flags().BoolVarP(&noTruncate, "no-truncate", "T", false, "Disable string truncation in debug logs")
+	cmd.Flags().BoolVarP(
+		&allowEmpty,
+		"allow-empty",
+		"E",
+		false,
+		"Continue starting even when no default model is configured",
+	)
 
 	return cmd
 }
diff --git a/cmd/picoclaw/internal/gateway/command_test.go b/cmd/picoclaw/internal/gateway/command_test.go
index 4d591ea67..839a7315a 100644
--- a/cmd/picoclaw/internal/gateway/command_test.go
+++ b/cmd/picoclaw/internal/gateway/command_test.go
@@ -28,4 +28,5 @@ func TestNewGatewayCommand(t *testing.T) {
 
 	assert.True(t, cmd.HasFlags())
 	assert.NotNil(t, cmd.Flags().Lookup("debug"))
+	assert.NotNil(t, cmd.Flags().Lookup("allow-empty"))
 }
diff --git a/cmd/picoclaw/internal/gateway/helpers.go b/cmd/picoclaw/internal/gateway/helpers.go
deleted file mode 100644
index 747f7d44e..000000000
--- a/cmd/picoclaw/internal/gateway/helpers.go
+++ /dev/null
@@ -1,241 +0,0 @@
-package gateway
-
-import (
-	"context"
-	"fmt"
-	"log"
-	"os"
-	"os/signal"
-	"path/filepath"
-	"time"
-
-	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
-	"github.com/sipeed/picoclaw/pkg/agent"
-	"github.com/sipeed/picoclaw/pkg/bus"
-	"github.com/sipeed/picoclaw/pkg/channels"
-	_ "github.com/sipeed/picoclaw/pkg/channels/dingtalk"
-	_ "github.com/sipeed/picoclaw/pkg/channels/discord"
-	_ "github.com/sipeed/picoclaw/pkg/channels/feishu"
-	_ "github.com/sipeed/picoclaw/pkg/channels/line"
-	_ "github.com/sipeed/picoclaw/pkg/channels/maixcam"
-	_ "github.com/sipeed/picoclaw/pkg/channels/onebot"
-	_ "github.com/sipeed/picoclaw/pkg/channels/pico"
-	_ "github.com/sipeed/picoclaw/pkg/channels/qq"
-	_ "github.com/sipeed/picoclaw/pkg/channels/slack"
-	_ "github.com/sipeed/picoclaw/pkg/channels/telegram"
-	_ "github.com/sipeed/picoclaw/pkg/channels/wecom"
-	_ "github.com/sipeed/picoclaw/pkg/channels/whatsapp"
-	_ "github.com/sipeed/picoclaw/pkg/channels/whatsapp_native"
-	"github.com/sipeed/picoclaw/pkg/config"
-	"github.com/sipeed/picoclaw/pkg/cron"
-	"github.com/sipeed/picoclaw/pkg/devices"
-	"github.com/sipeed/picoclaw/pkg/health"
-	"github.com/sipeed/picoclaw/pkg/heartbeat"
-	"github.com/sipeed/picoclaw/pkg/logger"
-	"github.com/sipeed/picoclaw/pkg/media"
-	"github.com/sipeed/picoclaw/pkg/providers"
-	"github.com/sipeed/picoclaw/pkg/state"
-	"github.com/sipeed/picoclaw/pkg/tools"
-)
-
-func gatewayCmd(debug bool) error {
-	if debug {
-		logger.SetLevel(logger.DEBUG)
-		fmt.Println("🔍 Debug mode enabled")
-	}
-
-	cfg, err := internal.LoadConfig()
-	if err != nil {
-		return fmt.Errorf("error loading config: %w", err)
-	}
-
-	provider, modelID, err := providers.CreateProvider(cfg)
-	if err != nil {
-		return fmt.Errorf("error creating provider: %w", err)
-	}
-
-	// Use the resolved model ID from provider creation
-	if modelID != "" {
-		cfg.Agents.Defaults.ModelName = modelID
-	}
-
-	msgBus := bus.NewMessageBus()
-	agentLoop := agent.NewAgentLoop(cfg, msgBus, provider)
-
-	// Print agent startup info
-	fmt.Println("\n📦 Agent Status:")
-	startupInfo := agentLoop.GetStartupInfo()
-	toolsInfo := startupInfo["tools"].(map[string]any)
-	skillsInfo := startupInfo["skills"].(map[string]any)
-	fmt.Printf("  • Tools: %d loaded\n", toolsInfo["count"])
-	fmt.Printf("  • Skills: %d/%d available\n",
-		skillsInfo["available"],
-		skillsInfo["total"])
-
-	// Log to file as well
-	logger.InfoCF("agent", "Agent initialized",
-		map[string]any{
-			"tools_count":      toolsInfo["count"],
-			"skills_total":     skillsInfo["total"],
-			"skills_available": skillsInfo["available"],
-		})
-
-	// Setup cron tool and service
-	execTimeout := time.Duration(cfg.Tools.Cron.ExecTimeoutMinutes) * time.Minute
-	cronService := setupCronTool(
-		agentLoop,
-		msgBus,
-		cfg.WorkspacePath(),
-		cfg.Agents.Defaults.RestrictToWorkspace,
-		execTimeout,
-		cfg,
-	)
-
-	heartbeatService := heartbeat.NewHeartbeatService(
-		cfg.WorkspacePath(),
-		cfg.Heartbeat.Interval,
-		cfg.Heartbeat.Enabled,
-	)
-	heartbeatService.SetBus(msgBus)
-	heartbeatService.SetHandler(func(prompt, channel, chatID string) *tools.ToolResult {
-		// Use cli:direct as fallback if no valid channel
-		if channel == "" || chatID == "" {
-			channel, chatID = "cli", "direct"
-		}
-		// Use ProcessHeartbeat - no session history, each heartbeat is independent
-		var response string
-		response, err = agentLoop.ProcessHeartbeat(context.Background(), prompt, channel, chatID)
-		if err != nil {
-			return tools.ErrorResult(fmt.Sprintf("Heartbeat error: %v", err))
-		}
-		if response == "HEARTBEAT_OK" {
-			return tools.SilentResult("Heartbeat OK")
-		}
-		// For heartbeat, always return silent - the subagent result will be
-		// sent to user via processSystemMessage when the async task completes
-		return tools.SilentResult(response)
-	})
-
-	// Create media store for file lifecycle management with TTL cleanup
-	mediaStore := media.NewFileMediaStoreWithCleanup(media.MediaCleanerConfig{
-		Enabled:  cfg.Tools.MediaCleanup.Enabled,
-		MaxAge:   time.Duration(cfg.Tools.MediaCleanup.MaxAge) * time.Minute,
-		Interval: time.Duration(cfg.Tools.MediaCleanup.Interval) * time.Minute,
-	})
-	mediaStore.Start()
-
-	channelManager, err := channels.NewManager(cfg, msgBus, mediaStore)
-	if err != nil {
-		mediaStore.Stop()
-		return fmt.Errorf("error creating channel manager: %w", err)
-	}
-
-	// Inject channel manager and media store into agent loop
-	agentLoop.SetChannelManager(channelManager)
-	agentLoop.SetMediaStore(mediaStore)
-
-	enabledChannels := channelManager.GetEnabledChannels()
-	if len(enabledChannels) > 0 {
-		fmt.Printf("✓ Channels enabled: %s\n", enabledChannels)
-	} else {
-		fmt.Println("⚠ Warning: No channels enabled")
-	}
-
-	fmt.Printf("✓ Gateway started on %s:%d\n", cfg.Gateway.Host, cfg.Gateway.Port)
-	fmt.Println("Press Ctrl+C to stop")
-
-	ctx, cancel := context.WithCancel(context.Background())
-	defer cancel()
-
-	if err := cronService.Start(); err != nil {
-		fmt.Printf("Error starting cron service: %v\n", err)
-	}
-	fmt.Println("✓ Cron service started")
-
-	if err := heartbeatService.Start(); err != nil {
-		fmt.Printf("Error starting heartbeat service: %v\n", err)
-	}
-	fmt.Println("✓ Heartbeat service started")
-
-	stateManager := state.NewManager(cfg.WorkspacePath())
-	deviceService := devices.NewService(devices.Config{
-		Enabled:    cfg.Devices.Enabled,
-		MonitorUSB: cfg.Devices.MonitorUSB,
-	}, stateManager)
-	deviceService.SetBus(msgBus)
-	if err := deviceService.Start(ctx); err != nil {
-		fmt.Printf("Error starting device service: %v\n", err)
-	} else if cfg.Devices.Enabled {
-		fmt.Println("✓ Device event service started")
-	}
-
-	// Setup shared HTTP server with health endpoints and webhook handlers
-	healthServer := health.NewServer(cfg.Gateway.Host, cfg.Gateway.Port)
-	addr := fmt.Sprintf("%s:%d", cfg.Gateway.Host, cfg.Gateway.Port)
-	channelManager.SetupHTTPServer(addr, healthServer)
-
-	if err := channelManager.StartAll(ctx); err != nil {
-		fmt.Printf("Error starting channels: %v\n", err)
-		return err
-	}
-
-	fmt.Printf("✓ Health endpoints available at http://%s:%d/health and /ready\n", cfg.Gateway.Host, cfg.Gateway.Port)
-
-	go agentLoop.Run(ctx)
-
-	sigChan := make(chan os.Signal, 1)
-	signal.Notify(sigChan, os.Interrupt)
-	<-sigChan
-
-	fmt.Println("\nShutting down...")
-	if cp, ok := provider.(providers.StatefulProvider); ok {
-		cp.Close()
-	}
-	cancel()
-	msgBus.Close()
-
-	// Use a fresh context with timeout for graceful shutdown,
-	// since the original ctx is already canceled.
-	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 15*time.Second)
-	defer shutdownCancel()
-
-	channelManager.StopAll(shutdownCtx)
-	deviceService.Stop()
-	heartbeatService.Stop()
-	cronService.Stop()
-	mediaStore.Stop()
-	agentLoop.Stop()
-	fmt.Println("✓ Gateway stopped")
-
-	return nil
-}
-
-func setupCronTool(
-	agentLoop *agent.AgentLoop,
-	msgBus *bus.MessageBus,
-	workspace string,
-	restrict bool,
-	execTimeout time.Duration,
-	cfg *config.Config,
-) *cron.CronService {
-	cronStorePath := filepath.Join(workspace, "cron", "jobs.json")
-
-	// Create cron service
-	cronService := cron.NewCronService(cronStorePath, nil)
-
-	// Create and register CronTool
-	cronTool, err := tools.NewCronTool(cronService, agentLoop, msgBus, workspace, restrict, execTimeout, cfg)
-	if err != nil {
-		log.Fatalf("Critical error during CronTool initialization: %v", err)
-	}
-
-	agentLoop.RegisterTool(cronTool)
-
-	// Set the onJob handler
-	cronService.SetOnJob(func(job *cron.CronJob) (string, error) {
-		result := cronTool.ExecuteJob(context.Background(), job)
-		return result, nil
-	})
-
-	return cronService
-}
diff --git a/cmd/picoclaw/internal/helpers.go b/cmd/picoclaw/internal/helpers.go
index 9655d3c08..17de88ccb 100644
--- a/cmd/picoclaw/internal/helpers.go
+++ b/cmd/picoclaw/internal/helpers.go
@@ -1,55 +1,56 @@
 package internal
 
 import (
-	"fmt"
 	"os"
 	"path/filepath"
-	"runtime"
 
+	"github.com/sipeed/picoclaw/pkg"
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
-const Logo = "🦞"
+const Logo = pkg.Logo
 
-var (
-	version   = "dev"
-	gitCommit string
-	buildTime string
-	goVersion string
-)
-
-func GetConfigPath() string {
-	if configPath := os.Getenv("PICOCLAW_CONFIG"); configPath != "" {
-		return configPath
+// GetPicoclawHome returns the picoclaw home directory.
+// Priority: $PICOCLAW_HOME > ~/.picoclaw
+func GetPicoclawHome() string {
+	if home := os.Getenv(config.EnvHome); home != "" {
+		return home
 	}
 	home, _ := os.UserHomeDir()
-	return filepath.Join(home, ".picoclaw", "config.json")
+	return filepath.Join(home, pkg.DefaultPicoClawHome)
+}
+
+func GetConfigPath() string {
+	if configPath := os.Getenv(config.EnvConfig); configPath != "" {
+		return configPath
+	}
+	return filepath.Join(GetPicoclawHome(), "config.json")
 }
 
 func LoadConfig() (*config.Config, error) {
-	return config.LoadConfig(GetConfigPath())
+	cfg, err := config.LoadConfig(GetConfigPath())
+	if err != nil {
+		return nil, err
+	}
+	logger.SetLevelFromString(cfg.Gateway.LogLevel)
+	return cfg, nil
 }
 
 // FormatVersion returns the version string with optional git commit
+// Deprecated: Use pkg/config.FormatVersion instead
 func FormatVersion() string {
-	v := version
-	if gitCommit != "" {
-		v += fmt.Sprintf(" (git: %s)", gitCommit)
-	}
-	return v
+	return config.FormatVersion()
 }
 
 // FormatBuildInfo returns build time and go version info
+// Deprecated: Use pkg/config.FormatBuildInfo instead
 func FormatBuildInfo() (string, string) {
-	build := buildTime
-	goVer := goVersion
-	if goVer == "" {
-		goVer = runtime.Version()
-	}
-	return build, goVer
+	return config.FormatBuildInfo()
 }
 
 // GetVersion returns the version string
+// Deprecated: Use pkg/config.GetVersion instead
 func GetVersion() string {
-	return version
+	return config.GetVersion()
 }
diff --git a/cmd/picoclaw/internal/helpers_test.go b/cmd/picoclaw/internal/helpers_test.go
index 47e2f8c07..953da8886 100644
--- a/cmd/picoclaw/internal/helpers_test.go
+++ b/cmd/picoclaw/internal/helpers_test.go
@@ -8,6 +8,8 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/pkg/config"
 )
 
 func TestGetConfigPath(t *testing.T) {
@@ -19,63 +21,25 @@ func TestGetConfigPath(t *testing.T) {
 	assert.Equal(t, want, got)
 }
 
-func TestFormatVersion_NoGitCommit(t *testing.T) {
-	oldVersion, oldGit := version, gitCommit
-	t.Cleanup(func() { version, gitCommit = oldVersion, oldGit })
+func TestGetConfigPath_WithPICOCLAW_HOME(t *testing.T) {
+	t.Setenv(config.EnvHome, "/custom/picoclaw")
+	t.Setenv("HOME", "/tmp/home")
 
-	version = "1.2.3"
-	gitCommit = ""
+	got := GetConfigPath()
+	want := filepath.Join("/custom/picoclaw", "config.json")
 
-	assert.Equal(t, "1.2.3", FormatVersion())
+	assert.Equal(t, want, got)
 }
 
-func TestFormatVersion_WithGitCommit(t *testing.T) {
-	oldVersion, oldGit := version, gitCommit
-	t.Cleanup(func() { version, gitCommit = oldVersion, oldGit })
+func TestGetConfigPath_WithPICOCLAW_CONFIG(t *testing.T) {
+	t.Setenv("PICOCLAW_CONFIG", "/custom/config.json")
+	t.Setenv(config.EnvHome, "/custom/picoclaw")
+	t.Setenv("HOME", "/tmp/home")
 
-	version = "1.2.3"
-	gitCommit = "abc123"
+	got := GetConfigPath()
+	want := "/custom/config.json"
 
-	assert.Equal(t, "1.2.3 (git: abc123)", FormatVersion())
-}
-
-func TestFormatBuildInfo_UsesBuildTimeAndGoVersion_WhenSet(t *testing.T) {
-	oldBuildTime, oldGoVersion := buildTime, goVersion
-	t.Cleanup(func() { buildTime, goVersion = oldBuildTime, oldGoVersion })
-
-	buildTime = "2026-02-20T00:00:00Z"
-	goVersion = "go1.23.0"
-
-	build, goVer := FormatBuildInfo()
-
-	assert.Equal(t, buildTime, build)
-	assert.Equal(t, goVersion, goVer)
-}
-
-func TestFormatBuildInfo_EmptyBuildTime_ReturnsEmptyBuild(t *testing.T) {
-	oldBuildTime, oldGoVersion := buildTime, goVersion
-	t.Cleanup(func() { buildTime, goVersion = oldBuildTime, oldGoVersion })
-
-	buildTime = ""
-	goVersion = "go1.23.0"
-
-	build, goVer := FormatBuildInfo()
-
-	assert.Empty(t, build)
-	assert.Equal(t, goVersion, goVer)
-}
-
-func TestFormatBuildInfo_EmptyGoVersion_FallsBackToRuntimeVersion(t *testing.T) {
-	oldBuildTime, oldGoVersion := buildTime, goVersion
-	t.Cleanup(func() { buildTime, goVersion = oldBuildTime, oldGoVersion })
-
-	buildTime = "x"
-	goVersion = ""
-
-	build, goVer := FormatBuildInfo()
-
-	assert.Equal(t, "x", build)
-	assert.Equal(t, runtime.Version(), goVer)
+	assert.Equal(t, want, got)
 }
 
 func TestGetConfigPath_Windows(t *testing.T) {
@@ -91,17 +55,3 @@ func TestGetConfigPath_Windows(t *testing.T) {
 
 	require.True(t, strings.EqualFold(got, want), "GetConfigPath() = %q, want %q", got, want)
 }
-
-func TestGetVersion(t *testing.T) {
-	assert.Equal(t, "dev", GetVersion())
-}
-
-func TestGetConfigPath_WithEnv(t *testing.T) {
-	t.Setenv("PICOCLAW_CONFIG", "/tmp/custom/config.json")
-	t.Setenv("HOME", "/tmp/home") // Also set home to ensure env is preferred
-
-	got := GetConfigPath()
-	want := "/tmp/custom/config.json"
-
-	assert.Equal(t, want, got)
-}
diff --git a/cmd/picoclaw/internal/model/command.go b/cmd/picoclaw/internal/model/command.go
new file mode 100644
index 000000000..314259d0f
--- /dev/null
+++ b/cmd/picoclaw/internal/model/command.go
@@ -0,0 +1,128 @@
+package model
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// LocalModel is a special model name that indicates that the model is local and with or without api_key.
+const LocalModel = "local-model"
+
+func NewModelCommand() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "model [model_name]",
+		Short: "Show or change the default model",
+		Long: `Show or change the default model configuration.
+
+If no argument is provided, shows the current default model.
+If a model name is provided, sets it as the default model.
+
+Examples:
+  picoclaw model                    # Show current default model
+  picoclaw model gpt-5.2           # Set gpt-5.2 as default
+  picoclaw model claude-sonnet-4.6 # Set claude-sonnet-4.6 as default
+  picoclaw model local-model       # Set local VLLM server as default
+
+Note: 'local-model' is a special value for using a local VLLM server
+(running at localhost:8000 by default) which does not require an API key.`,
+		Args: cobra.MaximumNArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			configPath := internal.GetConfigPath()
+
+			// Load current config
+			cfg, err := config.LoadConfig(configPath)
+			if err != nil {
+				return fmt.Errorf("failed to load config: %w", err)
+			}
+
+			if len(args) == 0 {
+				// Show current default model
+				showCurrentModel(cfg)
+				return nil
+			}
+
+			// Set new default model
+			modelName := args[0]
+			return setDefaultModel(configPath, cfg, modelName)
+		},
+	}
+
+	return cmd
+}
+
+func showCurrentModel(cfg *config.Config) {
+	defaultModel := cfg.Agents.Defaults.ModelName
+
+	if defaultModel == "" {
+		fmt.Println("No default model is currently set.")
+		fmt.Println("\nAvailable models in your config:")
+		listAvailableModels(cfg)
+	} else {
+		fmt.Printf("Current default model: %s\n", defaultModel)
+		fmt.Println("\nAvailable models in your config:")
+		listAvailableModels(cfg)
+	}
+}
+
+func listAvailableModels(cfg *config.Config) {
+	if len(cfg.ModelList) == 0 {
+		fmt.Println("  No models configured in model_list")
+		return
+	}
+
+	defaultModel := cfg.Agents.Defaults.ModelName
+
+	for _, model := range cfg.ModelList {
+		marker := "  "
+		if model.ModelName == defaultModel {
+			marker = "> "
+		}
+		if model.APIKey() == "" {
+			continue
+		}
+		fmt.Printf("%s- %s (%s)\n", marker, model.ModelName, model.Model)
+	}
+}
+
+func setDefaultModel(configPath string, cfg *config.Config, modelName string) error {
+	// Validate that the model exists in model_list
+	modelFound := false
+	for _, model := range cfg.ModelList {
+		if model.APIKey() != "" && model.ModelName == modelName {
+			modelFound = true
+			break
+		}
+	}
+
+	if !modelFound && modelName != LocalModel {
+		return fmt.Errorf("cannot found model '%s' in config", modelName)
+	}
+
+	// Update the default model
+	// Clear old model field and set new model_name
+	oldModel := cfg.Agents.Defaults.ModelName
+
+	cfg.Agents.Defaults.ModelName = modelName
+
+	// Save config back to file
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		return fmt.Errorf("failed to save config: %w", err)
+	}
+
+	fmt.Printf("✓ Default model changed from '%s' to '%s'\n",
+		formatModelName(oldModel), modelName)
+	fmt.Println("\nThe new default model will be used for all agent interactions.")
+
+	return nil
+}
+
+func formatModelName(name string) string {
+	if name == "" {
+		return "(none)"
+	}
+	return name
+}
diff --git a/cmd/picoclaw/internal/model/command_test.go b/cmd/picoclaw/internal/model/command_test.go
new file mode 100644
index 000000000..6cbbf0b55
--- /dev/null
+++ b/cmd/picoclaw/internal/model/command_test.go
@@ -0,0 +1,390 @@
+package model
+
+import (
+	"bytes"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+var configPath = ""
+
+func initTest(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath = filepath.Join(tmpDir, "config.json")
+	_ = os.Setenv("PICOCLAW_CONFIG", configPath)
+}
+
+// captureStdout captures stdout during the execution of fn and returns the captured output
+func captureStdout(fn func()) string {
+	oldStdout := os.Stdout
+	r, w, _ := os.Pipe()
+	os.Stdout = w
+
+	fn()
+
+	w.Close()
+	os.Stdout = oldStdout
+
+	var buf bytes.Buffer
+	io.Copy(&buf, r)
+	return buf.String()
+}
+
+func TestNewModelCommand(t *testing.T) {
+	cmd := NewModelCommand()
+
+	require.NotNil(t, cmd)
+
+	assert.Equal(t, "model [model_name]", cmd.Use)
+	assert.Equal(t, "Show or change the default model", cmd.Short)
+
+	assert.Len(t, cmd.Aliases, 0)
+
+	assert.False(t, cmd.HasFlags())
+
+	assert.Nil(t, cmd.Run)
+	assert.NotNil(t, cmd.RunE)
+
+	assert.Nil(t, cmd.PersistentPreRunE)
+	assert.Nil(t, cmd.PersistentPreRun)
+	assert.Nil(t, cmd.PersistentPostRun)
+}
+
+func TestShowCurrentModel_WithDefaultModel(t *testing.T) {
+	cfg := (&config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "gpt-4",
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{ModelName: "gpt-4", Model: "openai/gpt-4"},
+			{ModelName: "claude-3", Model: "anthropic/claude-3"},
+		},
+	}).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+		"gpt-4": {
+			APIKeys: []string{"test"},
+		},
+		"claude-3": {
+			APIKeys: []string{"test"},
+		},
+	}})
+
+	output := captureStdout(func() {
+		showCurrentModel(cfg)
+	})
+
+	assert.Contains(t, output, "Current default model: gpt-4")
+	assert.Contains(t, output, "Available models in your config:")
+	assert.Contains(t, output, "gpt-4")
+	assert.Contains(t, output, "claude-3")
+}
+
+func TestShowCurrentModel_NoDefaultModel(t *testing.T) {
+	cfg := (&config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "",
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{ModelName: "gpt-4", Model: "openai/gpt-4"},
+		},
+	}).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+		"gpt-4": {
+			APIKeys: []string{"test"},
+		},
+	}})
+
+	output := captureStdout(func() {
+		showCurrentModel(cfg)
+	})
+
+	assert.Contains(t, output, "No default model is currently set.")
+	assert.Contains(t, output, "Available models in your config:")
+}
+
+func TestListAvailableModels_Empty(t *testing.T) {
+	cfg := &config.Config{
+		ModelList: []*config.ModelConfig{},
+	}
+
+	output := captureStdout(func() {
+		listAvailableModels(cfg)
+	})
+
+	assert.Contains(t, output, "No models configured in model_list")
+}
+
+func TestListAvailableModels_WithModels(t *testing.T) {
+	cfg := (&config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "gpt-4",
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{ModelName: "gpt-4", Model: "openai/gpt-4"},
+			{ModelName: "claude-3", Model: "anthropic/claude-3"},
+			{ModelName: "no-key-model", Model: "openai/test"},
+		},
+	}).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+		"gpt-4": {
+			APIKeys: []string{"test"},
+		},
+		"claude-3": {
+			APIKeys: []string{"test"},
+		},
+	}})
+
+	output := captureStdout(func() {
+		listAvailableModels(cfg)
+	})
+
+	assert.NotEmpty(t, output)
+	assert.Contains(t, output, "> - gpt-4 (openai/gpt-4)")
+	assert.Contains(t, output, "claude-3 (anthropic/claude-3)")
+	assert.NotContains(t, output, "no-key-model")
+}
+
+func TestSetDefaultModel_ValidModel(t *testing.T) {
+	initTest(t)
+
+	cfg := (&config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "old-model",
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{ModelName: "new-model", Model: "openai/new-model"},
+			{ModelName: "old-model", Model: "openai/old-model"},
+		},
+	}).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+		"new-model": {
+			APIKeys: []string{"test"},
+		},
+		"old-model": {
+			APIKeys: []string{"test"},
+		},
+	}})
+
+	output := captureStdout(func() {
+		err := setDefaultModel(configPath, cfg, "new-model")
+		assert.NoError(t, err)
+	})
+
+	assert.Contains(t, output, "Default model changed from 'old-model' to 'new-model'")
+
+	// Verify config was updated
+	updatedCfg, err := config.LoadConfig(configPath)
+	require.NoError(t, err)
+	assert.Equal(t, "new-model", updatedCfg.Agents.Defaults.ModelName)
+}
+
+func TestSetDefaultModel_InvalidModel(t *testing.T) {
+	initTest(t)
+
+	cfg := (&config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "existing-model",
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{ModelName: "existing-model", Model: "openai/existing"},
+		},
+	}).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+		"existing-model": {
+			APIKeys: []string{"test"},
+		},
+	}})
+
+	assert.Error(t, setDefaultModel(configPath, cfg, "nonexistent-model"))
+}
+
+func TestSetDefaultModel_ModelWithoutAPIKey(t *testing.T) {
+	initTest(t)
+
+	cfg := (&config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "existing-model",
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{ModelName: "existing-model", Model: "openai/existing"},
+			{ModelName: "no-key-model", Model: "openai/nokey"},
+		},
+	}).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+		"existing-model": {
+			APIKeys: []string{"test"},
+		},
+		"no-key-model": {
+			APIKeys: []string{""},
+		},
+	}})
+
+	assert.Error(t, setDefaultModel(configPath, cfg, "no-key-model"))
+}
+
+func TestSetDefaultModel_SaveConfigError(t *testing.T) {
+	// Use an invalid path to trigger save error
+	invalidPath := "/nonexistent/directory/config.json"
+
+	cfg := (&config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "old-model",
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{ModelName: "new-model", Model: "openai/new-model"},
+		},
+	}).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+		"new-model": {
+			APIKeys: []string{"test"},
+		},
+	}})
+
+	err := setDefaultModel(invalidPath, cfg, "new-model")
+
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "failed to save config")
+}
+
+func TestFormatModelName(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{"empty string", "", "(none)"},
+		{"simple model", "gpt-4", "gpt-4"},
+		{"model with version", "claude-sonnet-4.6", "claude-sonnet-4.6"},
+		{"model with spaces", "my model", "my model"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := formatModelName(tt.input)
+			assert.Equal(t, tt.expected, result)
+		})
+	}
+}
+
+func TestModelCommandExecution_Show(t *testing.T) {
+	initTest(t)
+
+	// Create a test config
+	cfg := (&config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "test-model",
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{ModelName: "test-model", Model: "openai/test"},
+		},
+	}).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+		"test-model": {
+			APIKeys: []string{"test"},
+		},
+	}})
+
+	err := config.SaveConfig(configPath, cfg)
+	require.NoError(t, err)
+
+	cmd := NewModelCommand()
+
+	output := captureStdout(func() {
+		err = cmd.RunE(cmd, []string{})
+		assert.NoError(t, err)
+	})
+
+	assert.Contains(t, output, "Current default model: test-model")
+}
+
+func TestModelCommandExecution_Set(t *testing.T) {
+	initTest(t)
+
+	sec := &config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+		"old-model": {
+			APIKeys: []string{"test"},
+		},
+		"new-model": {
+			APIKeys: []string{"test"},
+		},
+	}}
+	cfg := (&config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "old-model",
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{ModelName: "old-model", Model: "openai/old"},
+			{ModelName: "new-model", Model: "openai/new"},
+		},
+	}).WithSecurity(sec)
+
+	err := config.SaveConfig(configPath, cfg)
+	require.NoError(t, err)
+
+	cmd := NewModelCommand()
+
+	output := captureStdout(func() {
+		err = cmd.RunE(cmd, []string{"new-model"})
+		assert.NoError(t, err)
+	})
+
+	assert.Contains(t, output, "Default model changed from 'old-model' to 'new-model'")
+}
+
+func TestModelCommandExecution_TooManyArgs(t *testing.T) {
+	cmd := NewModelCommand()
+
+	err := cmd.RunE(cmd, []string{"model1", "model2"})
+
+	assert.Error(t, err)
+}
+
+func TestListAvailableModels_MarkerLogic(t *testing.T) {
+	cfg := (&config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "middle-model",
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{ModelName: "first-model", Model: "openai/first"},
+			{ModelName: "middle-model", Model: "openai/middle"},
+			{ModelName: "last-model", Model: "openai/last"},
+		},
+	}).WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+		"first-model": {
+			APIKeys: []string{"test"},
+		},
+		"middle-model": {
+			APIKeys: []string{"test"},
+		},
+		"last-model": {
+			APIKeys: []string{"test"},
+		},
+	}})
+
+	output := captureStdout(func() {
+		listAvailableModels(cfg)
+	})
+
+	assert.Contains(t, output, "  - first-model (openai/first)")
+	assert.Contains(t, output, "> - middle-model (openai/middle)")
+	assert.Contains(t, output, "  - last-model (openai/last)")
+}
diff --git a/cmd/picoclaw/internal/onboard/command.go b/cmd/picoclaw/internal/onboard/command.go
index ec1012959..4be19b2a5 100644
--- a/cmd/picoclaw/internal/onboard/command.go
+++ b/cmd/picoclaw/internal/onboard/command.go
@@ -11,14 +11,24 @@ import (
 var embeddedFiles embed.FS
 
 func NewOnboardCommand() *cobra.Command {
+	var encrypt bool
+
 	cmd := &cobra.Command{
 		Use:     "onboard",
 		Aliases: []string{"o"},
 		Short:   "Initialize picoclaw configuration and workspace",
+		// Run without subcommands → original onboard flow
 		Run: func(cmd *cobra.Command, args []string) {
-			onboard()
+			if len(args) == 0 {
+				onboard(encrypt)
+			} else {
+				_ = cmd.Help()
+			}
 		},
 	}
 
+	cmd.Flags().BoolVar(&encrypt, "enc", false,
+		"Enable credential encryption (generates SSH key and prompts for passphrase)")
+
 	return cmd
 }
diff --git a/cmd/picoclaw/internal/onboard/command_test.go b/cmd/picoclaw/internal/onboard/command_test.go
index bc799a079..56936190b 100644
--- a/cmd/picoclaw/internal/onboard/command_test.go
+++ b/cmd/picoclaw/internal/onboard/command_test.go
@@ -24,6 +24,9 @@ func TestNewOnboardCommand(t *testing.T) {
 	assert.Nil(t, cmd.PersistentPreRun)
 	assert.Nil(t, cmd.PersistentPostRun)
 
-	assert.False(t, cmd.HasFlags())
+	assert.True(t, cmd.HasFlags())
+	encFlag := cmd.Flags().Lookup("enc")
+	require.NotNil(t, encFlag, "expected --enc flag to be registered")
+	assert.Equal(t, "false", encFlag.DefValue, "--enc should default to false")
 	assert.False(t, cmd.HasSubCommands())
 }
diff --git a/cmd/picoclaw/internal/onboard/helpers.go b/cmd/picoclaw/internal/onboard/helpers.go
index 4db8bdc8b..6f1d4bdd7 100644
--- a/cmd/picoclaw/internal/onboard/helpers.go
+++ b/cmd/picoclaw/internal/onboard/helpers.go
@@ -6,25 +6,71 @@ import (
 	"os"
 	"path/filepath"
 
+	"golang.org/x/term"
+
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/credential"
 )
 
-func onboard() {
+func onboard(encrypt bool) {
 	configPath := internal.GetConfigPath()
 
+	configExists := false
 	if _, err := os.Stat(configPath); err == nil {
-		fmt.Printf("Config already exists at %s\n", configPath)
-		fmt.Print("Overwrite? (y/n): ")
-		var response string
-		fmt.Scanln(&response)
-		if response != "y" {
-			fmt.Println("Aborted.")
-			return
+		configExists = true
+		if encrypt {
+			// Only ask for confirmation when *both* config and SSH key already exist,
+			// indicating a full re-onboard that would reset the config to defaults.
+			sshKeyPath, _ := credential.DefaultSSHKeyPath()
+			if _, err := os.Stat(sshKeyPath); err == nil {
+				// Both exist — confirm a full reset.
+				fmt.Printf("Config already exists at %s\n", configPath)
+				fmt.Print("Overwrite config with defaults? (y/n): ")
+				var response string
+				fmt.Scanln(&response)
+				if response != "y" {
+					fmt.Println("Aborted.")
+					return
+				}
+				configExists = false // user agreed to reset; treat as fresh
+			}
+			// Config exists but SSH key is missing — keep existing config, only add SSH key.
 		}
 	}
 
-	cfg := config.DefaultConfig()
+	var err error
+	if encrypt {
+		fmt.Println("\nSet up credential encryption")
+		fmt.Println("-----------------------------")
+		passphrase, pErr := promptPassphrase()
+		if pErr != nil {
+			fmt.Printf("Error: %v\n", pErr)
+			os.Exit(1)
+		}
+		// Expose the passphrase to credential.PassphraseProvider (which calls
+		// os.Getenv by default) so that SaveConfig can encrypt api_keys.
+		// This process is a one-shot CLI tool; the env var is never exposed outside
+		// the current process and disappears when it exits.
+		os.Setenv(credential.PassphraseEnvVar, passphrase)
+
+		if err = setupSSHKey(); err != nil {
+			fmt.Printf("Error generating SSH key: %v\n", err)
+			os.Exit(1)
+		}
+	}
+
+	var cfg *config.Config
+	if configExists {
+		// Preserve the existing config; SaveConfig will re-encrypt api_keys with the new passphrase.
+		cfg, err = config.LoadConfig(configPath)
+		if err != nil {
+			fmt.Printf("Error loading existing config: %v\n", err)
+			os.Exit(1)
+		}
+	} else {
+		cfg = config.DefaultConfig()
+	}
 	if err := config.SaveConfig(configPath, cfg); err != nil {
 		fmt.Printf("Error saving config: %v\n", err)
 		os.Exit(1)
@@ -33,9 +79,17 @@ func onboard() {
 	workspace := cfg.WorkspacePath()
 	createWorkspaceTemplates(workspace)
 
-	fmt.Printf("%s picoclaw is ready!\n", internal.Logo)
+	fmt.Printf("\n%s picoclaw is ready!\n", internal.Logo)
 	fmt.Println("\nNext steps:")
-	fmt.Println("  1. Add your API key to", configPath)
+	if encrypt {
+		fmt.Println("  1. Set your encryption passphrase before starting picoclaw:")
+		fmt.Println("       export PICOCLAW_KEY_PASSPHRASE=<your-passphrase>   # Linux/macOS")
+		fmt.Println("       set PICOCLAW_KEY_PASSPHRASE=<your-passphrase>      # Windows cmd")
+		fmt.Println("")
+		fmt.Println("  2. Add your API key to", configPath)
+	} else {
+		fmt.Println("  1. Add your API key to", configPath)
+	}
 	fmt.Println("")
 	fmt.Println("     Recommended:")
 	fmt.Println("     - OpenRouter: https://openrouter.ai/keys (access 100+ models)")
@@ -43,7 +97,62 @@ func onboard() {
 	fmt.Println("")
 	fmt.Println("     See README.md for 17+ supported providers.")
 	fmt.Println("")
-	fmt.Println("  2. Chat: picoclaw agent -m \"Hello!\"")
+	fmt.Println("  3. Chat: picoclaw agent -m \"Hello!\"")
+}
+
+// promptPassphrase reads the encryption passphrase twice from the terminal
+// (with echo disabled) and returns it. Returns an error if the passphrase is
+// empty or if the two inputs do not match.
+func promptPassphrase() (string, error) {
+	fmt.Print("Enter passphrase for credential encryption: ")
+	p1, err := term.ReadPassword(int(os.Stdin.Fd()))
+	fmt.Println()
+	if err != nil {
+		return "", fmt.Errorf("reading passphrase: %w", err)
+	}
+	if len(p1) == 0 {
+		return "", fmt.Errorf("passphrase must not be empty")
+	}
+
+	fmt.Print("Confirm passphrase: ")
+	p2, err := term.ReadPassword(int(os.Stdin.Fd()))
+	fmt.Println()
+	if err != nil {
+		return "", fmt.Errorf("reading passphrase confirmation: %w", err)
+	}
+
+	if string(p1) != string(p2) {
+		return "", fmt.Errorf("passphrases do not match")
+	}
+	return string(p1), nil
+}
+
+// setupSSHKey generates the picoclaw-specific SSH key at ~/.ssh/picoclaw_ed25519.key.
+// If the key already exists the user is warned and asked to confirm overwrite.
+// Answering anything other than "y" keeps the existing key (not an error).
+func setupSSHKey() error {
+	keyPath, err := credential.DefaultSSHKeyPath()
+	if err != nil {
+		return fmt.Errorf("cannot determine SSH key path: %w", err)
+	}
+
+	if _, err := os.Stat(keyPath); err == nil {
+		fmt.Printf("\n⚠️  WARNING: %s already exists.\n", keyPath)
+		fmt.Println("    Overwriting will invalidate any credentials previously encrypted with this key.")
+		fmt.Print("    Overwrite? (y/n): ")
+		var response string
+		fmt.Scanln(&response)
+		if response != "y" {
+			fmt.Println("Keeping existing SSH key.")
+			return nil
+		}
+	}
+
+	if err := credential.GenerateSSHKey(keyPath); err != nil {
+		return err
+	}
+	fmt.Printf("SSH key generated: %s\n", keyPath)
+	return nil
 }
 
 func createWorkspaceTemplates(workspace string) {
diff --git a/cmd/picoclaw/internal/onboard/helpers_test.go b/cmd/picoclaw/internal/onboard/helpers_test.go
index f3e0c92e0..23fc97c5a 100644
--- a/cmd/picoclaw/internal/onboard/helpers_test.go
+++ b/cmd/picoclaw/internal/onboard/helpers_test.go
@@ -6,20 +6,32 @@ import (
 	"testing"
 )
 
-func TestCopyEmbeddedToTargetUsesAgentsMarkdown(t *testing.T) {
+func TestCopyEmbeddedToTargetUsesStructuredAgentFiles(t *testing.T) {
 	targetDir := t.TempDir()
 
 	if err := copyEmbeddedToTarget(targetDir); err != nil {
 		t.Fatalf("copyEmbeddedToTarget() error = %v", err)
 	}
 
-	agentsPath := filepath.Join(targetDir, "AGENTS.md")
-	if _, err := os.Stat(agentsPath); err != nil {
-		t.Fatalf("expected %s to exist: %v", agentsPath, err)
+	agentPath := filepath.Join(targetDir, "AGENT.md")
+	if _, err := os.Stat(agentPath); err != nil {
+		t.Fatalf("expected %s to exist: %v", agentPath, err)
 	}
 
-	legacyPath := filepath.Join(targetDir, "AGENT.md")
-	if _, err := os.Stat(legacyPath); !os.IsNotExist(err) {
-		t.Fatalf("expected legacy file %s to be absent, got err=%v", legacyPath, err)
+	soulPath := filepath.Join(targetDir, "SOUL.md")
+	if _, err := os.Stat(soulPath); err != nil {
+		t.Fatalf("expected %s to exist: %v", soulPath, err)
+	}
+
+	userPath := filepath.Join(targetDir, "USER.md")
+	if _, err := os.Stat(userPath); err != nil {
+		t.Fatalf("expected %s to exist: %v", userPath, err)
+	}
+
+	for _, legacyName := range []string{"AGENTS.md", "IDENTITY.md"} {
+		legacyPath := filepath.Join(targetDir, legacyName)
+		if _, err := os.Stat(legacyPath); !os.IsNotExist(err) {
+			t.Fatalf("expected legacy file %s to be absent, got err=%v", legacyPath, err)
+		}
 	}
 }
diff --git a/cmd/picoclaw/internal/skills/command.go b/cmd/picoclaw/internal/skills/command.go
index 65eb127b9..4f64ef3f9 100644
--- a/cmd/picoclaw/internal/skills/command.go
+++ b/cmd/picoclaw/internal/skills/command.go
@@ -29,7 +29,15 @@ func NewSkillsCommand() *cobra.Command {
 			}
 
 			d.workspace = cfg.WorkspacePath()
-			d.installer = skills.NewSkillInstaller(d.workspace)
+			installer, err := skills.NewSkillInstaller(
+				d.workspace,
+				cfg.Tools.Skills.Github.Token(),
+				cfg.Tools.Skills.Github.Proxy,
+			)
+			if err != nil {
+				return fmt.Errorf("error creating skills installer: %w", err)
+			}
+			d.installer = installer
 
 			// get global config directory and builtin skills directory
 			globalDir := filepath.Dir(internal.GetConfigPath())
diff --git a/cmd/picoclaw/internal/skills/helpers.go b/cmd/picoclaw/internal/skills/helpers.go
index a59a2013a..a246f7da5 100644
--- a/cmd/picoclaw/internal/skills/helpers.go
+++ b/cmd/picoclaw/internal/skills/helpers.go
@@ -64,9 +64,20 @@ func skillsInstallFromRegistry(cfg *config.Config, registryName, slug string) er
 
 	fmt.Printf("Installing skill '%s' from %s registry...\n", slug, registryName)
 
+	clawHubConfig := cfg.Tools.Skills.Registries.ClawHub
 	registryMgr := skills.NewRegistryManagerFromConfig(skills.RegistryConfig{
 		MaxConcurrentSearches: cfg.Tools.Skills.MaxConcurrentSearches,
-		ClawHub:               skills.ClawHubConfig(cfg.Tools.Skills.Registries.ClawHub),
+		ClawHub: skills.ClawHubConfig{
+			Enabled:         clawHubConfig.Enabled,
+			BaseURL:         clawHubConfig.BaseURL,
+			AuthToken:       clawHubConfig.AuthToken(),
+			SearchPath:      clawHubConfig.SearchPath,
+			SkillsPath:      clawHubConfig.SkillsPath,
+			DownloadPath:    clawHubConfig.DownloadPath,
+			Timeout:         clawHubConfig.Timeout,
+			MaxZipSize:      clawHubConfig.MaxZipSize,
+			MaxResponseSize: clawHubConfig.MaxResponseSize,
+		},
 	})
 
 	registry := registryMgr.GetRegistry(registryName)
@@ -226,9 +237,20 @@ func skillsSearchCmd(query string) {
 		return
 	}
 
+	clawHubConfig := cfg.Tools.Skills.Registries.ClawHub
 	registryMgr := skills.NewRegistryManagerFromConfig(skills.RegistryConfig{
 		MaxConcurrentSearches: cfg.Tools.Skills.MaxConcurrentSearches,
-		ClawHub:               skills.ClawHubConfig(cfg.Tools.Skills.Registries.ClawHub),
+		ClawHub: skills.ClawHubConfig{
+			Enabled:         clawHubConfig.Enabled,
+			BaseURL:         clawHubConfig.BaseURL,
+			AuthToken:       clawHubConfig.AuthToken(),
+			SearchPath:      clawHubConfig.SearchPath,
+			SkillsPath:      clawHubConfig.SkillsPath,
+			DownloadPath:    clawHubConfig.DownloadPath,
+			Timeout:         clawHubConfig.Timeout,
+			MaxZipSize:      clawHubConfig.MaxZipSize,
+			MaxResponseSize: clawHubConfig.MaxResponseSize,
+		},
 	})
 
 	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
diff --git a/cmd/picoclaw/internal/skills/install.go b/cmd/picoclaw/internal/skills/install.go
index a30f68632..78bc421db 100644
--- a/cmd/picoclaw/internal/skills/install.go
+++ b/cmd/picoclaw/internal/skills/install.go
@@ -21,8 +21,8 @@ picoclaw skills install --registry clawhub github
 `,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if registry != "" {
-				if len(args) != 2 {
-					return fmt.Errorf("when --registry is set, exactly 2 arguments are required: <name> <slug>")
+				if len(args) != 1 {
+					return fmt.Errorf("when --registry is set, exactly 1 argument is required: <slug>")
 				}
 				return nil
 			}
@@ -45,7 +45,7 @@ picoclaw skills install --registry clawhub github
 					return err
 				}
 
-				return skillsInstallFromRegistry(cfg, args[0], args[1])
+				return skillsInstallFromRegistry(cfg, registry, args[0])
 			}
 
 			return skillsInstallCmd(installer, args[0])
diff --git a/cmd/picoclaw/internal/skills/install_test.go b/cmd/picoclaw/internal/skills/install_test.go
index 97787a986..6b362822d 100644
--- a/cmd/picoclaw/internal/skills/install_test.go
+++ b/cmd/picoclaw/internal/skills/install_test.go
@@ -26,3 +26,72 @@ func TestNewInstallSubcommand(t *testing.T) {
 
 	assert.Len(t, cmd.Aliases, 0)
 }
+
+func TestInstallCommandArgs(t *testing.T) {
+	tests := []struct {
+		name        string
+		args        []string
+		registry    string
+		expectError bool
+		errorMsg    string
+	}{
+		{
+			name:        "no registry, one arg",
+			args:        []string{"sipeed/picoclaw-skills/weather"},
+			registry:    "",
+			expectError: false,
+		},
+		{
+			name:        "no registry, no args",
+			args:        []string{},
+			registry:    "",
+			expectError: true,
+			errorMsg:    "exactly 1 argument is required: <github>",
+		},
+		{
+			name:        "no registry, too many args",
+			args:        []string{"arg1", "arg2"},
+			registry:    "",
+			expectError: true,
+			errorMsg:    "exactly 1 argument is required: <github>",
+		},
+		{
+			name:        "with registry, one arg",
+			args:        []string{"weather-skill"},
+			registry:    "clawhub",
+			expectError: false,
+		},
+		{
+			name:        "with registry, no args",
+			args:        []string{},
+			registry:    "clawhub",
+			expectError: true,
+			errorMsg:    "when --registry is set, exactly 1 argument is required: <slug>",
+		},
+		{
+			name:        "with registry, too many args",
+			args:        []string{"arg1", "arg2"},
+			registry:    "clawhub",
+			expectError: true,
+			errorMsg:    "when --registry is set, exactly 1 argument is required: <slug>",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := newInstallCommand(nil)
+
+			if tt.registry != "" {
+				require.NoError(t, cmd.Flags().Set("registry", tt.registry))
+			}
+
+			err := cmd.Args(cmd, tt.args)
+			if tt.expectError {
+				require.Error(t, err)
+				assert.Equal(t, tt.errorMsg, err.Error())
+			} else {
+				require.NoError(t, err)
+			}
+		})
+	}
+}
diff --git a/cmd/picoclaw/internal/status/helpers.go b/cmd/picoclaw/internal/status/helpers.go
index ab28f4885..43c5786a8 100644
--- a/cmd/picoclaw/internal/status/helpers.go
+++ b/cmd/picoclaw/internal/status/helpers.go
@@ -6,6 +6,7 @@ import (
 
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
 	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
 )
 
 func statusCmd() {
@@ -18,8 +19,8 @@ func statusCmd() {
 	configPath := internal.GetConfigPath()
 
 	fmt.Printf("%s picoclaw Status\n", internal.Logo)
-	fmt.Printf("Version: %s\n", internal.FormatVersion())
-	build, _ := internal.FormatBuildInfo()
+	fmt.Printf("Version: %s\n", config.FormatVersion())
+	build, _ := config.FormatBuildInfo()
 	if build != "" {
 		fmt.Printf("Build: %s\n", build)
 	}
@@ -41,48 +42,6 @@ func statusCmd() {
 	if _, err := os.Stat(configPath); err == nil {
 		fmt.Printf("Model: %s\n", cfg.Agents.Defaults.GetModelName())
 
-		hasOpenRouter := cfg.Providers.OpenRouter.APIKey != ""
-		hasAnthropic := cfg.Providers.Anthropic.APIKey != ""
-		hasOpenAI := cfg.Providers.OpenAI.APIKey != ""
-		hasGemini := cfg.Providers.Gemini.APIKey != ""
-		hasZhipu := cfg.Providers.Zhipu.APIKey != ""
-		hasQwen := cfg.Providers.Qwen.APIKey != ""
-		hasGroq := cfg.Providers.Groq.APIKey != ""
-		hasVLLM := cfg.Providers.VLLM.APIBase != ""
-		hasMoonshot := cfg.Providers.Moonshot.APIKey != ""
-		hasDeepSeek := cfg.Providers.DeepSeek.APIKey != ""
-		hasVolcEngine := cfg.Providers.VolcEngine.APIKey != ""
-		hasNvidia := cfg.Providers.Nvidia.APIKey != ""
-		hasOllama := cfg.Providers.Ollama.APIBase != ""
-
-		status := func(enabled bool) string {
-			if enabled {
-				return "✓"
-			}
-			return "not set"
-		}
-		fmt.Println("OpenRouter API:", status(hasOpenRouter))
-		fmt.Println("Anthropic API:", status(hasAnthropic))
-		fmt.Println("OpenAI API:", status(hasOpenAI))
-		fmt.Println("Gemini API:", status(hasGemini))
-		fmt.Println("Zhipu API:", status(hasZhipu))
-		fmt.Println("Qwen API:", status(hasQwen))
-		fmt.Println("Groq API:", status(hasGroq))
-		fmt.Println("Moonshot API:", status(hasMoonshot))
-		fmt.Println("DeepSeek API:", status(hasDeepSeek))
-		fmt.Println("VolcEngine API:", status(hasVolcEngine))
-		fmt.Println("Nvidia API:", status(hasNvidia))
-		if hasVLLM {
-			fmt.Printf("vLLM/Local: ✓ %s\n", cfg.Providers.VLLM.APIBase)
-		} else {
-			fmt.Println("vLLM/Local: not set")
-		}
-		if hasOllama {
-			fmt.Printf("Ollama: ✓ %s\n", cfg.Providers.Ollama.APIBase)
-		} else {
-			fmt.Println("Ollama: not set")
-		}
-
 		store, _ := auth.LoadStore()
 		if store != nil && len(store.Credentials) > 0 {
 			fmt.Println("\nOAuth/Token Auth:")
diff --git a/cmd/picoclaw/internal/version/command.go b/cmd/picoclaw/internal/version/command.go
index 1cf686671..71c7dd2f8 100644
--- a/cmd/picoclaw/internal/version/command.go
+++ b/cmd/picoclaw/internal/version/command.go
@@ -6,6 +6,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/config"
 )
 
 func NewVersionCommand() *cobra.Command {
@@ -22,8 +23,8 @@ func NewVersionCommand() *cobra.Command {
 }
 
 func printVersion() {
-	fmt.Printf("%s picoclaw %s\n", internal.Logo, internal.FormatVersion())
-	build, goVer := internal.FormatBuildInfo()
+	fmt.Printf("%s picoclaw %s\n", internal.Logo, config.FormatVersion())
+	build, goVer := config.FormatBuildInfo()
 	if build != "" {
 		fmt.Printf("  Build: %s\n", build)
 	}
diff --git a/cmd/picoclaw/main.go b/cmd/picoclaw/main.go
index 6db69c990..bf9c0389f 100644
--- a/cmd/picoclaw/main.go
+++ b/cmd/picoclaw/main.go
@@ -18,19 +18,21 @@ import (
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/cron"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/gateway"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/migrate"
+	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/model"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/onboard"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/skills"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/status"
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal/version"
+	"github.com/sipeed/picoclaw/pkg/config"
 )
 
 func NewPicoclawCommand() *cobra.Command {
-	short := fmt.Sprintf("%s picoclaw - Personal AI Assistant v%s\n\n", internal.Logo, internal.GetVersion())
+	short := fmt.Sprintf("%s picoclaw - Personal AI Assistant v%s\n\n", internal.Logo, config.GetVersion())
 
 	cmd := &cobra.Command{
 		Use:     "picoclaw",
 		Short:   short,
-		Example: "picoclaw list",
+		Example: "picoclaw version",
 	}
 
 	cmd.AddCommand(
@@ -42,13 +44,28 @@ func NewPicoclawCommand() *cobra.Command {
 		cron.NewCronCommand(),
 		migrate.NewMigrateCommand(),
 		skills.NewSkillsCommand(),
+		model.NewModelCommand(),
 		version.NewVersionCommand(),
 	)
 
 	return cmd
 }
 
+const (
+	colorBlue = "\033[1;38;2;62;93;185m"
+	colorRed  = "\033[1;38;2;213;70;70m"
+	banner    = "\r\n" +
+		colorBlue + "██████╗ ██╗ ██████╗ ██████╗ " + colorRed + " ██████╗██╗      █████╗ ██╗    ██╗\n" +
+		colorBlue + "██╔══██╗██║██╔════╝██╔═══██╗" + colorRed + "██╔════╝██║     ██╔══██╗██║    ██║\n" +
+		colorBlue + "██████╔╝██║██║     ██║   ██║" + colorRed + "██║     ██║     ███████║██║ █╗ ██║\n" +
+		colorBlue + "██╔═══╝ ██║██║     ██║   ██║" + colorRed + "██║     ██║     ██╔══██║██║███╗██║\n" +
+		colorBlue + "██║     ██║╚██████╗╚██████╔╝" + colorRed + "╚██████╗███████╗██║  ██║╚███╔███╔╝\n" +
+		colorBlue + "╚═╝     ╚═╝ ╚═════╝ ╚═════╝ " + colorRed + " ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝\n " +
+		"\033[0m\r\n"
+)
+
 func main() {
+	fmt.Printf("%s", banner)
 	cmd := NewPicoclawCommand()
 	if err := cmd.Execute(); err != nil {
 		os.Exit(1)
diff --git a/cmd/picoclaw/main_test.go b/cmd/picoclaw/main_test.go
index 3740ba358..ad18cb330 100644
--- a/cmd/picoclaw/main_test.go
+++ b/cmd/picoclaw/main_test.go
@@ -9,6 +9,7 @@ import (
 	"github.com/stretchr/testify/require"
 
 	"github.com/sipeed/picoclaw/cmd/picoclaw/internal"
+	"github.com/sipeed/picoclaw/pkg/config"
 )
 
 func TestNewPicoclawCommand(t *testing.T) {
@@ -16,7 +17,7 @@ func TestNewPicoclawCommand(t *testing.T) {
 
 	require.NotNil(t, cmd)
 
-	short := fmt.Sprintf("%s picoclaw - Personal AI Assistant v%s\n\n", internal.Logo, internal.GetVersion())
+	short := fmt.Sprintf("%s picoclaw - Personal AI Assistant v%s\n\n", internal.Logo, config.GetVersion())
 
 	assert.Equal(t, "picoclaw", cmd.Use)
 	assert.Equal(t, short, cmd.Short)
@@ -38,6 +39,7 @@ func TestNewPicoclawCommand(t *testing.T) {
 		"cron",
 		"gateway",
 		"migrate",
+		"model",
 		"onboard",
 		"skills",
 		"status",
diff --git a/config/config.example.json b/config/config.example.json
index d885ef94b..1408dda5b 100644
--- a/config/config.example.json
+++ b/config/config.example.json
@@ -3,16 +3,23 @@
     "defaults": {
       "workspace": "~/.picoclaw/workspace",
       "restrict_to_workspace": true,
-      "model_name": "gpt4",
+      "model_name": "gpt-5.4",
       "max_tokens": 8192,
+      "context_window": 131072,
       "temperature": 0.7,
-      "max_tool_iterations": 20
+      "max_tool_iterations": 20,
+      "summarize_message_threshold": 20,
+      "summarize_token_percent": 75,
+      "tool_feedback": {
+        "enabled": false,
+        "max_args_length": 300
+      }
     }
   },
   "model_list": [
     {
-      "model_name": "gpt4",
-      "model": "openai/gpt-5.2",
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
       "api_key": "sk-your-openai-key",
       "api_base": "https://api.openai.com/v1"
     },
@@ -20,7 +27,15 @@
       "model_name": "claude-sonnet-4.6",
       "model": "anthropic/claude-sonnet-4.6",
       "api_key": "sk-ant-your-key",
-      "api_base": "https://api.anthropic.com/v1"
+      "api_base": "https://api.anthropic.com/v1",
+      "thinking_level": "high"
+    },
+    {
+      "_comment": "Anthropic Messages API - use native format for direct Anthropic API access",
+      "model_name": "claude-opus-4-6",
+      "model": "anthropic-messages/claude-opus-4-6",
+      "api_key": "sk-ant-your-key",
+      "api_base": "https://api.anthropic.com"
     },
     {
       "model_name": "gemini",
@@ -33,14 +48,31 @@
       "api_key": "sk-your-deepseek-key"
     },
     {
-      "model_name": "loadbalanced-gpt4",
-      "model": "openai/gpt-5.2",
+      "model_name": "longcat",
+      "model": "longcat/LongCat-Flash-Thinking",
+      "api_key": "your-longcat-api-key"
+    },
+    {
+      "model_name": "modelscope-qwen",
+      "model": "modelscope/Qwen/Qwen3-235B-A22B-Instruct-2507",
+      "api_key": "your-modelscope-access-token",
+      "api_base": "https://api-inference.modelscope.cn/v1"
+    },
+    {
+      "model_name": "azure-gpt5",
+      "model": "azure/my-gpt5-deployment",
+      "api_key": "your-azure-api-key",
+      "api_base": "https://your-resource.openai.azure.com"
+    },
+    {
+      "model_name": "loadbalanced-gpt-5.4",
+      "model": "openai/gpt-5.4",
       "api_key": "sk-key1",
       "api_base": "https://api1.example.com/v1"
     },
     {
-      "model_name": "loadbalanced-gpt4",
-      "model": "openai/gpt-5.2",
+      "model_name": "loadbalanced-gpt-5.4",
+      "model": "openai/gpt-5.4",
       "api_key": "sk-key2",
       "api_base": "https://api2.example.com/v1"
     }
@@ -49,15 +81,19 @@
     "telegram": {
       "enabled": false,
       "token": "YOUR_TELEGRAM_BOT_TOKEN",
+      "base_url": "",
       "proxy": "",
-      "allow_from": [
-        "YOUR_USER_ID"
-      ],
-      "reasoning_channel_id": ""
+      "allow_from": ["YOUR_USER_ID"],
+      "use_markdown_v2": false,
+      "reasoning_channel_id": "",
+      "streaming": {
+        "enabled": true
+      }
     },
     "discord": {
       "enabled": false,
       "token": "YOUR_DISCORD_BOT_TOKEN",
+      "proxy": "",
       "allow_from": [],
       "group_trigger": {
         "mention_only": false
@@ -93,7 +129,9 @@
       "encrypt_key": "",
       "verification_token": "",
       "allow_from": [],
-      "reasoning_channel_id": ""
+      "reasoning_channel_id": "",
+      "random_reaction_emoji": [],
+      "is_lark": false
     },
     "dingtalk": {
       "enabled": false,
@@ -109,6 +147,25 @@
       "allow_from": [],
       "reasoning_channel_id": ""
     },
+    "matrix": {
+      "enabled": false,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "device_id": "",
+      "join_on_invite": true,
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "placeholder": {
+        "enabled": true,
+        "text": "Thinking... 💭"
+      },
+      "reasoning_channel_id": "",
+      "crypto_database_path": "",
+      "crypto_passphrase": "YOUR_MATRIX_CRYPTO_PICKLE_KEY"
+    },
     "line": {
       "enabled": false,
       "channel_secret": "YOUR_LINE_CHANNEL_SECRET",
@@ -127,27 +184,59 @@
       "reasoning_channel_id": ""
     },
     "wecom": {
-      "_comment": "WeCom Bot (智能机器人) - Easier setup, supports group chats",
+      "_comment": "WeCom AI Bot over WebSocket.",
       "enabled": false,
-      "token": "YOUR_TOKEN",
-      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
-      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
-      "webhook_path": "/webhook/wecom",
+      "bot_id": "YOUR_BOT_ID",
+      "secret": "YOUR_SECRET",
+      "websocket_url": "wss://openws.work.weixin.qq.com",
+      "send_thinking_message": true,
       "allow_from": [],
-      "reply_timeout": 5,
       "reasoning_channel_id": ""
     },
-    "wecom_app": {
-      "_comment": "WeCom App (自建应用) - More features, proactive messaging, private chat only. See docs/wecom-app-configuration.md",
+    "pico": {
       "enabled": false,
-      "corp_id": "YOUR_CORP_ID",
-      "corp_secret": "YOUR_CORP_SECRET",
-      "agent_id": 1000002,
-      "token": "YOUR_TOKEN",
-      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
-      "webhook_path": "/webhook/wecom-app",
+      "token": "YOUR_PICO_TOKEN",
+      "allow_token_query": false,
+      "allow_origins": [],
+      "ping_interval": 30,
+      "read_timeout": 60,
+      "max_connections": 100,
+      "allow_from": []
+    },
+    "pico_client": {
+      "enabled": false,
+      "url": "wss://remote-pico-server/pico/ws",
+      "token": "YOUR_PICO_TOKEN",
+      "session_id": "",
+      "ping_interval": 30,
+      "read_timeout": 60,
+      "allow_from": []
+    },
+    "irc": {
+      "enabled": false,
+      "server": "irc.libera.chat:6697",
+      "tls": true,
+      "nick": "mybot",
+      "user": "",
+      "real_name": "",
+      "password": "",
+      "nickserv_password": "",
+      "sasl_user": "",
+      "sasl_password": "",
+      "channels": [
+        "#mychannel"
+      ],
+      "request_caps": [
+        "server-time",
+        "message-tags"
+      ],
       "allow_from": [],
-      "reply_timeout": 5,
+      "group_trigger": {
+        "mention_only": true
+      },
+      "typing": {
+        "enabled": false
+      },
       "reasoning_channel_id": ""
     }
   },
@@ -210,15 +299,42 @@
     "mistral": {
       "api_key": "",
       "api_base": "https://api.mistral.ai/v1"
+    },
+    "avian": {
+      "api_key": "",
+      "api_base": "https://api.avian.io/v1"
+    },
+    "longcat": {
+      "api_key": "",
+      "api_base": "https://api.longcat.chat/openai"
+    },
+    "modelscope": {
+      "api_key": "",
+      "api_base": "https://api-inference.modelscope.cn/v1"
     }
   },
   "tools": {
+    "allow_read_paths": null,
+    "allow_write_paths": null,
     "web": {
+      "enabled": true,
+      "prefer_native": true,
+      "fetch_limit_bytes": 10485760,
+      "format": "plaintext",
       "brave": {
         "enabled": false,
         "api_key": "YOUR_BRAVE_API_KEY",
+        "api_keys": [
+          "YOUR_BRAVE_API_KEY"
+        ],
         "max_results": 5
       },
+      "tavily": {
+        "enabled": false,
+        "api_key": "",
+        "base_url": "",
+        "max_results": 0
+      },
       "duckduckgo": {
         "enabled": true,
         "max_results": 5
@@ -226,27 +342,176 @@
       "perplexity": {
         "enabled": false,
         "api_key": "pplx-xxx",
+        "api_keys": [
+          "pplx-xxx"
+        ],
         "max_results": 5
       },
-      "proxy": ""
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://localhost:8888",
+        "max_results": 5
+      },
+      "glm_search": {
+        "enabled": false,
+        "api_key": "",
+        "base_url": "https://open.bigmodel.cn/api/paas/v4/web_search",
+        "search_engine": "search_std",
+        "max_results": 5
+      },
+      "fetch_limit_bytes": 10485760,
+      "private_host_whitelist": []
     },
     "cron": {
+      "enabled": true,
       "exec_timeout_minutes": 5
     },
+    "mcp": {
+      "enabled": false,
+      "discovery": {
+        "enabled": false,
+        "ttl": 5,
+        "max_search_results": 5,
+        "use_bm25": true,
+        "use_regex": false
+      },
+      "servers": {
+        "context7": {
+          "enabled": false,
+          "type": "http",
+          "url": "https://mcp.context7.com/mcp",
+          "headers": {
+            "CONTEXT7_API_KEY": "ctx7sk-xx"
+          }
+        },
+        "filesystem": {
+          "enabled": false,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-filesystem",
+            "/tmp"
+          ]
+        },
+        "github": {
+          "enabled": false,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-github"
+          ],
+          "env": {
+            "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
+          }
+        },
+        "brave-search": {
+          "enabled": false,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-brave-search"
+          ],
+          "env": {
+            "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY"
+          }
+        },
+        "postgres": {
+          "enabled": false,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-postgres",
+            "postgresql://user:password@localhost/dbname"
+          ]
+        },
+        "slack": {
+          "enabled": false,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-slack"
+          ],
+          "env": {
+            "SLACK_BOT_TOKEN": "YOUR_SLACK_BOT_TOKEN",
+            "SLACK_TEAM_ID": "YOUR_SLACK_TEAM_ID"
+          }
+        }
+      }
+    },
     "exec": {
-      "enable_deny_patterns": false,
-      "custom_deny_patterns": []
+      "enabled": true,
+      "enable_deny_patterns": true,
+      "custom_deny_patterns": null,
+      "custom_allow_patterns": null
     },
     "skills": {
+      "enabled": true,
       "registries": {
         "clawhub": {
           "enabled": true,
           "base_url": "https://clawhub.ai",
-          "search_path": "/api/v1/search",
-          "skills_path": "/api/v1/skills",
-          "download_path": "/api/v1/download"
+          "auth_token": "",
+          "search_path": "",
+          "skills_path": "",
+          "download_path": "",
+          "timeout": 0,
+          "max_zip_size": 0,
+          "max_response_size": 0
         }
+      },
+      "github": {
+        "proxy": "http://127.0.0.1:7891",
+        "token": ""
+      },
+      "max_concurrent_searches": 2,
+      "search_cache": {
+        "max_size": 50,
+        "ttl_seconds": 300
       }
+    },
+    "media_cleanup": {
+      "enabled": true,
+      "max_age_minutes": 30,
+      "interval_minutes": 5
+    },
+    "append_file": {
+      "enabled": true
+    },
+    "edit_file": {
+      "enabled": true
+    },
+    "find_skills": {
+      "enabled": true
+    },
+    "i2c": {
+      "enabled": false
+    },
+    "install_skill": {
+      "enabled": true
+    },
+    "list_dir": {
+      "enabled": true
+    },
+    "message": {
+      "enabled": true
+    },
+    "read_file": {
+      "enabled": true
+    },
+    "spawn": {
+      "enabled": true
+    },
+    "spi": {
+      "enabled": false
+    },
+    "subagent": {
+      "enabled": true
+    },
+    "web_fetch": {
+      "enabled": true
+    },
+    "write_file": {
+      "enabled": true
     }
   },
   "heartbeat": {
@@ -257,8 +522,23 @@
     "enabled": false,
     "monitor_usb": true
   },
+  "voice": {
+    "model_name": "",
+    "echo_transcription": false
+  },
+  "hooks": {
+    "enabled": true,
+    "defaults": {
+      "observer_timeout_ms": 500,
+      "interceptor_timeout_ms": 5000,
+      "approval_timeout_ms": 60000
+    }
+  },
   "gateway": {
+    "_comment": "Default log level is set to 'fatal'. Other available options are 'debug', 'info', 'warn' and 'error'.",
     "host": "127.0.0.1",
-    "port": 18790
+    "port": 18790,
+    "hot_reload": false,
+    "log_level": "fatal"
   }
 }
diff --git a/docker/Dockerfile.full b/docker/Dockerfile.full
new file mode 100644
index 000000000..30e1680d5
--- /dev/null
+++ b/docker/Dockerfile.full
@@ -0,0 +1,44 @@
+# ============================================================
+# Stage 1: Build the picoclaw binary
+# ============================================================
+FROM golang:1.26.0-alpine AS builder
+
+RUN apk add --no-cache git make
+
+WORKDIR /src
+
+# Cache dependencies
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy source and build
+COPY . .
+RUN make build
+
+# ============================================================
+# Stage 2: Node.js-based runtime with full MCP support
+# ============================================================
+FROM node:24-alpine3.23
+
+# Install runtime dependencies
+RUN apk add --no-cache \
+  ca-certificates \
+  curl \
+  git \
+  python3 \
+  py3-pip
+
+# Install uv and symlink to system path
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
+  ln -s /root/.local/bin/uv /usr/local/bin/uv && \
+  ln -s /root/.local/bin/uvx /usr/local/bin/uvx && \
+  uv --version
+
+# Copy binary
+COPY --from=builder /src/build/picoclaw /usr/local/bin/picoclaw
+
+# Create picoclaw home directory
+RUN /usr/local/bin/picoclaw onboard
+
+ENTRYPOINT ["picoclaw"]
+CMD ["gateway"]
diff --git a/docker/Dockerfile.goreleaser.launcher b/docker/Dockerfile.goreleaser.launcher
new file mode 100644
index 000000000..5d65576f7
--- /dev/null
+++ b/docker/Dockerfile.goreleaser.launcher
@@ -0,0 +1,12 @@
+FROM alpine:3.21
+
+ARG TARGETPLATFORM
+
+RUN apk add --no-cache ca-certificates tzdata
+
+COPY $TARGETPLATFORM/picoclaw /usr/local/bin/picoclaw
+COPY $TARGETPLATFORM/picoclaw-launcher /usr/local/bin/picoclaw-launcher
+COPY $TARGETPLATFORM/picoclaw-launcher-tui /usr/local/bin/picoclaw-launcher-tui
+
+ENTRYPOINT ["picoclaw-launcher"]
+CMD ["-public", "-no-browser"]
diff --git a/docker/Dockerfile.heavy b/docker/Dockerfile.heavy
new file mode 100644
index 000000000..cbc243e39
--- /dev/null
+++ b/docker/Dockerfile.heavy
@@ -0,0 +1,67 @@
+# ============================================================
+# Stage 1: Build the picoclaw binary
+# ============================================================
+FROM golang:1.26.0-alpine AS builder
+
+RUN apk add --no-cache git make
+
+WORKDIR /src
+
+# Cache dependencies
+COPY go.mod go.sum ./
+RUN go mod download
+
+# Copy source and build
+COPY . .
+RUN make build
+
+# ============================================================
+# Stage 2: Node.js runtime with Python + MCP support
+# ============================================================
+FROM node:24-alpine3.23
+
+RUN apk add --no-cache \
+  ca-certificates \
+  curl \
+  git \
+  python3 \
+  py3-pip \
+  chromium \
+  jq
+
+# Install Playwright browsers for agent-browser
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/playwright-browsers
+RUN npm install -g agent-browser && \
+    npx playwright install chromium && \
+    chmod -R o+rx $PLAYWRIGHT_BROWSERS_PATH
+
+# Install uv
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh && \
+  ln -s /root/.local/bin/uv /usr/local/bin/uv && \
+  ln -s /root/.local/bin/uvx /usr/local/bin/uvx && \
+  uv --version
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD wget -q --spider http://localhost:18790/health || exit 1
+
+# Copy binary
+COPY --from=builder /src/build/picoclaw /usr/local/bin/picoclaw
+
+# Reuse existing node user (UID/GID 1000) — rename to picoclaw
+RUN deluser node 2>/dev/null; delgroup node 2>/dev/null; \
+    addgroup -g 1000 picoclaw 2>/dev/null; \
+    adduser -D -u 1000 -G picoclaw -h /home/picoclaw picoclaw 2>/dev/null || true
+
+USER picoclaw
+
+# Run onboard to create initial directories and config
+RUN /usr/local/bin/picoclaw onboard
+
+# Copy default workspace
+COPY --chown=picoclaw:picoclaw workspace/ /home/picoclaw/.picoclaw/workspace/
+
+VOLUME /home/picoclaw/.picoclaw/workspace
+
+ENTRYPOINT ["picoclaw"]
+CMD ["gateway"]
diff --git a/docker/docker-compose.full.yml b/docker/docker-compose.full.yml
new file mode 100644
index 000000000..6f34448c4
--- /dev/null
+++ b/docker/docker-compose.full.yml
@@ -0,0 +1,44 @@
+services:
+  # ─────────────────────────────────────────────
+  # PicoClaw Agent (one-shot query) - Full MCP Support
+  #   docker compose -f docker/docker-compose.full.yml run --rm picoclaw-agent -m "Hello"
+  # ─────────────────────────────────────────────
+  picoclaw-agent:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.full
+    container_name: picoclaw-agent-full
+    profiles:
+      - agent
+    volumes:
+      - ../config/config.json:/root/.picoclaw/config.json:ro
+      - picoclaw-workspace:/root/.picoclaw/workspace
+      - picoclaw-npm-cache:/root/.npm # npm cache for faster MCP server installs
+    entrypoint: ["picoclaw", "agent"]
+    stdin_open: true
+    tty: true
+
+  # ─────────────────────────────────────────────
+  # PicoClaw Gateway (Long-running Bot) - Full MCP Support
+  #   docker compose -f docker/docker-compose.full.yml --profile gateway up
+  # ─────────────────────────────────────────────
+  picoclaw-gateway:
+    build:
+      context: ..
+      dockerfile: docker/Dockerfile.full
+    container_name: picoclaw-gateway-full
+    restart: unless-stopped
+    profiles:
+      - gateway
+    volumes:
+      # Configuration file
+      - ../config/config.json:/root/.picoclaw/config.json:ro
+      # Persistent workspace (sessions, memory, logs)
+      - picoclaw-workspace:/root/.picoclaw/workspace
+      # NPM cache for faster MCP server installs
+      - picoclaw-npm-cache:/root/.npm
+    command: ["gateway"]
+
+volumes:
+  picoclaw-workspace:
+  picoclaw-npm-cache: # Cache npm packages to speed up MCP server installations
diff --git a/docker/docker-compose.yml b/docker/docker-compose.yml
index 9ec71abab..b26cf4199 100644
--- a/docker/docker-compose.yml
+++ b/docker/docker-compose.yml
@@ -19,7 +19,7 @@ services:
 
   # ─────────────────────────────────────────────
   # PicoClaw Gateway (Long-running Bot)
-  #   docker compose -f docker/docker-compose.yml up picoclaw-gateway
+  #   docker compose -f docker/docker-compose.yml --profile gateway up
   # ─────────────────────────────────────────────
   picoclaw-gateway:
     image: docker.io/sipeed/picoclaw:latest
@@ -32,3 +32,21 @@ services:
     #  - "host.docker.internal:host-gateway"
     volumes:
       - ./data:/root/.picoclaw
+
+  # ─────────────────────────────────────────────
+  # PicoClaw Launcher (Web Console + Gateway)
+  #   docker compose -f docker/docker-compose.yml --profile launcher up
+  # ─────────────────────────────────────────────
+  picoclaw-launcher:
+    image: docker.io/sipeed/picoclaw:launcher
+    container_name: picoclaw-launcher
+    restart: on-failure
+    profiles:
+      - launcher
+    environment:
+      - PICOCLAW_GATEWAY_HOST=0.0.0.0
+    ports:
+      - "127.0.0.1:18800:18800"
+      - "127.0.0.1:18790:18790"
+    volumes:
+      - ./data:/root/.picoclaw
diff --git a/docs/ANTIGRAVITY_AUTH.md b/docs/ANTIGRAVITY_AUTH.md
index 89261d899..d88d73c8d 100644
--- a/docs/ANTIGRAVITY_AUTH.md
+++ b/docs/ANTIGRAVITY_AUTH.md
@@ -438,7 +438,7 @@ type ProviderAuthResult = {
 
 ### 1. Required Environment/Dependencies
 
-- Go ≥ 1.21
+- Go ≥ 1.25
 - PicoClaw codebase (`pkg/providers/` and `pkg/auth/`)
 - `crypto` and `net/http` standard library packages
 
@@ -584,7 +584,7 @@ Each SSE message (`data: {...}`) is wrapped in a `response` field:
   ],
   "agents": {
     "defaults": {
-      "model": "gemini-flash"
+      "model_name": "gemini-flash"
     }
   }
 }
@@ -674,7 +674,7 @@ Add a default entry in `pkg/config/defaults.go`:
 
 #### 5. Add Auth Support (Optional)
 
-If your provider requires OAuth or special authentication, add a case to `cmd/picoclaw/cmd_auth.go`:
+If your provider requires OAuth or special authentication, add a case to `cmd/picoclaw/internal/auth/helpers.go`:
 
 ```go
 case "your-provider":
@@ -736,7 +736,7 @@ export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/m
   - `pkg/auth/store.go` - Auth credential storage (`~/.picoclaw/auth.json`)
   - `pkg/providers/factory.go` - Provider factory and protocol routing
   - `pkg/providers/types.go` - Provider interface definitions
-  - `cmd/picoclaw/cmd_auth.go` - Auth CLI commands
+  - `cmd/picoclaw/internal/auth/helpers.go` - Auth CLI commands
 
 - **Documentation:**
   - `docs/ANTIGRAVITY_USAGE.md` - Antigravity usage guide
diff --git a/docs/agent-refactor/README.md b/docs/agent-refactor/README.md
new file mode 100644
index 000000000..db8575fc9
--- /dev/null
+++ b/docs/agent-refactor/README.md
@@ -0,0 +1,145 @@
+# Agent Refactor
+
+## What this directory is for
+
+This directory is the working area for the current Agent refactor.
+
+The purpose of this refactor is simple:
+
+the project needs a smaller, clearer, and more stable Agent model before more Agent-related behavior is added.
+
+The codebase already contains meaningful Agent behavior. What it still lacks is a sufficiently explicit and stable semantic boundary around that behavior.
+
+This refactor exists to fix that first.
+
+---
+
+## Refactor stance
+
+This is a maintenance-led consolidation effort.
+
+It is not a general invitation to expand Agent behavior in parallel.
+
+During this refactor window, Agent-related work should converge on the current refactor track instead of branching into new semantics.
+
+That means:
+
+- concept clarification before feature expansion
+- boundary tightening before abstraction growth
+- semantic consolidation before new behavior
+
+---
+
+## Core rule: minimum concepts only
+
+This refactor follows one hard rule:
+
+**do not introduce a new concept unless it is strictly necessary**
+
+More explicitly:
+
+- if an existing concept can be clarified, reuse it
+- if an existing boundary can be made explicit, do that first
+- if a behavior can be expressed without a new abstraction, do not add one
+- "future flexibility" is not enough justification on its own
+
+The goal of this refactor is not to grow the model.
+
+The goal is to reduce ambiguity.
+
+---
+
+## What is being clarified
+
+This refactor is currently concerned with the following questions:
+
+1. what an `Agent` is
+2. what an `AgentLoop` is
+3. what the lifecycle of `AgentLoop` is
+4. what the event surface around `AgentLoop` is
+5. how persona / identity is assembled
+6. how capabilities are represented
+7. how context boundaries and compression work
+8. how subagent coordination works
+
+These are the current working boundaries.
+
+If they need to be adjusted, they should be adjusted explicitly rather than drift implicitly in code.
+
+---
+
+## Status of this directory
+
+The documents here are working materials.
+
+They are not final or immutable.
+
+If current notes are incomplete, incorrectly split, or too broad, they should be revised. This directory should evolve with the refactor rather than pretending the first draft is complete.
+
+---
+
+## Suggested document split
+
+This directory may eventually contain notes such as:
+
+- `agent-overview.md`
+  - what an Agent is
+- `agent-loop.md`
+  - AgentLoop contract, lifecycle, event surface
+- `persona.md`
+  - persona and identity assembly
+- `capability.md`
+  - tools / skills / MCP capability semantics
+- `context.md`
+  - context scope, history, summary, compression
+- `subagent.md`
+  - subagent coordination rules
+
+These files should be added only when they help clarify the current refactor work.
+
+This directory should not turn into a generic architecture dump.
+
+---
+
+## What this directory is not for
+
+This directory is not intended for:
+
+- broad speculative architecture
+- future multi-node protocol design not required by the current refactor
+- parallel feature planning unrelated to Agent consolidation
+- adding new concepts before current ones are made clear
+
+If a topic does not directly help reduce ambiguity in the current Agent model, it probably does not belong here yet.
+
+---
+
+## Relationship to implementation
+
+Implementation changes should not keep redefining Agent semantics implicitly.
+
+If a PR changes or depends on Agent semantics, those semantics should either already exist here or be clarified in a linked issue first.
+
+This directory is here to make implementation narrower and more disciplined.
+
+---
+
+## Relationship to GitHub tracking
+
+The umbrella issue for this refactor should point here.
+
+The issue is the coordination surface.
+
+This directory is the repository-local working surface.
+
+---
+
+## Summary
+
+The main question of this refactor is not:
+
+- what more can Agent do
+
+The main question is:
+
+- what is the smallest stable model that current Agent behavior can be organized around
diff --git a/docs/agent-refactor/context.md b/docs/agent-refactor/context.md
new file mode 100644
index 000000000..2269d9258
--- /dev/null
+++ b/docs/agent-refactor/context.md
@@ -0,0 +1,164 @@
+# Context
+
+## What this document covers
+
+This document makes explicit the boundaries of context management in the agent loop:
+
+- what fills the context window and how space is divided
+- what is stored in session history vs. built at request time
+- when and how context compression happens
+- how token budgets are estimated
+
+These are existing concepts. This document clarifies their boundaries rather than introducing new ones.
+
+---
+
+## Context window regions
+
+The context window is the model's total input capacity. Four regions fill it:
+
+| Region | Assembled by | Stored in session? |
+|---|---|---|
+| System prompt | `BuildMessages()` — static + dynamic parts | No |
+| Summary | `SetSummary()` stores it; `BuildMessages()` injects it | Separate from history |
+| Session history | User / assistant / tool messages | Yes |
+| Tool definitions | Provider adapter injects at call time | No |
+
+`MaxTokens` (the output generation limit) must also be reserved from the total budget.
+
+The available space for history is therefore:
+
+```
+history_budget = ContextWindow - system_prompt - summary - tool_definitions - MaxTokens
+```
+
+---
+
+## ContextWindow vs MaxTokens
+
+These serve different purposes:
+
+- **MaxTokens** — maximum tokens the LLM may generate in one response. Sent as the `max_tokens` request parameter.
+- **ContextWindow** — the model's total input context capacity.
+
+These were previously set to the same value, which caused the summarization threshold to fire either far too early (at the default 32K) or not at all (when a user raised `max_tokens`).
+
+Current default when not explicitly configured: `ContextWindow = MaxTokens * 4`.
+
+---
+
+## Session history
+
+Session history stores only conversation messages:
+
+- `user` — user input
+- `assistant` — LLM response (may include `ToolCalls`)
+- `tool` — tool execution results
+
+Session history does **not** contain:
+
+- System prompts — assembled at request time by `BuildMessages`
+- Summary content — stored separately via `SetSummary`, injected by `BuildMessages`
+
+This distinction matters: any code that operates on session history — compression, boundary detection, token estimation — must not assume a system message is present.
+
+---
+
+## Turn
+
+A **Turn** is one complete cycle:
+
+> user message -> LLM iterations (possibly including tool calls) -> final assistant response
+
+This definition comes from the agent loop design (#1316). In session history, Turn boundaries are identified by `user`-role messages.
+
+Turn is the atomic unit for compression. Cutting inside a Turn can orphan tool-call sequences — an assistant message with `ToolCalls` separated from its corresponding `tool` results. Compressing at Turn boundaries avoids this by construction.
+
+`parseTurnBoundaries(history)` returns the starting index of each Turn.
+`findSafeBoundary(history, targetIndex)` snaps a target cut point to the nearest Turn boundary.
+
+---
+
+## Compression paths
+
+Three compression paths exist, in order of preference:
+
+### 1. Async summarization
+
+`maybeSummarize` runs after each Turn completes.
+
+Triggers when message count exceeds a threshold, or when estimated history tokens exceed a percentage of `ContextWindow`. If triggered, a background goroutine calls the LLM to produce a summary of the oldest messages. The summary is stored via `SetSummary`; `BuildMessages` injects it into the system prompt on the next call.
+
+Cut point uses `findSafeBoundary` so no Turn is split.
+
+### 2. Proactive budget check
+
+`isOverContextBudget` runs before each LLM call.
+
+Uses the full budget formula: `message_tokens + tool_def_tokens + MaxTokens > ContextWindow`. If over budget, triggers `forceCompression` and rebuilds messages before calling the LLM.
+
+This prevents wasted (and billed) LLM calls that would otherwise fail with a context-window error.
+
+### 3. Emergency compression (reactive)
+
+`forceCompression` runs when the LLM returns a context-window error despite the proactive check.
+
+Drops the oldest ~50% of Turns. If the history is a single Turn with no safe split point (e.g. one user message followed by a massive tool response), falls back to keeping only the most recent user message — breaking Turn atomicity as a last resort to avoid a context-exceeded loop.
+
+Stores a compression note in the session summary (not in history messages) so `BuildMessages` can include it in the next system prompt.
+
+This is the fallback for when the token estimate undershoots reality.
+
+---
+
+## Token estimation
+
+Estimation uses a heuristic of ~2.5 characters per token (`chars * 2 / 5`).
+
+`estimateMessageTokens` counts:
+
+- `Content` (rune count, for multibyte correctness)
+- `ReasoningContent` (extended thinking / chain-of-thought)
+- `ToolCalls` — ID, type, function name, arguments
+- `ToolCallID` (tool result metadata)
+- Per-message overhead (role label, JSON structure)
+- `Media` items — flat per-item token estimate, added directly to the final count (not through the character heuristic, since actual cost depends on resolution and provider-specific image tokenization)
+
+`estimateToolDefsTokens` counts tool definition overhead: name, description, JSON schema of parameters.
+
+These are deliberately heuristic. The proactive check handles the common case; the reactive path catches estimation errors.
+
+---
+
+## Interface boundaries
+
+Context budget functions (`parseTurnBoundaries`, `findSafeBoundary`, `estimateMessageTokens`, `isOverContextBudget`) are **pure functions**. They take `[]providers.Message` and integer parameters. They have no dependency on `AgentLoop` or any other runtime struct.
+
+`BuildMessages` is the sole assembler of the final message array sent to the LLM. Budget functions inform compression decisions but do not construct messages.
+
+`forceCompression` and `summarizeSession` mutate session state (history and summary). `BuildMessages` reads that state to construct context. The flow is:
+
+```
+budget check --> compression decision --> mutate session --> BuildMessages reads session --> LLM call
+```
+
+---
+
+## Known gaps
+
+These are recognized limitations in the current implementation, documented here for visibility:
+
+- **Summarization trigger does not use the full budget formula.** `maybeSummarize` compares estimated history tokens against a percentage of `ContextWindow`. It does not account for system prompt size, tool definition overhead, or `MaxTokens` reserve. The proactive check covers the critical path (preventing 400 errors), but the summarization trigger could be aligned with the same budget model for more accurate early compression.
+
+- **Token estimation is heuristic.** It does not account for provider-specific tokenization, exact system prompt size (assembled separately), or variable image token costs. The two-path design (proactive + reactive) is intended to tolerate this imprecision.
+
+- **Reactive retry does not preserve media.** When the reactive path rebuilds context after compression, it currently passes empty values for media references. This is a pre-existing issue in the main loop, not introduced by the budget system.
+
+---
+
+## What this document does not cover
+
+- How `AGENT.md` frontmatter configures context parameters — that is part of the Agent definition work
+- How the context builder assembles context in the new architecture — that is upcoming work
+- How compression events surface through the event system — that is part of the event model (#1316)
+- Subagent context isolation — that is a separate track
diff --git a/docs/channels/dingtalk/README.fr.md b/docs/channels/dingtalk/README.fr.md
new file mode 100644
index 000000000..969346d65
--- /dev/null
+++ b/docs/channels/dingtalk/README.fr.md
@@ -0,0 +1,35 @@
+> Retour au [README](../../../README.fr.md)
+
+# DingTalk
+
+DingTalk est la plateforme de communication d'entreprise d'Alibaba, très populaire dans les milieux professionnels chinois. Elle utilise un SDK de streaming pour maintenir des connexions persistantes.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Champ         | Type   | Requis | Description                                                      |
+| ------------- | ------ | ------ | ---------------------------------------------------------------- |
+| enabled       | bool   | Oui    | Activer ou non le canal DingTalk                                 |
+| client_id     | string | Oui    | Client ID de l'application DingTalk                              |
+| client_secret | string | Oui    | Client Secret de l'application DingTalk                          |
+| allow_from    | array  | Non    | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
+
+## Procédure de configuration
+
+1. Rendez-vous sur la [plateforme ouverte DingTalk](https://open.dingtalk.com/)
+2. Créez une application interne d'entreprise
+3. Obtenez le Client ID et le Client Secret depuis les paramètres de l'application
+4. Configurez OAuth et les abonnements aux événements (si nécessaire)
+5. Renseignez le Client ID et le Client Secret dans le fichier de configuration
diff --git a/docs/channels/dingtalk/README.ja.md b/docs/channels/dingtalk/README.ja.md
new file mode 100644
index 000000000..d44a87820
--- /dev/null
+++ b/docs/channels/dingtalk/README.ja.md
@@ -0,0 +1,35 @@
+> [README](../../../README.ja.md) に戻る
+
+# DingTalk
+
+DingTalkはアリババの企業向けコミュニケーションプラットフォームで、中国のビジネス環境で広く利用されています。ストリーミング SDK を使用して持続的な接続を維持します。
+
+## 設定
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| フィールド    | 型     | 必須 | 説明                                         |
+| ------------- | ------ | ---- | -------------------------------------------- |
+| enabled       | bool   | はい | DingTalk チャンネルを有効にするかどうか      |
+| client_id     | string | はい | DingTalk アプリケーションの Client ID        |
+| client_secret | string | はい | DingTalk アプリケーションの Client Secret    |
+| allow_from    | array  | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可 |
+
+## セットアップ手順
+
+1. [DingTalk オープンプラットフォーム](https://open.dingtalk.com/) にアクセスする
+2. 企業内部アプリケーションを作成する
+3. アプリケーション設定から Client ID と Client Secret を取得する
+4. OAuth とイベントサブスクリプションを設定する（必要な場合）
+5. Client ID と Client Secret を設定ファイルに入力する
diff --git a/docs/channels/dingtalk/README.md b/docs/channels/dingtalk/README.md
new file mode 100644
index 000000000..a3f23a1e6
--- /dev/null
+++ b/docs/channels/dingtalk/README.md
@@ -0,0 +1,35 @@
+> Back to [README](../../../README.md)
+
+# DingTalk
+
+DingTalk is Alibaba's enterprise communication platform, widely used in Chinese workplaces. It uses a streaming SDK to maintain persistent connections.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field         | Type   | Required | Description                                              |
+| ------------- | ------ | -------- | -------------------------------------------------------- |
+| enabled       | bool   | Yes      | Whether to enable the DingTalk channel                   |
+| client_id     | string | Yes      | Client ID of the DingTalk application                    |
+| client_secret | string | Yes      | Client Secret of the DingTalk application                |
+| allow_from    | array  | No       | User ID whitelist; empty means all users are allowed     |
+
+## Setup
+
+1. Go to the [DingTalk Open Platform](https://open.dingtalk.com/)
+2. Create an internal enterprise application
+3. Obtain the Client ID and Client Secret from the application settings
+4. Configure OAuth and event subscriptions (if needed)
+5. Fill in the Client ID and Client Secret in the configuration file
diff --git a/docs/channels/dingtalk/README.pt-br.md b/docs/channels/dingtalk/README.pt-br.md
new file mode 100644
index 000000000..f9056217f
--- /dev/null
+++ b/docs/channels/dingtalk/README.pt-br.md
@@ -0,0 +1,35 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# DingTalk
+
+DingTalk é a plataforma de comunicação empresarial da Alibaba, amplamente utilizada no ambiente corporativo chinês. Ela usa um SDK de streaming para manter conexões persistentes.
+
+## Configuração
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Campo         | Tipo   | Obrigatório | Descrição                                                        |
+| ------------- | ------ | ----------- | ---------------------------------------------------------------- |
+| enabled       | bool   | Sim         | Se o canal DingTalk deve ser habilitado                          |
+| client_id     | string | Sim         | Client ID do aplicativo DingTalk                                 |
+| client_secret | string | Sim         | Client Secret do aplicativo DingTalk                             |
+| allow_from    | array  | Não         | Lista de permissão de IDs de usuário; vazio permite todos        |
+
+## Configuração passo a passo
+
+1. Acesse a [Plataforma Aberta DingTalk](https://open.dingtalk.com/)
+2. Crie um aplicativo interno corporativo
+3. Obtenha o Client ID e o Client Secret nas configurações do aplicativo
+4. Configure OAuth e assinaturas de eventos (se necessário)
+5. Preencha o Client ID e o Client Secret no arquivo de configuração
diff --git a/docs/channels/dingtalk/README.vi.md b/docs/channels/dingtalk/README.vi.md
new file mode 100644
index 000000000..8c060a382
--- /dev/null
+++ b/docs/channels/dingtalk/README.vi.md
@@ -0,0 +1,35 @@
+> Quay lại [README](../../../README.vi.md)
+
+# DingTalk
+
+DingTalk là nền tảng giao tiếp doanh nghiệp của Alibaba, được sử dụng rộng rãi trong môi trường làm việc tại Trung Quốc. Nền tảng này sử dụng SDK streaming để duy trì kết nối liên tục.
+
+## Cấu hình
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Trường        | Kiểu   | Bắt buộc | Mô tả                                                            |
+| ------------- | ------ | -------- | ---------------------------------------------------------------- |
+| enabled       | bool   | Có       | Có bật kênh DingTalk hay không                                   |
+| client_id     | string | Có       | Client ID của ứng dụng DingTalk                                  |
+| client_secret | string | Có       | Client Secret của ứng dụng DingTalk                              |
+| allow_from    | array  | Không    | Danh sách trắng ID người dùng; để trống cho phép tất cả          |
+
+## Quy trình thiết lập
+
+1. Truy cập [Nền tảng mở DingTalk](https://open.dingtalk.com/)
+2. Tạo một ứng dụng nội bộ doanh nghiệp
+3. Lấy Client ID và Client Secret từ cài đặt ứng dụng
+4. Cấu hình OAuth và đăng ký sự kiện (nếu cần)
+5. Điền Client ID và Client Secret vào file cấu hình
diff --git a/docs/channels/dingtalk/README.zh.md b/docs/channels/dingtalk/README.zh.md
index 1e445d0b0..bdaaa1ee1 100644
--- a/docs/channels/dingtalk/README.zh.md
+++ b/docs/channels/dingtalk/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
 # 钉钉
 
 钉钉是阿里巴巴的企业通讯平台，在中国职场中广受欢迎。它采用流式 SDK 来维持持久连接。
diff --git a/docs/channels/discord/README.fr.md b/docs/channels/discord/README.fr.md
new file mode 100644
index 000000000..61c34abb9
--- /dev/null
+++ b/docs/channels/discord/README.fr.md
@@ -0,0 +1,39 @@
+> Retour au [README](../../../README.fr.md)
+
+# Discord
+
+Discord est une application gratuite de chat vocal, vidéo et textuel conçue pour les communautés. PicoClaw se connecte aux serveurs Discord via l'API Bot Discord, avec prise en charge de la réception et de l'envoi de messages.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"],
+      "group_trigger": {
+        "mention_only": false
+      }
+    }
+  }
+}
+```
+
+| Champ         | Type   | Requis | Description                                                                 |
+| ------------- | ------ | ------ | --------------------------------------------------------------------------- |
+| enabled       | bool   | Oui    | Activer ou non le canal Discord                                             |
+| token         | string | Oui    | Token du bot Discord                                                        |
+| allow_from    | array  | Non    | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
+| group_trigger | object | Non    | Paramètres de déclenchement de groupe (exemple : { "mention_only": false }) |
+
+## Configuration initiale
+
+1. Accéder au [Portail des développeurs Discord](https://discord.com/developers/applications) et créer une nouvelle application
+2. Activer les Intents :
+   - Message Content Intent
+   - Server Members Intent
+3. Obtenir le Token du bot
+4. Renseigner le Token du bot dans le fichier de configuration
+5. Inviter le bot sur le serveur et lui accorder les permissions nécessaires (ex. envoyer des messages, lire l'historique des messages)
diff --git a/docs/channels/discord/README.ja.md b/docs/channels/discord/README.ja.md
new file mode 100644
index 000000000..ecce30059
--- /dev/null
+++ b/docs/channels/discord/README.ja.md
@@ -0,0 +1,39 @@
+> [README](../../../README.ja.md) に戻る
+
+# Discord
+
+Discord はコミュニティ向けに設計された無料の音声・ビデオ・テキストチャットアプリケーションです。PicoClaw は Discord Bot API を通じて Discord サーバーに接続し、メッセージの受信と送信をサポートします。
+
+## 設定
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"],
+      "group_trigger": {
+        "mention_only": false
+      }
+    }
+  }
+}
+```
+
+| フィールド    | 型     | 必須   | 説明                                                              |
+| ------------- | ------ | ------ | ----------------------------------------------------------------- |
+| enabled       | bool   | はい   | Discord チャンネルを有効にするかどうか                            |
+| token         | string | はい   | Discord ボットトークン                                            |
+| allow_from    | array  | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可     |
+| group_trigger | object | いいえ | グループトリガー設定（例: { "mention_only": false }）             |
+
+## セットアップ手順
+
+1. [Discord 開発者ポータル](https://discord.com/developers/applications) にアクセスして新しいアプリケーションを作成する
+2. Intents を有効にする:
+   - Message Content Intent
+   - Server Members Intent
+3. Bot トークンを取得する
+4. 設定ファイルに Bot トークンを入力する
+5. ボットをサーバーに招待し、必要な権限を付与する（例: メッセージの送信、メッセージ履歴の読み取りなど）
diff --git a/docs/channels/discord/README.md b/docs/channels/discord/README.md
new file mode 100644
index 000000000..e1ce7ab06
--- /dev/null
+++ b/docs/channels/discord/README.md
@@ -0,0 +1,39 @@
+> Back to [README](../../../README.md)
+
+# Discord
+
+Discord is a free voice, video, and text chat application designed for communities. PicoClaw connects to Discord servers via the Discord Bot API, supporting both receiving and sending messages.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"],
+      "group_trigger": {
+        "mention_only": false
+      }
+    }
+  }
+}
+```
+
+| Field         | Type   | Required | Description                                                                 |
+| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
+| enabled       | bool   | Yes      | Whether to enable the Discord channel                                       |
+| token         | string | Yes      | Discord Bot Token                                                           |
+| allow_from    | array  | No       | Allowlist of user IDs; empty means all users are allowed                    |
+| group_trigger | object | No       | Group trigger settings (example: { "mention_only": false })                 |
+
+## Setup
+
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications) and create a new application
+2. Enable Intents:
+   - Message Content Intent
+   - Server Members Intent
+3. Obtain the Bot Token
+4. Fill in the Bot Token in the configuration file
+5. Invite the bot to your server and grant the necessary permissions (e.g. Send Messages, Read Message History)
diff --git a/docs/channels/discord/README.pt-br.md b/docs/channels/discord/README.pt-br.md
new file mode 100644
index 000000000..c9ed2809b
--- /dev/null
+++ b/docs/channels/discord/README.pt-br.md
@@ -0,0 +1,39 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# Discord
+
+Discord é um aplicativo gratuito de chat de voz, vídeo e texto projetado para comunidades. O PicoClaw se conecta a servidores Discord via Discord Bot API, com suporte para receber e enviar mensagens.
+
+## Configuração
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"],
+      "group_trigger": {
+        "mention_only": false
+      }
+    }
+  }
+}
+```
+
+| Campo         | Tipo   | Obrigatório | Descrição                                                                   |
+| ------------- | ------ | ----------- | --------------------------------------------------------------------------- |
+| enabled       | bool   | Sim         | Se o canal Discord deve ser habilitado                                      |
+| token         | string | Sim         | Token do Bot Discord                                                        |
+| allow_from    | array  | Não         | Lista de IDs de usuários permitidos; vazio significa todos os usuários      |
+| group_trigger | object | Não         | Configurações de gatilho de grupo (exemplo: { "mention_only": false })      |
+
+## Configuração inicial
+
+1. Acesse o [Portal de Desenvolvedores do Discord](https://discord.com/developers/applications) e crie uma nova aplicação
+2. Habilite os Intents:
+   - Message Content Intent
+   - Server Members Intent
+3. Obtenha o Token do Bot
+4. Preencha o Token do Bot no arquivo de configuração
+5. Convide o bot para o servidor e conceda as permissões necessárias (ex. enviar mensagens, ler histórico de mensagens)
diff --git a/docs/channels/discord/README.vi.md b/docs/channels/discord/README.vi.md
new file mode 100644
index 000000000..7073b04f1
--- /dev/null
+++ b/docs/channels/discord/README.vi.md
@@ -0,0 +1,39 @@
+> Quay lại [README](../../../README.vi.md)
+
+# Discord
+
+Discord là ứng dụng chat thoại, video và văn bản miễn phí được thiết kế cho cộng đồng. PicoClaw kết nối với máy chủ Discord qua Discord Bot API, hỗ trợ nhận và gửi tin nhắn.
+
+## Cấu hình
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"],
+      "group_trigger": {
+        "mention_only": false
+      }
+    }
+  }
+}
+```
+
+| Trường        | Kiểu   | Bắt buộc | Mô tả                                                                       |
+| ------------- | ------ | -------- | --------------------------------------------------------------------------- |
+| enabled       | bool   | Có       | Có bật kênh Discord hay không                                               |
+| token         | string | Có       | Token Bot Discord                                                           |
+| allow_from    | array  | Không    | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả           |
+| group_trigger | object | Không    | Cài đặt kích hoạt nhóm (ví dụ: { "mention_only": false })                  |
+
+## Hướng dẫn thiết lập
+
+1. Truy cập [Discord Developer Portal](https://discord.com/developers/applications) và tạo ứng dụng mới
+2. Bật các Intents:
+   - Message Content Intent
+   - Server Members Intent
+3. Lấy Bot Token
+4. Điền Bot Token vào file cấu hình
+5. Mời bot vào máy chủ và cấp các quyền cần thiết (ví dụ: gửi tin nhắn, đọc lịch sử tin nhắn)
diff --git a/docs/channels/discord/README.zh.md b/docs/channels/discord/README.zh.md
index 6d3c502cf..673af4854 100644
--- a/docs/channels/discord/README.zh.md
+++ b/docs/channels/discord/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
 # Discord
 
 Discord 是一个专为社区设计的免费语音、视频和文本聊天应用。PicoClaw 通过 Discord Bot API 连接到 Discord 服务器，支持接收和发送消息。
diff --git a/docs/channels/feishu/README.fr.md b/docs/channels/feishu/README.fr.md
new file mode 100644
index 000000000..f1ff26480
--- /dev/null
+++ b/docs/channels/feishu/README.fr.md
@@ -0,0 +1,52 @@
+> Retour au [README](../../../README.fr.md)
+
+# Feishu
+
+Feishu (nom international : Lark) est une plateforme de collaboration d'entreprise de ByteDance. Elle prend en charge les marchés chinois et mondiaux via des connexions WebSocket pilotées par événements.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "app_id": "cli_xxx",
+      "app_secret": "xxx",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Champ                 | Type   | Requis | Description                                                                 |
+| --------------------- | ------ | ------ | --------------------------------------------------------------------------- |
+| enabled               | bool   | Oui    | Activer ou non le canal Feishu                                              |
+| app_id                | string | Oui    | App ID de l'application Feishu (commence par `cli_`)                        |
+| app_secret            | string | Oui    | App Secret de l'application Feishu                                          |
+| encrypt_key           | string | Non    | Clé de chiffrement pour les callbacks d'événements                          |
+| verification_token    | string | Non    | Token utilisé pour la vérification des événements Webhook                   |
+| allow_from            | array  | Non    | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
+| random_reaction_emoji | array  | Non    | Liste d'emojis de réaction aléatoires ; vide utilise le "Pin" par défaut    |
+
+## Configuration initiale
+
+1. Accéder à la [plateforme ouverte Feishu](https://open.feishu.cn/) et créer une application
+2. Activer la capacité **Bot** dans les paramètres de l'application
+3. Créer une version et publier l'application (la configuration prend effet après la publication)
+4. Obtenir l'**App ID** (commence par `cli_`) et l'**App Secret**
+5. Renseigner l'App ID et l'App Secret dans le fichier de configuration PicoClaw
+6. Exécuter `picoclaw gateway` pour démarrer le service
+7. Rechercher le nom du bot dans Feishu et commencer une conversation
+
+> PicoClaw se connecte à Feishu en mode WebSocket/SDK — aucune adresse de callback publique ni URL Webhook n'est requise.
+>
+> `encrypt_key` et `verification_token` sont optionnels ; l'activation du chiffrement des événements est recommandée pour les environnements de production.
+>
+> Pour les références d'emojis personnalisés, voir : [Liste des emojis Feishu](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
+
+## Limitations de plateforme
+
+> ⚠️ **Le canal Feishu ne prend pas en charge les appareils 32 bits.** Le SDK Feishu ne fournit que des builds 64 bits. Les architectures 32 bits (armv6, armv7, mipsle, etc.) ne peuvent pas utiliser le canal Feishu. Pour la messagerie sur des appareils 32 bits, utilisez Telegram, Discord ou OneBot.
diff --git a/docs/channels/feishu/README.ja.md b/docs/channels/feishu/README.ja.md
new file mode 100644
index 000000000..4bb75a734
--- /dev/null
+++ b/docs/channels/feishu/README.ja.md
@@ -0,0 +1,52 @@
+> [README](../../../README.ja.md) に戻る
+
+# 飛書（Feishu）
+
+飛書（国際名：Lark）は ByteDance が提供するエンタープライズコラボレーションプラットフォームです。イベント駆動型の WebSocket 接続を通じて、中国および世界市場の両方をサポートします。
+
+## 設定
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "app_id": "cli_xxx",
+      "app_secret": "xxx",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| フィールド            | 型     | 必須   | 説明                                                              |
+| --------------------- | ------ | ------ | ----------------------------------------------------------------- |
+| enabled               | bool   | はい   | 飛書チャンネルを有効にするかどうか                                |
+| app_id                | string | はい   | 飛書アプリケーションの App ID（`cli_` で始まる）                  |
+| app_secret            | string | はい   | 飛書アプリケーションの App Secret                                 |
+| encrypt_key           | string | いいえ | イベントコールバックの暗号化キー                                  |
+| verification_token    | string | いいえ | Webhook イベント検証に使用するトークン                            |
+| allow_from            | array  | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可     |
+| random_reaction_emoji | array  | いいえ | ランダムに追加する絵文字のリスト。空の場合はデフォルトの "Pin" を使用 |
+
+## セットアップ手順
+
+1. [飛書オープンプラットフォーム](https://open.feishu.cn/) にアクセスしてアプリケーションを作成する
+2. アプリケーション設定で**ボット**機能を有効にする
+3. バージョンを作成してアプリケーションを公開する（公開後に設定が有効になる）
+4. **App ID**（`cli_` で始まる）と **App Secret** を取得する
+5. PicoClaw 設定ファイルに App ID と App Secret を入力する
+6. `picoclaw gateway` を実行してサービスを起動する
+7. 飛書でボット名を検索して会話を始める
+
+> PicoClaw は WebSocket/SDK モードで飛書に接続するため、公開コールバックアドレスや Webhook URL の設定は不要です。
+>
+> `encrypt_key` と `verification_token` はオプションですが、本番環境ではイベント暗号化を有効にすることを推奨します。
+>
+> カスタム絵文字の参考：[飛書絵文字リスト](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
+
+## プラットフォーム制限
+
+> ⚠️ **飛書チャネルは 32 ビットデバイスをサポートしていません。** 飛書 SDK は 64 ビットビルドのみ提供しています。armv6 / armv7 / mipsle などの 32 ビットアーキテクチャでは飛書チャネルを使用できません。32 ビットデバイスでのメッセージングには、Telegram、Discord、または OneBot をご利用ください。
diff --git a/docs/channels/feishu/README.md b/docs/channels/feishu/README.md
new file mode 100644
index 000000000..2aeaa31cb
--- /dev/null
+++ b/docs/channels/feishu/README.md
@@ -0,0 +1,52 @@
+> Back to [README](../../../README.md)
+
+# Feishu
+
+Feishu (international name: Lark) is an enterprise collaboration platform by ByteDance. It supports both Chinese and global markets through event-driven WebSocket connections.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "app_id": "cli_xxx",
+      "app_secret": "xxx",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field                 | Type   | Required | Description                                                        |
+| --------------------- | ------ | -------- | ------------------------------------------------------------------ |
+| enabled               | bool   | Yes      | Whether to enable the Feishu channel                               |
+| app_id                | string | Yes      | App ID of the Feishu application (starts with `cli_`)              |
+| app_secret            | string | Yes      | App Secret of the Feishu application                               |
+| encrypt_key           | string | No       | Encryption key for event callbacks                                 |
+| verification_token    | string | No       | Token used for Webhook event verification                          |
+| allow_from            | array  | No       | Allowlist of user IDs; empty means all users are allowed           |
+| random_reaction_emoji | array  | No       | List of random reaction emojis; empty uses the default "Pin"       |
+
+## Setup
+
+1. Go to the [Feishu Open Platform](https://open.feishu.cn/) and create an application
+2. Enable the **Bot** capability in the application settings
+3. Create a version and publish the application (configuration takes effect only after publishing)
+4. Obtain the **App ID** (starts with `cli_`) and **App Secret**
+5. Fill in the App ID and App Secret in the PicoClaw configuration file
+6. Run `picoclaw gateway` to start the service
+7. Search for the bot name in Feishu and start a conversation
+
+> PicoClaw connects to Feishu using WebSocket/SDK mode — no public callback address or Webhook URL is required.
+>
+> `encrypt_key` and `verification_token` are optional; enabling event encryption is recommended for production environments.
+>
+> For custom emoji references, see: [Feishu Emoji List](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
+
+## Platform Limitations
+
+> ⚠️ **Feishu channel does not support 32-bit devices.** The Feishu SDK only provides 64-bit builds. Devices running armv6, armv7, mipsle, or other 32-bit architectures cannot use the Feishu channel. For messaging on 32-bit devices, use Telegram, Discord, or OneBot instead.
diff --git a/docs/channels/feishu/README.pt-br.md b/docs/channels/feishu/README.pt-br.md
new file mode 100644
index 000000000..5b5fcaf68
--- /dev/null
+++ b/docs/channels/feishu/README.pt-br.md
@@ -0,0 +1,52 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# Feishu
+
+Feishu (nome internacional: Lark) é uma plataforma de colaboração empresarial da ByteDance. Suporta os mercados chinês e global por meio de conexões WebSocket orientadas a eventos.
+
+## Configuração
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "app_id": "cli_xxx",
+      "app_secret": "xxx",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Campo                 | Tipo   | Obrigatório | Descrição                                                                  |
+| --------------------- | ------ | ----------- | -------------------------------------------------------------------------- |
+| enabled               | bool   | Sim         | Se o canal Feishu deve ser habilitado                                      |
+| app_id                | string | Sim         | App ID da aplicação Feishu (começa com `cli_`)                             |
+| app_secret            | string | Sim         | App Secret da aplicação Feishu                                             |
+| encrypt_key           | string | Não         | Chave de criptografia para callbacks de eventos                            |
+| verification_token    | string | Não         | Token usado para verificação de eventos Webhook                            |
+| allow_from            | array  | Não         | Lista de IDs de usuários permitidos; vazio significa todos os usuários     |
+| random_reaction_emoji | array  | Não         | Lista de emojis de reação aleatórios; vazio usa o "Pin" padrão             |
+
+## Configuração inicial
+
+1. Acesse a [Plataforma Aberta Feishu](https://open.feishu.cn/) e crie uma aplicação
+2. Habilite a capacidade de **Bot** nas configurações da aplicação
+3. Crie uma versão e publique a aplicação (a configuração entra em vigor após a publicação)
+4. Obtenha o **App ID** (começa com `cli_`) e o **App Secret**
+5. Preencha o App ID e o App Secret no arquivo de configuração do PicoClaw
+6. Execute `picoclaw gateway` para iniciar o serviço
+7. Pesquise o nome do bot no Feishu e inicie uma conversa
+
+> O PicoClaw se conecta ao Feishu usando o modo WebSocket/SDK — nenhum endereço de callback público ou URL de Webhook é necessário.
+>
+> `encrypt_key` e `verification_token` são opcionais; recomenda-se habilitar a criptografia de eventos em ambientes de produção.
+>
+> Para referências de emojis personalizados, consulte: [Lista de Emojis do Feishu](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
+
+## Limitações de Plataforma
+
+> ⚠️ **O canal Feishu não suporta dispositivos 32 bits.** O SDK do Feishu fornece apenas builds 64 bits. Arquiteturas 32 bits (armv6, armv7, mipsle, etc.) não podem usar o canal Feishu. Para mensagens em dispositivos 32 bits, use Telegram, Discord ou OneBot.
diff --git a/docs/channels/feishu/README.vi.md b/docs/channels/feishu/README.vi.md
new file mode 100644
index 000000000..e704b7794
--- /dev/null
+++ b/docs/channels/feishu/README.vi.md
@@ -0,0 +1,52 @@
+> Quay lại [README](../../../README.vi.md)
+
+# Feishu
+
+Feishu (tên quốc tế: Lark) là nền tảng cộng tác doanh nghiệp của ByteDance. Hỗ trợ cả thị trường Trung Quốc và toàn cầu thông qua kết nối WebSocket theo hướng sự kiện.
+
+## Cấu hình
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "app_id": "cli_xxx",
+      "app_secret": "xxx",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Trường                | Kiểu   | Bắt buộc | Mô tả                                                                    |
+| --------------------- | ------ | -------- | ------------------------------------------------------------------------ |
+| enabled               | bool   | Có       | Có bật kênh Feishu hay không                                             |
+| app_id                | string | Có       | App ID của ứng dụng Feishu (bắt đầu bằng `cli_`)                        |
+| app_secret            | string | Có       | App Secret của ứng dụng Feishu                                           |
+| encrypt_key           | string | Không    | Khóa mã hóa cho callback sự kiện                                         |
+| verification_token    | string | Không    | Token dùng để xác minh sự kiện Webhook                                   |
+| allow_from            | array  | Không    | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả        |
+| random_reaction_emoji | array  | Không    | Danh sách emoji phản ứng ngẫu nhiên; để trống dùng "Pin" mặc định       |
+
+## Hướng dẫn thiết lập
+
+1. Truy cập [Nền tảng Mở Feishu](https://open.feishu.cn/) và tạo ứng dụng
+2. Bật khả năng **Bot** trong cài đặt ứng dụng
+3. Tạo phiên bản và xuất bản ứng dụng (cấu hình có hiệu lực sau khi xuất bản)
+4. Lấy **App ID** (bắt đầu bằng `cli_`) và **App Secret**
+5. Điền App ID và App Secret vào file cấu hình PicoClaw
+6. Chạy `picoclaw gateway` để khởi động dịch vụ
+7. Tìm kiếm tên bot trong Feishu và bắt đầu trò chuyện
+
+> PicoClaw kết nối với Feishu bằng chế độ WebSocket/SDK — không cần cấu hình địa chỉ callback công khai hay Webhook URL.
+>
+> `encrypt_key` và `verification_token` là tùy chọn; nên bật mã hóa sự kiện trong môi trường sản xuất.
+>
+> Tham khảo emoji tùy chỉnh: [Danh sách Emoji Feishu](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce)
+
+## Giới hạn nền tảng
+
+> ⚠️ **Kênh Feishu không hỗ trợ thiết bị 32 bit.** SDK Feishu chỉ cung cấp bản build 64 bit. Các kiến trúc 32 bit (armv6, armv7, mipsle, v.v.) không thể sử dụng kênh Feishu. Để nhắn tin trên thiết bị 32 bit, hãy dùng Telegram, Discord hoặc OneBot.
diff --git a/docs/channels/feishu/README.zh.md b/docs/channels/feishu/README.zh.md
index 310827723..6e2829547 100644
--- a/docs/channels/feishu/README.zh.md
+++ b/docs/channels/feishu/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
 # 飞书
 
 飞书（国际版名称：Lark）是字节跳动旗下的企业协作平台。它通过事件驱动的 Webhook 同时支持中国和全球市场。
@@ -13,25 +15,33 @@
       "app_secret": "xxx",
       "encrypt_key": "",
       "verification_token": "",
-      "allow_from": []
+      "allow_from": [],
+      "is_lark": false
     }
   }
 }
 ```
 
-| 字段               | 类型   | 必填 | 描述                             |
-| ------------------ | ------ | ---- | -------------------------------- |
-| enabled            | bool   | 是   | 是否启用飞书频道                 |
-| app_id             | string | 是   | 飞书应用的 App ID(以cli\_开头)   |
-| app_secret         | string | 是   | 飞书应用的 App Secret            |
-| encrypt_key        | string | 否   | 事件回调加密密钥                 |
-| verification_token | string | 否   | 用于Webhook事件验证的Token       |
-| allow_from         | array  | 否   | 用户ID白名单，空表示允许所有用户 |
+| 字段                  | 类型   | 必填 | 描述                                                                                             |
+| --------------------- | ------ | ---- | ------------------------------------------------------------------------------------------------ |
+| enabled               | bool   | 是   | 是否启用飞书频道                                                                                 |
+| app_id                | string | 是   | 飞书应用的 App ID(以cli\_开头)                                                                   |
+| app_secret            | string | 是   | 飞书应用的 App Secret                                                                            |
+| encrypt_key           | string | 否   | 事件回调加密密钥                                                                                 |
+| verification_token    | string | 否   | 用于Webhook事件验证的Token                                                                       |
+| allow_from            | array  | 否   | 用户ID白名单，空表示所有用户                                                                     |
+| random_reaction_emoji | array  | 否   | 随机添加的表情列表，空则使用默认 "Pin"                                                           |
+| is_lark               | bool   | 否   | 是否使用 Lark 国际版域名（`open.larksuite.com`），默认为 `false`（使用飞书域名 `open.feishu.cn`） |
 
 ## 设置流程
 
-1. 前往 [飞书开放平台](https://open.feishu.cn/)创建应用程序
+1. 前往 [飞书开放平台](https://open.feishu.cn/)（国际版用户请前往 [Lark 开放平台](https://open.larksuite.com/)）创建应用程序
 2. 获取 App ID 和 App Secret
 3. 配置事件订阅和Webhook URL
 4. 设置加密(可选,生产环境建议启用)
 5. 将 App ID、App Secret、Encrypt Key 和 Verification Token(如果启用加密) 填入配置文件中
+6. 自定义你希望 PicoClaw react 你消息时的表情（可选, Reference URL: [Feishu Emoji List](https://open.larkoffice.com/document/server-docs/im-v1/message-reaction/emojis-introduce))
+
+## 平台限制
+
+> ⚠️ **飞书通道不支持 32 位设备。** 飞书官方 SDK 仅提供 64 位构建，armv6 / armv7 / mipsle 等 32 位架构无法使用飞书通道。如需在 32 位设备上接入即时通讯，请改用 Telegram、Discord 或 OneBot 等通道。
diff --git a/docs/channels/line/README.fr.md b/docs/channels/line/README.fr.md
new file mode 100644
index 000000000..10bdf3e58
--- /dev/null
+++ b/docs/channels/line/README.fr.md
@@ -0,0 +1,40 @@
+> Retour au [README](../../../README.fr.md)
+
+# Line
+
+PicoClaw prend en charge LINE via l'API LINE Messaging avec des callbacks webhook.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Champ                | Type   | Requis | Description                                                              |
+| -------------------- | ------ | ------ | ------------------------------------------------------------------------ |
+| enabled              | bool   | Oui    | Activer ou non le canal LINE                                             |
+| channel_secret       | string | Oui    | Channel Secret de l'API LINE Messaging                                   |
+| channel_access_token | string | Oui    | Channel Access Token de l'API LINE Messaging                             |
+| webhook_path         | string | Non    | Chemin du webhook (par défaut : /webhook/line)                           |
+| allow_from           | array  | Non    | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs    |
+
+## Procédure de configuration
+
+1. Rendez-vous sur la [LINE Developers Console](https://developers.line.biz/console/) et créez un fournisseur de services ainsi qu'un canal Messaging API
+2. Obtenez le Channel Secret et le Channel Access Token
+3. Configurez le webhook :
+   - LINE exige que les webhooks utilisent HTTPS. Vous devez donc déployer un serveur compatible HTTPS ou utiliser un outil de proxy inverse comme ngrok pour exposer votre serveur local sur Internet
+   - PicoClaw utilise un serveur HTTP Gateway partagé pour recevoir les callbacks webhook de tous les canaux, écoutant par défaut sur 127.0.0.1:18790
+   - Définissez l'URL du webhook sur `https://your-domain.com/webhook/line`, puis configurez un proxy inverse de votre domaine externe vers le Gateway local (port par défaut 18790)
+   - Activez le webhook et vérifiez l'URL
+4. Renseignez le Channel Secret et le Channel Access Token dans le fichier de configuration
diff --git a/docs/channels/line/README.ja.md b/docs/channels/line/README.ja.md
new file mode 100644
index 000000000..0e559093a
--- /dev/null
+++ b/docs/channels/line/README.ja.md
@@ -0,0 +1,40 @@
+> [README](../../../README.ja.md) に戻る
+
+# Line
+
+PicoClaw は LINE Messaging API と Webhook コールバックを通じて LINE をサポートします。
+
+## 設定
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| フィールド           | 型     | 必須   | 説明                                                               |
+| -------------------- | ------ | ------ | ------------------------------------------------------------------ |
+| enabled              | bool   | はい   | LINE チャンネルを有効にするかどうか                                |
+| channel_secret       | string | はい   | LINE Messaging API の Channel Secret                               |
+| channel_access_token | string | はい   | LINE Messaging API の Channel Access Token                         |
+| webhook_path         | string | いいえ | Webhook のパス（デフォルト: /webhook/line）                        |
+| allow_from           | array  | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可             |
+
+## セットアップ手順
+
+1. [LINE Developers Console](https://developers.line.biz/console/) にアクセスし、サービスプロバイダーと Messaging API チャンネルを作成する
+2. Channel Secret と Channel Access Token を取得する
+3. Webhook を設定する:
+   - LINE は Webhook に HTTPS が必要なため、HTTPS 対応サーバーをデプロイするか、ngrok などのリバースプロキシツールを使用してローカルサーバーをインターネットに公開する必要があります
+   - PicoClaw は共有の Gateway HTTP サーバーを使用してすべてのチャンネルの Webhook コールバックを受信します。デフォルトのリッスンアドレスは 127.0.0.1:18790 です
+   - Webhook URL を `https://your-domain.com/webhook/line` に設定し、外部ドメインをローカルの Gateway（デフォルトポート 18790）にリバースプロキシする
+   - Webhook を有効にして URL を検証する
+4. Channel Secret と Channel Access Token を設定ファイルに入力する
diff --git a/docs/channels/line/README.md b/docs/channels/line/README.md
new file mode 100644
index 000000000..1aad18eee
--- /dev/null
+++ b/docs/channels/line/README.md
@@ -0,0 +1,40 @@
+> Back to [README](../../../README.md)
+
+# Line
+
+PicoClaw supports LINE through the LINE Messaging API with webhook callbacks.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field                | Type   | Required | Description                                                        |
+| -------------------- | ------ | -------- | ------------------------------------------------------------------ |
+| enabled              | bool   | Yes      | Whether to enable the LINE channel                                 |
+| channel_secret       | string | Yes      | Channel Secret for the LINE Messaging API                          |
+| channel_access_token | string | Yes      | Channel Access Token for the LINE Messaging API                    |
+| webhook_path         | string | No       | Webhook path (default: /webhook/line)                              |
+| allow_from           | array  | No       | User ID whitelist; empty means all users are allowed               |
+
+## Setup
+
+1. Go to the [LINE Developers Console](https://developers.line.biz/console/) and create a provider and a Messaging API channel
+2. Obtain the Channel Secret and Channel Access Token
+3. Configure the webhook:
+   - LINE requires webhooks to use HTTPS, so you need to deploy a server with HTTPS support, or use a reverse proxy tool like ngrok to expose your local server to the internet
+   - PicoClaw uses a shared Gateway HTTP server to receive webhook callbacks for all channels, listening on 127.0.0.1:18790 by default
+   - Set the Webhook URL to `https://your-domain.com/webhook/line`, then reverse-proxy your external domain to the local Gateway (default port 18790)
+   - Enable the webhook and verify the URL
+4. Fill in the Channel Secret and Channel Access Token in the configuration file
diff --git a/docs/channels/line/README.pt-br.md b/docs/channels/line/README.pt-br.md
new file mode 100644
index 000000000..b3334461f
--- /dev/null
+++ b/docs/channels/line/README.pt-br.md
@@ -0,0 +1,40 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# Line
+
+O PicoClaw suporta o LINE por meio da LINE Messaging API com callbacks de webhook.
+
+## Configuração
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Campo                | Tipo   | Obrigatório | Descrição                                                              |
+| -------------------- | ------ | ----------- | ---------------------------------------------------------------------- |
+| enabled              | bool   | Sim         | Se o canal LINE deve ser habilitado                                    |
+| channel_secret       | string | Sim         | Channel Secret da LINE Messaging API                                   |
+| channel_access_token | string | Sim         | Channel Access Token da LINE Messaging API                             |
+| webhook_path         | string | Não         | Caminho do webhook (padrão: /webhook/line)                             |
+| allow_from           | array  | Não         | Lista de permissão de IDs de usuário; vazio permite todos              |
+
+## Configuração passo a passo
+
+1. Acesse o [LINE Developers Console](https://developers.line.biz/console/) e crie um provedor de serviços e um canal Messaging API
+2. Obtenha o Channel Secret e o Channel Access Token
+3. Configure o webhook:
+   - O LINE exige que os webhooks usem HTTPS, portanto é necessário implantar um servidor com suporte a HTTPS ou usar uma ferramenta de proxy reverso como o ngrok para expor seu servidor local à internet
+   - O PicoClaw usa um servidor HTTP Gateway compartilhado para receber callbacks de webhook de todos os canais, escutando em 127.0.0.1:18790 por padrão
+   - Defina a URL do webhook como `https://your-domain.com/webhook/line` e configure um proxy reverso do seu domínio externo para o Gateway local (porta padrão 18790)
+   - Ative o webhook e verifique a URL
+4. Preencha o Channel Secret e o Channel Access Token no arquivo de configuração
diff --git a/docs/channels/line/README.vi.md b/docs/channels/line/README.vi.md
new file mode 100644
index 000000000..3e5511a84
--- /dev/null
+++ b/docs/channels/line/README.vi.md
@@ -0,0 +1,40 @@
+> Quay lại [README](../../../README.vi.md)
+
+# Line
+
+PicoClaw hỗ trợ LINE thông qua LINE Messaging API kết hợp với webhook callback.
+
+## Cấu hình
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Trường               | Kiểu   | Bắt buộc | Mô tả                                                                  |
+| -------------------- | ------ | -------- | ---------------------------------------------------------------------- |
+| enabled              | bool   | Có       | Có bật kênh LINE hay không                                             |
+| channel_secret       | string | Có       | Channel Secret của LINE Messaging API                                  |
+| channel_access_token | string | Có       | Channel Access Token của LINE Messaging API                            |
+| webhook_path         | string | Không    | Đường dẫn webhook (mặc định: /webhook/line)                            |
+| allow_from           | array  | Không    | Danh sách trắng ID người dùng; để trống cho phép tất cả                |
+
+## Quy trình thiết lập
+
+1. Truy cập [LINE Developers Console](https://developers.line.biz/console/) và tạo một nhà cung cấp dịch vụ cùng một kênh Messaging API
+2. Lấy Channel Secret và Channel Access Token
+3. Cấu hình webhook:
+   - LINE yêu cầu webhook phải sử dụng HTTPS, vì vậy bạn cần triển khai máy chủ hỗ trợ HTTPS hoặc dùng công cụ reverse proxy như ngrok để expose máy chủ cục bộ ra internet
+   - PicoClaw sử dụng máy chủ HTTP Gateway dùng chung để nhận webhook callback cho tất cả các kênh, mặc định lắng nghe tại 127.0.0.1:18790
+   - Đặt Webhook URL thành `https://your-domain.com/webhook/line`, sau đó reverse proxy tên miền bên ngoài về Gateway cục bộ (cổng mặc định 18790)
+   - Bật webhook và xác minh URL
+4. Điền Channel Secret và Channel Access Token vào file cấu hình
diff --git a/docs/channels/line/README.zh.md b/docs/channels/line/README.zh.md
index a36f622c2..0f7dd0cd8 100644
--- a/docs/channels/line/README.zh.md
+++ b/docs/channels/line/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
 # Line
 
 PicoClaw 通过 LINE Messaging API 配合 Webhook 回调功能实现对 LINE 的支持。
diff --git a/docs/channels/maixcam/README.fr.md b/docs/channels/maixcam/README.fr.md
new file mode 100644
index 000000000..8fddb203a
--- /dev/null
+++ b/docs/channels/maixcam/README.fr.md
@@ -0,0 +1,35 @@
+> Retour au [README](../../../README.fr.md)
+
+# MaixCam
+
+MaixCam est un canal dédié à la connexion aux caméras AI Sipeed MaixCAM et MaixCAM2. Il utilise des sockets TCP pour une communication bidirectionnelle et prend en charge les scénarios de déploiement d'IA en périphérie.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true,
+      "host": "0.0.0.0",
+      "port": 18790,
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Champ      | Type   | Requis | Description                                                                 |
+| ---------- | ------ | ------ | --------------------------------------------------------------------------- |
+| enabled    | bool   | Oui    | Activer ou non le canal MaixCam                                             |
+| host       | string | Oui    | Adresse d'écoute du serveur TCP                                             |
+| port       | int    | Oui    | Port d'écoute du serveur TCP                                                |
+| allow_from | array  | Non    | Liste blanche d'identifiants d'appareils ; vide signifie tous les appareils |
+
+## Cas d'utilisation
+
+Le canal MaixCam permet à PicoClaw de fonctionner comme backend IA pour les appareils en périphérie :
+
+- **Surveillance intelligente** : MaixCAM envoie des images ; PicoClaw les analyse via des modèles de vision
+- **Contrôle IoT** : Les appareils envoient des données de capteurs ; PicoClaw coordonne les réponses
+- **IA hors ligne** : Déployer PicoClaw sur un réseau local pour une inférence à faible latence
diff --git a/docs/channels/maixcam/README.ja.md b/docs/channels/maixcam/README.ja.md
new file mode 100644
index 000000000..0a5f27baa
--- /dev/null
+++ b/docs/channels/maixcam/README.ja.md
@@ -0,0 +1,35 @@
+> [README](../../../README.ja.md) に戻る
+
+# MaixCam
+
+MaixCam は、Sipeed MaixCAM および MaixCAM2 AI カメラデバイスへの接続専用チャンネルです。TCP ソケットを使用した双方向通信を実装し、エッジ AI デプロイメントシナリオをサポートします。
+
+## 設定
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true,
+      "host": "0.0.0.0",
+      "port": 18790,
+      "allow_from": []
+    }
+  }
+}
+```
+
+| フィールド | 型     | 必須   | 説明                                                          |
+| ---------- | ------ | ------ | ------------------------------------------------------------- |
+| enabled    | bool   | はい   | MaixCam チャンネルを有効にするかどうか                        |
+| host       | string | はい   | TCP サーバーのリッスンアドレス                                |
+| port       | int    | はい   | TCP サーバーのリッスンポート                                  |
+| allow_from | array  | いいえ | 許可するデバイスIDのリスト。空の場合はすべてのデバイスを許可 |
+
+## ユースケース
+
+MaixCam チャンネルにより、PicoClaw はエッジデバイスの AI バックエンドとして機能できます：
+
+- **スマート監視**：MaixCAM が画像フレームを送信し、PicoClaw がビジョンモデルで分析する
+- **IoT 制御**：デバイスがセンサーデータを送信し、PicoClaw がレスポンスを調整する
+- **オフライン AI**：ローカルネットワークに PicoClaw をデプロイして低遅延推論を実現する
diff --git a/docs/channels/maixcam/README.md b/docs/channels/maixcam/README.md
new file mode 100644
index 000000000..c22c9236f
--- /dev/null
+++ b/docs/channels/maixcam/README.md
@@ -0,0 +1,35 @@
+> Back to [README](../../../README.md)
+
+# MaixCam
+
+MaixCam is a dedicated channel for connecting to Sipeed MaixCAM and MaixCAM2 AI camera devices. It uses TCP sockets for bidirectional communication and supports edge AI deployment scenarios.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true,
+      "host": "0.0.0.0",
+      "port": 18790,
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field      | Type   | Required | Description                                                      |
+| ---------- | ------ | -------- | ---------------------------------------------------------------- |
+| enabled    | bool   | Yes      | Whether to enable the MaixCam channel                            |
+| host       | string | Yes      | TCP server listening address                                     |
+| port       | int    | Yes      | TCP server listening port                                        |
+| allow_from | array  | No       | Allowlist of device IDs; empty means all devices are allowed     |
+
+## Use Cases
+
+The MaixCam channel enables PicoClaw to act as an AI backend for edge devices:
+
+- **Smart Surveillance**: MaixCAM sends image frames; PicoClaw analyzes them using vision models
+- **IoT Control**: Devices send sensor data; PicoClaw coordinates responses
+- **Offline AI**: Deploy PicoClaw on a local network for low-latency inference
diff --git a/docs/channels/maixcam/README.pt-br.md b/docs/channels/maixcam/README.pt-br.md
new file mode 100644
index 000000000..81a1f3f00
--- /dev/null
+++ b/docs/channels/maixcam/README.pt-br.md
@@ -0,0 +1,35 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# MaixCam
+
+MaixCam é um canal dedicado para conectar dispositivos de câmera AI Sipeed MaixCAM e MaixCAM2. Utiliza sockets TCP para comunicação bidirecional e suporta cenários de implantação de IA na borda.
+
+## Configuração
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true,
+      "host": "0.0.0.0",
+      "port": 18790,
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Campo      | Tipo   | Obrigatório | Descrição                                                                  |
+| ---------- | ------ | ----------- | -------------------------------------------------------------------------- |
+| enabled    | bool   | Sim         | Se o canal MaixCam deve ser habilitado                                     |
+| host       | string | Sim         | Endereço de escuta do servidor TCP                                         |
+| port       | int    | Sim         | Porta de escuta do servidor TCP                                            |
+| allow_from | array  | Não         | Lista de IDs de dispositivos permitidos; vazio significa todos os dispositivos |
+
+## Casos de uso
+
+O canal MaixCam permite que o PicoClaw atue como backend de IA para dispositivos de borda:
+
+- **Vigilância inteligente**: MaixCAM envia quadros de imagem; PicoClaw os analisa usando modelos de visão
+- **Controle IoT**: Dispositivos enviam dados de sensores; PicoClaw coordena as respostas
+- **IA offline**: Implante o PicoClaw em uma rede local para inferência de baixa latência
diff --git a/docs/channels/maixcam/README.vi.md b/docs/channels/maixcam/README.vi.md
new file mode 100644
index 000000000..8955bae86
--- /dev/null
+++ b/docs/channels/maixcam/README.vi.md
@@ -0,0 +1,35 @@
+> Quay lại [README](../../../README.vi.md)
+
+# MaixCam
+
+MaixCam là kênh chuyên dụng để kết nối với các thiết bị camera AI Sipeed MaixCAM và MaixCAM2. Sử dụng TCP socket để giao tiếp hai chiều và hỗ trợ các kịch bản triển khai AI tại biên.
+
+## Cấu hình
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true,
+      "host": "0.0.0.0",
+      "port": 18790,
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Trường     | Kiểu   | Bắt buộc | Mô tả                                                                    |
+| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
+| enabled    | bool   | Có       | Có bật kênh MaixCam hay không                                            |
+| host       | string | Có       | Địa chỉ lắng nghe của máy chủ TCP                                        |
+| port       | int    | Có       | Cổng lắng nghe của máy chủ TCP                                           |
+| allow_from | array  | Không    | Danh sách trắng ID thiết bị; để trống nghĩa là cho phép tất cả thiết bị  |
+
+## Trường hợp sử dụng
+
+Kênh MaixCam cho phép PicoClaw hoạt động như backend AI cho các thiết bị biên:
+
+- **Giám sát thông minh**: MaixCAM gửi khung hình ảnh; PicoClaw phân tích bằng mô hình thị giác
+- **Điều khiển IoT**: Thiết bị gửi dữ liệu cảm biến; PicoClaw điều phối phản hồi
+- **AI ngoại tuyến**: Triển khai PicoClaw trên mạng nội bộ để suy luận độ trễ thấp
diff --git a/docs/channels/maixcam/README.zh.md b/docs/channels/maixcam/README.zh.md
index 8d53d4bef..b0d58e733 100644
--- a/docs/channels/maixcam/README.zh.md
+++ b/docs/channels/maixcam/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
 # MaixCam
 
 MaixCam 是专用于连接矽速科技 MaixCAM 与 MaixCAM2 AI 摄像设备的通道。它采用 TCP 套接字实现双向通信，支持边缘 AI 部署场景。
@@ -9,18 +11,20 @@ MaixCam 是专用于连接矽速科技 MaixCAM 与 MaixCAM2 AI 摄像设备的
   "channels": {
     "maixcam": {
       "enabled": true,
-      "server_address": "0.0.0.0:8899",
+      "host": "0.0.0.0",
+      "port": 18790,
       "allow_from": []
     }
   }
 }
 ```
 
-| 字段           | 类型   | 必填 | 描述                             |
-| -------------- | ------ | ---- | -------------------------------- |
-| enabled        | bool   | 是   | 是否启用 MaixCam 频道            |
-| server_address | string | 是   | TCP 服务器监听地址和端口         |
-| allow_from     | array  | 否   | 设备ID白名单，空表示允许所有设备 |
+| 字段       | 类型   | 必填 | 描述                             |
+| ---------- | ------ | ---- | -------------------------------- |
+| enabled    | bool   | 是   | 是否启用 MaixCam 频道            |
+| host       | string | 是   | TCP 服务器监听地址               |
+| port       | int    | 是   | TCP 服务器监听端口               |
+| allow_from | array  | 否   | 设备ID白名单，空表示允许所有设备 |
 
 ## 使用场景
 
diff --git a/docs/channels/matrix/README.fr.md b/docs/channels/matrix/README.fr.md
new file mode 100644
index 000000000..ec762a8b8
--- /dev/null
+++ b/docs/channels/matrix/README.fr.md
@@ -0,0 +1,64 @@
+> Retour au [README](../../../README.fr.md)
+
+# Guide de configuration du canal Matrix
+
+## 1. Exemple de configuration
+
+Ajoutez ceci à `config.json` :
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "device_id": "",
+      "join_on_invite": true,
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "placeholder": {
+        "enabled": true,
+        "text": "Thinking..."
+      },
+      "reasoning_channel_id": "",
+      "message_format": "richtext"
+    }
+  }
+}
+```
+
+## 2. Référence des champs
+
+| Champ                | Type     | Requis | Description |
+|----------------------|----------|--------|-------------|
+| enabled              | bool     | Oui    | Activer ou désactiver le canal Matrix |
+| homeserver           | string   | Oui    | URL du homeserver Matrix (par exemple `https://matrix.org`) |
+| user_id              | string   | Oui    | ID utilisateur Matrix du bot (par exemple `@bot:matrix.org`) |
+| access_token         | string   | Oui    | Jeton d'accès du bot |
+| device_id            | string   | Non    | ID d'appareil Matrix optionnel |
+| join_on_invite       | bool     | Non    | Rejoindre automatiquement les salons invités |
+| allow_from           | []string | Non    | Liste blanche d'utilisateurs (IDs Matrix) |
+| group_trigger        | object   | Non    | Stratégie de déclenchement de groupe (`mention_only` / `prefixes`) |
+| placeholder          | object   | Non    | Configuration du message de remplacement |
+| reasoning_channel_id | string   | Non    | Canal cible pour la sortie de raisonnement |
+| message_format       | string   | Non    | Format de sortie : `"richtext"` (défaut) rend le markdown en HTML ; `"plain"` envoie du texte brut uniquement |
+
+## 3. Fonctionnalités actuellement supportées
+
+- Envoi/réception de messages texte avec rendu markdown (gras, italique, titres, blocs de code, etc.)
+- Format de message configurable (`richtext` / `plain`)
+- Téléchargement d'images/audio/vidéo/fichiers entrants (MediaStore en priorité, chemin local en secours)
+- Normalisation de l'audio entrant dans le flux de transcription existant (`[audio: ...]`)
+- Upload et envoi d'images/audio/vidéo/fichiers sortants
+- Règles de déclenchement de groupe (y compris le mode mention uniquement)
+- État de frappe (`m.typing`)
+- Message de remplacement + remplacement de la réponse finale
+- Rejoindre automatiquement les salons invités (peut être désactivé)
+
+## 4. TODO
+
+- Améliorations des métadonnées des médias riches (par exemple taille et miniatures des images/vidéos)
diff --git a/docs/channels/matrix/README.ja.md b/docs/channels/matrix/README.ja.md
new file mode 100644
index 000000000..e5a773d4d
--- /dev/null
+++ b/docs/channels/matrix/README.ja.md
@@ -0,0 +1,64 @@
+> [README](../../../README.ja.md) に戻る
+
+# Matrix チャンネル設定ガイド
+
+## 1. 設定例
+
+`config.json` に以下を追加してください：
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "device_id": "",
+      "join_on_invite": true,
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "placeholder": {
+        "enabled": true,
+        "text": "Thinking..."
+      },
+      "reasoning_channel_id": "",
+      "message_format": "richtext"
+    }
+  }
+}
+```
+
+## 2. フィールドリファレンス
+
+| フィールド           | 型       | 必須 | 説明 |
+|----------------------|----------|------|------|
+| enabled              | bool     | はい | Matrix チャンネルの有効/無効 |
+| homeserver           | string   | はい | Matrix ホームサーバー URL（例：`https://matrix.org`） |
+| user_id              | string   | はい | ボットの Matrix ユーザー ID（例：`@bot:matrix.org`） |
+| access_token         | string   | はい | ボットのアクセストークン |
+| device_id            | string   | いいえ | オプションの Matrix デバイス ID |
+| join_on_invite       | bool     | いいえ | 招待されたルームに自動参加 |
+| allow_from           | []string | いいえ | ユーザーホワイトリスト（Matrix ユーザー ID） |
+| group_trigger        | object   | いいえ | グループトリガー戦略（`mention_only` / `prefixes`） |
+| placeholder          | object   | いいえ | プレースホルダーメッセージ設定 |
+| reasoning_channel_id | string   | いいえ | 推論出力のターゲットチャンネル |
+| message_format       | string   | いいえ | 出力形式：`"richtext"`（デフォルト）は markdown を HTML としてレンダリング；`"plain"` はプレーンテキストのみ送信 |
+
+## 3. 現在サポートされている機能
+
+- markdown レンダリング付きテキストメッセージ送受信（太字、斜体、見出し、コードブロックなど）
+- 設定可能なメッセージ形式（`richtext` / `plain`）
+- 受信画像/音声/動画/ファイルのダウンロード（MediaStore 優先、ローカルパスフォールバック）
+- 受信音声の既存文字起こしフローへの正規化（`[audio: ...]`）
+- 送信画像/音声/動画/ファイルのアップロードと送信
+- グループトリガールール（メンションのみモードを含む）
+- タイピング状態（`m.typing`）
+- プレースホルダーメッセージ + 最終返信の置き換え
+- 招待されたルームへの自動参加（無効化可能）
+
+## 4. TODO
+
+- リッチメディアメタデータの改善（例：画像/動画のサイズとサムネイル）
diff --git a/docs/channels/matrix/README.md b/docs/channels/matrix/README.md
new file mode 100644
index 000000000..dd4b45eba
--- /dev/null
+++ b/docs/channels/matrix/README.md
@@ -0,0 +1,69 @@
+> Back to [README](../../../README.md)
+
+# Matrix Channel Configuration Guide
+
+## 1. Example Configuration
+
+Add this to `config.json`:
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "device_id": "",
+      "join_on_invite": true,
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "placeholder": {
+        "enabled": true,
+        "text": "Thinking..."
+      },
+      "reasoning_channel_id": "",
+      "message_format": "richtext",
+      "crypto_database_path": "",
+      "crypto_passphrase": "YOUR_MATRIX_CRYPTO_PICKLE_KEY"
+    }
+  }
+}
+```
+
+## 2. Field Reference
+
+| Field                | Type     | Required | Description |
+|----------------------|----------|----------|-------------|
+| enabled              | bool     | Yes      | Enable or disable the Matrix channel |
+| homeserver           | string   | Yes      | Matrix homeserver URL (for example `https://matrix.org`) |
+| user_id              | string   | Yes      | Bot Matrix user ID (for example `@bot:matrix.org`) |
+| access_token         | string   | Yes      | Bot access token |
+| device_id            | string   | No       | Optional Matrix device ID |
+| join_on_invite       | bool     | No       | Auto-join invited rooms |
+| allow_from           | []string | No       | User whitelist (Matrix user IDs) |
+| group_trigger        | object   | No       | Group trigger strategy (`mention_only` / `prefixes`) |
+| placeholder          | object   | No       | Placeholder message config |
+| reasoning_channel_id | string   | No       | Target channel for reasoning output |
+| message_format       | string   | No       | Output format: `"richtext"` (default) renders markdown as HTML; `"plain"` sends plain text only |
+| crypto_database_path | string   | No       | Path to store the crypto database (uses workspace path `~/.picoclaw/workspace` if empty) |
+| crypto_passphrase    | string   | No       | Serialization key for encrypting session keys in the database; must remain unchanged once set |
+
+## 3. Currently Supported
+
+- Text message send/receive with markdown rendering (bold, italic, headers, code blocks, etc.)
+- Configurable message format (`richtext` / `plain`)
+- Incoming image/audio/video/file download (MediaStore first, local path fallback)
+- Incoming audio normalization into existing transcription flow (`[audio: ...]`)
+- Outgoing image/audio/video/file upload and send
+- Group trigger rules (including mention-only mode)
+- Typing state (`m.typing`)
+- Placeholder message + final reply replacement
+- Auto-join invited rooms (can be disabled)
+- End-to-end encryption (E2EE) support for encrypted messages
+
+## 4. TODO
+
+- Rich media metadata improvements (for example image/video size and thumbnails)
diff --git a/docs/channels/matrix/README.pt-br.md b/docs/channels/matrix/README.pt-br.md
new file mode 100644
index 000000000..11a9aaa11
--- /dev/null
+++ b/docs/channels/matrix/README.pt-br.md
@@ -0,0 +1,64 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# Guia de Configuração do Canal Matrix
+
+## 1. Exemplo de Configuração
+
+Adicione isto ao `config.json`:
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "device_id": "",
+      "join_on_invite": true,
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "placeholder": {
+        "enabled": true,
+        "text": "Thinking..."
+      },
+      "reasoning_channel_id": "",
+      "message_format": "richtext"
+    }
+  }
+}
+```
+
+## 2. Referência de Campos
+
+| Campo                | Tipo     | Obrigatório | Descrição |
+|----------------------|----------|-------------|-----------|
+| enabled              | bool     | Sim         | Habilitar ou desabilitar o canal Matrix |
+| homeserver           | string   | Sim         | URL do homeserver Matrix (por exemplo `https://matrix.org`) |
+| user_id              | string   | Sim         | ID de usuário Matrix do bot (por exemplo `@bot:matrix.org`) |
+| access_token         | string   | Sim         | Token de acesso do bot |
+| device_id            | string   | Não         | ID de dispositivo Matrix opcional |
+| join_on_invite       | bool     | Não         | Entrar automaticamente em salas convidadas |
+| allow_from           | []string | Não         | Lista branca de usuários (IDs Matrix) |
+| group_trigger        | object   | Não         | Estratégia de gatilho de grupo (`mention_only` / `prefixes`) |
+| placeholder          | object   | Não         | Configuração de mensagem de espaço reservado |
+| reasoning_channel_id | string   | Não         | Canal alvo para saída de raciocínio |
+| message_format       | string   | Não         | Formato de saída: `"richtext"` (padrão) renderiza markdown como HTML; `"plain"` envia apenas texto simples |
+
+## 3. Suporte Atual
+
+- Envio/recebimento de mensagens de texto com renderização markdown (negrito, itálico, cabeçalhos, blocos de código, etc.)
+- Formato de mensagem configurável (`richtext` / `plain`)
+- Download de imagens/áudio/vídeo/arquivos recebidos (MediaStore primeiro, fallback para caminho local)
+- Normalização de áudio recebido no fluxo de transcrição existente (`[audio: ...]`)
+- Upload e envio de imagens/áudio/vídeo/arquivos de saída
+- Regras de gatilho de grupo (incluindo modo somente menção)
+- Estado de digitação (`m.typing`)
+- Mensagem de espaço reservado + substituição de resposta final
+- Entrada automática em salas convidadas (pode ser desabilitado)
+
+## 4. TODO
+
+- Melhorias nos metadados de mídia rica (por exemplo tamanho e miniaturas de imagens/vídeos)
diff --git a/docs/channels/matrix/README.vi.md b/docs/channels/matrix/README.vi.md
new file mode 100644
index 000000000..f1272076f
--- /dev/null
+++ b/docs/channels/matrix/README.vi.md
@@ -0,0 +1,64 @@
+> Quay lại [README](../../../README.vi.md)
+
+# Hướng dẫn Cấu hình Kênh Matrix
+
+## 1. Cấu hình Mẫu
+
+Thêm vào `config.json`:
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "device_id": "",
+      "join_on_invite": true,
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "placeholder": {
+        "enabled": true,
+        "text": "Thinking..."
+      },
+      "reasoning_channel_id": "",
+      "message_format": "richtext"
+    }
+  }
+}
+```
+
+## 2. Tham chiếu Trường
+
+| Trường               | Kiểu     | Bắt buộc | Mô tả |
+|----------------------|----------|----------|-------|
+| enabled              | bool     | Có       | Bật hoặc tắt kênh Matrix |
+| homeserver           | string   | Có       | URL homeserver Matrix (ví dụ `https://matrix.org`) |
+| user_id              | string   | Có       | ID người dùng Matrix của bot (ví dụ `@bot:matrix.org`) |
+| access_token         | string   | Có       | Token truy cập của bot |
+| device_id            | string   | Không    | ID thiết bị Matrix tùy chọn |
+| join_on_invite       | bool     | Không    | Tự động tham gia phòng được mời |
+| allow_from           | []string | Không    | Danh sách trắng người dùng (ID Matrix) |
+| group_trigger        | object   | Không    | Chiến lược kích hoạt nhóm (`mention_only` / `prefixes`) |
+| placeholder          | object   | Không    | Cấu hình tin nhắn giữ chỗ |
+| reasoning_channel_id | string   | Không    | Kênh đích cho đầu ra suy luận |
+| message_format       | string   | Không    | Định dạng đầu ra: `"richtext"` (mặc định) render markdown thành HTML; `"plain"` chỉ gửi văn bản thuần |
+
+## 3. Tính năng Hiện tại
+
+- Gửi/nhận tin nhắn văn bản với render markdown (đậm, nghiêng, tiêu đề, khối code, v.v.)
+- Định dạng tin nhắn có thể cấu hình (`richtext` / `plain`)
+- Tải xuống hình ảnh/âm thanh/video/tệp đến (MediaStore trước, fallback đường dẫn cục bộ)
+- Chuẩn hóa âm thanh đến vào luồng phiên âm hiện có (`[audio: ...]`)
+- Tải lên và gửi hình ảnh/âm thanh/video/tệp đi
+- Quy tắc kích hoạt nhóm (bao gồm chế độ chỉ đề cập)
+- Trạng thái đang gõ (`m.typing`)
+- Tin nhắn giữ chỗ + thay thế phản hồi cuối cùng
+- Tự động tham gia phòng được mời (có thể tắt)
+
+## 4. TODO
+
+- Cải thiện metadata phương tiện phong phú (ví dụ kích thước và hình thu nhỏ hình ảnh/video)
diff --git a/docs/channels/matrix/README.zh.md b/docs/channels/matrix/README.zh.md
new file mode 100644
index 000000000..cd68a057e
--- /dev/null
+++ b/docs/channels/matrix/README.zh.md
@@ -0,0 +1,68 @@
+> 返回 [README](../../../README.zh.md)
+
+# Matrix 通道配置指南
+
+## 1. 配置示例
+
+在 `config.json` 中添加：
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "device_id": "",
+      "join_on_invite": true,
+      "allow_from": [],
+      "group_trigger": {
+        "mention_only": true
+      },
+      "placeholder": {
+        "enabled": true,
+        "text": "Thinking... 💭"
+      },
+      "reasoning_channel_id": "",
+      "message_format": "richtext",
+      "crypto_database_path": "",
+      "crypto_passphrase": "YOUR_MATRIX_CRYPTO_PICKLE_KEY"
+    }
+  }
+}
+```
+
+## 2. 参数说明
+
+| 字段                 | 类型     | 必填 | 说明 |
+|----------------------|----------|------|------|
+| enabled              | bool     | 是   | 是否启用 Matrix 通道 |
+| homeserver           | string   | 是   | Matrix 服务器地址（例如 `https://matrix.org`） |
+| user_id              | string   | 是   | 机器人 Matrix 用户 ID（例如 `@bot:matrix.org`） |
+| access_token         | string   | 是   | 机器人 access token |
+| device_id            | string   | 否   | 设备 ID（可选） |
+| join_on_invite       | bool     | 否   | 是否自动加入邀请房间 |
+| allow_from           | []string | 否   | 白名单用户（Matrix 用户 ID） |
+| group_trigger        | object   | 否   | 群聊触发策略（支持 `mention_only` / `prefixes`） |
+| placeholder          | object   | 否   | 占位消息配置 |
+| reasoning_channel_id | string   | 否   | 思维链输出目标通道 |
+| message_format       | string   | 否   | 消息格式：`richtext`（富文本）或 `plain`（纯文本） |
+| crypto_database_path | string   | 否   | 加密数据库存储路径（为空时使用工作空间路径 `~/.picoclaw/workspace`） |
+| crypto_passphrase    | string   | 否   | 加密数据库中 session key 的序列化密钥；设置后不能更改 |
+
+## 3. 当前支持
+
+- 文本消息收发
+- 图片/音频/视频/文件消息入站下载（写入 MediaStore / 本地路径回退）
+- 音频消息按统一标记进入现有转写流程（`[audio: ...]`）
+- 图片/音频/视频/文件消息出站发送（上传到 Matrix 媒体库后发送）
+- 群聊触发规则（支持仅 @ 提及时响应）
+- Typing 状态（`m.typing`）
+- 占位消息（`Thinking... 💭`）+ 最终回复替换
+- 自动加入邀请房间（可关闭）
+- 端对端加密（E2EE）消息支持
+
+## 4. TODO
+
+- 富媒体细节增强（如 image/video 的尺寸、缩略图等 metadata）
diff --git a/docs/channels/onebot/README.fr.md b/docs/channels/onebot/README.fr.md
new file mode 100644
index 000000000..7c9ffe1d3
--- /dev/null
+++ b/docs/channels/onebot/README.fr.md
@@ -0,0 +1,33 @@
+> Retour au [README](../../../README.fr.md)
+
+# OneBot
+
+OneBot est un standard de protocole ouvert pour les bots QQ, fournissant une interface unifiée pour diverses implémentations de bots QQ (par exemple go-cqhttp, Mirai). Il utilise WebSocket pour la communication.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://localhost:8080",
+      "access_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Champ        | Type   | Requis | Description                                                          |
+| ------------ | ------ | ------ | -------------------------------------------------------------------- |
+| enabled      | bool   | Oui    | Activer ou non le canal OneBot                                       |
+| ws_url       | string | Oui    | URL WebSocket du serveur OneBot                                      |
+| access_token | string | Non    | Jeton d'accès pour la connexion au serveur OneBot                    |
+| allow_from   | array  | Non    | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs |
+
+## Procédure de configuration
+
+1. Déployez une implémentation compatible OneBot (par exemple napcat)
+2. Configurez l'implémentation OneBot pour activer le service WebSocket et définir un jeton d'accès (si nécessaire)
+3. Renseignez l'URL WebSocket et le jeton d'accès dans le fichier de configuration
diff --git a/docs/channels/onebot/README.ja.md b/docs/channels/onebot/README.ja.md
new file mode 100644
index 000000000..ce628572b
--- /dev/null
+++ b/docs/channels/onebot/README.ja.md
@@ -0,0 +1,33 @@
+> [README](../../../README.ja.md) に戻る
+
+# OneBot
+
+OneBot は QQ ボット向けのオープンプロトコル標準で、複数の QQ ボット実装（例: go-cqhttp、Mirai）に統一されたインターフェースを提供します。通信には WebSocket を使用します。
+
+## 設定
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://localhost:8080",
+      "access_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| フィールド   | 型     | 必須   | 説明                                                             |
+| ------------ | ------ | ------ | ---------------------------------------------------------------- |
+| enabled      | bool   | はい   | OneBot チャンネルを有効にするかどうか                            |
+| ws_url       | string | はい   | OneBot サーバーの WebSocket URL                                  |
+| access_token | string | いいえ | OneBot サーバーへの接続に使用するアクセストークン                |
+| allow_from   | array  | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可           |
+
+## セットアップ手順
+
+1. OneBot 互換の実装（例: napcat）をデプロイする
+2. OneBot 実装で WebSocket サービスを有効にし、アクセストークンを設定する（必要な場合）
+3. WebSocket URL とアクセストークンを設定ファイルに入力する
diff --git a/docs/channels/onebot/README.md b/docs/channels/onebot/README.md
new file mode 100644
index 000000000..42af39b4e
--- /dev/null
+++ b/docs/channels/onebot/README.md
@@ -0,0 +1,33 @@
+> Back to [README](../../../README.md)
+
+# OneBot
+
+OneBot is an open protocol standard for QQ bots, providing a unified interface for various QQ bot implementations (e.g. go-cqhttp, Mirai). It uses WebSocket for communication.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://localhost:8080",
+      "access_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field        | Type   | Required | Description                                                      |
+| ------------ | ------ | -------- | ---------------------------------------------------------------- |
+| enabled      | bool   | Yes      | Whether to enable the OneBot channel                             |
+| ws_url       | string | Yes      | WebSocket URL of the OneBot server                               |
+| access_token | string | No       | Access token for connecting to the OneBot server                 |
+| allow_from   | array  | No       | User ID whitelist; empty means all users are allowed             |
+
+## Setup
+
+1. Deploy a OneBot-compatible implementation (e.g. napcat)
+2. Configure the OneBot implementation to enable the WebSocket service and set an access token (if needed)
+3. Fill in the WebSocket URL and access token in the configuration file
diff --git a/docs/channels/onebot/README.pt-br.md b/docs/channels/onebot/README.pt-br.md
new file mode 100644
index 000000000..5323163ee
--- /dev/null
+++ b/docs/channels/onebot/README.pt-br.md
@@ -0,0 +1,33 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# OneBot
+
+OneBot é um padrão de protocolo aberto para bots QQ, fornecendo uma interface unificada para diversas implementações de bots QQ (ex.: go-cqhttp, Mirai). Utiliza WebSocket para comunicação.
+
+## Configuração
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://localhost:8080",
+      "access_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Campo        | Tipo   | Obrigatório | Descrição                                                            |
+| ------------ | ------ | ----------- | -------------------------------------------------------------------- |
+| enabled      | bool   | Sim         | Se o canal OneBot deve ser habilitado                                |
+| ws_url       | string | Sim         | URL WebSocket do servidor OneBot                                     |
+| access_token | string | Não         | Token de acesso para conexão ao servidor OneBot                      |
+| allow_from   | array  | Não         | Lista de permissão de IDs de usuário; vazio permite todos            |
+
+## Configuração passo a passo
+
+1. Implante uma implementação compatível com OneBot (ex.: napcat)
+2. Configure a implementação OneBot para habilitar o serviço WebSocket e definir um token de acesso (se necessário)
+3. Preencha a URL WebSocket e o token de acesso no arquivo de configuração
diff --git a/docs/channels/onebot/README.vi.md b/docs/channels/onebot/README.vi.md
new file mode 100644
index 000000000..a572e7afa
--- /dev/null
+++ b/docs/channels/onebot/README.vi.md
@@ -0,0 +1,33 @@
+> Quay lại [README](../../../README.vi.md)
+
+# OneBot
+
+OneBot là tiêu chuẩn giao thức mở dành cho bot QQ, cung cấp giao diện thống nhất cho nhiều triển khai bot QQ khác nhau (ví dụ: go-cqhttp, Mirai). Nó sử dụng WebSocket để giao tiếp.
+
+## Cấu hình
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://localhost:8080",
+      "access_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Trường       | Kiểu   | Bắt buộc | Mô tả                                                                |
+| ------------ | ------ | -------- | -------------------------------------------------------------------- |
+| enabled      | bool   | Có       | Có bật kênh OneBot hay không                                         |
+| ws_url       | string | Có       | URL WebSocket của máy chủ OneBot                                     |
+| access_token | string | Không    | Token truy cập để kết nối với máy chủ OneBot                         |
+| allow_from   | array  | Không    | Danh sách trắng ID người dùng; để trống cho phép tất cả              |
+
+## Quy trình thiết lập
+
+1. Triển khai một bản triển khai tương thích OneBot (ví dụ: napcat)
+2. Cấu hình bản triển khai OneBot để bật dịch vụ WebSocket và đặt token truy cập (nếu cần)
+3. Điền URL WebSocket và token truy cập vào file cấu hình
diff --git a/docs/channels/onebot/README.zh.md b/docs/channels/onebot/README.zh.md
index 6195f1c98..8caba0b80 100644
--- a/docs/channels/onebot/README.zh.md
+++ b/docs/channels/onebot/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
 # OneBot
 
 OneBot 是一个面向 QQ 机器人的开放协议标准，为多种 QQ 机器人实现（例如 go-cqhttp、Mirai）提供了统一的接口。它使用 WebSocket 进行通信。
diff --git a/docs/channels/qq/README.fr.md b/docs/channels/qq/README.fr.md
new file mode 100644
index 000000000..38de1b751
--- /dev/null
+++ b/docs/channels/qq/README.fr.md
@@ -0,0 +1,54 @@
+> Retour au [README](../../../README.fr.md)
+
+# QQ
+
+PicoClaw prend en charge QQ via l'API Bot officielle de la plateforme ouverte QQ.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Champ      | Type   | Requis | Description                                                                 |
+| ---------- | ------ | ------ | --------------------------------------------------------------------------- |
+| enabled    | bool   | Oui    | Activer ou non le canal QQ                                                  |
+| app_id     | string | Oui    | App ID de l'application bot QQ                                              |
+| app_secret | string | Oui    | App Secret de l'application bot QQ                                          |
+| allow_from | array  | Non    | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
+
+## Configuration initiale
+
+### Configuration rapide (recommandée)
+
+La plateforme ouverte QQ propose une entrée de création en un clic :
+
+1. Ouvrir [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) et se connecter en scannant le QR code
+2. Le système crée automatiquement un bot — copier l'**App ID** et l'**App Secret**
+3. Renseigner les identifiants dans le fichier de configuration PicoClaw
+4. Exécuter `picoclaw gateway` pour démarrer le service
+5. Ouvrir QQ et commencer à discuter avec le bot
+
+> L'App Secret n'est affiché qu'une seule fois — sauvegardez-le immédiatement. Le consulter à nouveau forcera une réinitialisation.
+>
+> Les bots créés via l'entrée rapide sont réservés à l'usage personnel du créateur et ne prennent pas en charge les discussions de groupe. Pour la prise en charge des groupes, configurez le mode sandbox sur la [plateforme ouverte QQ](https://q.qq.com/).
+
+### Configuration manuelle
+
+1. Se connecter à la [plateforme ouverte QQ](https://q.qq.com/) avec son compte QQ et s'inscrire en tant que développeur
+2. Créer un bot QQ et personnaliser son avatar et son nom
+3. Obtenir l'**App ID** et l'**App Secret** dans les paramètres du bot
+4. Renseigner les identifiants dans le fichier de configuration PicoClaw
+5. Exécuter `picoclaw gateway` pour démarrer le service
+6. Rechercher votre bot dans QQ et commencer à discuter
+
+> Pendant le développement, il est recommandé d'activer le mode sandbox et d'y ajouter les utilisateurs et groupes de test pour le débogage.
diff --git a/docs/channels/qq/README.ja.md b/docs/channels/qq/README.ja.md
new file mode 100644
index 000000000..2990f9622
--- /dev/null
+++ b/docs/channels/qq/README.ja.md
@@ -0,0 +1,54 @@
+> [README](../../../README.ja.md) に戻る
+
+# QQ
+
+PicoClaw は QQ オープンプラットフォームの公式 Bot API を通じて QQ をサポートします。
+
+## 設定
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| フィールド | 型     | 必須   | 説明                                                          |
+| ---------- | ------ | ------ | ------------------------------------------------------------- |
+| enabled    | bool   | はい   | QQ チャンネルを有効にするかどうか                             |
+| app_id     | string | はい   | QQ ボットアプリケーションの App ID                            |
+| app_secret | string | はい   | QQ ボットアプリケーションの App Secret                        |
+| allow_from | array  | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可 |
+
+## セットアップ手順
+
+### クイックセットアップ（推奨）
+
+QQ オープンプラットフォームにはワンクリック作成エントリーが用意されています：
+
+1. [QQ ボットクイック作成](https://q.qq.com/qqbot/openclaw/index.html) を開き、QR コードをスキャンしてログインする
+2. システムが自動的にボットを作成するので、**App ID** と **App Secret** をコピーする
+3. PicoClaw 設定ファイルに認証情報を入力する
+4. `picoclaw gateway` を実行してサービスを起動する
+5. QQ を開いてボットとの会話を始める
+
+> App Secret は一度しか表示されません。すぐに保存してください。再度表示しようとすると強制的にリセットされます。
+>
+> クイックエントリーで作成したボットは作成者本人のみが使用でき、グループチャットには対応していません。グループチャット機能が必要な場合は、[QQ オープンプラットフォーム](https://q.qq.com/) でサンドボックスモードを設定してください。
+
+### 手動セットアップ
+
+1. QQ アカウントで [QQ オープンプラットフォーム](https://q.qq.com/) にログインし、開発者アカウントを登録する
+2. QQ ボットを作成し、アバターと名前をカスタマイズする
+3. ボット設定から **App ID** と **App Secret** を取得する
+4. PicoClaw 設定ファイルに認証情報を入力する
+5. `picoclaw gateway` を実行してサービスを起動する
+6. QQ でボットを検索して会話を始める
+
+> 開発段階ではサンドボックスモードを有効にし、テストユーザーとグループをサンドボックスに追加してデバッグすることを推奨します。
diff --git a/docs/channels/qq/README.md b/docs/channels/qq/README.md
new file mode 100644
index 000000000..35e4a769c
--- /dev/null
+++ b/docs/channels/qq/README.md
@@ -0,0 +1,54 @@
+> Back to [README](../../../README.md)
+
+# QQ
+
+PicoClaw provides QQ support via the official Bot API from the QQ Open Platform.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field      | Type   | Required | Description                                              |
+| ---------- | ------ | -------- | -------------------------------------------------------- |
+| enabled    | bool   | Yes      | Whether to enable the QQ channel                         |
+| app_id     | string | Yes      | App ID of the QQ bot application                         |
+| app_secret | string | Yes      | App Secret of the QQ bot application                     |
+| allow_from | array  | No       | Allowlist of user IDs; empty means all users are allowed |
+
+## Setup
+
+### Quick Setup (Recommended)
+
+The QQ Open Platform provides a one-click creation entry:
+
+1. Open [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) and log in by scanning the QR code
+2. The system automatically creates a bot — copy the **App ID** and **App Secret**
+3. Fill in the credentials in the PicoClaw configuration file
+4. Run `picoclaw gateway` to start the service
+5. Open QQ and start chatting with the bot
+
+> The App Secret is only shown once — save it immediately. Viewing it again will force a reset.
+>
+> Bots created via the quick entry are for the creator's personal use only and do not support group chats. For group chat support, configure sandbox mode on the [QQ Open Platform](https://q.qq.com/).
+
+### Manual Setup
+
+1. Log in to the [QQ Open Platform](https://q.qq.com/) with your QQ account and register as a developer
+2. Create a QQ bot and customize its avatar and name
+3. Obtain the **App ID** and **App Secret** from the bot settings
+4. Fill in the credentials in the PicoClaw configuration file
+5. Run `picoclaw gateway` to start the service
+6. Search for your bot in QQ and start chatting
+
+> During development, it is recommended to enable sandbox mode and add test users and groups to the sandbox for debugging.
diff --git a/docs/channels/qq/README.pt-br.md b/docs/channels/qq/README.pt-br.md
new file mode 100644
index 000000000..507df7f7e
--- /dev/null
+++ b/docs/channels/qq/README.pt-br.md
@@ -0,0 +1,54 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# QQ
+
+O PicoClaw oferece suporte ao QQ via API Bot oficial da Plataforma Aberta QQ.
+
+## Configuração
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Campo      | Tipo   | Obrigatório | Descrição                                                                  |
+| ---------- | ------ | ----------- | -------------------------------------------------------------------------- |
+| enabled    | bool   | Sim         | Se o canal QQ deve ser habilitado                                          |
+| app_id     | string | Sim         | App ID da aplicação bot QQ                                                 |
+| app_secret | string | Sim         | App Secret da aplicação bot QQ                                             |
+| allow_from | array  | Não         | Lista de IDs de usuários permitidos; vazio significa todos os usuários     |
+
+## Configuração inicial
+
+### Configuração rápida (recomendada)
+
+A Plataforma Aberta QQ oferece uma entrada de criação com um clique:
+
+1. Abra o [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) e faça login escaneando o QR code
+2. O sistema cria o bot automaticamente — copie o **App ID** e o **App Secret**
+3. Preencha as credenciais no arquivo de configuração do PicoClaw
+4. Execute `picoclaw gateway` para iniciar o serviço
+5. Abra o QQ e comece a conversar com o bot
+
+> O App Secret é exibido apenas uma vez — salve-o imediatamente. Visualizá-lo novamente forçará uma redefinição.
+>
+> Bots criados pela entrada rápida são apenas para uso pessoal do criador e não suportam chats em grupo. Para suporte a grupos, configure o modo sandbox na [Plataforma Aberta QQ](https://q.qq.com/).
+
+### Configuração manual
+
+1. Faça login na [Plataforma Aberta QQ](https://q.qq.com/) com sua conta QQ e registre-se como desenvolvedor
+2. Crie um bot QQ e personalize seu avatar e nome
+3. Obtenha o **App ID** e o **App Secret** nas configurações do bot
+4. Preencha as credenciais no arquivo de configuração do PicoClaw
+5. Execute `picoclaw gateway` para iniciar o serviço
+6. Pesquise seu bot no QQ e comece a conversar
+
+> Durante o desenvolvimento, recomenda-se habilitar o modo sandbox e adicionar usuários e grupos de teste ao sandbox para depuração.
diff --git a/docs/channels/qq/README.vi.md b/docs/channels/qq/README.vi.md
new file mode 100644
index 000000000..1f3eb89da
--- /dev/null
+++ b/docs/channels/qq/README.vi.md
@@ -0,0 +1,54 @@
+> Quay lại [README](../../../README.vi.md)
+
+# QQ
+
+PicoClaw hỗ trợ QQ thông qua API Bot chính thức của Nền tảng Mở QQ.
+
+## Cấu hình
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Trường     | Kiểu   | Bắt buộc | Mô tả                                                                    |
+| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
+| enabled    | bool   | Có       | Có bật kênh QQ hay không                                                 |
+| app_id     | string | Có       | App ID của ứng dụng bot QQ                                               |
+| app_secret | string | Có       | App Secret của ứng dụng bot QQ                                           |
+| allow_from | array  | Không    | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả        |
+
+## Hướng dẫn thiết lập
+
+### Thiết lập nhanh (Khuyến nghị)
+
+Nền tảng Mở QQ cung cấp lối vào tạo bot một chạm:
+
+1. Mở [QQ Bot Quick Create](https://q.qq.com/qqbot/openclaw/index.html) và đăng nhập bằng cách quét mã QR
+2. Hệ thống tự động tạo bot — sao chép **App ID** và **App Secret**
+3. Điền thông tin xác thực vào file cấu hình PicoClaw
+4. Chạy `picoclaw gateway` để khởi động dịch vụ
+5. Mở QQ và bắt đầu trò chuyện với bot
+
+> App Secret chỉ hiển thị một lần — hãy lưu lại ngay. Xem lại sẽ buộc phải đặt lại.
+>
+> Bot được tạo qua lối vào nhanh chỉ dành cho người tạo sử dụng cá nhân và chưa hỗ trợ chat nhóm. Để hỗ trợ chat nhóm, hãy cấu hình chế độ sandbox trên [Nền tảng Mở QQ](https://q.qq.com/).
+
+### Tạo thủ công
+
+1. Đăng nhập vào [Nền tảng Mở QQ](https://q.qq.com/) bằng tài khoản QQ và đăng ký tài khoản nhà phát triển
+2. Tạo bot QQ, tùy chỉnh ảnh đại diện và tên
+3. Lấy **App ID** và **App Secret** trong cài đặt bot
+4. Điền thông tin xác thực vào file cấu hình PicoClaw
+5. Chạy `picoclaw gateway` để khởi động dịch vụ
+6. Tìm kiếm bot của bạn trong QQ và bắt đầu trò chuyện
+
+> Trong giai đoạn phát triển, nên bật chế độ sandbox và thêm người dùng, nhóm thử nghiệm vào sandbox để gỡ lỗi.
diff --git a/docs/channels/qq/README.zh.md b/docs/channels/qq/README.zh.md
index bd774960f..e7f6d2050 100644
--- a/docs/channels/qq/README.zh.md
+++ b/docs/channels/qq/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
 # QQ
 
 PicoClaw 通过 QQ 开放平台的官方机器人 API 提供对 QQ 的支持。
@@ -11,22 +13,44 @@ PicoClaw 通过 QQ 开放平台的官方机器人 API 提供对 QQ 的支持。
       "enabled": true,
       "app_id": "YOUR_APP_ID",
       "app_secret": "YOUR_APP_SECRET",
-      "allow_from": []
+      "allow_from": [],
+      "max_base64_file_size_mib": 0
     }
   }
 }
 ```
 
-| 字段       | 类型   | 必填 | 描述                             |
-| ---------- | ------ | ---- | -------------------------------- |
-| enabled    | bool   | 是   | 是否启用 QQ Channel              |
-| app_id     | string | 是   | QQ 机器人应用的 App ID           |
-| app_secret | string | 是   | QQ 机器人应用的 App Secret       |
-| allow_from | array  | 否   | 用户ID白名单，空表示允许所有用户 |
+| 字段                 | 类型   | 必填 | 描述                                                         |
+| -------------------- | ------ | ---- | ------------------------------------------------------------ |
+| enabled              | bool   | 是   | 是否启用 QQ Channel                                          |
+| app_id               | string | 是   | QQ 机器人应用的 App ID                                       |
+| app_secret           | string | 是   | QQ 机器人应用的 App Secret                                   |
+| allow_from           | array  | 否   | 用户ID白名单，空表示允许所有用户                             |
+| max_base64_file_size_mib | int | 否   | 本地文件转 base64 上传的最大体积，单位 MiB；`0` 表示不限制。仅影响本地文件，不影响 URL 直传 |
 
 ## 设置流程
 
-1. 前往 [QQ 开放平台](https://q.qq.com/) 创建一个机器人
-2. 通过仪表盘获取 App ID 和 App Secret
-3. 开启机器人沙箱模式, 将用户和群添加到沙箱中
-4. 将 App ID 和 App Secret 填入配置文件中
+### 快捷方式（推荐）
+
+QQ 开放平台提供了一键创建入口：
+
+1. 打开 [QQ 机器人快速创建](https://q.qq.com/qqbot/openclaw/index.html)，扫码登录
+2. 系统自动创建机器人，复制 **App ID** 和 **App Secret**
+3. 将凭证填入 PicoClaw 配置文件
+4. 运行 `picoclaw gateway` 启动服务
+5. 打开 QQ，与机器人开始对话
+
+> App Secret 仅显示一次，请立即保存。再次查看将强制重置。
+>
+> 通过快捷入口创建的机器人仅供创建人使用，暂不支持群聊。如需群聊功能，请在 [QQ 开放平台](https://q.qq.com/) 配置沙箱模式。
+
+### 手动创建
+
+1. 使用 QQ 账号登录 [QQ 开放平台](https://q.qq.com/)，注册开发者账号
+2. 创建 QQ 机器人，自定义头像和名称
+3. 在机器人设置中获取 **App ID** 和 **App Secret**
+4. 将凭证填入 PicoClaw 配置文件
+5. 运行 `picoclaw gateway` 启动服务
+6. 在 QQ 中搜索你的机器人，开始对话
+
+> 开发阶段建议开启沙箱模式，将测试用户和群添加到沙箱中进行调试。
diff --git a/docs/channels/slack/README.fr.md b/docs/channels/slack/README.fr.md
new file mode 100644
index 000000000..81dcebdec
--- /dev/null
+++ b/docs/channels/slack/README.fr.md
@@ -0,0 +1,35 @@
+> Retour au [README](../../../README.fr.md)
+
+# Slack
+
+Slack est l'une des principales plateformes de messagerie instantanée pour les entreprises. PicoClaw utilise le Socket Mode de Slack pour une communication bidirectionnelle en temps réel, sans nécessiter la configuration d'un endpoint webhook public.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "bot_token": "xoxb-...",
+      "app_token": "xapp-...",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Champ      | Type   | Requis | Description                                                                  |
+| ---------- | ------ | ------ | ---------------------------------------------------------------------------- |
+| enabled    | bool   | Oui    | Activer ou non le canal Slack                                                |
+| bot_token  | string | Oui    | Bot User OAuth Token du bot Slack (commence par xoxb-)                       |
+| app_token  | string | Oui    | App Level Token Socket Mode de l'application Slack (commence par xapp-)      |
+| allow_from | array  | Non    | Liste blanche d'ID utilisateurs ; vide signifie tous les utilisateurs        |
+
+## Procédure de configuration
+
+1. Rendez-vous sur [Slack API](https://api.slack.com/) et créez une nouvelle application Slack
+2. Activez le Socket Mode et obtenez l'App Level Token
+3. Ajoutez des Bot Token Scopes (par exemple `chat:write`, `im:history`, etc.)
+4. Installez l'application dans votre espace de travail et obtenez le Bot User OAuth Token
+5. Renseignez le Bot Token et l'App Token dans le fichier de configuration
diff --git a/docs/channels/slack/README.ja.md b/docs/channels/slack/README.ja.md
new file mode 100644
index 000000000..c8d268b9c
--- /dev/null
+++ b/docs/channels/slack/README.ja.md
@@ -0,0 +1,35 @@
+> [README](../../../README.ja.md) に戻る
+
+# Slack
+
+Slack は世界をリードする企業向けインスタントメッセージングプラットフォームです。PicoClaw は Slack の Socket Mode を使用してリアルタイムの双方向通信を実現しており、公開 Webhook エンドポイントの設定は不要です。
+
+## 設定
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "bot_token": "xoxb-...",
+      "app_token": "xapp-...",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| フィールド | 型     | 必須   | 説明                                                                     |
+| ---------- | ------ | ------ | ------------------------------------------------------------------------ |
+| enabled    | bool   | はい   | Slack チャンネルを有効にするかどうか                                     |
+| bot_token  | string | はい   | Slack ボットの Bot User OAuth Token（xoxb- で始まる）                    |
+| app_token  | string | はい   | Slack アプリの Socket Mode App Level Token（xapp- で始まる）             |
+| allow_from | array  | いいえ | ユーザーIDのホワイトリスト。空の場合は全ユーザーを許可                   |
+
+## セットアップ手順
+
+1. [Slack API](https://api.slack.com/) にアクセスして新しい Slack アプリを作成する
+2. Socket Mode を有効にして App Level Token を取得する
+3. Bot Token Scopes を追加する（例: `chat:write`、`im:history` など）
+4. アプリをワークスペースにインストールして Bot User OAuth Token を取得する
+5. Bot Token と App Token を設定ファイルに入力する
diff --git a/docs/channels/slack/README.md b/docs/channels/slack/README.md
new file mode 100644
index 000000000..9d5aafab9
--- /dev/null
+++ b/docs/channels/slack/README.md
@@ -0,0 +1,35 @@
+> Back to [README](../../../README.md)
+
+# Slack
+
+Slack is a leading enterprise instant messaging platform. PicoClaw uses Slack's Socket Mode for real-time bidirectional communication, with no need to configure a public webhook endpoint.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "bot_token": "xoxb-...",
+      "app_token": "xapp-...",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field      | Type   | Required | Description                                                              |
+| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
+| enabled    | bool   | Yes      | Whether to enable the Slack channel                                      |
+| bot_token  | string | Yes      | Bot User OAuth Token for the Slack bot (starts with xoxb-)               |
+| app_token  | string | Yes      | Socket Mode App Level Token for the Slack app (starts with xapp-)        |
+| allow_from | array  | No       | User ID whitelist; empty means all users are allowed                     |
+
+## Setup
+
+1. Go to [Slack API](https://api.slack.com/) and create a new Slack app
+2. Enable Socket Mode and obtain the App Level Token
+3. Add Bot Token Scopes (e.g. `chat:write`, `im:history`, etc.)
+4. Install the app to your workspace and obtain the Bot User OAuth Token
+5. Fill in the Bot Token and App Token in the configuration file
diff --git a/docs/channels/slack/README.pt-br.md b/docs/channels/slack/README.pt-br.md
new file mode 100644
index 000000000..ea8a6c0fc
--- /dev/null
+++ b/docs/channels/slack/README.pt-br.md
@@ -0,0 +1,35 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# Slack
+
+O Slack é uma das principais plataformas de mensagens instantâneas para empresas. O PicoClaw usa o Socket Mode do Slack para comunicação bidirecional em tempo real, sem necessidade de configurar um endpoint de webhook público.
+
+## Configuração
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "bot_token": "xoxb-...",
+      "app_token": "xapp-...",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Campo      | Tipo   | Obrigatório | Descrição                                                                    |
+| ---------- | ------ | ----------- | ---------------------------------------------------------------------------- |
+| enabled    | bool   | Sim         | Se o canal Slack deve ser habilitado                                         |
+| bot_token  | string | Sim         | Bot User OAuth Token do bot Slack (começa com xoxb-)                         |
+| app_token  | string | Sim         | App Level Token do Socket Mode do aplicativo Slack (começa com xapp-)        |
+| allow_from | array  | Não         | Lista de permissão de IDs de usuário; vazio permite todos                    |
+
+## Configuração passo a passo
+
+1. Acesse o [Slack API](https://api.slack.com/) e crie um novo aplicativo Slack
+2. Ative o Socket Mode e obtenha o App Level Token
+3. Adicione Bot Token Scopes (ex.: `chat:write`, `im:history`, etc.)
+4. Instale o aplicativo no seu workspace e obtenha o Bot User OAuth Token
+5. Preencha o Bot Token e o App Token no arquivo de configuração
diff --git a/docs/channels/slack/README.vi.md b/docs/channels/slack/README.vi.md
new file mode 100644
index 000000000..dae84728c
--- /dev/null
+++ b/docs/channels/slack/README.vi.md
@@ -0,0 +1,35 @@
+> Quay lại [README](../../../README.vi.md)
+
+# Slack
+
+Slack là nền tảng nhắn tin tức thì hàng đầu dành cho doanh nghiệp. PicoClaw sử dụng Socket Mode của Slack để giao tiếp hai chiều theo thời gian thực, không cần cấu hình endpoint webhook công khai.
+
+## Cấu hình
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "bot_token": "xoxb-...",
+      "app_token": "xapp-...",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Trường     | Kiểu   | Bắt buộc | Mô tả                                                                        |
+| ---------- | ------ | -------- | ---------------------------------------------------------------------------- |
+| enabled    | bool   | Có       | Có bật kênh Slack hay không                                                  |
+| bot_token  | string | Có       | Bot User OAuth Token của Slack bot (bắt đầu bằng xoxb-)                      |
+| app_token  | string | Có       | App Level Token Socket Mode của ứng dụng Slack (bắt đầu bằng xapp-)          |
+| allow_from | array  | Không    | Danh sách trắng ID người dùng; để trống cho phép tất cả                      |
+
+## Quy trình thiết lập
+
+1. Truy cập [Slack API](https://api.slack.com/) và tạo một ứng dụng Slack mới
+2. Bật Socket Mode và lấy App Level Token
+3. Thêm Bot Token Scopes (ví dụ: `chat:write`, `im:history`, v.v.)
+4. Cài đặt ứng dụng vào workspace và lấy Bot User OAuth Token
+5. Điền Bot Token và App Token vào file cấu hình
diff --git a/docs/channels/slack/README.zh.md b/docs/channels/slack/README.zh.md
index 58ebcb566..884039162 100644
--- a/docs/channels/slack/README.zh.md
+++ b/docs/channels/slack/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../README.zh.md)
+
 # Slack
 
 Slack 是全球领先的企业级即时通讯平台。PicoClaw 采用 Slack 的 Socket Mode 实现实时双向通信，无需配置公开的 Webhook 端点。
diff --git a/docs/channels/telegram/README.fr.md b/docs/channels/telegram/README.fr.md
new file mode 100644
index 000000000..d9ab0644f
--- /dev/null
+++ b/docs/channels/telegram/README.fr.md
@@ -0,0 +1,35 @@
+> Retour au [README](../../../README.fr.md)
+
+# Telegram
+
+Le canal Telegram utilise le long polling via l'API Bot Telegram pour une communication basée sur les bots. Il prend en charge les messages texte, les pièces jointes multimédias (photos, messages vocaux, audio, documents), la transcription vocale via Groq Whisper et la gestion des commandes intégrée.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
+      "allow_from": ["123456789"],
+      "proxy": ""
+    }
+  }
+}
+```
+
+| Champ      | Type   | Requis | Description                                                              |
+| ---------- | ------ | ------ | ------------------------------------------------------------------------ |
+| enabled    | bool   | Oui    | Activer ou non le canal Telegram                                         |
+| token      | string | Oui    | Token de l'API Bot Telegram                                              |
+| allow_from | array  | Non    | Liste blanche d'identifiants utilisateur ; vide signifie tous les utilisateurs |
+| proxy      | string | Non    | URL du proxy pour se connecter à l'API Telegram (ex. http://127.0.0.1:7890) |
+
+## Configuration initiale
+
+1. Rechercher `@BotFather` dans Telegram
+2. Envoyer la commande `/newbot` et suivre les instructions pour créer un nouveau bot
+3. Obtenir le Token de l'API HTTP
+4. Renseigner le Token dans le fichier de configuration
+5. (Optionnel) Configurer `allow_from` pour restreindre les identifiants utilisateur autorisés à interagir (les IDs peuvent être obtenus via `@userinfobot`)
diff --git a/docs/channels/telegram/README.ja.md b/docs/channels/telegram/README.ja.md
new file mode 100644
index 000000000..03c48cb64
--- /dev/null
+++ b/docs/channels/telegram/README.ja.md
@@ -0,0 +1,35 @@
+> [README](../../../README.ja.md) に戻る
+
+# Telegram
+
+Telegram チャンネルは、Telegram Bot API を使用したロングポーリングによるボットベースの通信を実装しています。テキストメッセージ、メディア添付ファイル（写真、音声、オーディオ、ドキュメント）、Groq Whisper による音声文字起こし、および組み込みコマンドハンドラーをサポートしています。
+
+## 設定
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
+      "allow_from": ["123456789"],
+      "proxy": ""
+    }
+  }
+}
+```
+
+| フィールド | 型     | 必須 | 説明                                                              |
+| ---------- | ------ | ---- | ----------------------------------------------------------------- |
+| enabled    | bool   | はい | Telegram チャンネルを有効にするかどうか                           |
+| token      | string | はい | Telegram Bot API トークン                                         |
+| allow_from | array  | いいえ | 許可するユーザーIDのリスト。空の場合はすべてのユーザーを許可     |
+| proxy      | string | いいえ | Telegram API への接続に使用するプロキシ URL (例: http://127.0.0.1:7890) |
+
+## セットアップ手順
+
+1. Telegram で `@BotFather` を検索する
+2. `/newbot` コマンドを送信し、指示に従って新しいボットを作成する
+3. HTTP API トークンを取得する
+4. 設定ファイルにトークンを入力する
+5. (任意) `allow_from` を設定して、対話を許可するユーザー ID を制限する（ID は `@userinfobot` で取得可能）
diff --git a/docs/channels/telegram/README.md b/docs/channels/telegram/README.md
new file mode 100644
index 000000000..86c016a5d
--- /dev/null
+++ b/docs/channels/telegram/README.md
@@ -0,0 +1,55 @@
+> Back to [README](../../../README.md)
+
+# Telegram
+
+The Telegram channel uses long polling via the Telegram Bot API for bot-based communication. It supports text messages, media attachments (photos, voice, audio, documents), voice transcription ([setup](../../providers.md#voice-transcription)), and built-in command handling.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
+      "allow_from": ["123456789"],
+      "proxy": ""
+    }
+  }
+}
+```
+
+| Field      | Type   | Required | Description                                                        |
+| ---------- | ------ | -------- | ------------------------------------------------------------------ |
+| enabled    | bool   | Yes      | Whether to enable the Telegram channel                             |
+| token      | string | Yes      | Telegram Bot API Token                                             |
+| allow_from | array  | No       | Allowlist of user IDs; empty means all users are allowed           |
+| proxy      | string | No       | Proxy URL for connecting to the Telegram API (e.g. http://127.0.0.1:7890) |
+
+## Setup
+
+1. Search for `@BotFather` in Telegram
+2. Send the `/newbot` command and follow the prompts to create a new bot
+3. Obtain the HTTP API Token
+4. Fill in the Token in the configuration file
+5. (Optional) Configure `allow_from` to restrict which user IDs can interact (you can get IDs via `@userinfobot`)
+
+## Built-in Commands
+
+Telegram auto-registers PicoClaw's top-level bot commands at startup, including `/start`, `/help`, `/show`, `/list`, and `/use`.
+
+Skill-related commands:
+
+- `/list skills` lists the installed skills visible to the current agent.
+- `/use <skill> <message>` forces a skill for a single request.
+- `/use <skill>` arms the skill for your next message in the same chat.
+- `/use clear` clears a pending skill override.
+
+Examples:
+
+```text
+/list skills
+/use git explain how to squash the last 3 commits
+/use git
+explain how to squash the last 3 commits
+```
diff --git a/docs/channels/telegram/README.pt-br.md b/docs/channels/telegram/README.pt-br.md
new file mode 100644
index 000000000..8d2c935b4
--- /dev/null
+++ b/docs/channels/telegram/README.pt-br.md
@@ -0,0 +1,35 @@
+> Voltar ao [README](../../../README.pt-br.md)
+
+# Telegram
+
+O canal Telegram utiliza long polling via a API de Bot do Telegram para comunicação baseada em bots. Suporta mensagens de texto, anexos de mídia (fotos, voz, áudio, documentos), transcrição de voz via Groq Whisper e tratamento de comandos integrado.
+
+## Configuração
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
+      "allow_from": ["123456789"],
+      "proxy": ""
+    }
+  }
+}
+```
+
+| Campo      | Tipo   | Obrigatório | Descrição                                                                  |
+| ---------- | ------ | ----------- | -------------------------------------------------------------------------- |
+| enabled    | bool   | Sim         | Se o canal Telegram deve ser habilitado                                    |
+| token      | string | Sim         | Token da API de Bot do Telegram                                            |
+| allow_from | array  | Não         | Lista de IDs de usuários permitidos; vazio significa todos os usuários     |
+| proxy      | string | Não         | URL do proxy para conexão com a API do Telegram (ex. http://127.0.0.1:7890) |
+
+## Configuração inicial
+
+1. Pesquise por `@BotFather` no Telegram
+2. Envie o comando `/newbot` e siga as instruções para criar um novo bot
+3. Obtenha o Token da API HTTP
+4. Preencha o Token no arquivo de configuração
+5. (Opcional) Configure `allow_from` para restringir quais IDs de usuário podem interagir (os IDs podem ser obtidos via `@userinfobot`)
diff --git a/docs/channels/telegram/README.vi.md b/docs/channels/telegram/README.vi.md
new file mode 100644
index 000000000..858a9fc41
--- /dev/null
+++ b/docs/channels/telegram/README.vi.md
@@ -0,0 +1,35 @@
+> Quay lại [README](../../../README.vi.md)
+
+# Telegram
+
+Kênh Telegram sử dụng long polling qua Telegram Bot API để giao tiếp dựa trên bot. Hỗ trợ tin nhắn văn bản, tệp đính kèm đa phương tiện (ảnh, giọng nói, âm thanh, tài liệu), chuyển giọng nói thành văn bản qua Groq Whisper và xử lý lệnh tích hợp sẵn.
+
+## Cấu hình
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
+      "allow_from": ["123456789"],
+      "proxy": ""
+    }
+  }
+}
+```
+
+| Trường     | Kiểu   | Bắt buộc | Mô tả                                                                    |
+| ---------- | ------ | -------- | ------------------------------------------------------------------------ |
+| enabled    | bool   | Có       | Có bật kênh Telegram hay không                                           |
+| token      | string | Có       | Token API Bot Telegram                                                   |
+| allow_from | array  | Không    | Danh sách trắng ID người dùng; để trống nghĩa là cho phép tất cả        |
+| proxy      | string | Không    | URL proxy để kết nối với Telegram API (ví dụ: http://127.0.0.1:7890)    |
+
+## Hướng dẫn thiết lập
+
+1. Tìm kiếm `@BotFather` trong Telegram
+2. Gửi lệnh `/newbot` và làm theo hướng dẫn để tạo bot mới
+3. Lấy Token API HTTP
+4. Điền Token vào file cấu hình
+5. (Tùy chọn) Cấu hình `allow_from` để giới hạn ID người dùng được phép tương tác (có thể lấy ID qua `@userinfobot`)
diff --git a/docs/channels/telegram/README.zh.md b/docs/channels/telegram/README.zh.md
index d453c68fa..1d9dcc46e 100644
--- a/docs/channels/telegram/README.zh.md
+++ b/docs/channels/telegram/README.zh.md
@@ -1,6 +1,8 @@
+> 返回 [README](../../../README.zh.md)
+
 # Telegram
 
-Telegram Channel 通过 Telegram 机器人 API 使用长轮询实现基于机器人的通信。它支持文本消息、媒体附件（照片、语音、音频、文档）、通过 Groq Whisper 进行语音转录以及内置命令处理器。
+Telegram Channel 通过 Telegram 机器人 API 使用长轮询实现基于机器人的通信。它支持文本消息、媒体附件（照片、语音、音频、文档）、语音转录（配置见[提供商与模型配置](../../zh/providers.md#语音转录)），以及内置命令处理器。
 
 ## 配置
 
@@ -31,3 +33,23 @@ Telegram Channel 通过 Telegram 机器人 API 使用长轮询实现基于机器
 3. 获取 HTTP API Token
 4. 将 Token 填入配置文件中
 5. (可选) 配置 `allow_from` 以限制允许互动的用户 ID (可通过 `@userinfobot` 获取 ID)
+
+## 内置命令
+
+Telegram 会在启动时自动注册 PicoClaw 的顶级 Bot 命令，包括 `/start`、`/help`、`/show`、`/list` 和 `/use`。
+
+与技能相关的命令：
+
+- `/list skills`：列出当前 Agent 可见的已安装技能。
+- `/use <skill> <message>`：只在本次请求中强制使用指定技能。
+- `/use <skill>`：为同一聊天中的下一条消息预先启用该技能。
+- `/use clear`：清除待应用的技能覆盖。
+
+示例：
+
+```text
+/list skills
+/use git explain how to squash the last 3 commits
+/use italiapersonalfinance
+dammi le ultime news
+```
diff --git a/docs/channels/wecom/README.md b/docs/channels/wecom/README.md
new file mode 100644
index 000000000..ecdfbc47b
--- /dev/null
+++ b/docs/channels/wecom/README.md
@@ -0,0 +1,104 @@
+> Back to [README](../../../README.md)
+
+# WeCom
+
+PicoClaw now exposes WeCom as a single `channels.wecom` channel built on the official WeCom AI Bot WebSocket API.
+This replaces the legacy `wecom`, `wecom_app`, and `wecom_aibot` split with one configuration model.
+
+## What This Channel Supports
+
+- Direct chat and group chat delivery
+- Channel-side streaming replies over WeCom's AI Bot protocol
+- Incoming text, voice, image, file, video, and mixed messages
+- Outbound text and media replies (`image`, `file`, `voice`, `video`)
+- QR-based CLI onboarding with `picoclaw auth wecom`
+- Shared allowlist and `reasoning_channel_id` routing
+
+> No public webhook callback URL is required for this channel. PicoClaw opens an outbound WebSocket connection to WeCom.
+
+## Quick Start
+
+### Option 1: QR Login From CLI
+
+Run:
+
+```bash
+picoclaw auth wecom
+```
+
+The command prints a QR code in the terminal, waits for confirmation in WeCom, and then writes the resulting
+`bot_id` and `secret` into `channels.wecom`.
+
+Use `--timeout` if you want to wait longer:
+
+```bash
+picoclaw auth wecom --timeout 10m
+```
+
+### Option 2: Configure Manually
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "bot_id": "YOUR_BOT_ID",
+      "secret": "YOUR_SECRET",
+      "websocket_url": "wss://openws.work.weixin.qq.com",
+      "send_thinking_message": true,
+      "allow_from": [],
+      "reasoning_channel_id": ""
+    }
+  }
+}
+```
+
+## Configuration
+
+| Field | Type | Required | Description |
+| ----- | ---- | -------- | ----------- |
+| `enabled` | bool | No | Enables the WeCom channel. |
+| `bot_id` | string | Yes | WeCom AI Bot identifier. Required when the channel is enabled. |
+| `secret` | string | Yes | WeCom AI Bot secret. Required when the channel is enabled. |
+| `websocket_url` | string | No | WebSocket endpoint. Defaults to `wss://openws.work.weixin.qq.com`. |
+| `send_thinking_message` | bool | No | Sends an initial `Processing...` chunk before the final streamed reply. Defaults to `true`. |
+| `allow_from` | array | No | Sender allowlist. Empty means allow all senders. |
+| `reasoning_channel_id` | string | No | Optional destination for reasoning/thinking output. |
+
+## Runtime Behavior
+
+- PicoClaw keeps the active WeCom turn so normal replies can continue the same stream when possible.
+- If streaming is no longer available, replies fall back to active push delivery to the resolved chat route.
+- Incoming media is downloaded into the media store before being handed to the agent.
+- Outbound media is uploaded to WeCom in temporary chunks and then sent as a regular media message.
+
+## Migration Notes
+
+This branch removes the old multi-channel WeCom model.
+
+| Previous config | Now |
+| --------------- | --- |
+| `channels.wecom` webhook bot | Replace with `channels.wecom` using `bot_id` + `secret`. |
+| `channels.wecom_app` | Remove it and use `channels.wecom`. |
+| `channels.wecom_aibot` | Move the config to `channels.wecom`. |
+| `token`, `encoding_aes_key`, `webhook_url`, `webhook_path` | No longer used by the WeCom channel. |
+| `corp_id`, `corp_secret`, `agent_id` | No longer used by the WeCom channel. |
+| `welcome_message`, `processing_message`, `max_steps` under WeCom | No longer part of the WeCom channel config. |
+
+## Troubleshooting
+
+### `picoclaw auth wecom` times out
+
+- Re-run with a larger `--timeout`.
+- Make sure the QR code was confirmed inside WeCom, not only scanned.
+
+### WebSocket connection fails
+
+- Verify `bot_id` and `secret`.
+- Confirm the host can reach `wss://openws.work.weixin.qq.com`.
+
+### Replies do not arrive
+
+- Check whether `allow_from` blocks the sender.
+- Check launcher or startup validation for missing `channels.wecom.bot_id` / `channels.wecom.secret`.
+
diff --git a/docs/channels/wecom/README.zh.md b/docs/channels/wecom/README.zh.md
new file mode 100644
index 000000000..6b4a5e495
--- /dev/null
+++ b/docs/channels/wecom/README.zh.md
@@ -0,0 +1,104 @@
+> 返回 [README](../../../README.zh.md)
+
+# 企业微信
+
+PicoClaw 现在将企业微信统一为一个 `channels.wecom` 渠道，并基于企业微信官方 AI Bot WebSocket 协议实现。
+这取代了旧的 `wecom`、`wecom_app`、`wecom_aibot` 三套配置模型。
+
+## 当前渠道能力
+
+- 支持私聊和群聊
+- 支持企业微信侧流式回复
+- 支持接收文本、语音、图片、文件、视频和 mixed 消息
+- 支持发送文本与媒体消息（`image`、`file`、`voice`、`video`）
+- 支持通过 `picoclaw auth wecom` 扫码写入配置
+- 支持统一白名单与 `reasoning_channel_id`
+
+> 这个渠道不再需要公网 webhook 回调地址。PicoClaw 会主动向企业微信发起 WebSocket 连接。
+
+## 快速开始
+
+### 方式 1：命令行扫码登录
+
+运行：
+
+```bash
+picoclaw auth wecom
+```
+
+该命令会在终端打印二维码，等待你在企业微信中确认，然后把生成的 `bot_id` 和 `secret` 写入
+`channels.wecom`。
+
+如果需要更长等待时间，可以加 `--timeout`：
+
+```bash
+picoclaw auth wecom --timeout 10m
+```
+
+### 方式 2：手动配置
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "bot_id": "YOUR_BOT_ID",
+      "secret": "YOUR_SECRET",
+      "websocket_url": "wss://openws.work.weixin.qq.com",
+      "send_thinking_message": true,
+      "allow_from": [],
+      "reasoning_channel_id": ""
+    }
+  }
+}
+```
+
+## 配置字段
+
+| 字段 | 类型 | 必填 | 说明 |
+| ---- | ---- | ---- | ---- |
+| `enabled` | bool | 否 | 是否启用企业微信渠道。 |
+| `bot_id` | string | 是 | 企业微信 AI Bot 标识。渠道启用时必填。 |
+| `secret` | string | 是 | 企业微信 AI Bot 密钥。渠道启用时必填。 |
+| `websocket_url` | string | 否 | WebSocket 地址，默认 `wss://openws.work.weixin.qq.com`。 |
+| `send_thinking_message` | bool | 否 | 是否在流式最终回复前先发送一段 `Processing...` 开场消息，默认 `true`。 |
+| `allow_from` | array | 否 | 发送者白名单；空数组表示允许所有发送者。 |
+| `reasoning_channel_id` | string | 否 | 可选的 reasoning/thinking 输出目标。 |
+
+## 运行时行为
+
+- PicoClaw 会保留当前会话对应的企业微信 turn，优先继续同一个流式回复。
+- 如果流式上下文已经失效，回复会自动回退到主动推送消息。
+- 收到的媒体会先下载到 media store，再交给 Agent 处理。
+- 发出的媒体会先按分片上传到企业微信，再作为普通媒体消息发送。
+
+## 迁移说明
+
+这个分支移除了旧的多通道企业微信模型。
+
+| 旧配置 | 现在怎么做 |
+| ------ | ---------- |
+| `channels.wecom` webhook 机器人 | 改为使用 `bot_id` + `secret` 的 `channels.wecom`。 |
+| `channels.wecom_app` | 删除，统一迁移到 `channels.wecom`。 |
+| `channels.wecom_aibot` | 配置迁移到 `channels.wecom`。 |
+| `token`、`encoding_aes_key`、`webhook_url`、`webhook_path` | 企业微信渠道不再使用这些字段。 |
+| `corp_id`、`corp_secret`、`agent_id` | 企业微信渠道不再使用这些字段。 |
+| 企业微信下的 `welcome_message`、`processing_message`、`max_steps` | 不再属于企业微信渠道配置。 |
+
+## 常见问题
+
+### `picoclaw auth wecom` 超时
+
+- 用更大的 `--timeout` 重新执行。
+- 确认是在企业微信里完成了确认，而不只是扫描二维码。
+
+### WebSocket 连接失败
+
+- 检查 `bot_id` 和 `secret` 是否正确。
+- 确认运行环境可以访问 `wss://openws.work.weixin.qq.com`。
+
+### 消息没有回到企业微信
+
+- 检查 `allow_from` 是否拦截了发送者。
+- 检查启动日志或 launcher 校验，确认 `channels.wecom.bot_id` / `channels.wecom.secret` 已填写。
+
diff --git a/docs/channels/wecom/wecom_aibot/README.fr.md b/docs/channels/wecom/wecom_aibot/README.fr.md
new file mode 100644
index 000000000..8020dd7b0
--- /dev/null
+++ b/docs/channels/wecom/wecom_aibot/README.fr.md
@@ -0,0 +1,118 @@
+> Retour au [README](../../../../README.fr.md)
+
+# WeCom AI Bot
+
+Le WeCom AI Bot est une méthode d'intégration de conversation IA officiellement fournie par WeCom. Il prend en charge les conversations privées et de groupe, intègre un protocole de réponse en streaming et supporte l'envoi proactif de la réponse finale via `response_url` en cas de dépassement de délai.
+
+## Comparaison avec les autres canaux WeCom
+
+| Fonctionnalité | WeCom Bot | WeCom App | **WeCom AI Bot** |
+|----------------|-----------|-----------|-----------------|
+| Chat privé | ✅ | ✅ | ✅ |
+| Chat de groupe | ✅ | ❌ | ✅ |
+| Sortie en streaming | ❌ | ❌ | ✅ |
+| Push proactif en cas de timeout | ❌ | ✅ | ✅ |
+| Complexité de configuration | Faible | Élevée | Moyenne |
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-aibot",
+      "allow_from": [],
+      "welcome_message": "你好！有什么可以帮助你的吗？",
+      "max_steps": 10
+    }
+  }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ---------------- | ------ | ------ | -------------------------------------------------- |
+| token | string | Oui | Jeton de vérification du callback, configuré sur la page de gestion de l'AI Bot |
+| encoding_aes_key | string | Oui | Clé AES de 43 caractères, générée aléatoirement sur la page de gestion de l'AI Bot |
+| webhook_path | string | Non | Chemin du webhook (par défaut : /webhook/wecom-aibot) |
+| allow_from | array | Non | Liste blanche d'ID utilisateurs ; un tableau vide autorise tous les utilisateurs |
+| welcome_message | string | Non | Message de bienvenue envoyé à l'ouverture du chat ; laisser vide pour désactiver |
+| reply_timeout | int | Non | Délai de réponse en secondes (par défaut : 5) |
+| max_steps | int | Non | Nombre maximum d'étapes d'exécution de l'agent (par défaut : 10) |
+
+## Procédure de configuration
+
+1. Connectez-vous à la [console d'administration WeCom](https://work.weixin.qq.com/wework_admin)
+2. Accédez à « Gestion des applications » → « AI Bot », puis créez ou sélectionnez un AI Bot
+3. Sur la page de configuration de l'AI Bot, renseignez les informations de « Réception des messages » :
+   - **URL** : `http://<your-server-ip>:18790/webhook/wecom-aibot`
+   - **Token** : Généré aléatoirement ou personnalisé
+   - **EncodingAESKey** : Cliquez sur « Générer aléatoirement » pour obtenir une clé de 43 caractères
+4. Saisissez le Token et l'EncodingAESKey dans le fichier de configuration PicoClaw, démarrez le service, puis revenez à la console d'administration pour enregistrer (WeCom enverra une requête de vérification)
+
+> [!TIP]
+> Le serveur doit être accessible par les serveurs WeCom. Si vous êtes sur un intranet ou en développement local, utilisez [ngrok](https://ngrok.com) ou frp pour le tunneling.
+
+## Protocole de réponse en streaming
+
+Le WeCom AI Bot utilise un protocole de « pull en streaming », différent de la réponse unique d'un webhook standard :
+
+```
+L'utilisateur envoie un message
+  │
+  ▼
+PicoClaw retourne immédiatement {finish: false} (l'agent commence le traitement)
+  │
+  ▼
+WeCom effectue un pull environ toutes les 1 seconde avec {msgtype: "stream", stream: {id: "..."}}
+  │
+  ├─ Agent non terminé → retourne {finish: false} (continuer à attendre)
+  │
+  └─ Agent terminé → retourne {finish: true, content: "contenu de la réponse"}
+```
+
+**Gestion du timeout** (tâche dépassant 30 secondes) :
+
+Si le traitement de l'agent dépasse environ 30 secondes (la fenêtre de polling maximale de WeCom est de 6 minutes), PicoClaw va :
+
+1. Fermer immédiatement le stream et afficher à l'utilisateur : « ⏳ 正在处理中，请稍候，结果将稍后发送。 »
+2. L'agent continue de s'exécuter en arrière-plan
+3. Une fois l'agent terminé, la réponse finale est envoyée proactivement à l'utilisateur via le `response_url` inclus dans le message
+
+> `response_url` est émis par WeCom, valable 1 heure, utilisable une seule fois, sans chiffrement requis — il suffit de POSTer directement le corps du message markdown.
+
+## Message de bienvenue
+
+Lorsque `welcome_message` est configuré, PicoClaw répond automatiquement avec ce message lorsqu'un utilisateur ouvre la fenêtre de chat avec l'AI Bot (événement `enter_chat`). Laisser vide pour ignorer silencieusement.
+
+```json
+"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
+```
+
+## FAQ
+
+### Échec de la vérification de l'URL de callback
+
+- Vérifiez que le pare-feu du serveur autorise le port concerné (par défaut 18790)
+- Vérifiez que `token` et `encoding_aes_key` sont correctement renseignés
+- Consultez les logs PicoClaw pour voir si une requête GET de WeCom a été reçue
+
+### Les messages ne reçoivent pas de réponse
+
+- Vérifiez que `allow_from` ne restreint pas accidentellement l'expéditeur
+- Recherchez `context canceled` ou des erreurs d'agent dans les logs
+- Vérifiez que la configuration de l'agent (ex. `model_name`) est correcte
+
+### Pas de push final reçu pour les tâches longues
+
+- Vérifiez que le callback du message inclut `response_url` (uniquement supporté par la nouvelle version du WeCom AI Bot)
+- Vérifiez que le serveur peut effectuer des requêtes sortantes (nécessite un POST vers `response_url`)
+- Consultez les logs pour les mots-clés `response_url mode` et `Sending reply via response_url`
+
+## Références
+
+- [Documentation d'intégration WeCom AI Bot](https://developer.work.weixin.qq.com/document/path/100719)
+- [Description du protocole de réponse en streaming](https://developer.work.weixin.qq.com/document/path/100719)
+- [Réponse proactive via response_url](https://developer.work.weixin.qq.com/document/path/101138)
diff --git a/docs/channels/wecom/wecom_aibot/README.ja.md b/docs/channels/wecom/wecom_aibot/README.ja.md
new file mode 100644
index 000000000..210caffb4
--- /dev/null
+++ b/docs/channels/wecom/wecom_aibot/README.ja.md
@@ -0,0 +1,118 @@
+> [README](../../../../README.ja.md) に戻る
+
+# 企業WeChat AIボット
+
+企業WeChat AIボット（AI Bot）は、企業WeChatが公式に提供するAI会話連携方式です。プライベートチャットとグループチャットの両方をサポートし、ストリーミングレスポンスプロトコルを内蔵しており、タイムアウト後に `response_url` を通じて最終返信をプッシュする機能もサポートしています。
+
+## 他のWeCom チャンネルとの比較
+
+| 機能 | WeCom Bot | WeCom App | **WeCom AI Bot** |
+|------|-----------|-----------|-----------------|
+| プライベートチャット | ✅ | ✅ | ✅ |
+| グループチャット | ✅ | ❌ | ✅ |
+| ストリーミング出力 | ❌ | ❌ | ✅ |
+| タイムアウト時のプッシュ | ❌ | ✅ | ✅ |
+| 設定の複雑さ | 低 | 高 | 中 |
+
+## 設定
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-aibot",
+      "allow_from": [],
+      "welcome_message": "你好！有什么可以帮助你的吗？",
+      "max_steps": 10
+    }
+  }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ---------------- | ------ | ---- | -------------------------------------------------- |
+| token | string | はい | コールバック検証トークン。AIボット管理ページで設定 |
+| encoding_aes_key | string | はい | 43文字のAESキー。AIボット管理ページでランダム生成 |
+| webhook_path | string | いいえ | Webhookパス（デフォルト：/webhook/wecom-aibot） |
+| allow_from | array | いいえ | ユーザーIDの許可リスト。空配列は全ユーザーを許可 |
+| welcome_message | string | いいえ | ユーザーがチャットを開いたときに送信するウェルカムメッセージ。空白の場合は送信しない |
+| reply_timeout | int | いいえ | 返信タイムアウト（秒、デフォルト：5） |
+| max_steps | int | いいえ | エージェントの最大実行ステップ数（デフォルト：10） |
+
+## セットアップ手順
+
+1. [企業WeChat管理コンソール](https://work.weixin.qq.com/wework_admin) にログイン
+2. 「アプリ管理」→「AIボット」に進み、AIボットを作成または選択
+3. AIボット設定ページで「メッセージ受信」情報を入力：
+   - **URL**：`http://<your-server-ip>:18790/webhook/wecom-aibot`
+   - **Token**：ランダム生成またはカスタム
+   - **EncodingAESKey**：「ランダム生成」をクリックして43文字のキーを取得
+4. TokenとEncodingAESKeyをPicoClawの設定ファイルに入力し、サービスを起動してから管理コンソールに戻って保存（企業WeChatが検証リクエストを送信します）
+
+> [!TIP]
+> サーバーは企業WeChatのサーバーからアクセス可能である必要があります。イントラネットやローカル開発環境の場合は、[ngrok](https://ngrok.com) またはfrpを使用してトンネリングしてください。
+
+## ストリーミングレスポンスプロトコル
+
+WeCom AIボットは「ストリーミングプル」プロトコルを使用しており、通常のWebhookの一回限りの返信とは異なります：
+
+```
+ユーザーがメッセージを送信
+  │
+  ▼
+PicoClawが即座に {finish: false} を返す（エージェントが処理開始）
+  │
+  ▼
+企業WeChatが約1秒ごとに {msgtype: "stream", stream: {id: "..."}} でプル
+  │
+  ├─ エージェント未完了 → {finish: false} を返す（待機継続）
+  │
+  └─ エージェント完了 → {finish: true, content: "返信内容"} を返す
+```
+
+**タイムアウト処理**（タスクが30秒を超える場合）：
+
+エージェントの処理時間が約30秒を超えた場合（企業WeChatの最大ポーリングウィンドウは6分）、PicoClawは：
+
+1. 即座にストリームを閉じ、ユーザーに「⏳ 正在处理中，请稍候，结果将稍后发送。」と表示
+2. エージェントはバックグラウンドで処理を継続
+3. エージェント完了後、メッセージに含まれる `response_url` を通じて最終返信をユーザーにプッシュ
+
+> `response_url` は企業WeChatが発行し、有効期限は1時間、使用は1回限りで、暗号化不要。マークダウンメッセージ本文をそのままPOSTするだけです。
+
+## ウェルカムメッセージ
+
+`welcome_message` を設定すると、ユーザーがAIボットとのチャットウィンドウを開いたとき（`enter_chat` イベント）に、PicoClawが自動的にそのメッセージを返信します。空白の場合は無視されます。
+
+```json
+"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
+```
+
+## よくある質問
+
+### コールバックURL検証の失敗
+
+- サーバーのファイアウォールで該当ポートが開放されているか確認（デフォルト18790）
+- `token` と `encoding_aes_key` が正しく入力されているか確認
+- PicoClawのログに企業WeChatからのGETリクエストが届いているか確認
+
+### メッセージに返信がない
+
+- `allow_from` が誤って送信者を制限していないか確認
+- ログに `context canceled` またはエージェントエラーが出ていないか確認
+- エージェント設定（`model_name` など）が正しいか確認
+
+### 長時間タスクで最終プッシュが届かない
+
+- メッセージコールバックに `response_url` が含まれているか確認（新バージョンの企業WeChat AIボットのみ対応）
+- サーバーが外部ネットワークへのアウトバウンドリクエストを送信できるか確認（`response_url` へのPOSTが必要）
+- ログのキーワード `response_url mode` と `Sending reply via response_url` を確認
+
+## 参考ドキュメント
+
+- [企業WeChat AIボット連携ドキュメント](https://developer.work.weixin.qq.com/document/path/100719)
+- [ストリーミングレスポンスプロトコルの説明](https://developer.work.weixin.qq.com/document/path/100719)
+- [response_url によるプロアクティブ返信](https://developer.work.weixin.qq.com/document/path/101138)
diff --git a/docs/channels/wecom/wecom_aibot/README.md b/docs/channels/wecom/wecom_aibot/README.md
new file mode 100644
index 000000000..31d831617
--- /dev/null
+++ b/docs/channels/wecom/wecom_aibot/README.md
@@ -0,0 +1,118 @@
+> Back to [README](../../../../README.md)
+
+# WeCom AI Bot
+
+The WeCom AI Bot is an official AI conversation integration provided by WeCom. It supports both private and group chats, has a built-in streaming response protocol, and supports proactively pushing the final reply via `response_url` after a timeout.
+
+## Comparison with Other WeCom Channels
+
+| Feature | WeCom Bot | WeCom App | **WeCom AI Bot** |
+|---------|-----------|-----------|-----------------|
+| Private Chat | ✅ | ✅ | ✅ |
+| Group Chat | ✅ | ❌ | ✅ |
+| Streaming Output | ❌ | ❌ | ✅ |
+| Proactive Push on Timeout | ❌ | ✅ | ✅ |
+| Configuration Complexity | Low | High | Medium |
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-aibot",
+      "allow_from": [],
+      "welcome_message": "你好！有什么可以帮助你的吗？",
+      "max_steps": 10
+    }
+  }
+}
+```
+
+| Field | Type | Required | Description |
+| ---------------- | ------ | -------- | -------------------------------------------------- |
+| token | string | Yes | Callback verification token, configured on the AI Bot management page |
+| encoding_aes_key | string | Yes | 43-character AES key, randomly generated on the AI Bot management page |
+| webhook_path | string | No | Webhook path (default: /webhook/wecom-aibot) |
+| allow_from | array | No | User ID allowlist; empty array allows all users |
+| welcome_message | string | No | Welcome message sent when a user opens the chat; leave empty to disable |
+| reply_timeout | int | No | Reply timeout in seconds (default: 5) |
+| max_steps | int | No | Maximum agent execution steps (default: 10) |
+
+## Setup
+
+1. Log in to the [WeCom Admin Console](https://work.weixin.qq.com/wework_admin)
+2. Go to "App Management" → "AI Bot", then create or select an AI Bot
+3. On the AI Bot configuration page, fill in the "Message Reception" details:
+   - **URL**: `http://<your-server-ip>:18790/webhook/wecom-aibot`
+   - **Token**: Randomly generated or custom
+   - **EncodingAESKey**: Click "Random Generate" to get a 43-character key
+4. Enter the Token and EncodingAESKey into the PicoClaw config file, start the service, then return to the admin console to save (WeCom will send a verification request)
+
+> [!TIP]
+> The server must be accessible by WeCom's servers. If you are on an intranet or developing locally, use [ngrok](https://ngrok.com) or frp for tunneling.
+
+## Streaming Response Protocol
+
+WeCom AI Bot uses a "streaming pull" protocol, which differs from the one-shot reply of a standard webhook:
+
+```
+User sends a message
+  │
+  ▼
+PicoClaw immediately returns {finish: false} (Agent starts processing)
+  │
+  ▼
+WeCom pulls approximately every 1 second with {msgtype: "stream", stream: {id: "..."}}
+  │
+  ├─ Agent not done → returns {finish: false} (keep waiting)
+  │
+  └─ Agent done → returns {finish: true, content: "reply content"}
+```
+
+**Timeout Handling** (task exceeds 30 seconds):
+
+If the Agent takes longer than approximately 30 seconds (WeCom's maximum polling window is 6 minutes), PicoClaw will:
+
+1. Immediately close the stream and show the user: "⏳ 正在处理中，请稍候，结果将稍后发送。"
+2. The Agent continues running in the background
+3. Once the Agent finishes, the final reply is proactively pushed to the user via the `response_url` included in the message
+
+> `response_url` is issued by WeCom, valid for 1 hour, can only be used once, requires no encryption — just POST the markdown message body directly.
+
+## Welcome Message
+
+When `welcome_message` is configured, PicoClaw will automatically reply with it when a user opens the chat window with the AI Bot (`enter_chat` event). Leave it empty to silently ignore the event.
+
+```json
+"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
+```
+
+## FAQ
+
+### Callback URL Verification Failed
+
+- Confirm the server firewall has the relevant port open (default 18790)
+- Confirm `token` and `encoding_aes_key` are entered correctly
+- Check PicoClaw logs to see if a GET request from WeCom was received
+
+### Messages Not Getting a Reply
+
+- Check whether `allow_from` is accidentally restricting the sender
+- Look for `context canceled` or Agent errors in the logs
+- Confirm the Agent configuration (e.g., `model_name`) is correct
+
+### No Final Push Received for Long-Running Tasks
+
+- Confirm the message callback includes `response_url` (only supported by the newer WeCom AI Bot)
+- Confirm the server can make outbound requests (needs to POST to `response_url`)
+- Check logs for keywords `response_url mode` and `Sending reply via response_url`
+
+## Reference
+
+- [WeCom AI Bot Integration Docs](https://developer.work.weixin.qq.com/document/path/100719)
+- [Streaming Response Protocol](https://developer.work.weixin.qq.com/document/path/100719)
+- [Proactive Reply via response_url](https://developer.work.weixin.qq.com/document/path/101138)
diff --git a/docs/channels/wecom/wecom_aibot/README.pt-br.md b/docs/channels/wecom/wecom_aibot/README.pt-br.md
new file mode 100644
index 000000000..1ab735c41
--- /dev/null
+++ b/docs/channels/wecom/wecom_aibot/README.pt-br.md
@@ -0,0 +1,118 @@
+> Voltar ao [README](../../../../README.pt-br.md)
+
+# WeCom AI Bot
+
+O WeCom AI Bot é uma forma oficial de integração de conversas com IA fornecida pelo WeCom. Suporta conversas privadas e em grupo, possui um protocolo de resposta em streaming integrado e suporta o envio proativo da resposta final via `response_url` após um timeout.
+
+## Comparação com outros canais WeCom
+
+| Recurso | WeCom Bot | WeCom App | **WeCom AI Bot** |
+|---------|-----------|-----------|-----------------|
+| Chat privado | ✅ | ✅ | ✅ |
+| Chat em grupo | ✅ | ❌ | ✅ |
+| Saída em streaming | ❌ | ❌ | ✅ |
+| Push proativo em timeout | ❌ | ✅ | ✅ |
+| Complexidade de configuração | Baixa | Alta | Média |
+
+## Configuração
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-aibot",
+      "allow_from": [],
+      "welcome_message": "你好！有什么可以帮助你的吗？",
+      "max_steps": 10
+    }
+  }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ---------------- | ------ | ----------- | -------------------------------------------------- |
+| token | string | Sim | Token de verificação de callback, configurado na página de gerenciamento do AI Bot |
+| encoding_aes_key | string | Sim | Chave AES de 43 caracteres, gerada aleatoriamente na página de gerenciamento do AI Bot |
+| webhook_path | string | Não | Caminho do webhook (padrão: /webhook/wecom-aibot) |
+| allow_from | array | Não | Lista de permissão de IDs de usuários; array vazio permite todos os usuários |
+| welcome_message | string | Não | Mensagem de boas-vindas enviada quando o usuário abre o chat; deixe vazio para desativar |
+| reply_timeout | int | Não | Timeout de resposta em segundos (padrão: 5) |
+| max_steps | int | Não | Número máximo de etapas de execução do agente (padrão: 10) |
+
+## Configuração passo a passo
+
+1. Faça login no [Console de Administração do WeCom](https://work.weixin.qq.com/wework_admin)
+2. Acesse "Gerenciamento de Apps" → "AI Bot", depois crie ou selecione um AI Bot
+3. Na página de configuração do AI Bot, preencha as informações de "Recebimento de Mensagens":
+   - **URL**: `http://<your-server-ip>:18790/webhook/wecom-aibot`
+   - **Token**: Gerado aleatoriamente ou personalizado
+   - **EncodingAESKey**: Clique em "Gerar Aleatoriamente" para obter uma chave de 43 caracteres
+4. Insira o Token e o EncodingAESKey no arquivo de configuração do PicoClaw, inicie o serviço e volte ao console de administração para salvar (o WeCom enviará uma requisição de verificação)
+
+> [!TIP]
+> O servidor precisa ser acessível pelos servidores do WeCom. Se estiver em uma intranet ou desenvolvendo localmente, use [ngrok](https://ngrok.com) ou frp para tunelamento.
+
+## Protocolo de resposta em streaming
+
+O WeCom AI Bot usa um protocolo de "pull em streaming", diferente da resposta única de um webhook padrão:
+
+```
+Usuário envia uma mensagem
+  │
+  ▼
+PicoClaw retorna imediatamente {finish: false} (Agente começa a processar)
+  │
+  ▼
+WeCom faz pull aproximadamente a cada 1 segundo com {msgtype: "stream", stream: {id: "..."}}
+  │
+  ├─ Agente não concluído → retorna {finish: false} (continuar aguardando)
+  │
+  └─ Agente concluído → retorna {finish: true, content: "conteúdo da resposta"}
+```
+
+**Tratamento de timeout** (tarefa excede 30 segundos):
+
+Se o processamento do agente demorar mais de aproximadamente 30 segundos (a janela máxima de polling do WeCom é de 6 minutos), o PicoClaw irá:
+
+1. Fechar imediatamente o stream e exibir ao usuário: "⏳ 正在处理中，请稍候，结果将稍后发送。"
+2. O agente continua executando em segundo plano
+3. Após a conclusão do agente, a resposta final é enviada proativamente ao usuário via `response_url` incluído na mensagem
+
+> `response_url` é emitido pelo WeCom, válido por 1 hora, pode ser usado apenas uma vez, sem necessidade de criptografia — basta fazer um POST com o corpo da mensagem em markdown diretamente.
+
+## Mensagem de boas-vindas
+
+Quando `welcome_message` está configurado, o PicoClaw responde automaticamente com essa mensagem quando um usuário abre a janela de chat com o AI Bot (evento `enter_chat`). Deixe vazio para ignorar silenciosamente.
+
+```json
+"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
+```
+
+## Perguntas frequentes
+
+### Falha na verificação da URL de callback
+
+- Confirme que o firewall do servidor tem a porta correspondente aberta (padrão 18790)
+- Confirme que `token` e `encoding_aes_key` estão preenchidos corretamente
+- Verifique os logs do PicoClaw para ver se uma requisição GET do WeCom foi recebida
+
+### Mensagens sem resposta
+
+- Verifique se `allow_from` está restringindo acidentalmente o remetente
+- Procure por `context canceled` ou erros do agente nos logs
+- Confirme que a configuração do agente (ex.: `model_name`) está correta
+
+### Nenhum push final recebido para tarefas longas
+
+- Confirme que o callback da mensagem inclui `response_url` (suportado apenas pelo novo WeCom AI Bot)
+- Confirme que o servidor consegue fazer requisições de saída (precisa fazer POST para `response_url`)
+- Verifique nos logs as palavras-chave `response_url mode` e `Sending reply via response_url`
+
+## Referências
+
+- [Documentação de integração do WeCom AI Bot](https://developer.work.weixin.qq.com/document/path/100719)
+- [Descrição do protocolo de resposta em streaming](https://developer.work.weixin.qq.com/document/path/100719)
+- [Resposta proativa via response_url](https://developer.work.weixin.qq.com/document/path/101138)
diff --git a/docs/channels/wecom/wecom_aibot/README.vi.md b/docs/channels/wecom/wecom_aibot/README.vi.md
new file mode 100644
index 000000000..cb6586e6e
--- /dev/null
+++ b/docs/channels/wecom/wecom_aibot/README.vi.md
@@ -0,0 +1,118 @@
+> Quay lại [README](../../../../README.vi.md)
+
+# WeCom AI Bot
+
+WeCom AI Bot là phương thức tích hợp hội thoại AI chính thức do WeCom cung cấp. Hỗ trợ cả chat riêng tư và chat nhóm, tích hợp giao thức phản hồi streaming, và hỗ trợ chủ động đẩy phản hồi cuối cùng qua `response_url` sau khi hết thời gian chờ.
+
+## So sánh với các kênh WeCom khác
+
+| Tính năng | WeCom Bot | WeCom App | **WeCom AI Bot** |
+|-----------|-----------|-----------|-----------------|
+| Chat riêng tư | ✅ | ✅ | ✅ |
+| Chat nhóm | ✅ | ❌ | ✅ |
+| Đầu ra streaming | ❌ | ❌ | ✅ |
+| Đẩy chủ động khi timeout | ❌ | ✅ | ✅ |
+| Độ phức tạp cấu hình | Thấp | Cao | Trung bình |
+
+## Cấu hình
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-aibot",
+      "allow_from": [],
+      "welcome_message": "你好！有什么可以帮助你的吗？",
+      "max_steps": 10
+    }
+  }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ---------------- | ------ | --------- | -------------------------------------------------- |
+| token | string | Có | Token xác minh callback, cấu hình trên trang quản lý AI Bot |
+| encoding_aes_key | string | Có | Khóa AES 43 ký tự, được tạo ngẫu nhiên trên trang quản lý AI Bot |
+| webhook_path | string | Không | Đường dẫn webhook (mặc định: /webhook/wecom-aibot) |
+| allow_from | array | Không | Danh sách cho phép ID người dùng; mảng rỗng cho phép tất cả người dùng |
+| welcome_message | string | Không | Tin nhắn chào mừng gửi khi người dùng mở chat; để trống để tắt |
+| reply_timeout | int | Không | Thời gian chờ phản hồi tính bằng giây (mặc định: 5) |
+| max_steps | int | Không | Số bước thực thi tối đa của agent (mặc định: 10) |
+
+## Hướng dẫn thiết lập
+
+1. Đăng nhập vào [Bảng điều khiển quản trị WeCom](https://work.weixin.qq.com/wework_admin)
+2. Vào "Quản lý ứng dụng" → "AI Bot", sau đó tạo hoặc chọn một AI Bot
+3. Trên trang cấu hình AI Bot, điền thông tin "Nhận tin nhắn":
+   - **URL**: `http://<your-server-ip>:18790/webhook/wecom-aibot`
+   - **Token**: Tạo ngẫu nhiên hoặc tùy chỉnh
+   - **EncodingAESKey**: Nhấp "Tạo ngẫu nhiên" để lấy khóa 43 ký tự
+4. Nhập Token và EncodingAESKey vào file cấu hình PicoClaw, khởi động dịch vụ rồi quay lại bảng điều khiển quản trị để lưu (WeCom sẽ gửi yêu cầu xác minh)
+
+> [!TIP]
+> Máy chủ cần có thể truy cập được từ các máy chủ WeCom. Nếu bạn đang ở mạng nội bộ hoặc phát triển cục bộ, hãy sử dụng [ngrok](https://ngrok.com) hoặc frp để tạo tunnel.
+
+## Giao thức phản hồi streaming
+
+WeCom AI Bot sử dụng giao thức "pull streaming", khác với phản hồi một lần của webhook thông thường:
+
+```
+Người dùng gửi tin nhắn
+  │
+  ▼
+PicoClaw trả về ngay {finish: false} (Agent bắt đầu xử lý)
+  │
+  ▼
+WeCom pull khoảng mỗi 1 giây với {msgtype: "stream", stream: {id: "..."}}
+  │
+  ├─ Agent chưa xong → trả về {finish: false} (tiếp tục chờ)
+  │
+  └─ Agent xong → trả về {finish: true, content: "nội dung phản hồi"}
+```
+
+**Xử lý timeout** (tác vụ vượt quá 30 giây):
+
+Nếu thời gian xử lý của agent vượt quá khoảng 30 giây (cửa sổ polling tối đa của WeCom là 6 phút), PicoClaw sẽ:
+
+1. Đóng stream ngay lập tức và hiển thị cho người dùng: "⏳ 正在处理中，请稍候，结果将稍后发送。"
+2. Agent tiếp tục chạy ở nền
+3. Sau khi agent hoàn thành, phản hồi cuối cùng được chủ động đẩy đến người dùng qua `response_url` có trong tin nhắn
+
+> `response_url` do WeCom cấp, có hiệu lực 1 giờ, chỉ dùng được một lần, không cần mã hóa — chỉ cần POST trực tiếp nội dung tin nhắn markdown.
+
+## Tin nhắn chào mừng
+
+Khi `welcome_message` được cấu hình, PicoClaw sẽ tự động phản hồi bằng tin nhắn đó khi người dùng mở cửa sổ chat với AI Bot (sự kiện `enter_chat`). Để trống để bỏ qua im lặng.
+
+```json
+"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
+```
+
+## Câu hỏi thường gặp
+
+### Xác minh URL callback thất bại
+
+- Xác nhận tường lửa máy chủ đã mở cổng tương ứng (mặc định 18790)
+- Xác nhận `token` và `encoding_aes_key` được điền đúng
+- Kiểm tra log PicoClaw xem có nhận được yêu cầu GET từ WeCom không
+
+### Tin nhắn không nhận được phản hồi
+
+- Kiểm tra xem `allow_from` có vô tình hạn chế người gửi không
+- Tìm `context canceled` hoặc lỗi agent trong log
+- Xác nhận cấu hình agent (ví dụ: `model_name`) là đúng
+
+### Không nhận được push cuối cùng cho tác vụ dài
+
+- Xác nhận callback tin nhắn có chứa `response_url` (chỉ hỗ trợ bởi WeCom AI Bot phiên bản mới)
+- Xác nhận máy chủ có thể thực hiện yêu cầu ra ngoài (cần POST đến `response_url`)
+- Kiểm tra log với từ khóa `response_url mode` và `Sending reply via response_url`
+
+## Tài liệu tham khảo
+
+- [Tài liệu tích hợp WeCom AI Bot](https://developer.work.weixin.qq.com/document/path/100719)
+- [Mô tả giao thức phản hồi streaming](https://developer.work.weixin.qq.com/document/path/100719)
+- [Phản hồi chủ động qua response_url](https://developer.work.weixin.qq.com/document/path/101138)
diff --git a/docs/channels/wecom/wecom_aibot/README.zh.md b/docs/channels/wecom/wecom_aibot/README.zh.md
new file mode 100644
index 000000000..9da5ee1b9
--- /dev/null
+++ b/docs/channels/wecom/wecom_aibot/README.zh.md
@@ -0,0 +1,185 @@
+> 返回 [README](../../../../README.zh.md)
+
+# 企业微信智能机器人 (AI Bot)
+
+企业微信智能机器人（AI Bot）是企业微信官方提供的 AI 对话接入方式，支持私聊与群聊，内置流式响应协议。PicoClaw 当前同时支持两种接入模式：
+
+- WebSocket 长连接模式：使用 `bot_id` + `secret`，优先级更高，推荐使用
+- Webhook 短连接模式：使用 `token` + `encoding_aes_key`，兼容传统回调，并支持超时后通过 `response_url` 主动推送最终回复
+
+## 与其他 WeCom 通道的对比
+
+| 特性 | WeCom Bot | WeCom App | **WeCom AI Bot** |
+|------|-----------|-----------|-----------------|
+| 私聊 | ✅ | ✅ | ✅ |
+| 群聊 | ✅ | ❌ | ✅ |
+| 流式输出 | ❌ | ❌ | ✅ |
+| 超时主动推送 | ❌ | ✅ | ✅ |
+| 配置复杂度 | 低 | 高 | 中 |
+
+## 配置
+
+### WebSocket 长连接模式（推荐）
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "bot_id": "YOUR_BOT_ID",
+      "secret": "YOUR_SECRET",
+      "allow_from": [],
+      "welcome_message": "你好！有什么可以帮助你的吗？",
+      "max_steps": 10
+    }
+  }
+}
+```
+
+### Webhook 短连接模式
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-aibot",
+      "allow_from": [],
+      "welcome_message": "你好！有什么可以帮助你的吗？",
+      "processing_message": "⏳ Processing, please wait. The results will be sent shortly.",
+      "max_steps": 10
+    }
+  }
+}
+```
+
+### WebSocket 模式字段
+
+| 字段   | 类型   | 必填 | 描述                                       |
+|--------|--------|------|--------------------------------------------|
+| bot_id | string | 是   | AI Bot 的唯一标识，在 AI Bot 管理页面配置 |
+| secret | string | 是   | AI Bot 的密钥，在 AI Bot 管理页面配置     |
+
+### Webhook 模式字段
+
+| 字段             | 类型   | 必填 | 描述                                         |
+|------------------|--------|------|----------------------------------------------|
+| token            | string | 是   | 回调验证令牌，在 AI Bot 管理页面配置         |
+| encoding_aes_key | string | 是   | 43 字符 AES 密钥，在 AI Bot 管理页面随机生成 |
+| webhook_path     | string | 否   | Webhook 路径，默认 `/webhook/wecom-aibot`    |
+| processing_message | string | 否 | 流式超时后返回给用户的提示语                 |
+
+### 通用字段
+
+| 字段            | 类型   | 必填 | 描述                                     |
+|-----------------|--------|------|------------------------------------------|
+| allow_from      | array  | 否   | 用户 ID 白名单，空数组表示允许所有用户   |
+| welcome_message | string | 否   | 用户进入聊天时发送的欢迎语，留空则不发送 |
+| reply_timeout   | int    | 否   | 回复超时时间（秒，默认：5）              |
+| max_steps       | int    | 否   | Agent 最大执行步骤数（默认：10）         |
+
+## 模式选择
+
+- 当 `bot_id` 和 `secret` 同时存在时，PicoClaw 会优先使用 WebSocket 长连接模式
+- 否则，当 `token` 和 `encoding_aes_key` 同时存在时，PicoClaw 会使用 Webhook 短连接模式
+
+## 设置流程
+
+### WebSocket 长连接模式
+
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin)
+2. 进入"应用管理" → "智能机器人"，创建或选择一个 AI Bot
+3. 在 AI Bot 配置页面，配置 Bot 的名称、头像等信息，获取 `Bot ID` 和 `Secret`
+4. 在 PicoClaw 配置文件中添加上述配置，重启 PicoClaw
+
+### Webhook 短连接模式
+
+1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin)
+2. 进入"应用管理" → "智能机器人"，创建或选择一个 AI Bot
+3. 在 AI Bot 配置页面，填写"消息接收"信息：
+   - **URL**：`http://<your-server-ip>:18790/webhook/wecom-aibot`
+   - **Token**：随机生成或自定义
+   - **EncodingAESKey**：点击"随机生成"，得到 43 字符密钥
+4. 将 Token 和 EncodingAESKey 填入 PicoClaw 配置文件，启动服务后回到管理后台保存
+
+> [!TIP]
+> 服务器需要能被企业微信服务器访问。如在内网或本地开发，可使用 [ngrok](https://ngrok.com) 或 frp 做内网穿透。
+
+## Webhook 模式的流式响应协议
+
+Webhook 模式使用"流式拉取"协议，区别于普通 Webhook 的一次性回复：
+
+```
+用户发消息
+  │
+  ▼
+PicoClaw 立即返回 {finish: false}（Agent 开始处理）
+  │
+  ▼
+企业微信每隔约 1 秒拉取一次 {msgtype: "stream", stream: {id: "..."}}
+  │
+  ├─ Agent 未完成 → 返回 {finish: false}（继续等待）
+  │
+  └─ Agent 完成 → 返回 {finish: true, content: "回答内容"}
+```
+
+**超时处理**（任务超过约 30 秒）：
+
+若 Agent 处理时间超过轮询窗口，PicoClaw 会：
+
+1. 立即关闭流，向用户显示 `processing_message` 提示语
+2. Agent 继续在后台运行
+3. Agent 完成后，通过消息中携带的 `response_url` 将最终回复主动推送给用户
+
+> `response_url` 由企业微信颁发，有效期 1 小时，只可使用一次，无需加密，直接 POST markdown 消息体即可。
+
+## 超时提示语
+
+配置 `processing_message` 后，当 Webhook 模式的流式轮询超时并切换到 `response_url` 主动推送模式时，PicoClaw 会先返回这段提示语来结束当前流。
+
+```json
+"processing_message": "⏳ Processing, please wait. The results will be sent shortly."
+```
+
+## 欢迎语
+
+配置 `welcome_message` 后，当用户打开与 AI Bot 的聊天窗口时（`enter_chat` 事件），PicoClaw 会自动回复该欢迎语。留空则静默忽略。
+
+```json
+"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"
+```
+
+## 常见问题
+
+### WebSocket 模式无法连接
+
+- 检查 `bot_id` 和 `secret` 是否填写正确
+- 查看日志中是否有 WebSocket 连接或鉴权失败信息
+- 确认服务器可以访问企业微信长连接接口
+
+### 回调 URL 验证失败
+
+
+- 确认 `token` 与 `encoding_aes_key` 填写正确
+- 确认服务器防火墙已开放对应端口
+- 检查 PicoClaw 日志是否收到了来自企业微信的验证请求
+
+### 消息没有回复
+
+- 检查 `allow_from` 是否意外限制了发送者
+- 查看日志中是否出现 `context canceled` 或 Agent 错误
+- 确认 Agent 配置（`model_name` 等）正确
+
+### 超长任务没有收到最终推送
+
+- 确认消息回调中携带了 `response_url`
+- 确认服务器能主动访问外网
+- 查看日志关键词 `response_url mode` 和 `Sending reply via response_url`
+
+## 参考文档
+
+- [企业微信 AI Bot 接入文档](https://developer.work.weixin.qq.com/document/path/101463)
+- [流式响应协议说明](https://developer.work.weixin.qq.com/document/path/100719)
+- [response_url 主动回复](https://developer.work.weixin.qq.com/document/path/101138)
diff --git a/docs/channels/wecom/wecom_app/README.fr.md b/docs/channels/wecom/wecom_app/README.fr.md
new file mode 100644
index 000000000..f95426497
--- /dev/null
+++ b/docs/channels/wecom/wecom_app/README.fr.md
@@ -0,0 +1,47 @@
+> Retour au [README](../../../../README.fr.md)
+
+# Application interne WeCom
+
+Une application interne WeCom est une application créée par une entreprise au sein de WeCom, principalement destinée à un usage interne. Grâce aux applications internes WeCom, les entreprises peuvent assurer une communication et une collaboration efficaces avec leurs employés, améliorant ainsi la productivité.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "wecom_app": {
+      "enabled": true,
+      "corp_id": "wwxxxxxxxxxxxxxxxx",
+      "corp_secret": "YOUR_CORP_SECRET",
+      "agent_id": 1000002,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": [],
+      "reply_timeout": 5
+    }
+  }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ---------------- | ------ | ------ | ---------------------------------------- |
+| corp_id | string | Oui | ID de l'entreprise |
+| corp_secret | string | Oui | Secret de l'application |
+| agent_id | int | Oui | ID de l'agent de l'application |
+| token | string | Oui | Jeton de vérification du callback |
+| encoding_aes_key | string | Oui | Clé AES de 43 caractères |
+| webhook_path | string | Non | Chemin du webhook (par défaut : /webhook/wecom-app) |
+| allow_from | array | Non | Liste blanche d'ID utilisateurs |
+| reply_timeout | int | Non | Délai de réponse en secondes |
+
+## Procédure de configuration
+
+1. Connectez-vous à la [console d'administration WeCom](https://work.weixin.qq.com/)
+2. Accédez à « Gestion des applications » -> « Créer une application »
+3. Obtenez l'ID d'entreprise (CorpID) et le Secret de l'application
+4. Configurez « Réception des messages » dans les paramètres de l'application pour obtenir le Token et l'EncodingAESKey
+5. Définissez l'URL de callback sur `http://<your-server-ip>:<port>/webhook/wecom-app`
+6. Saisissez le CorpID, le Secret, l'AgentID et les autres informations dans le fichier de configuration
+
+   Remarque : PicoClaw utilise désormais un serveur HTTP Gateway partagé pour recevoir les callbacks webhook de tous les canaux. L'adresse d'écoute par défaut est 127.0.0.1:18790. Pour recevoir des callbacks depuis l'internet public, configurez un reverse proxy de votre domaine externe vers le Gateway (port par défaut 18790).
diff --git a/docs/channels/wecom/wecom_app/README.ja.md b/docs/channels/wecom/wecom_app/README.ja.md
new file mode 100644
index 000000000..4bd5a7101
--- /dev/null
+++ b/docs/channels/wecom/wecom_app/README.ja.md
@@ -0,0 +1,47 @@
+> [README](../../../../README.ja.md) に戻る
+
+# 企業WeChat 自社開発アプリ
+
+企業WeChat 自社開発アプリとは、企業が企業WeChat内で作成するアプリケーションで、主に社内利用を目的としています。企業WeChat 自社開発アプリを通じて、企業は従業員との効率的なコミュニケーションと協業を実現し、業務効率を向上させることができます。
+
+## 設定
+
+```json
+{
+  "channels": {
+    "wecom_app": {
+      "enabled": true,
+      "corp_id": "wwxxxxxxxxxxxxxxxx",
+      "corp_secret": "YOUR_CORP_SECRET",
+      "agent_id": 1000002,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": [],
+      "reply_timeout": 5
+    }
+  }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ---------------- | ------ | ---- | ---------------------------------------- |
+| corp_id | string | はい | 企業ID |
+| corp_secret | string | はい | アプリケーションシークレット |
+| agent_id | int | はい | アプリケーションエージェントID |
+| token | string | はい | コールバック検証トークン |
+| encoding_aes_key | string | はい | 43文字のAESキー |
+| webhook_path | string | いいえ | Webhookパス（デフォルト：/webhook/wecom-app） |
+| allow_from | array | いいえ | ユーザーIDの許可リスト |
+| reply_timeout | int | いいえ | 返信タイムアウト（秒） |
+
+## セットアップ手順
+
+1. [企業WeChat管理コンソール](https://work.weixin.qq.com/) にログイン
+2. 「アプリ管理」→「アプリを作成」に進む
+3. 企業ID（CorpID）とアプリのSecretを取得
+4. アプリ設定で「メッセージ受信」を設定し、TokenとEncodingAESKeyを取得
+5. コールバックURLを `http://<your-server-ip>:<port>/webhook/wecom-app` に設定
+6. CorpID、Secret、AgentIDなどの情報を設定ファイルに入力
+
+   注意：PicoClawは現在、すべてのチャンネルのwebhookコールバックを受信するために共有のGateway HTTPサーバーを使用しています。デフォルトのリスニングアドレスは127.0.0.1:18790です。公共インターネットからコールバックを受信するには、外部ドメインをGateway（デフォルトポート18790）にリバースプロキシしてください。
diff --git a/docs/channels/wecom/wecom_app/README.md b/docs/channels/wecom/wecom_app/README.md
new file mode 100644
index 000000000..4397f805a
--- /dev/null
+++ b/docs/channels/wecom/wecom_app/README.md
@@ -0,0 +1,47 @@
+> Back to [README](../../../../README.md)
+
+# WeCom Internal App
+
+A WeCom Internal App is an application created by an enterprise within WeCom, primarily intended for internal use. Through WeCom Internal Apps, enterprises can achieve efficient communication and collaboration with employees, improving productivity.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "wecom_app": {
+      "enabled": true,
+      "corp_id": "wwxxxxxxxxxxxxxxxx",
+      "corp_secret": "YOUR_CORP_SECRET",
+      "agent_id": 1000002,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": [],
+      "reply_timeout": 5
+    }
+  }
+}
+```
+
+| Field | Type | Required | Description |
+| ---------------- | ------ | -------- | ---------------------------------------- |
+| corp_id | string | Yes | Enterprise ID |
+| corp_secret | string | Yes | Application secret |
+| agent_id | int | Yes | Application agent ID |
+| token | string | Yes | Callback verification token |
+| encoding_aes_key | string | Yes | 43-character AES key |
+| webhook_path | string | No | Webhook path (default: /webhook/wecom-app) |
+| allow_from | array | No | User ID allowlist |
+| reply_timeout | int | No | Reply timeout in seconds |
+
+## Setup
+
+1. Log in to the [WeCom Admin Console](https://work.weixin.qq.com/)
+2. Go to "App Management" -> "Create App"
+3. Obtain the Enterprise ID (CorpID) and App Secret
+4. Configure "Receive Messages" in the app settings to get the Token and EncodingAESKey
+5. Set the callback URL to `http://<your-server-ip>:<port>/webhook/wecom-app`
+6. Enter the CorpID, Secret, AgentID, and other details into the config file
+
+   Note: PicoClaw now uses a shared Gateway HTTP server to receive webhook callbacks for all channels. The default listening address is 127.0.0.1:18790. To receive callbacks from the public internet, reverse-proxy your external domain to the Gateway (default port 18790).
diff --git a/docs/channels/wecom/wecom_app/README.pt-br.md b/docs/channels/wecom/wecom_app/README.pt-br.md
new file mode 100644
index 000000000..bd0538ed0
--- /dev/null
+++ b/docs/channels/wecom/wecom_app/README.pt-br.md
@@ -0,0 +1,47 @@
+> Voltar ao [README](../../../../README.pt-br.md)
+
+# App Interno WeCom
+
+Um App Interno WeCom é um aplicativo criado por uma empresa dentro do WeCom, destinado principalmente ao uso interno. Por meio dos Apps Internos WeCom, as empresas podem alcançar comunicação e colaboração eficientes com os funcionários, melhorando a produtividade.
+
+## Configuração
+
+```json
+{
+  "channels": {
+    "wecom_app": {
+      "enabled": true,
+      "corp_id": "wwxxxxxxxxxxxxxxxx",
+      "corp_secret": "YOUR_CORP_SECRET",
+      "agent_id": 1000002,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": [],
+      "reply_timeout": 5
+    }
+  }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ---------------- | ------ | ----------- | ---------------------------------------- |
+| corp_id | string | Sim | ID da empresa |
+| corp_secret | string | Sim | Segredo da aplicação |
+| agent_id | int | Sim | ID do agente da aplicação |
+| token | string | Sim | Token de verificação de callback |
+| encoding_aes_key | string | Sim | Chave AES de 43 caracteres |
+| webhook_path | string | Não | Caminho do webhook (padrão: /webhook/wecom-app) |
+| allow_from | array | Não | Lista de permissão de IDs de usuários |
+| reply_timeout | int | Não | Timeout de resposta em segundos |
+
+## Configuração passo a passo
+
+1. Faça login no [Console de Administração do WeCom](https://work.weixin.qq.com/)
+2. Acesse "Gerenciamento de Apps" -> "Criar App"
+3. Obtenha o ID da Empresa (CorpID) e o Secret do App
+4. Configure "Receber Mensagens" nas configurações do app para obter o Token e o EncodingAESKey
+5. Defina a URL de callback como `http://<your-server-ip>:<port>/webhook/wecom-app`
+6. Insira o CorpID, Secret, AgentID e outras informações no arquivo de configuração
+
+   Nota: O PicoClaw agora usa um servidor HTTP Gateway compartilhado para receber callbacks de webhook de todos os canais. O endereço de escuta padrão é 127.0.0.1:18790. Para receber callbacks da internet pública, configure um reverse proxy do seu domínio externo para o Gateway (porta padrão 18790).
diff --git a/docs/channels/wecom/wecom_app/README.vi.md b/docs/channels/wecom/wecom_app/README.vi.md
new file mode 100644
index 000000000..f713f9501
--- /dev/null
+++ b/docs/channels/wecom/wecom_app/README.vi.md
@@ -0,0 +1,47 @@
+> Quay lại [README](../../../../README.vi.md)
+
+# Ứng dụng nội bộ WeCom
+
+Ứng dụng nội bộ WeCom là ứng dụng được doanh nghiệp tạo ra trong WeCom, chủ yếu dùng cho mục đích nội bộ. Thông qua ứng dụng nội bộ WeCom, doanh nghiệp có thể thực hiện giao tiếp và cộng tác hiệu quả với nhân viên, nâng cao hiệu suất làm việc.
+
+## Cấu hình
+
+```json
+{
+  "channels": {
+    "wecom_app": {
+      "enabled": true,
+      "corp_id": "wwxxxxxxxxxxxxxxxx",
+      "corp_secret": "YOUR_CORP_SECRET",
+      "agent_id": 1000002,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": [],
+      "reply_timeout": 5
+    }
+  }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ---------------- | ------ | --------- | ---------------------------------------- |
+| corp_id | string | Có | ID doanh nghiệp |
+| corp_secret | string | Có | Secret của ứng dụng |
+| agent_id | int | Có | ID agent của ứng dụng |
+| token | string | Có | Token xác minh callback |
+| encoding_aes_key | string | Có | Khóa AES 43 ký tự |
+| webhook_path | string | Không | Đường dẫn webhook (mặc định: /webhook/wecom-app) |
+| allow_from | array | Không | Danh sách cho phép ID người dùng |
+| reply_timeout | int | Không | Thời gian chờ phản hồi tính bằng giây |
+
+## Hướng dẫn thiết lập
+
+1. Đăng nhập vào [Bảng điều khiển quản trị WeCom](https://work.weixin.qq.com/)
+2. Vào "Quản lý ứng dụng" -> "Tạo ứng dụng"
+3. Lấy ID doanh nghiệp (CorpID) và Secret của ứng dụng
+4. Cấu hình "Nhận tin nhắn" trong cài đặt ứng dụng để lấy Token và EncodingAESKey
+5. Đặt URL callback thành `http://<your-server-ip>:<port>/webhook/wecom-app`
+6. Nhập CorpID, Secret, AgentID và các thông tin khác vào file cấu hình
+
+   Lưu ý: PicoClaw hiện sử dụng máy chủ HTTP Gateway dùng chung để nhận callback webhook cho tất cả các kênh. Địa chỉ lắng nghe mặc định là 127.0.0.1:18790. Để nhận callback từ internet công cộng, hãy cấu hình reverse proxy từ tên miền bên ngoài của bạn đến Gateway (cổng mặc định 18790).
diff --git a/docs/channels/wecom/wecom_app/README.zh.md b/docs/channels/wecom/wecom_app/README.zh.md
index 0a9858107..81268692d 100644
--- a/docs/channels/wecom/wecom_app/README.zh.md
+++ b/docs/channels/wecom/wecom_app/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../../README.zh.md)
+
 # 企业微信自建应用
 
 企业微信自建应用是指企业在企业微信中创建的应用，主要用于企业内部使用。通过企业微信自建应用，企业可以实现与员工的高效沟通和协作，提高工作效率。
diff --git a/docs/channels/wecom/wecom_bot/README.fr.md b/docs/channels/wecom/wecom_bot/README.fr.md
new file mode 100644
index 000000000..fa3caeb37
--- /dev/null
+++ b/docs/channels/wecom/wecom_bot/README.fr.md
@@ -0,0 +1,41 @@
+> Retour au [README](../../../../README.fr.md)
+
+# WeCom Bot
+
+Le WeCom Bot est une méthode d'intégration rapide fournie par WeCom, permettant de recevoir des messages via une URL Webhook.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+      "webhook_path": "/webhook/wecom",
+      "allow_from": [],
+      "reply_timeout": 5
+    }
+  }
+}
+```
+
+| Champ | Type | Requis | Description |
+| ---------------- | ------ | ------ | -------------------------------------------- |
+| token | string | Oui | Jeton de vérification de signature |
+| encoding_aes_key | string | Oui | Clé AES de 43 caractères utilisée pour le déchiffrement |
+| webhook_url | string | Oui | URL Webhook du bot de groupe WeCom utilisée pour envoyer les réponses |
+| webhook_path | string | Non | Chemin de l'endpoint webhook (par défaut : /webhook/wecom) |
+| allow_from | array | Non | Liste blanche d'ID utilisateurs (vide = autoriser tous les utilisateurs) |
+| reply_timeout | int | Non | Délai de réponse en secondes (par défaut : 5) |
+
+## Procédure de configuration
+
+1. Ajouter un bot à un groupe WeCom
+2. Obtenir l'URL Webhook
+3. (Pour recevoir des messages) Configurer l'adresse API de réception des messages (URL de callback), le Token et l'EncodingAESKey sur la page de configuration du bot
+4. Saisir les informations pertinentes dans le fichier de configuration
+
+   Remarque : PicoClaw utilise désormais un serveur HTTP Gateway partagé pour recevoir les callbacks webhook de tous les canaux. L'adresse d'écoute par défaut est 127.0.0.1:18790. Pour recevoir des callbacks depuis l'internet public, configurez un reverse proxy de votre domaine externe vers le Gateway (port par défaut 18790).
diff --git a/docs/channels/wecom/wecom_bot/README.ja.md b/docs/channels/wecom/wecom_bot/README.ja.md
new file mode 100644
index 000000000..c932c6b4f
--- /dev/null
+++ b/docs/channels/wecom/wecom_bot/README.ja.md
@@ -0,0 +1,41 @@
+> [README](../../../../README.ja.md) に戻る
+
+# 企業WeChat ボット
+
+企業WeChat ボットは、企業WeChatが提供するWebhook URLを通じてメッセージを受信できる迅速な連携方式です。
+
+## 設定
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+      "webhook_path": "/webhook/wecom",
+      "allow_from": [],
+      "reply_timeout": 5
+    }
+  }
+}
+```
+
+| フィールド | 型 | 必須 | 説明 |
+| ---------------- | ------ | ---- | -------------------------------------------- |
+| token | string | はい | 署名検証トークン |
+| encoding_aes_key | string | はい | 復号化に使用する43文字のAESキー |
+| webhook_url | string | はい | 返信送信に使用する企業WeChatグループボットのWebhook URL |
+| webhook_path | string | いいえ | Webhookエンドポイントパス（デフォルト：/webhook/wecom） |
+| allow_from | array | いいえ | ユーザーIDの許可リスト（空 = 全ユーザーを許可） |
+| reply_timeout | int | いいえ | 返信タイムアウト（秒、デフォルト：5） |
+
+## セットアップ手順
+
+1. 企業WeChatグループにボットを追加
+2. Webhook URLを取得
+3. （メッセージを受信する場合）ボット設定ページでメッセージ受信APIアドレス（コールバックURL）、Token、EncodingAESKeyを設定
+4. 関連情報を設定ファイルに入力
+
+   注意：PicoClawは現在、すべてのチャンネルのwebhookコールバックを受信するために共有のGateway HTTPサーバーを使用しています。デフォルトのリスニングアドレスは127.0.0.1:18790です。公共インターネットからコールバックを受信するには、外部ドメインをGateway（デフォルトポート18790）にリバースプロキシしてください。
diff --git a/docs/channels/wecom/wecom_bot/README.md b/docs/channels/wecom/wecom_bot/README.md
new file mode 100644
index 000000000..2600a6a6b
--- /dev/null
+++ b/docs/channels/wecom/wecom_bot/README.md
@@ -0,0 +1,41 @@
+> Back to [README](../../../../README.md)
+
+# WeCom Bot
+
+WeCom Bot is a quick integration method provided by WeCom that can receive messages via a Webhook URL.
+
+## Configuration
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+      "webhook_path": "/webhook/wecom",
+      "allow_from": [],
+      "reply_timeout": 5
+    }
+  }
+}
+```
+
+| Field | Type | Required | Description |
+| ---------------- | ------ | -------- | -------------------------------------------- |
+| token | string | Yes | Signature verification token |
+| encoding_aes_key | string | Yes | 43-character AES key used for decryption |
+| webhook_url | string | Yes | WeCom group bot webhook URL used to send replies |
+| webhook_path | string | No | Webhook endpoint path (default: /webhook/wecom) |
+| allow_from | array | No | User ID allowlist (empty = allow all users) |
+| reply_timeout | int | No | Reply timeout in seconds (default: 5) |
+
+## Setup
+
+1. Add a bot to a WeCom group
+2. Obtain the Webhook URL
+3. (To receive messages) Configure the message receiving API address (callback URL), Token, and EncodingAESKey on the bot configuration page
+4. Enter the relevant information into the config file
+
+   Note: PicoClaw now uses a shared Gateway HTTP server to receive webhook callbacks for all channels. The default listening address is 127.0.0.1:18790. To receive callbacks from the public internet, reverse-proxy your external domain to the Gateway (default port 18790).
diff --git a/docs/channels/wecom/wecom_bot/README.pt-br.md b/docs/channels/wecom/wecom_bot/README.pt-br.md
new file mode 100644
index 000000000..4b3af1404
--- /dev/null
+++ b/docs/channels/wecom/wecom_bot/README.pt-br.md
@@ -0,0 +1,41 @@
+> Voltar ao [README](../../../../README.pt-br.md)
+
+# WeCom Bot
+
+O WeCom Bot é um método de integração rápida fornecido pelo WeCom que pode receber mensagens via URL de Webhook.
+
+## Configuração
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+      "webhook_path": "/webhook/wecom",
+      "allow_from": [],
+      "reply_timeout": 5
+    }
+  }
+}
+```
+
+| Campo | Tipo | Obrigatório | Descrição |
+| ---------------- | ------ | ----------- | -------------------------------------------- |
+| token | string | Sim | Token de verificação de assinatura |
+| encoding_aes_key | string | Sim | Chave AES de 43 caracteres usada para descriptografia |
+| webhook_url | string | Sim | URL do webhook do bot de grupo WeCom usada para enviar respostas |
+| webhook_path | string | Não | Caminho do endpoint webhook (padrão: /webhook/wecom) |
+| allow_from | array | Não | Lista de permissão de IDs de usuários (vazio = permitir todos) |
+| reply_timeout | int | Não | Timeout de resposta em segundos (padrão: 5) |
+
+## Configuração passo a passo
+
+1. Adicione um bot a um grupo WeCom
+2. Obtenha a URL do Webhook
+3. (Para receber mensagens) Configure o endereço da API de recebimento de mensagens (URL de callback), Token e EncodingAESKey na página de configuração do bot
+4. Insira as informações relevantes no arquivo de configuração
+
+   Nota: O PicoClaw agora usa um servidor HTTP Gateway compartilhado para receber callbacks de webhook de todos os canais. O endereço de escuta padrão é 127.0.0.1:18790. Para receber callbacks da internet pública, configure um reverse proxy do seu domínio externo para o Gateway (porta padrão 18790).
diff --git a/docs/channels/wecom/wecom_bot/README.vi.md b/docs/channels/wecom/wecom_bot/README.vi.md
new file mode 100644
index 000000000..aab4b46cd
--- /dev/null
+++ b/docs/channels/wecom/wecom_bot/README.vi.md
@@ -0,0 +1,41 @@
+> Quay lại [README](../../../../README.vi.md)
+
+# WeCom Bot
+
+WeCom Bot là phương thức tích hợp nhanh do WeCom cung cấp, có thể nhận tin nhắn qua URL Webhook.
+
+## Cấu hình
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+      "webhook_path": "/webhook/wecom",
+      "allow_from": [],
+      "reply_timeout": 5
+    }
+  }
+}
+```
+
+| Trường | Kiểu | Bắt buộc | Mô tả |
+| ---------------- | ------ | --------- | -------------------------------------------- |
+| token | string | Có | Token xác minh chữ ký |
+| encoding_aes_key | string | Có | Khóa AES 43 ký tự dùng để giải mã |
+| webhook_url | string | Có | URL webhook của bot nhóm WeCom dùng để gửi phản hồi |
+| webhook_path | string | Không | Đường dẫn endpoint webhook (mặc định: /webhook/wecom) |
+| allow_from | array | Không | Danh sách cho phép ID người dùng (rỗng = cho phép tất cả) |
+| reply_timeout | int | Không | Thời gian chờ phản hồi tính bằng giây (mặc định: 5) |
+
+## Hướng dẫn thiết lập
+
+1. Thêm bot vào một nhóm WeCom
+2. Lấy URL Webhook
+3. (Để nhận tin nhắn) Cấu hình địa chỉ API nhận tin nhắn (URL callback), Token và EncodingAESKey trên trang cấu hình bot
+4. Nhập thông tin liên quan vào file cấu hình
+
+   Lưu ý: PicoClaw hiện sử dụng máy chủ HTTP Gateway dùng chung để nhận callback webhook cho tất cả các kênh. Địa chỉ lắng nghe mặc định là 127.0.0.1:18790. Để nhận callback từ internet công cộng, hãy cấu hình reverse proxy từ tên miền bên ngoài của bạn đến Gateway (cổng mặc định 18790).
diff --git a/docs/channels/wecom/wecom_bot/README.zh.md b/docs/channels/wecom/wecom_bot/README.zh.md
index 63d9b84d6..016fcf973 100644
--- a/docs/channels/wecom/wecom_bot/README.zh.md
+++ b/docs/channels/wecom/wecom_bot/README.zh.md
@@ -1,3 +1,5 @@
+> 返回 [README](../../../../README.zh.md)
+
 # 企业微信机器人
 
 企业微信机器人是企业微信提供的一种快速接入方式，可以通过 Webhook URL 接收消息。
diff --git a/docs/channels/weixin/README.md b/docs/channels/weixin/README.md
new file mode 100644
index 000000000..0c51ff3c5
--- /dev/null
+++ b/docs/channels/weixin/README.md
@@ -0,0 +1,58 @@
+# 💬 Weixin (WeChat Personal) Channel
+
+PicoClaw supports connecting to your personal WeChat account using the official Tencent iLink API.
+
+## 🚀 Quick Onboarding
+
+The easiest way to set up the Weixin channel is using the interactive onboarding command:
+
+```bash
+picoclaw auth weixin
+```
+
+This command will:
+1. Request a QR code from the iLink API and display it in your terminal.
+2. Wait for you to scan the QR code with your WeChat mobile app.
+3. Upon approval, automatically save the generated access token to your `~/.picoclaw/config.json`.
+
+After onboarding, you can start the gateway:
+
+```bash
+picoclaw gateway
+```
+
+---
+
+## ⚙️ Configuration
+
+You can also manually configure the filter rules in `config.json` under the `channels.weixin` section.
+
+```json
+{
+  "channels": {
+    "weixin": {
+      "enabled": true,
+      "token": "YOUR_WEIXIN_TOKEN",
+      "allow_from": [
+        "user_id_1",
+        "user_id_2"
+      ],
+      "proxy": ""
+    }
+  }
+}
+```
+
+### Configuration Fields
+
+| Field | Description |
+|---|---|
+| `enabled` | Set to `true` to enable the channel at startup. |
+| `token` | The authentication token obtained via QR login. |
+| `allow_from` | (Optional) List of WeChat User IDs permitted to interact with the bot. If empty, anyone who can send messages to the connected account can trigger the bot. |
+| `proxy` | (Optional) HTTP proxy address (e.g. `http://localhost:7890`) for environments where connection to `ilinkai.weixin.qq.com` is restricted. |
+
+## ⚠️ Important Notes
+
+- **One Account Only**: The iLink token binds to a single session. Starting a new interaction generally invalidates older tokens if another device authorizes.
+- **Message Rate Limits**: To avoid getting your account restricted by WeChat anti-spam systems, avoid loop triggers or high-frequency broadcasts.
diff --git a/docs/channels/weixin/README.zh.md b/docs/channels/weixin/README.zh.md
new file mode 100644
index 000000000..0f1181878
--- /dev/null
+++ b/docs/channels/weixin/README.zh.md
@@ -0,0 +1,58 @@
+# 💬 微信个人号渠道 (Weixin)
+
+PicoClaw 支持使用腾讯官方 iLink API 连接您的个人微信账号。
+
+## 🚀 快速激活
+
+最简单的方法是使用交互式 onboarding 命令进行一键激活：
+
+```bash
+picoclaw auth weixin
+```
+
+该命令将：
+1. 从 iLink API 获取二维码并在终端中打印。
+2. 等待您使用手机微信 App 扫码。
+3. 扫码确认后，自动将生成的 Access Token 保存至您的 `~/.picoclaw/config.json` 中。
+
+配置完成后，即可启动网关：
+
+```bash
+picoclaw gateway
+```
+
+---
+
+## ⚙️ 配置说明
+
+您也可以在 `config.json` 的 `channels.weixin` 段目下进行手动维护。
+
+```json
+{
+  "channels": {
+    "weixin": {
+      "enabled": true,
+      "token": "YOUR_WEIXIN_TOKEN",
+      "allow_from": [
+        "user_id_1",
+        "user_id_2"
+      ],
+      "proxy": ""
+    }
+  }
+}
+```
+
+### 字段解析
+
+| 字段 | 说明 |
+|---|---|
+| `enabled` | 设置为 `true` 以在启动时激活该频道。 |
+| `token` | 通过扫码获取的认证令牌。 |
+| `allow_from` | (可选) 允许与机器人交互的微信 User ID 列表。如果为空，任何能给此微信号发消息的人都可以触发机器人。 |
+| `proxy` | (可选) HTTP 代理地址（例如 `http://localhost:7890`），适合网络访问受限环境。 |
+
+## ⚠️ 注意事项
+
+- **单端绑定**: iLink 令牌通常与单个会话绑定。在其他地方重新扫码激活可能会导致旧令牌失效。
+- **频率控制**: 为避免触发微信的风控反垃圾机制，请避免设置死循环触发、高频广播等恶意行为。
diff --git a/docs/chat-apps.md b/docs/chat-apps.md
new file mode 100644
index 000000000..3d01994ff
--- /dev/null
+++ b/docs/chat-apps.md
@@ -0,0 +1,573 @@
+# 💬 Chat Apps Configuration
+
+> Back to [README](../README.md)
+
+## 💬 Chat Apps
+
+Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, WeCom, Feishu, Slack, IRC, OneBot, MaixCam, or Pico (native protocol)
+
+> **Note**: Channels that rely on HTTP callbacks share a single Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Socket/stream-based channels such as Feishu, DingTalk, and WeCom do not rely on the shared webhook server for inbound delivery.
+
+| Channel              | Difficulty         | Description                                           | Documentation                                                                                                    |
+| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Telegram**         | ⭐ Easy            | Recommended, voice-to-text, long polling (no public IP needed) | [Docs](channels/telegram/README.md)                                                                  |
+| **Discord**          | ⭐ Easy            | Socket Mode, group/DM support, rich bot ecosystem     | [Docs](channels/discord/README.md)                                                                           |
+| **WhatsApp**         | ⭐ Easy            | Native (QR scan) or Bridge URL                        | [Docs](#whatsapp)                                                                                                |
+| **Weixin**           | ⭐ Easy            | Native QR scan (Tencent iLink API)                    | [Docs](#weixin)                                                                            |
+| **Slack**            | ⭐ Easy            | **Socket Mode** (no public IP needed), enterprise     | [Docs](channels/slack/README.md)                                                                             |
+| **Matrix**           | ⭐⭐ Medium        | Federated protocol, self-hosting supported            | [Docs](channels/matrix/README.md)                                                                            |
+| **QQ**               | ⭐⭐ Medium        | Official bot API, Chinese community                   | [Docs](channels/qq/README.md)                                                                                |
+| **DingTalk**         | ⭐⭐ Medium        | Stream mode (no public IP needed), enterprise         | [Docs](channels/dingtalk/README.md)                                                                          |
+| **LINE**             | ⭐⭐⭐ Advanced    | HTTPS Webhook required                                | [Docs](channels/line/README.md)                                                                              |
+| **WeCom (企业微信)** | ⭐⭐⭐ Advanced    | Official AI Bot over WebSocket, streaming + media     | [Docs](channels/wecom/README.md) |
+| **Feishu (飞书)**    | ⭐⭐⭐ Advanced    | Enterprise collaboration, feature-rich                | [Docs](channels/feishu/README.md)                                                                            |
+| **IRC**              | ⭐⭐ Medium        | Server + TLS configuration                            | [Docs](#irc)                                                                                                     |
+| **OneBot**           | ⭐⭐ Medium        | NapCat/Go-CQHTTP compatible, community ecosystem      | [Docs](channels/onebot/README.md)                                                                            |
+| **MaixCam**          | ⭐ Easy            | Hardware integration channel for Sipeed AI cameras    | [Docs](channels/maixcam/README.md)                                                                           |
+| **Pico**             | ⭐ Easy            | Native PicoClaw protocol channel                      |                                                                                                                  |
+
+<a id="telegram"></a>
+<details>
+<summary><b>Telegram</b> (Recommended)</summary>
+
+**1. Create a bot**
+
+* Open Telegram, search `@BotFather`
+* Send `/newbot`, follow prompts
+* Copy the token
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"],
+      "use_markdown_v2": false
+    }
+  }
+}
+```
+
+> Get your user ID from `@userinfobot` on Telegram.
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+**4. Telegram command menu (auto-registered at startup)**
+
+PicoClaw now keeps command definitions in one shared registry. On startup, Telegram will automatically register supported bot commands (for example `/start`, `/help`, `/show`, `/list`, `/use`) so command menu and runtime behavior stay in sync.
+Telegram command menu registration remains channel-local discovery UX; generic command execution is handled centrally in the agent loop via the commands executor.
+
+If command registration fails (network/API transient errors), the channel still starts and PicoClaw retries registration in the background.
+
+You can also manage installed skills directly from Telegram:
+
+- `/list skills`
+- `/use <skill> <message>`
+- `/use <skill>` and then send the actual request in the next message
+- `/use clear`
+
+**4. Advanced Formatting**
+You can set use_markdown_v2: true to enable enhanced formatting options. This allows the bot to utilize the full range of Telegram MarkdownV2 features, including nested styles, spoilers, and custom fixed-width blocks.
+
+</details>
+
+<a id="discord"></a>
+<details>
+<summary><b>Discord</b></summary>
+
+**1. Create a bot**
+
+* Go to <https://discord.com/developers/applications>
+* Create an application → Bot → Add Bot
+* Copy the bot token
+
+**2. Enable intents**
+
+* In the Bot settings, enable **MESSAGE CONTENT INTENT**
+* (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data
+
+**3. Get your User ID**
+* Discord Settings → Advanced → enable **Developer Mode**
+* Right-click your avatar → **Copy User ID**
+
+**4. Configure**
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**5. Invite the bot**
+
+* OAuth2 → URL Generator
+* Scopes: `bot`
+* Bot Permissions: `Send Messages`, `Read Message History`
+* Open the generated invite URL and add the bot to your server
+
+**Optional: Group trigger mode**
+
+By default the bot responds to all messages in a server channel. To restrict responses to @-mentions only, add:
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "mention_only": true }
+    }
+  }
+}
+```
+
+You can also trigger by keyword prefixes (e.g. `!bot`):
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "prefixes": ["!bot"] }
+    }
+  }
+}
+```
+
+**6. Run**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="whatsapp"></a>
+<details>
+<summary><b>WhatsApp</b> (native via whatsmeow)</summary>
+
+PicoClaw can connect to WhatsApp in two ways:
+
+- **Native (recommended):** In-process using [whatsmeow](https://github.com/tulir/whatsmeow). No separate bridge. Set `"use_native": true` and leave `bridge_url` empty. On first run, scan the QR code with WhatsApp (Linked Devices). Session is stored under your workspace (e.g. `workspace/whatsapp/`). The native channel is **optional** to keep the default binary small; build with `-tags whatsapp_native` (e.g. `make build-whatsapp-native` or `go build -tags whatsapp_native ./cmd/...`).
+- **Bridge:** Connect to an external WebSocket bridge. Set `bridge_url` (e.g. `ws://localhost:3001`) and keep `use_native` false.
+
+**Configure (native)**
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "use_native": true,
+      "session_store_path": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+If `session_store_path` is empty, the session is stored in `<workspace>/whatsapp/`. Run `picoclaw gateway`; on first run, scan the QR code printed in the terminal with WhatsApp → Linked Devices.
+
+</details>
+
+<a id="weixin"></a>
+<details>
+<summary><b>Weixin</b> (WeChat Personal)</summary>
+
+PicoClaw supports connecting to your personal WeChat account using the official Tencent iLink API.
+
+**1. Login**
+
+Run the interactive QR login flow:
+```bash
+picoclaw auth weixin
+```
+Scan the printed QR code with your WeChat mobile app. On success, the token is saved to your config.
+
+**2. Configure**
+
+(Optional) Update `allow_from` with your WeChat User ID to restrict who can message the bot:
+```json
+{
+  "channels": {
+    "weixin": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**3. Run**
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="qq"></a>
+<details>
+<summary><b>QQ</b></summary>
+
+**Quick setup (recommended)**
+
+QQ Open Platform provides a one-click setup page for OpenClaw-compatible bots:
+
+1. Open [QQ Bot Quick Start](https://q.qq.com/qqbot/openclaw/index.html) and scan the QR code to log in
+2. A bot is created automatically — copy the **App ID** and **App Secret**
+3. Configure PicoClaw:
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+4. Run `picoclaw gateway` and open QQ to chat with your bot
+
+> The App Secret is only shown once. Save it immediately — viewing it again will force a reset.
+>
+> Bots created via the quick setup page are initially for the creator only and do not support group chats. To enable group access, configure sandbox mode on the [QQ Open Platform](https://q.qq.com/).
+
+**Manual setup**
+
+If you prefer to create the bot manually:
+
+* Log in at [QQ Open Platform](https://q.qq.com/) to register as a developer
+* Create a QQ bot — customize its avatar and name
+* Copy the **App ID** and **App Secret** from the bot settings
+* Configure as shown above and run `picoclaw gateway`
+
+</details>
+
+<a id="dingtalk"></a>
+<details>
+<summary><b>DingTalk</b></summary>
+
+**1. Create a bot**
+
+* Go to [Open Platform](https://open.dingtalk.com/)
+* Create an internal app
+* Copy Client ID and Client Secret
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Set `allow_from` to empty to allow all users, or specify DingTalk user IDs to restrict access.
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+</details>
+
+<a id="matrix"></a>
+<details>
+<summary><b>Matrix</b></summary>
+
+**1. Prepare bot account**
+
+* Use your preferred homeserver (e.g. `https://matrix.org` or self-hosted)
+* Create a bot user and obtain its access token
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+For full options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), see [Matrix Channel Configuration Guide](channels/matrix/README.md).
+
+</details>
+
+<a id="line"></a>
+<details>
+<summary><b>LINE</b></summary>
+
+**1. Create a LINE Official Account**
+
+- Go to [LINE Developers Console](https://developers.line.biz/)
+- Create a provider → Create a Messaging API channel
+- Copy **Channel Secret** and **Channel Access Token**
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> LINE webhook is served on the shared Gateway server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`).
+
+**3. Set up Webhook URL**
+
+LINE requires HTTPS for webhooks. Use a reverse proxy or tunnel:
+
+```bash
+# Example with ngrok (gateway default port is 18790)
+ngrok http 18790
+```
+
+Then set the Webhook URL in LINE Developers Console to `https://your-domain/webhook/line` and enable **Use webhook**.
+
+**4. Run**
+
+```bash
+picoclaw gateway
+```
+
+> In group chats, the bot responds only when @mentioned. Replies quote the original message.
+
+</details>
+
+<a id="wecom"></a>
+<details>
+<summary><b>WeCom (企业微信)</b></summary>
+
+PicoClaw now exposes WeCom as a single AI Bot channel over WebSocket.
+No public webhook callback URL is required.
+
+See [WeCom Configuration Guide](channels/wecom/README.md) for the full configuration reference and migration notes.
+
+**Quick Setup - Recommended**
+
+**1. Authenticate**
+
+```bash
+picoclaw auth wecom
+```
+
+This command shows a QR code, waits for approval in WeCom, and writes `bot_id` + `secret` into `channels.wecom`.
+
+**2. Configure manually if needed**
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "bot_id": "YOUR_BOT_ID",
+      "secret": "YOUR_SECRET",
+      "websocket_url": "wss://openws.work.weixin.qq.com",
+      "send_thinking_message": true,
+      "allow_from": [],
+      "reasoning_channel_id": ""
+    }
+  }
+}
+```
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+> Legacy `wecom_app` and `wecom_aibot` entries are replaced by the unified `channels.wecom` config in this branch.
+
+</details>
+
+<a id="feishu"></a>
+<details>
+<summary><b>Feishu (Lark)</b></summary>
+
+PicoClaw connects to Feishu via WebSocket/SDK mode — no public webhook URL or callback server needed.
+
+**1. Create an app**
+
+* Go to [Feishu Open Platform](https://open.feishu.cn/) and create an application
+* In the app settings, enable the **Bot** capability
+* Create a version and publish the app (the app must be published to take effect)
+* Copy the **App ID** (starts with `cli_`) and **App Secret**
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "app_id": "cli_xxx",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+Optional fields: `encrypt_key` and `verification_token` for event encryption (recommended for production).
+
+**3. Run and chat**
+
+```bash
+picoclaw gateway
+```
+
+Open Feishu, search for your bot name, and start chatting. You can also add the bot to a group — use `group_trigger.mention_only: true` to only respond when @mentioned.
+
+For full options, see [Feishu Channel Configuration Guide](channels/feishu/README.md).
+
+</details>
+
+<a id="slack"></a>
+<details>
+<summary><b>Slack</b></summary>
+
+**1. Create a Slack app**
+
+* Go to [Slack API](https://api.slack.com/apps) and create a new app
+* Under **OAuth & Permissions**, add bot scopes: `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write`
+* Install the app to your workspace
+* Copy the **Bot Token** (`xoxb-...`) and **App-Level Token** (`xapp-...`, enable Socket Mode to get this)
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "bot_token": "xoxb-YOUR-BOT-TOKEN",
+      "app_token": "xapp-YOUR-APP-TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="irc"></a>
+<details>
+<summary><b>IRC</b></summary>
+
+**1. Configure**
+
+```json
+{
+  "channels": {
+    "irc": {
+      "enabled": true,
+      "server": "irc.libera.chat:6697",
+      "tls": true,
+      "nick": "picoclaw-bot",
+      "channels": ["#your-channel"],
+      "password": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+Optional: `nickserv_password` for NickServ authentication, `sasl_user`/`sasl_password` for SASL auth.
+
+**2. Run**
+
+```bash
+picoclaw gateway
+```
+
+The bot will connect to the IRC server and join the specified channels.
+
+</details>
+
+<a id="onebot"></a>
+<details>
+<summary><b>OneBot (QQ via OneBot protocol)</b></summary>
+
+OneBot is an open protocol for QQ bots. PicoClaw connects to any OneBot v11 compatible implementation (e.g., [Lagrange](https://github.com/LagrangeDev/Lagrange.Core), [NapCat](https://github.com/NapNeko/NapCatQQ)) via WebSocket.
+
+**1. Set up a OneBot implementation**
+
+Install and run a OneBot v11 compatible QQ bot framework. Enable its WebSocket server.
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://127.0.0.1:8080",
+      "access_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `ws_url` | WebSocket URL of the OneBot implementation |
+| `access_token` | Access token for authentication (if configured in OneBot) |
+| `reconnect_interval` | Reconnect interval in seconds (default: 5) |
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+</details>
diff --git a/docs/config-versioning.md b/docs/config-versioning.md
new file mode 100644
index 000000000..36d7fdd25
--- /dev/null
+++ b/docs/config-versioning.md
@@ -0,0 +1,230 @@
+# Config Schema Versioning Guide
+
+## Overview
+
+PicoClaw uses a schema versioning system for `config.json` to ensure smooth upgrades as the configuration format evolves.
+
+## Version History
+
+### Version 1
+- **Introduction**: Initial version with version field support
+- **Changes**: Added `version` field to Config struct
+- **Migration**: No structural changes needed for existing configs
+
+## How It Works
+
+### Automatic Migration
+When you load a config file:
+1. The system first reads the `version` field from the JSON
+2. Based on the detected version, it loads the appropriate config struct (`ConfigV0`, `ConfigV1`, etc.)
+3. If the loaded version is less than the latest, migrations are applied incrementally
+4. The version number is updated automatically
+5. The migrated config is automatically saved back to disk
+
+### Version Field
+The `version` field in `config.json` indicates the schema version:
+- `0` or missing: Legacy config (no version field)
+- `1`: Current version with versioning support
+
+```json
+{
+  "version": 1,
+  "agents": {...},
+  ...
+}
+```
+
+## Adding a New Migration
+
+When making breaking changes to the config schema:
+
+### Step 1: Define the New Version Struct
+
+Create a new struct for the new version if the structure changes significantly:
+
+```go
+// ConfigV2 represents version 2 config structure
+type ConfigV2 struct {
+    Version   int             `json:"version"`
+    Agents    AgentsConfig    `json:"agents"`
+    // ... other fields with new structure
+}
+```
+
+### Step 2: Update Current Config Version
+
+```go
+const CurrentConfigVersion = 2  // Increment this
+```
+
+### Step 3: Add a Loader Function
+
+```go
+// loadConfigV2 loads a version 2 config
+func loadConfigV2(data []byte) (*Config, error) {
+    cfg := DefaultConfig()
+
+    // Parse to ConfigV2 struct
+    var v2 ConfigV2
+    if err := json.Unmarshal(data, &v2); err != nil {
+        return nil, err
+    }
+
+    // Convert to current Config
+    cfg.Version = v2.Version
+    cfg.Agents = v2.Agents
+    // ... map other fields
+
+    return cfg, nil
+}
+```
+
+### Step 4: Add Migration Logic
+
+```go
+// applyMigration applies a single migration step from fromVersion to toVersion
+func applyMigration(cfg *Config, fromVersion, toVersion int) (*Config, error) {
+    switch toVersion {
+    case 1:
+        // Migration from version 0 to 1
+        return &Config{
+            Version: 1,
+            Agents:  cfg.Agents,
+            // ... copy all fields
+        }, nil
+    case 2:
+        // Migration from version 1 to 2
+        // Example: Move or rename fields
+        migrated := *cfg
+        migrated.Version = 2
+        // Apply structural changes
+        if cfg.SomeOldField != "" {
+            migrated.SomeNewField = cfg.SomeOldField
+        }
+        return &migrated, nil
+    default:
+        return nil, fmt.Errorf("unsupported migration target version: %d", toVersion)
+    }
+}
+```
+
+### Step 5: Update LoadConfig Switch
+
+```go
+func LoadConfig(path string) (*Config, error) {
+    // ... read file ...
+
+    switch versionInfo.Version {
+    case 0:
+        cfg, err = loadConfigV0(data)
+    case 1:
+        cfg, err = loadConfigV1(data)
+    case 2:
+        cfg, err = loadConfigV2(data)
+    default:
+        return nil, fmt.Errorf("unsupported config version: %d", versionInfo.Version)
+    }
+
+    // ... migrate and validate ...
+}
+```
+
+### Step 6: Test Your Migration
+
+Create a test in `config_migration_test.go`:
+
+```go
+func TestMigrateV1ToV2(t *testing.T) {
+    // Create a version 1 config
+    v1Config := Config{
+        Version: 1,
+        // ... set up test data
+    }
+
+    // Apply migration
+    migrated, err := applyMigration(&v1Config, 1, 2)
+    if err != nil {
+        t.Fatalf("Migration failed: %v", err)
+    }
+
+    // Verify version is updated
+    if migrated.Version != 2 {
+        t.Errorf("Expected version 2, got %d", migrated.Version)
+    }
+
+    // Verify data is preserved/transformed correctly
+    // ...
+}
+```
+
+## Migration Best Practices
+
+1. **Version-Specific Structs**: Define a separate struct for each version that has structural changes
+2. **Backward Compatibility**: Ensure old configs can still be loaded with their specific structs
+3. **No Data Loss**: Migrations should preserve all user settings
+4. **Idempotent**: Running the same migration multiple times should be safe
+5. **Auto-Save**: Migrated configs are automatically saved to update the user's file
+6. **Test Thoroughly**: Test with real user config files
+7. **Update Defaults**: Keep `defaults.go` in sync with the latest schema
+
+## Example Migration
+
+### Scenario: Adding a new field with default value
+
+Old config (version 1):
+```json
+{
+  "version": 1,
+  "agents": {
+    "defaults": {
+      "max_tokens": 32768
+    }
+  }
+}
+```
+
+Migration to version 2:
+```go
+case 2:
+    migrated := *cfg
+    migrated.Version = 2
+
+    // Add new field with default value if not set
+    if migrated.Agents.Defaults.NewFeatureEnabled == false {
+        // Use default value
+    }
+
+    return &migrated, nil
+```
+
+New config (version 2):
+```json
+{
+  "version": 2,
+  "agents": {
+    "defaults": {
+      "max_tokens": 32768,
+      "new_feature_enabled": false
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Config Not Upgrading
+- Check that `CurrentConfigVersion` is incremented
+- Verify migration logic in `applyMigration()` handles the target version
+- Ensure `migrateConfig()` is called in `LoadConfig()`
+
+### Migration Errors
+- Check error messages for specific migration failures
+- Review migration logic for edge cases
+- Ensure all required fields are properly initialized
+- Verify the loader function for the source version
+
+### Data Loss After Migration
+- Ensure all fields are copied during migration
+- Check that the migration doesn't overwrite values with defaults unnecessarily
+- Review the conversion logic in the loader functions
+
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 000000000..4e77300cf
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,761 @@
+# ⚙️ Configuration Guide
+
+> Back to [README](../README.md)
+
+## ⚙️ Configuration
+
+Config file: `~/.picoclaw/config.json`
+
+### Environment Variables
+
+You can override default paths using environment variables. This is useful for portable installations, containerized deployments, or running picoclaw as a system service. These variables are independent and control different paths.
+
+| Variable          | Description                                                                                                                             | Default Path              |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | Overrides the path to the configuration file. This directly tells picoclaw which `config.json` to load, ignoring all other locations. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | Overrides the root directory for picoclaw data. This changes the default location of the `workspace` and other data directories.          | `~/.picoclaw`             |
+
+**Examples:**
+
+```bash
+# Run picoclaw using a specific config file
+# The workspace path will be read from within that config file
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Run picoclaw with all its data stored in /opt/picoclaw
+# Config will be loaded from the default ~/.picoclaw/config.json
+# Workspace will be created at /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Use both for a fully customized setup
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
+### Workspace Layout
+
+PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspace`):
+
+```
+~/.picoclaw/workspace/
+├── sessions/          # Conversation sessions and history
+├── memory/           # Long-term memory (MEMORY.md)
+├── state/            # Persistent state (last channel, etc.)
+├── cron/             # Scheduled jobs database
+├── skills/           # Custom skills
+├── AGENT.md          # Agent behavior guide
+├── HEARTBEAT.md      # Periodic task prompts (checked every 30 min)
+├── IDENTITY.md       # Agent identity
+├── SOUL.md           # Agent soul
+└── USER.md           # User preferences
+```
+
+> **Note:** Changes to `AGENT.md`, `SOUL.md`, `USER.md` and `memory/MEMORY.md` are automatically detected at runtime via file modification time (mtime) tracking. You do **not** need to restart the gateway after editing these files — the agent picks up the new content on the next request.
+
+### Skill Sources
+
+By default, skills are loaded from:
+
+1. `~/.picoclaw/workspace/skills` (workspace)
+2. `~/.picoclaw/skills` (global)
+3. `<binary-embedded-path>/skills` (builtin, set at build time)
+
+For advanced/test setups, you can override the builtin skills root with:
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
+### Using Skills From Chat Channels
+
+Once skills are installed, you can inspect and force them directly from a chat channel:
+
+- `/list skills` shows the installed skill names available to the current agent.
+- `/use <skill> <message>` forces a specific skill for a single request.
+- `/use <skill>` arms that skill for your next message in the same chat session.
+- `/use clear` cancels a pending skill override created by `/use <skill>`.
+
+Examples:
+
+```text
+/list skills
+/use git explain how to squash the last 3 commits
+/use italiapersonalfinance
+dammi le ultime news
+```
+
+### Unified Command Execution Policy
+
+- Generic slash commands are executed through a single path in `pkg/agent/loop.go` via `commands.Executor`.
+- Channel adapters no longer consume generic commands locally; they forward inbound text to the bus/agent path. Telegram still auto-registers supported commands at startup.
+- Unknown slash command (for example `/foo`) passes through to normal LLM processing.
+- Registered but unsupported command on the current channel (for example `/show` on WhatsApp) returns an explicit user-facing error and stops further processing.
+
+### Agent Bindings (Route messages to specific agents)
+
+Use `bindings` in `config.json` to route incoming messages to different agents by channel/account/context.
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "gpt-4o-mini"
+    },
+    "list": [
+      { "id": "main", "default": true, "name": "Main Assistant" },
+      { "id": "support", "name": "Support Assistant" },
+      { "id": "sales", "name": "Sales Assistant" }
+    ]
+  },
+  "bindings": [
+    {
+      "agent_id": "support",
+      "match": {
+        "channel": "telegram",
+        "account_id": "*",
+        "peer": { "kind": "direct", "id": "user123" }
+      }
+    },
+    {
+      "agent_id": "sales",
+      "match": {
+        "channel": "discord",
+        "account_id": "my-discord-bot",
+        "guild_id": "987654321"
+      }
+    }
+  ]
+}
+```
+
+#### `bindings` fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `agent_id` | Yes | Target agent id in `agents.list` |
+| `match.channel` | Yes | Channel name (e.g. `telegram`, `discord`) |
+| `match.account_id` | No | Channel account filter. Use `"*"` for all accounts of that channel. If omitted, only default account is matched |
+| `match.peer.kind` + `match.peer.id` | No | Exact peer match (e.g. direct chat / topic / group id) |
+| `match.guild_id` | No | Guild/server-level match |
+| `match.team_id` | No | Team/workspace-level match |
+
+#### Matching priority
+
+When multiple bindings exist, PicoClaw resolves in this order:
+
+1. `peer`
+2. `parent_peer` (for thread/topic parent contexts)
+3. `guild_id`
+4. `team_id`
+5. `account_id` (non-wildcard)
+6. channel wildcard (`account_id: "*"`)
+7. default agent
+
+If a binding points to a missing `agent_id`, PicoClaw falls back to the default agent.
+
+#### How matching works (step-by-step)
+
+1. PicoClaw first filters bindings by `match.channel` (must equal current channel).
+2. It then filters by `match.account_id`:
+   - omitted: match only the channel's default account
+   - `"*"`: match all accounts on this channel
+   - explicit value: exact account id match (case-insensitive)
+3. From the remaining candidates, it applies the priority chain above and stops at the first hit.
+
+In other words: **channel + account form the candidate set; peer/guild/team then decide final winner**.
+
+#### Common recipes
+
+**1) Route one specific DM user to a specialist agent**
+
+```json
+{
+  "agent_id": "support",
+  "match": {
+    "channel": "telegram",
+    "account_id": "*",
+    "peer": { "kind": "direct", "id": "user123" }
+  }
+}
+```
+
+**2) Route one Discord server (guild) to a dedicated agent**
+
+```json
+{
+  "agent_id": "sales",
+  "match": {
+    "channel": "discord",
+    "account_id": "my-discord-bot",
+    "guild_id": "987654321"
+  }
+}
+```
+
+**3) Route all remaining traffic of a channel to a fallback agent**
+
+```json
+{
+  "agent_id": "main",
+  "match": {
+    "channel": "discord",
+    "account_id": "*"
+  }
+}
+```
+
+#### Authoring guidelines (important)
+
+- Keep exactly one clear default agent in `agents.list` (`"default": true`).
+- Put specific rules (`peer`, `guild_id`, `team_id`) and broad rules (`account_id: "*"` only) together safely; priority already guarantees specific rules win.
+- Avoid duplicate rules with the same specificity and match values. If duplicates exist, the first matching entry in the config array wins.
+- Ensure every `agent_id` exists in `agents.list`; unknown IDs silently fall back to default.
+
+#### Troubleshooting checklist
+
+- **Rule not taking effect?** Check `match.channel` spelling first (must be exact).
+- **Expected account-specific routing but still using default?** Verify `match.account_id` equals actual runtime account id.
+- **Wildcard catches too much traffic?** Add more specific `peer/guild/team` rules for critical paths.
+- **Unexpected default fallback?** Confirm `agent_id` exists and is not misspelled.
+
+### 🔒 Security Sandbox
+
+PicoClaw runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace.
+
+#### Default Configuration
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "restrict_to_workspace": true
+    }
+  }
+}
+```
+
+| Option                  | Default                 | Description                               |
+| ----------------------- | ----------------------- | ----------------------------------------- |
+| `workspace`             | `~/.picoclaw/workspace` | Working directory for the agent           |
+| `restrict_to_workspace` | `true`                  | Restrict file/command access to workspace |
+
+#### Protected Tools
+
+When `restrict_to_workspace: true`, the following tools are sandboxed:
+
+| Tool          | Function         | Restriction                            |
+| ------------- | ---------------- | -------------------------------------- |
+| `read_file`   | Read files       | Only files within workspace            |
+| `write_file`  | Write files      | Only files within workspace            |
+| `list_dir`    | List directories | Only directories within workspace      |
+| `edit_file`   | Edit files       | Only files within workspace            |
+| `append_file` | Append to files  | Only files within workspace            |
+| `exec`        | Execute commands | Command paths must be within workspace |
+
+#### Additional Exec Protection
+
+Even with `restrict_to_workspace: false`, the `exec` tool blocks these dangerous commands:
+
+* `rm -rf`, `del /f`, `rmdir /s` — Bulk deletion
+* `format`, `mkfs`, `diskpart` — Disk formatting
+* `dd if=` — Disk imaging
+* Writing to `/dev/sd[a-z]` — Direct disk writes
+* `shutdown`, `reboot`, `poweroff` — System shutdown
+* Fork bomb `:(){ :|:& };:`
+
+### File Access Control
+
+| Config Key | Type | Default | Description |
+|------------|------|---------|-------------|
+| `tools.allow_read_paths` | string[] | `[]` | Additional paths allowed for reading outside workspace |
+| `tools.allow_write_paths` | string[] | `[]` | Additional paths allowed for writing outside workspace |
+
+### Exec Security
+
+| Config Key | Type | Default | Description |
+|------------|------|---------|-------------|
+| `tools.exec.allow_remote` | bool | `false` | Allow exec tool from remote channels (Telegram/Discord etc.) |
+| `tools.exec.enable_deny_patterns` | bool | `true` | Enable dangerous command interception |
+| `tools.exec.custom_deny_patterns` | string[] | `[]` | Custom regex patterns to block |
+| `tools.exec.custom_allow_patterns` | string[] | `[]` | Custom regex patterns to allow |
+
+> **Security Note:** Symlink protection is enabled by default — all file paths are resolved through `filepath.EvalSymlinks` before whitelist matching, preventing symlink escape attacks.
+
+#### Known Limitation: Child Processes From Build Tools
+
+The exec safety guard only inspects the command line PicoClaw launches directly. It does not recursively inspect child
+processes spawned by allowed developer tools such as `make`, `go run`, `cargo`, `npm run`, or custom build scripts.
+
+That means a top-level command can still compile or launch other binaries after it passes the initial guard check. In
+practice, treat build scripts, Makefiles, package scripts, and generated binaries as executable code that needs the same
+level of review as a direct shell command.
+
+For higher-risk environments:
+
+* Review build scripts before execution.
+* Prefer approval/manual review for compile-and-run workflows.
+* Run PicoClaw inside a container or VM if you need stronger isolation than the built-in guard provides.
+
+#### Error Examples
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (path outside working dir)}
+```
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
+```
+
+#### Disabling Restrictions (Security Risk)
+
+If you need the agent to access paths outside the workspace:
+
+**Method 1: Config file**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "restrict_to_workspace": false
+    }
+  }
+}
+```
+
+**Method 2: Environment variable**
+
+```bash
+export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
+```
+
+> ⚠️ **Warning**: Disabling this restriction allows the agent to access any path on your system. Use with caution in controlled environments only.
+
+#### Security Boundary Consistency
+
+The `restrict_to_workspace` setting applies consistently across all execution paths:
+
+| Execution Path   | Security Boundary            |
+| ---------------- | ---------------------------- |
+| Main Agent       | `restrict_to_workspace` ✅   |
+| Subagent / Spawn | Inherits same restriction ✅ |
+| Heartbeat tasks  | Inherits same restriction ✅ |
+
+All paths share the same workspace restriction — there's no way to bypass the security boundary through subagents or scheduled tasks.
+
+### Heartbeat (Periodic Tasks)
+
+PicoClaw can perform periodic tasks automatically. Create a `HEARTBEAT.md` file in your workspace:
+
+```markdown
+# Periodic Tasks
+
+- Check my email for important messages
+- Review my calendar for upcoming events
+- Check the weather forecast
+```
+
+The agent will read this file every 30 minutes (configurable) and execute any tasks using available tools.
+
+#### Async Tasks with Spawn
+
+For long-running tasks (web search, API calls), use the `spawn` tool to create a **subagent**:
+
+```markdown
+# Periodic Tasks
+
+## Quick Tasks (respond directly)
+
+- Report current time
+
+## Long Tasks (use spawn for async)
+
+- Search the web for AI news and summarize
+- Check email and report important messages
+```
+
+**Key behaviors:**
+
+| Feature                 | Description                                               |
+| ----------------------- | --------------------------------------------------------- |
+| **spawn**               | Creates async subagent, doesn't block heartbeat           |
+| **Independent context** | Subagent has its own context, no session history          |
+| **message tool**        | Subagent communicates with user directly via message tool |
+| **Non-blocking**        | After spawning, heartbeat continues to next task          |
+
+#### How Subagent Communication Works
+
+```
+Heartbeat triggers
+    ↓
+Agent reads HEARTBEAT.md
+    ↓
+For long task: spawn subagent
+    ↓                           ↓
+Continue to next task      Subagent works independently
+    ↓                           ↓
+All tasks done            Subagent uses "message" tool
+    ↓                           ↓
+Respond HEARTBEAT_OK      User receives result directly
+```
+
+The subagent has access to tools (message, web_search, etc.) and can communicate with the user independently without going through the main agent.
+
+**Configuration:**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| Option     | Default | Description                        |
+| ---------- | ------- | ---------------------------------- |
+| `enabled`  | `true`  | Enable/disable heartbeat           |
+| `interval` | `30`    | Check interval in minutes (min: 5) |
+
+**Environment variables:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` to disable
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` to change interval
+
+### Providers
+
+> [!NOTE]
+> Groq provides free voice transcription via Whisper. If configured, audio messages from any channel will be automatically transcribed at the agent level.
+
+| Provider     | Purpose                                 | Get API Key                                                  |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini`     | LLM (Gemini direct)                     | [aistudio.google.com](https://aistudio.google.com)           |
+| `zhipu`      | LLM (Zhipu direct)                      | [bigmodel.cn](https://bigmodel.cn)                           |
+| `volcengine` | LLM (Volcengine direct)                 | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai)                       |
+| `anthropic`  | LLM (Claude direct)                     | [console.anthropic.com](https://console.anthropic.com)       |
+| `openai`     | LLM (GPT direct)                        | [platform.openai.com](https://platform.openai.com)           |
+| `deepseek`   | LLM (DeepSeek direct)                   | [platform.deepseek.com](https://platform.deepseek.com)       |
+| `qwen`       | LLM (Qwen direct)                       | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq`       | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com)                 |
+| `cerebras`   | LLM (Cerebras direct)                   | [cerebras.ai](https://cerebras.ai)                           |
+| `vivgrid`    | LLM (Vivgrid direct)                    | [vivgrid.com](https://vivgrid.com)                           |
+
+### Model Configuration (model_list)
+
+> **What's New?** PicoClaw now uses a **model-centric** configuration approach. Simply specify `vendor/model` format (e.g., `zhipu/glm-4.7`) to add new providers — **zero code changes required!**
+
+This design also enables **multi-agent support** with flexible provider selection:
+
+- **Different agents, different providers**: Each agent can use its own LLM provider
+- **Model fallbacks**: Configure primary and fallback models for resilience
+- **Load balancing**: Distribute requests across multiple endpoints
+- **Centralized configuration**: Manage all providers in one place
+
+#### All Supported Vendors
+
+| Vendor                  | `model` Prefix    | Default API Base                                    | Protocol  | API Key                                                          |
+| ----------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
+| **OpenAI**              | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [Get Key](https://platform.openai.com)                           |
+| **Anthropic**           | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [Get Key](https://console.anthropic.com)                         |
+| **智谱 AI (GLM)**       | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek**            | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [Get Key](https://platform.deepseek.com)                         |
+| **Google Gemini**       | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI    | [Get Key](https://aistudio.google.com/api-keys)                  |
+| **Groq**                | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [Get Key](https://console.groq.com)                              |
+| **Moonshot**            | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [Get Key](https://platform.moonshot.cn)                          |
+| **通义千问 (Qwen)**     | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Get Key](https://dashscope.console.aliyun.com)                  |
+| **NVIDIA**              | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [Get Key](https://build.nvidia.com)                              |
+| **Ollama**              | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | Local (no key needed)                                            |
+| **OpenRouter**          | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [Get Key](https://openrouter.ai/keys)                            |
+| **LiteLLM Proxy**       | `litellm/`        | `http://localhost:4000/v1`                          | OpenAI    | Your LiteLLM proxy key                                           |
+| **VLLM**                | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | Local                                                            |
+| **Cerebras**            | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [Get Key](https://cerebras.ai)                                   |
+| **VolcEngine (Doubao)** | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **神算云**              | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | —                                                                |
+| **BytePlus**            | `byteplus/`       | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [Get Key](https://www.byteplus.com)                              |
+| **Vivgrid**             | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [Get Key](https://vivgrid.com)                                   |
+| **LongCat**             | `longcat/`        | `https://api.longcat.chat/openai`                   | OpenAI    | [Get Key](https://longcat.chat/platform)                         |
+| **ModelScope (魔搭)**   | `modelscope/`     | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [Get Token](https://modelscope.cn/my/tokens)                     |
+| **Antigravity**         | `antigravity/`    | Google Cloud                                        | Custom    | OAuth only                                                       |
+| **GitHub Copilot**      | `github-copilot/` | `localhost:4321`                                    | gRPC      | —                                                                |
+
+#### Basic Configuration
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-openai-key"
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "sk-ant-your-key"
+    },
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-zhipu-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model": "gpt-5.4"
+    }
+  }
+}
+```
+
+#### Vendor-Specific Examples
+
+<details>
+<summary><b>OpenAI</b></summary>
+
+```json
+{
+  "model_name": "gpt-5.4",
+  "model": "openai/gpt-5.4",
+  "api_key": "sk-..."
+}
+```
+
+</details>
+
+<details>
+<summary><b>VolcEngine (Doubao)</b></summary>
+
+```json
+{
+  "model_name": "ark-code-latest",
+  "model": "volcengine/ark-code-latest",
+  "api_key": "sk-..."
+}
+```
+
+</details>
+
+<details>
+<summary><b>智谱 AI (GLM)</b></summary>
+
+```json
+{
+  "model_name": "glm-4.7",
+  "model": "zhipu/glm-4.7",
+  "api_key": "your-key"
+}
+```
+
+</details>
+
+<details>
+<summary><b>DeepSeek</b></summary>
+
+```json
+{
+  "model_name": "deepseek-chat",
+  "model": "deepseek/deepseek-chat",
+  "api_key": "sk-..."
+}
+```
+
+</details>
+
+<details>
+<summary><b>Anthropic</b></summary>
+
+```json
+{
+  "model_name": "claude-sonnet-4.6",
+  "model": "anthropic/claude-sonnet-4.6",
+  "api_key": "sk-ant-your-key"
+}
+```
+
+> Run `picoclaw auth login --provider anthropic` to paste your API token.
+
+For direct Anthropic API access or custom endpoints that only support Anthropic's native message format:
+
+```json
+{
+  "model_name": "claude-opus-4-6",
+  "model": "anthropic-messages/claude-opus-4-6",
+  "api_key": "sk-ant-your-key",
+  "api_base": "https://api.anthropic.com"
+}
+```
+
+> Use `anthropic-messages` when the endpoint requires Anthropic's native `/v1/messages` format instead of OpenAI-compatible `/v1/chat/completions`.
+
+</details>
+
+<details>
+<summary><b>Ollama (local)</b></summary>
+
+```json
+{
+  "model_name": "llama3",
+  "model": "ollama/llama3"
+}
+```
+
+</details>
+
+<details>
+<summary><b>Custom Proxy / LiteLLM</b></summary>
+
+```json
+{
+  "model_name": "my-custom-model",
+  "model": "openai/custom-model",
+  "api_base": "https://my-proxy.com/v1",
+  "api_key": "sk-..."
+}
+```
+
+PicoClaw strips only the outer `litellm/` prefix before sending the request, so `litellm/lite-gpt4` sends `lite-gpt4`, while `litellm/openai/gpt-4o` sends `openai/gpt-4o`.
+
+</details>
+
+#### Load Balancing
+
+Configure multiple endpoints for the same model name — PicoClaw will automatically round-robin between them:
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api1.example.com/v1",
+      "api_key": "sk-key1"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api2.example.com/v1",
+      "api_key": "sk-key2"
+    }
+  ]
+}
+```
+
+#### Migration from Legacy `providers` Config
+
+The old `providers` configuration is **deprecated** but still supported for backward compatibility. See [docs/migration/model-list-migration.md](../migration/model-list-migration.md) for the full guide.
+
+### Provider Architecture
+
+PicoClaw routes providers by protocol family:
+
+- **OpenAI-compatible**: OpenRouter, Groq, Zhipu, vLLM-style endpoints, and most others.
+- **Anthropic**: Claude-native API behavior.
+- **Codex/OAuth**: OpenAI OAuth/token authentication route.
+
+This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`).
+
+<details>
+<summary><b>Zhipu (legacy providers format)</b></summary>
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "providers": {
+    "zhipu": {
+      "api_key": "Your API Key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>Full config example</b></summary>
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": "anthropic/claude-opus-4-5"
+    }
+  },
+  "session": {
+    "dm_scope": "per-channel-peer",
+    "backlog_limit": 20
+  },
+  "providers": {
+    "openrouter": {
+      "api_key": "sk-or-v1-xxx"
+    },
+    "groq": {
+      "api_key": "gsk_xxx"
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456:ABC...",
+      "allow_from": ["123456789"]
+    }
+  },
+  "tools": {
+    "web": {
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      }
+    }
+  },
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+</details>
+
+### Scheduled Tasks / Reminders
+
+PicoClaw supports cron-style scheduled tasks via the `cron` tool. The agent can set, list, and cancel reminders or recurring jobs that trigger at specified times.
+
+```json
+{
+  "tools": {
+    "cron": {
+      "enabled": true,
+      "exec_timeout_minutes": 5
+    }
+  }
+}
+```
+
+Scheduled tasks persist across restarts and are stored in `~/.picoclaw/workspace/cron/`.
+
+### Advanced Topics
+
+| Topic | Description |
+| ----- | ----------- |
+| [Sensitive Data Filtering](sensitive_data_filtering.md) | Filter API keys and tokens from tool results before sending to LLM |
+| [Hook System](hooks/README.md) | Event-driven hooks: observers, interceptors, approval hooks |
+| [Steering](steering.md) | Inject messages into a running agent loop between tool calls |
+| [SubTurn](subturn.md) | Subagent coordination, concurrency control, lifecycle |
+| [Context Management](agent-refactor/context.md) | Context boundary detection, proactive budget check, compression |
diff --git a/docs/credential_encryption.md b/docs/credential_encryption.md
new file mode 100644
index 000000000..dde8c782c
--- /dev/null
+++ b/docs/credential_encryption.md
@@ -0,0 +1,157 @@
+# Credential Encryption
+
+PicoClaw supports encrypting `api_key` values in `model_list` configuration entries.
+Encrypted keys are stored as `enc://<base64>` strings and decrypted automatically at startup.
+
+---
+
+## Quick Start
+
+**1. Set your passphrase**
+
+```bash
+export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
+```
+
+**2. Encrypt an API key**
+
+Run `picoclaw onboard` — it prompts for your passphrase and generates the SSH key,
+then automatically re-encrypts any plaintext `api_key` entries in your config on
+the next `SaveConfig` call. The resulting `enc://` value will look like:
+
+```
+enc://AAAA...base64...
+```
+
+**3. Paste the output into your config**
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-4o",
+      "model": "openai/gpt-4o",
+      "api_key": "enc://AAAA...base64...",
+      "api_base": "https://api.openai.com/v1"
+    }
+  ]
+}
+```
+
+---
+
+## Supported `api_key` Formats
+
+| Format | Example | Behaviour |
+|--------|---------|-----------|
+| Plaintext | `sk-abc123` | Used as-is |
+| File reference | `file://openai.key` | Content read from the same directory as the config file |
+| Encrypted | `enc://<base64>` | Decrypted at startup using `PICOCLAW_KEY_PASSPHRASE` |
+| Empty | `""` | Passed through unchanged (used with `auth_method: oauth`) |
+
+---
+
+## Cryptographic Design
+
+### Key Derivation
+
+Encryption uses **HKDF-SHA256** with an SSH private key as a second factor.
+
+```
+sshHash = SHA256(ssh_private_key_file_bytes)
+ikm     = HMAC-SHA256(key=sshHash, message=passphrase)
+aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+```
+
+### Encryption
+
+```
+AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
+```
+
+### Wire Format
+
+```
+enc://<base64( salt[16] + nonce[12] + ciphertext )>
+```
+
+| Field | Size | Description |
+|-------|------|-------------|
+| `salt` | 16 bytes | Random per encryption; fed into HKDF |
+| `nonce` | 12 bytes | Random per encryption; AES-GCM IV |
+| `ciphertext` | variable | AES-256-GCM ciphertext + 16-byte authentication tag |
+
+The GCM authentication tag is appended to the ciphertext automatically. Any tampering causes decryption to fail with an error rather than returning corrupt plaintext.
+
+### Performance
+
+| Operation | Time (ARM Cortex-A) |
+|-----------|---------------------|
+| Key derivation (HKDF) | < 1 ms |
+| AES-256-GCM decrypt | < 1 ms |
+| **Total startup overhead** | **< 2 ms per key** |
+
+---
+
+## Two-Factor Security with SSH Key
+
+When a SSH private key is provided, breaking the encryption requires **both**:
+
+1. The **passphrase** (`PICOCLAW_KEY_PASSPHRASE`)
+2. The **SSH private key file**
+
+This means a leaked config file alone is not sufficient to recover the API key, even if the passphrase is weak. The SSH key contributes 256 bits of entropy (Ed25519) regardless of passphrase strength.
+
+### Threat Model
+
+| Attacker Has | Can Decrypt? |
+|---|---|
+| Config file only | No — needs passphrase + SSH key |
+| SSH key only | No — needs passphrase |
+| Passphrase only | No — needs SSH key |
+| Config file + SSH key + passphrase | Yes — full compromise |
+
+---
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PICOCLAW_KEY_PASSPHRASE` | Yes (for `enc://`) | Passphrase used for key derivation |
+| `PICOCLAW_SSH_KEY_PATH` | No | Path to SSH private key. If not set, auto-detects from `~/.ssh/picoclaw_ed25519.key` |
+
+### SSH Key Auto-Detection
+
+If `PICOCLAW_SSH_KEY_PATH` is not set, PicoClaw looks for the picoclaw-specific key:
+
+```
+~/.ssh/picoclaw_ed25519.key
+```
+
+This dedicated file avoids conflicts with the user's existing SSH keys.
+Run `picoclaw onboard` to generate it automatically.
+
+`os.UserHomeDir()` is used for cross-platform home directory resolution (reads `USERPROFILE` on Windows, `HOME` on Unix/macOS).
+
+> **Note:** An SSH key file is required for credential encryption. If no key is found and `PICOCLAW_SSH_KEY_PATH` is not set, encryption/decryption will fail. Run `picoclaw onboard` to generate the key automatically.
+
+---
+
+## Migration
+
+Because the only secret material is `PICOCLAW_KEY_PASSPHRASE` and the SSH private key file, migration is straightforward:
+
+1. Copy the config file to the new machine.
+2. Set `PICOCLAW_KEY_PASSPHRASE` to the same value.
+3. Copy the SSH private key file to the same path (or set `PICOCLAW_SSH_KEY_PATH` to its new location).
+
+No re-encryption is needed.
+
+---
+
+## Security Considerations
+
+- **Both passphrase and SSH key are required.** The SSH key acts as a second factor — without it, encryption/decryption will fail. Run `picoclaw onboard` to generate the key if it doesn't exist.
+- **The SSH key is read-only at runtime.** PicoClaw never writes to or modifies the SSH key file.
+- **Plaintext keys remain supported.** Existing configs without `enc://` are unaffected.
+- **The `enc://` format is versioned** via the HKDF `info` field (`picoclaw-credential-v1`), allowing future algorithm upgrades without breaking existing encrypted values.
diff --git a/docs/debug.md b/docs/debug.md
new file mode 100644
index 000000000..b9e776f0f
--- /dev/null
+++ b/docs/debug.md
@@ -0,0 +1,99 @@
+# Debugging PicoClaw
+
+PicoClaw performs multiple complex interactions under the hood for every single request it receives—from routing messages and evaluating complexity, to executing tools and adapting to model failures. Being able to see exactly what is happening is crucial, not just for troubleshooting potential issues, but also for truly understanding how the agent operates.
+## Starting PicoClaw in Debug Mode
+
+To get detailed information about what the agent is doing (LLM requests, tool calls, message routing), you can start the PicoClaw gateway with the debug flag:
+
+```bash
+picoclaw gateway --debug
+# or
+picoclaw gateway -d
+```
+
+In this mode, the system will format the logs extensively and display previews of system prompts and tool execution results.
+
+## Disabling Log Truncation (Full Logs)
+
+By default, PicoClaw truncates very long strings (such as the *System Prompt* or large JSON output results) in the debug logs to keep the console readable.
+
+If you need to inspect the complete output of a command or the exact payload sent to the LLM model, you can use the `--no-truncate` flag.
+
+**Note:** This flag *only* works when combined with the `--debug` mode.
+
+```bash
+picoclaw gateway --debug --no-truncate
+
+```
+
+When this flag is active, the global truncation function is disabled. This is extremely useful for:
+
+* Verifying the exact syntax of the messages sent to the provider.
+* Reading the complete output of tools like `exec`, `web_fetch`, or `read_file`.
+* Debugging the session history saved in memory.
+
+## Tool Call Visibility in Debug Logs
+
+When debug mode is active, the agent emits structured log entries at each stage of the tool execution lifecycle. These entries carry a `component=agent` label and use `INFO` or `DEBUG` level depending on the amount of detail:
+
+| Log message | Level | Key fields | Description |
+|---|---|---|---|
+| `LLM requested tool calls` | INFO | `tools`, `count`, `iteration` | List of tool names the model decided to call |
+| `Tool call: <name>(<args>)` | INFO | `tool`, `iteration` | The tool name and a preview of its arguments (truncated to 200 chars) |
+| `Sent tool result to user` | DEBUG | `tool`, `content_len` | Fired when a tool result is forwarded to the chat channel |
+| `TTL tick after tool execution` | DEBUG | `agent_id`, `iteration` | MCP tool-discovery TTL decrement after each tool round |
+| `Async tool completed, publishing result` | INFO | `tool`, `content_len`, `channel` | Only for tools that run asynchronously in the background |
+
+### Reading a tool call log entry
+
+A typical synchronous tool call produces two consecutive lines in the console:
+
+```
+[...] [INFO] agent: LLM requested tool calls {tools=[web_search], count=1, iteration=1}
+[...] [INFO] agent: Tool call: web_search({"query":"picoclaw release notes"}) {tool=web_search, iteration=1}
+```
+
+The arguments preview is hard-capped at **200 characters** in the logs regardless of the `--no-truncate` flag, because it belongs to the `INFO`-level path. Use `--no-truncate` together with `--debug` to see the full `tools_json` field emitted by the `Full LLM request` DEBUG entry, which contains every tool definition sent to the model.
+
+## Real-Time Tool Feedback in Chat (tool_feedback)
+
+Debug logs are server-side only. If you want the agent to send a visible notification directly into the chat channel every time it executes a tool—useful when sharing the bot with other users or for transparency—enable the `tool_feedback` feature in `config.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "tool_feedback": {
+        "enabled": true,
+        "max_args_length": 300
+      }
+    }
+  }
+}
+```
+
+When `enabled` is `true`, every tool call sends a short message to the chat before the tool result is returned to the model. The message looks like:
+
+```bash
+🔧 `web_search`
+{"query": "picoclaw release notes"}
+```
+
+
+### Options
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | bool | `false` | Send a chat notification for each tool call |
+| `max_args_length` | int | `300` | Maximum characters of the serialised arguments included in the notification |
+
+### Environment variables
+
+Both fields can also be set via environment variables:
+
+```bash
+PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_ENABLED=true
+PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_MAX_ARGS_LENGTH=300
+```
+
+> **Note:** `tool_feedback` is independent of `--debug` mode. It works in production and does not require the gateway to be started with any special flag.
diff --git a/docs/design/hook-system-design.zh.md b/docs/design/hook-system-design.zh.md
new file mode 100644
index 000000000..ab5566bec
--- /dev/null
+++ b/docs/design/hook-system-design.zh.md
@@ -0,0 +1,476 @@
+# PicoClaw Hook 系统设计（基于 `refactor/agent`）
+
+## 背景
+
+本设计围绕两个议题展开：
+
+- `#1316`：把 agent loop 重构为事件驱动、可中断、可追加、可观测
+- `#1796`：在 EventBus 稳定后，把 hooks 设计为 EventBus 的 consumer，而不是重新发明一套事件模型
+
+当前分支已经完成了第一步里的“事件系统基础”，但还没有真正的 hook 挂载层。因此这里的目标不是重新设计 event，而是在已有实现上补出一层可扩展、可拦截、可外挂的 HookManager。
+
+## 外部项目对比
+
+### OpenClaw
+
+OpenClaw 的扩展能力分成三层：
+
+- Internal hooks：目录发现，运行在 Gateway 进程内
+- Plugin hooks：插件在运行时注册 hook，也在进程内
+- Webhooks：外部系统通过 HTTP 触发 Gateway 动作，属于进程外
+
+值得借鉴的点：
+
+- 有“项目内挂载”和“项目外挂载”两种路径
+- hook 是配置驱动，可启停
+- 外部入口有明确的安全边界和映射层
+
+不建议直接照搬的点：
+
+- OpenClaw 的 hooks / plugin hooks / webhooks 是三套路由，PicoClaw 当前体量下会偏重
+- HTTP webhook 更适合“事件进入系统”，不适合作为“可同步拦截 agent loop”的基础机制
+
+### pi-mono
+
+pi-mono 的核心思路更接近当前分支：
+
+- 扩展统一为 extension API
+- 事件分为观察型和可变更型
+- 某些阶段允许 `transform` / `block` / `replace`
+- 扩展代码主要是进程内执行
+- RPC mode 把 UI 交互桥接到进程外客户端
+
+值得借鉴的点：
+
+- 不把“观察”和“拦截”混成一个接口
+- 允许返回结构化动作，而不是只有回调
+- 进程外通信只暴露必要协议，不把整个内部对象图泄露出去
+
+## 当前分支现状
+
+### 已有能力
+
+当前分支已经具备 hook 系统的地基：
+
+- `pkg/agent/events.go` 定义了稳定的 `EventKind`、`EventMeta` 和 payload
+- `pkg/agent/eventbus.go` 提供了非阻塞 fan-out 的 `EventBus`
+- `pkg/agent/loop.go` 中的 `runTurn()` 已在 turn、llm、tool、interrupt、follow-up、summary 等节点发射事件
+- `pkg/agent/steering.go` 已支持 steering、graceful interrupt、hard abort
+- `pkg/agent/turn.go` 已维护 turn phase、恢复点、active turn、abort 状态
+
+### 现有缺口
+
+当前分支还缺四件事：
+
+- 没有 HookManager，只有 EventBus
+- 没有 Before/After LLM、Before/After Tool 这种同步拦截点
+- 没有审批型 hook
+- 子 agent 仍走 `pkg/tools/SubagentManager + RunToolLoop`，没有接入 `pkg/agent` 的 turn tree 和事件流
+
+### 一个关键现实
+
+`#1316` 文案里提到“只读并行、写入串行”的工具执行策略，但当前 `runTurn()` 实现已经先收敛成“顺序执行 + 每个工具后检查 steering / interrupt”。因此 hook 设计不应依赖未来的并行模型，而应该先兼容当前顺序执行，再为以后增加 `ReadOnlyIndicator` 留口子。
+
+## 设计原则
+
+- Hook 必须建立在 `pkg/agent` 的 EventBus 和 turn 上下文之上
+- EventBus 负责广播，HookManager 负责拦截，两者职责分离
+- 项目内挂载要简单，项目外挂载必须走 IPC
+- 观察型 hook 不能阻塞 loop；拦截型 hook 必须有超时
+- 先覆盖主 turn，不把 sub-turn 一次做满
+- 不新增第二套用户事件命名系统，优先复用 `EventKind.String()`
+
+## 总体架构
+
+分成三层：
+
+1. `EventBus`
+   负责广播只读事件，现有实现直接复用
+
+2. `HookManager`
+   负责管理 hook、排序、超时、错误隔离，并在 `runTurn()` 的明确检查点执行同步拦截
+
+3. `HookMount`
+   负责两种挂载方式：
+   - 进程内 Go hook
+   - 进程外 IPC hook
+
+换句话说：
+
+- EventBus 是“发生了什么”
+- HookManager 是“谁能介入”
+- HookMount 是“这些 hook 从哪里来”
+
+## Hook 分类
+
+不建议把所有 hook 都设计成 `OnEvent(evt)`。
+
+建议拆成两类。
+
+### 1. 观察型
+
+只消费事件，不修改流程：
+
+```go
+type EventObserver interface {
+    OnEvent(ctx context.Context, evt agent.Event) error
+}
+```
+
+这类 hook 直接订阅 EventBus 即可。
+
+适用场景：
+
+- 审计日志
+- 指标上报
+- 调试 trace
+- 将事件转发给外部 UI / TUI / Web 面板
+
+### 2. 拦截型
+
+只在少数明确节点触发，允许返回动作：
+
+```go
+type LLMInterceptor interface {
+    BeforeLLM(ctx context.Context, req *LLMRequest) HookDecision[*LLMRequest]
+    AfterLLM(ctx context.Context, resp *LLMResponse) HookDecision[*LLMResponse]
+}
+
+type ToolInterceptor interface {
+    BeforeTool(ctx context.Context, call *ToolCall) HookDecision[*ToolCall]
+    AfterTool(ctx context.Context, result *ToolResultView) HookDecision[*ToolResultView]
+}
+
+type ToolApprover interface {
+    ApproveTool(ctx context.Context, req *ToolApprovalRequest) ApprovalDecision
+}
+```
+
+这里的 `HookDecision` 统一支持：
+
+- `continue`
+- `modify`
+- `deny_tool`
+- `abort_turn`
+- `hard_abort`
+
+## 对外暴露的最小 hook 面
+
+V1 不需要把所有 EventKind 都变成可拦截点。
+
+建议只开放这些同步 hook：
+
+- `before_llm`
+- `after_llm`
+- `before_tool`
+- `after_tool`
+- `approve_tool`
+
+其余节点继续作为只读事件暴露：
+
+- `turn_start`
+- `turn_end`
+- `llm_request`
+- `llm_response`
+- `tool_exec_start`
+- `tool_exec_end`
+- `tool_exec_skipped`
+- `steering_injected`
+- `follow_up_queued`
+- `interrupt_received`
+- `context_compress`
+- `session_summarize`
+- `error`
+
+`subturn_*` 在 V1 中保留名字，但不承诺一定触发，直到子 turn 迁移完成。
+
+## 项目内挂载
+
+内部挂载必须尽量低摩擦。
+
+建议提供两种等价方式，底层都走 HookManager。
+
+### 方式 A：代码显式挂载
+
+```go
+al.MountHook(hooks.Named("audit", &AuditHook{}))
+```
+
+适用于：
+
+- 仓内内建 hook
+- 单元测试
+- feature flag 控制
+
+### 方式 B：内建 registry
+
+```go
+func init() {
+    hooks.RegisterBuiltin("audit", func() hooks.Hook {
+        return &AuditHook{}
+    })
+}
+```
+
+启动时根据配置启用：
+
+```json
+{
+  "hooks": {
+    "builtins": {
+      "audit": { "enabled": true }
+    }
+  }
+}
+```
+
+这比 OpenClaw 的目录扫描更轻，也更贴合 Go 项目。
+
+## 项目外挂载
+
+这是本设计的硬要求。
+
+建议 V1 采用：
+
+- `JSON-RPC over stdio`
+
+原因：
+
+- 跨平台最简单
+- 不依赖额外端口
+- 非常适合“由 PicoClaw 启动一个外部 hook 进程”
+- 比 HTTP webhook 更适合同步拦截
+
+### 外部 hook 进程模型
+
+PicoClaw 启动外部进程，并在其 stdin/stdout 上跑协议。
+
+配置示例：
+
+```json
+{
+  "hooks": {
+    "processes": {
+      "review-gate": {
+        "enabled": true,
+        "transport": "stdio",
+        "command": ["uvx", "picoclaw-hook-reviewer"],
+        "observe": ["turn_start", "turn_end", "tool_exec_end"],
+        "intercept": ["before_tool", "approve_tool"],
+        "timeout_ms": 5000
+      }
+    }
+  }
+}
+```
+
+### 协议边界
+
+不要把内部 Go 结构体直接暴露给 IPC。
+
+建议定义稳定的协议对象：
+
+- `HookHandshake`
+- `HookEventNotification`
+- `BeforeLLMRequest`
+- `AfterLLMRequest`
+- `BeforeToolRequest`
+- `AfterToolRequest`
+- `ApproveToolRequest`
+- `HookDecision`
+
+其中：
+
+- 观察型事件用 notification，fire-and-forget
+- 拦截型事件用 request/response，同步等待
+
+### 为什么是 stdio，而不是直接用 HTTP webhook
+
+因为两者用途不同：
+
+- HTTP webhook 更适合“外部系统向 PicoClaw 投递事件”
+- stdio/RPC 更适合“PicoClaw 在 turn 内同步询问外部 hook 是否改写 / 放行 / 拒绝”
+
+如果未来需要 OpenClaw 式 webhook，可以作为独立入口层，再把外部事件转成 inbound message 或 steering，而不是直接替代 hook IPC。
+
+## Hook 执行顺序
+
+建议统一排序规则：
+
+- 先内建 in-process hook
+- 再外部 IPC hook
+- 同组内按 `priority` 从小到大执行
+
+原因：
+
+- 内建 hook 延迟更低，适合做基础规范化
+- 外部 hook 更适合做审批、审计、组织级策略
+
+## 超时与错误策略
+
+### 观察型
+
+- 默认超时：`500ms`
+- 超时或报错：记录日志，继续主流程
+
+### 拦截型
+
+- `before_llm` / `after_llm` / `before_tool` / `after_tool`：默认 `5s`
+- `approve_tool`：默认 `60s`
+
+超时行为：
+
+- 普通拦截：`continue`
+- 审批：`deny`
+
+这点应直接沿用 `#1316` 的安全倾向。
+
+## 与当前分支的对接点
+
+### 直接复用
+
+- 事件定义：`pkg/agent/events.go`
+- 事件广播：`pkg/agent/eventbus.go`
+- 活跃 turn / interrupt / rollback：`pkg/agent/turn.go`
+- 事件发射点：`pkg/agent/loop.go`
+
+### 需要新增
+
+- `pkg/agent/hooks.go`
+  - Hook 接口
+  - HookDecision / ApprovalDecision
+  - HookManager
+
+- `pkg/agent/hook_mount.go`
+  - 内建 hook 注册
+  - 外部进程 hook 注册
+
+- `pkg/agent/hook_ipc.go`
+  - stdio JSON-RPC bridge
+
+- `pkg/agent/hook_types.go`
+  - IPC 稳定载荷
+
+### 需要改造
+
+- `pkg/agent/loop.go`
+  - 在 LLM 和 tool 关键路径前后插入 HookManager 调用
+
+- `pkg/tools/base.go`
+  - 可选新增 `ReadOnlyIndicator`
+
+- `pkg/tools/spawn.go`
+- `pkg/tools/subagent.go`
+  - 先保留现状
+  - 等 sub-turn 迁移后再接入 `subturn_*` hook
+
+## 一个更贴合当前分支的数据流
+
+### 观察链路
+
+```text
+runTurn() -> emitEvent() -> EventBus -> observers
+```
+
+### 拦截链路
+
+```text
+runTurn()
+  -> HookManager.BeforeLLM()
+  -> Provider.Chat()
+  -> HookManager.AfterLLM()
+  -> HookManager.BeforeTool()
+  -> HookManager.ApproveTool()
+  -> tool.Execute()
+  -> HookManager.AfterTool()
+```
+
+也就是说：
+
+- observer 不改变现有 `emitEvent()`
+- interceptor 直接插在 `runTurn()` 热路径
+
+## 用户可见配置
+
+建议新增：
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "builtins": {},
+    "processes": {},
+    "defaults": {
+      "observer_timeout_ms": 500,
+      "interceptor_timeout_ms": 5000,
+      "approval_timeout_ms": 60000
+    }
+  }
+}
+```
+
+V1 不做复杂自动发现。
+
+原因：
+
+- 当前分支重点是把地基打稳
+- 目录扫描、安装器、脚手架可以后置
+- 先让仓内和仓外都能挂上去，比“管理体验完整”更重要
+
+## 推荐的 V1 范围
+
+### 必做
+
+- HookManager
+- in-process 挂载
+- stdio IPC 挂载
+- observer hooks
+- `before_tool` / `after_tool` / `approve_tool`
+- `before_llm` / `after_llm`
+
+### 可后置
+
+- hook CLI 管理命令
+- hook 自动发现
+- Unix socket / named pipe transport
+- sub-turn hook 生命周期
+- read-only 并行分组
+- webhook 到 inbound message 的映射入口
+
+## 分阶段落地
+
+### Phase 1
+
+- 引入 HookManager
+- 支持 in-process observer + interceptor
+- 先只接主 turn
+
+### Phase 2
+
+- 引入 `stdio` 外部 hook 进程桥
+- 支持组织级审批 / 审计 / 参数改写
+
+### Phase 3
+
+- 把 `SubagentManager` 迁移到 `runTurn/sub-turn`
+- 接通 `subturn_spawn` / `subturn_end` / `subturn_result_delivered`
+
+### Phase 4
+
+- 视需求补 `ReadOnlyIndicator`
+- 在主 turn 和 sub-turn 上统一只读并行策略
+
+## 最终结论
+
+最适合 PicoClaw 当前分支的方案，不是直接复制 OpenClaw 的 hooks，也不是完整照搬 pi-mono 的 extension system，而是：
+
+- 以现有 `EventBus` 为只读观察面
+- 以新增 `HookManager` 为同步拦截面
+- 项目内通过 Go 对象直接挂载
+- 项目外通过 `stdio JSON-RPC` 进程通信挂载
+
+这样做有三个好处：
+
+- 和 `#1796` 一致，hooks 只是 EventBus 之上的消费层
+- 和当前 `refactor/agent` 实现一致，不需要推翻已有事件系统
+- 同时满足“仓内简单挂载”和“仓外进程通信挂载”两个硬需求
diff --git a/docs/design/provider-refactoring.md b/docs/design/provider-refactoring.md
index a214d9857..38f379c50 100644
--- a/docs/design/provider-refactoring.md
+++ b/docs/design/provider-refactoring.md
@@ -66,7 +66,7 @@ Problem: Agent needs to know both `provider` and `model`, adding complexity.
 Inspired by [LiteLLM](https://docs.litellm.ai/docs/proxy/configs) design:
 
 1. **Model-centric**: Users care about models, not providers
-2. **Protocol prefix**: Use `protocol/model_name` format, e.g., `openai/gpt-5.2`, `anthropic/claude-sonnet-4.6`
+2. **Protocol prefix**: Use `protocol/model_name` format, e.g., `openai/gpt-5.4`, `anthropic/claude-sonnet-4.6`
 3. **Configuration-driven**: Adding new Providers only requires config changes, no code changes
 
 ### 2.2 New Configuration Structure
@@ -81,8 +81,8 @@ Inspired by [LiteLLM](https://docs.litellm.ai/docs/proxy/configs) design:
       "api_key": "sk-xxx"
     },
     {
-      "model_name": "gpt-5.2",
-      "model": "openai/gpt-5.2",
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
       "api_key": "sk-xxx"
     },
     {
@@ -128,7 +128,7 @@ type Config struct {
 type ModelConfig struct {
     // Required
     ModelName string `json:"model_name"`  // user-facing name (alias)
-    Model     string `json:"model"`       // protocol/model, e.g., openai/gpt-5.2
+    Model     string `json:"model"`       // protocol/model, e.g., openai/gpt-5.4
 
     // Common config
     APIBase   string `json:"api_base,omitempty"`
@@ -180,7 +180,7 @@ Identify protocol via prefix in `model` field:
       "model": "deepseek-chat"
     },
     "coder": {
-      "model": "gpt-5.2",
+      "model": "gpt-5.4",
       "system_prompt": "You are a coding assistant..."
     },
     "translator": {
@@ -200,7 +200,7 @@ Each Agent only needs to specify `model` (corresponds to `model_name` in `model_
 model_list:
   - model_name: gpt-4o
     litellm_params:
-      model: openai/gpt-5.2
+      model: openai/gpt-5.4
       api_key: xxx
   - model_name: my-custom
     litellm_params:
diff --git a/docs/design/steering-spec.md b/docs/design/steering-spec.md
new file mode 100644
index 000000000..0951bf864
--- /dev/null
+++ b/docs/design/steering-spec.md
@@ -0,0 +1,306 @@
+# Steering — Implementation Specification
+
+## Problem
+
+When the agent is running (executing a chain of tool calls), the user has no way to redirect it. They must wait for the full cycle to complete before sending a new message. This creates a poor experience when the agent takes a wrong direction — the user watches it waste time on tools that are no longer relevant.
+
+## Solution
+
+Steering introduces a **message queue** that external callers can push into at any time. The agent loop polls this queue at well-defined checkpoints. When a steering message is found, the agent:
+
+1. Stops executing further tools in the current batch
+2. Injects the user's message into the conversation context
+3. Calls the LLM again with the updated context
+
+The user's intent reaches the model **as soon as the current tool finishes**, not after the entire turn completes.
+
+## Architecture Overview
+
+```mermaid
+graph TD
+    subgraph External Callers
+        TG[Telegram]
+        DC[Discord]
+        SL[Slack]
+    end
+
+    subgraph AgentLoop
+        BUS[MessageBus]
+        DRAIN[drainBusToSteering goroutine]
+        SQ[steeringQueue]
+        RLI[runLLMIteration]
+        TE[Tool Execution Loop]
+        LLM[LLM Call]
+    end
+
+    TG -->|PublishInbound| BUS
+    DC -->|PublishInbound| BUS
+    SL -->|PublishInbound| BUS
+
+    BUS -->|ConsumeInbound while busy| DRAIN
+    DRAIN -->|Steer| SQ
+
+    RLI -->|1. initial poll| SQ
+    TE -->|2. poll after each tool| SQ
+
+    SQ -->|pendingMessages| RLI
+    RLI -->|inject into context| LLM
+```
+
+### Bus drain mechanism
+
+Channels (Telegram, Discord, etc.) publish messages to the `MessageBus` via `PublishInbound`. Without additional wiring, these messages would sit in the bus buffer until the current `processMessage` finishes — meaning steering would never work for real users.
+
+The solution: when `Run()` starts processing a message, it spawns a **drain goroutine** (`drainBusToSteering`) that keeps consuming from the bus and calling `Steer()`. When `processMessage` returns, the drain is canceled and normal consumption resumes.
+
+```mermaid
+sequenceDiagram
+    participant Bus
+    participant Run
+    participant Drain
+    participant AgentLoop
+
+    Run->>Bus: ConsumeInbound() → msg
+    Run->>Drain: spawn drainBusToSteering(ctx)
+    Run->>Run: processMessage(msg)
+
+    Note over Drain: running concurrently
+
+    Bus-->>Drain: ConsumeInbound() → newMsg
+    Drain->>AgentLoop: al.transcribeAudioInMessage(ctx, newMsg)
+    Drain->>AgentLoop: Steer(providers.Message{Content: newMsg.Content})
+
+    Run->>Run: processMessage returns
+    Run->>Drain: cancel context
+    Note over Drain: exits
+```
+
+## Data Structures
+
+### steeringQueue
+
+A thread-safe FIFO queue, private to the `agent` package.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mu` | `sync.Mutex` | Protects all access to `queue` and `mode` |
+| `queue` | `[]providers.Message` | Pending steering messages |
+| `mode` | `SteeringMode` | Dequeue strategy |
+
+**Methods:**
+
+| Method | Description |
+|--------|-------------|
+| `push(msg) error` | Appends a message to the queue. Returns an error if the queue is full (`MaxQueueSize`) |
+| `dequeue() []Message` | Removes and returns messages according to `mode`. Returns `nil` if empty |
+| `len() int` | Returns the current queue length |
+| `setMode(mode)` | Updates the dequeue strategy |
+| `getMode() SteeringMode` | Returns the current mode |
+
+### SteeringMode
+
+| Value | Constant | Behavior |
+|-------|----------|----------|
+| `"one-at-a-time"` | `SteeringOneAtATime` | `dequeue()` returns only the **first** message. Remaining messages stay in the queue for subsequent polls. |
+| `"all"` | `SteeringAll` | `dequeue()` drains the **entire** queue and returns all messages at once. |
+
+Default: `"one-at-a-time"`.
+
+### processOptions extension
+
+A new field was added to `processOptions`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `SkipInitialSteeringPoll` | `bool` | When `true`, the initial steering poll at loop start is skipped. Used by `Continue()` to avoid double-dequeuing. |
+
+## Public API on AgentLoop
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `Steer` | `Steer(msg providers.Message) error` | Enqueues a steering message. Returns an error if the queue is full or not initialized. Thread-safe, can be called from any goroutine. |
+| `SteeringMode` | `SteeringMode() SteeringMode` | Returns the current dequeue mode. |
+| `SetSteeringMode` | `SetSteeringMode(mode SteeringMode)` | Changes the dequeue mode at runtime. |
+| `Continue` | `Continue(ctx, sessionKey, channel, chatID) (string, error)` | Resumes an idle agent using pending steering messages. Returns `""` if queue is empty. |
+
+## Integration into the Agent Loop
+
+### Where steering is wired
+
+The steering queue lives as a field on `AgentLoop`:
+
+```
+AgentLoop
+  ├── bus
+  ├── cfg
+  ├── registry
+  ├── steering  *steeringQueue   ← new
+  ├── ...
+```
+
+It is initialized in `NewAgentLoop` from `cfg.Agents.Defaults.SteeringMode`.
+
+### Detailed flow through runLLMIteration
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant AgentLoop
+    participant runLLMIteration
+    participant ToolExecution
+    participant LLM
+
+    User->>AgentLoop: Steer(message)
+    Note over AgentLoop: steeringQueue.push(message)
+
+    Note over runLLMIteration: ── iteration starts ──
+
+    runLLMIteration->>AgentLoop: dequeueSteeringMessages()<br/>[initial poll]
+    AgentLoop-->>runLLMIteration: [] (empty, or messages)
+
+    alt pendingMessages not empty
+        runLLMIteration->>runLLMIteration: inject into messages[]<br/>save to session
+    end
+
+    runLLMIteration->>LLM: Chat(messages, tools)
+    LLM-->>runLLMIteration: response with toolCalls[0..N]
+
+    loop for each tool call (sequential)
+        ToolExecution->>ToolExecution: execute tool[i]
+        ToolExecution->>ToolExecution: process result,<br/>append to messages[]
+
+        ToolExecution->>AgentLoop: dequeueSteeringMessages()
+        AgentLoop-->>ToolExecution: steeringMessages
+
+        alt steering found
+            opt remaining tools > 0
+                Note over ToolExecution: Mark tool[i+1..N-1] as<br/>"Skipped due to queued user message."
+            end
+            Note over ToolExecution: steeringAfterTools = steeringMessages
+            Note over ToolExecution: break out of tool loop
+        end
+    end
+
+    alt steeringAfterTools not empty
+        ToolExecution-->>runLLMIteration: pendingMessages = steeringAfterTools
+        Note over runLLMIteration: next iteration will inject<br/>these before calling LLM
+    end
+
+    Note over runLLMIteration: ── loop back to iteration start ──
+```
+
+### Polling checkpoints
+
+| # | Location | When | Purpose |
+|---|----------|------|---------|
+| 1 | Top of `runLLMIteration`, before first LLM call | Once, at loop entry | Catch messages enqueued while the agent was still setting up context |
+| 2 | After every tool completes (including the first and the last) | Immediately after each tool's result is processed | Interrupt the batch as early as possible — if steering is found and there are remaining tools, they are all skipped |
+
+### What happens to skipped tools
+
+When steering interrupts a tool batch after tool `[i]` completes, all tools from `[i+1]` to `[N-1]` are **not executed**. Instead, a tool result message is generated for each:
+
+```json
+{
+  "role": "tool",
+  "content": "Skipped due to queued user message.",
+  "tool_call_id": "<original_call_id>"
+}
+```
+
+These results are:
+- Appended to the conversation `messages[]`
+- Saved to the session via `AddFullMessage`
+
+This ensures the LLM knows which of its requested actions were not performed.
+
+### Loop condition change
+
+The iteration loop condition was changed from:
+
+```go
+for iteration < agent.MaxIterations
+```
+
+to:
+
+```go
+for iteration < agent.MaxIterations || len(pendingMessages) > 0
+```
+
+This allows **one extra iteration** when steering arrives right at the max iteration boundary, ensuring the steering message is always processed.
+
+### Tool execution: parallel → sequential
+
+**Before steering:** all tool calls in a batch were executed in parallel using `sync.WaitGroup`.
+
+**After steering:** tool calls execute **sequentially**. This is required because steering must be polled between individual tool completions. A parallel execution model would not allow interrupting mid-batch.
+
+> **Trade-off:** This introduces latency when the LLM requests multiple independent tools in a single turn. In practice, most batches contain 1-2 tools, so the impact is minimal. The benefit of being able to interrupt outweighs the cost.
+
+### Why skip remaining tools (instead of letting them finish)
+
+Two strategies were considered when a steering message is detected mid-batch:
+
+1. **Skip remaining tools** (chosen) — stop executing, mark the rest as skipped, inject steering
+2. **Finish all tools, then inject** — let everything run, append steering afterwards
+
+Strategy 2 was rejected for three reasons:
+
+**Irreversible side effects.** Tools can send emails, write files, spawn subagents, or call external APIs. If the user says "stop" or "change direction", those actions have already happened and cannot be undone.
+
+| Tool batch | Steering | Skip (1) | Finish (2) |
+|---|---|---|---|
+| `[search, send_email]` | "don't send it" | Email not sent | Email sent |
+| `[query, write_file, spawn]` | "wrong database" | Only query runs | File + subagent wasted |
+| `[fetch₁, fetch₂, fetch₃, write]` | topic change | 1 fetch | 3 fetches + write, all discarded |
+
+**Wasted latency.** Tools like web fetches and API calls take seconds each. In a 3-tool batch averaging 3-4s per tool, the user would wait 10+ seconds for work that gets thrown away.
+
+**The LLM retains full awareness.** Skipped tools receive an explicit `"Skipped due to queued user message."` result, so the model knows what was not done and can decide whether to re-execute with the new context or take a different path.
+
+## The Continue() method
+
+`Continue` handles the case where the agent is **idle** (its last message was from the assistant) and the user has enqueued steering messages in the meantime.
+
+```mermaid
+flowchart TD
+    A[Continue called] --> B{dequeueSteeringMessages}
+    B -->|empty| C["return ('', nil)"]
+    B -->|messages found| D[Combine message contents]
+    D --> E["runAgentLoop with<br/>SkipInitialSteeringPoll: true"]
+    E --> F[Return response]
+```
+
+**Why `SkipInitialSteeringPoll: true`?** Because `Continue` already dequeued the messages itself. Without this flag, `runLLMIteration` would poll again at the start and find nothing (the queue is already empty), or worse, double-process if new messages arrived in the meantime.
+
+## Configuration
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "steering_mode": "one-at-a-time"
+    }
+  }
+}
+```
+
+| Field | Type | Default | Env var |
+|-------|------|---------|---------|
+| `steering_mode` | `string` | `"one-at-a-time"` | `PICOCLAW_AGENTS_DEFAULTS_STEERING_MODE` |
+
+
+## Design decisions and trade-offs
+
+| Decision | Rationale |
+|----------|-----------|
+| Sequential tool execution | Required for per-tool steering polls. Parallel execution cannot be interrupted mid-batch. |
+| Polling-based (not channel/signal) | Keeps the implementation simple. No need for `select` or signal channels. The polling cost is negligible (mutex lock + slice length check). |
+| `one-at-a-time` as default | Gives the model a chance to react to each steering message individually. More predictable behavior than dumping all messages at once. |
+| Skipped tools get explicit error results | The LLM protocol requires a tool result for every tool call in the assistant message. Omitting them would cause API errors. The skip message also informs the model about what was not done. |
+| `Continue()` uses `SkipInitialSteeringPoll` | Prevents race conditions and double-dequeuing when resuming an idle agent. |
+| Queue stored on `AgentLoop`, not `AgentInstance` | Steering is a loop-level concern (it affects the iteration flow), not a per-agent concern. All agents share the same steering queue since `processMessage` is sequential. |
+| Bus drain goroutine in `Run()` | Channels (Telegram, Discord, etc.) publish to the bus via `PublishInbound`. Without the drain, messages would queue in the bus channel buffer and only be consumed after `processMessage` returns — defeating the purpose of steering. The drain goroutine bridges the gap by consuming new bus messages and calling `Steer()` while the agent is busy. |
+| Audio transcription before steering | The drain goroutine calls `al.transcribeAudioInMessage(ctx, msg)` before steering, so voice messages are converted to text before the agent sees them. If transcription fails, the error is silently discarded and the original message is steered as-is. |
+| `MaxQueueSize = 10` | Prevents unbounded memory growth if a user sends many messages while the agent is busy. Excess messages are dropped with a warning. |
diff --git a/docs/docker.md b/docs/docker.md
new file mode 100644
index 000000000..f868d4a42
--- /dev/null
+++ b/docs/docker.md
@@ -0,0 +1,167 @@
+# 🐳 Docker & Quick Start Guide
+
+> Back to [README](../README.md)
+
+## 🐳 Docker Compose
+
+You can also run PicoClaw using Docker Compose without installing anything locally.
+
+```bash
+# 1. Clone this repo
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. First run — auto-generates docker/data/config.json then exits
+#    (only triggers when both config.json and workspace/ are missing)
+docker compose -f docker/docker-compose.yml --profile gateway up
+# The container prints "First-run setup complete." and stops.
+
+# 3. Set your API keys
+vim docker/data/config.json   # Set provider API keys, bot tokens, etc.
+
+# 4. Start
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+> [!TIP]
+> **Docker Users**: By default, the Gateway listens on `127.0.0.1` which is not accessible from the host. If you need to access the health endpoints or expose ports, set `PICOCLAW_GATEWAY_HOST=0.0.0.0` in your environment or update `config.json`.
+
+```bash
+# 5. Check logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. Stop
+docker compose -f docker/docker-compose.yml --profile gateway down
+```
+
+### Launcher Mode (Web Console)
+
+The `launcher` image includes all three binaries (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) and starts the web console by default, which provides a browser-based UI for configuration and chat.
+
+```bash
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+```
+
+Open http://localhost:18800 in your browser. The launcher manages the gateway process automatically.
+
+> [!WARNING]
+> The web console does not yet support authentication. Avoid exposing it to the public internet.
+
+### Agent Mode (One-shot)
+
+```bash
+# Ask a question
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
+
+# Interactive mode
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+```
+
+### Update
+
+```bash
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+### 🚀 Quick Start
+
+> [!TIP]
+> Set your API Key in `~/.picoclaw/config.json`. Get API Keys: [Volcengine (CodingPlan)](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM). Web search is optional — get a free [Tavily API](https://tavily.com) (1000 free queries/month) or [Brave Search API](https://brave.com/search/api) (2000 free queries/month).
+
+**1. Initialize**
+
+```bash
+picoclaw onboard
+```
+
+**2. Configure** (`~/.picoclaw/config.json`)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "gpt-5.4",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key",
+      "api_base":"https://ark.cn-beijing.volces.com/api/coding/v3"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "your-api-key",
+      "request_timeout": 300
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "your-anthropic-key"
+    }
+  ],
+  "tools": {
+    "web": {
+      "enabled": true,
+      "fetch_limit_bytes": 10485760,
+      "format": "plaintext",
+      "brave": {
+        "enabled": false,
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      },
+      "tavily": {
+        "enabled": false,
+        "api_key": "YOUR_TAVILY_API_KEY",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "YOUR_PERPLEXITY_API_KEY",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://your-searxng-instance:8888",
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+> **New**: The `model_list` configuration format allows zero-code provider addition. See [Model Configuration](#model-configuration-model_list) for details.
+> `request_timeout` is optional and uses seconds. If omitted or set to `<= 0`, PicoClaw uses the default timeout (120s).
+
+**3. Get API Keys**
+
+* **LLM Provider**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
+* **Web Search** (optional):
+  * [Brave Search](https://brave.com/search/api) - Paid ($5/1000 queries, ~$5-6/month)
+  * [Perplexity](https://www.perplexity.ai) - AI-powered search with chat interface
+  * [SearXNG](https://github.com/searxng/searxng) - Self-hosted metasearch engine (free, no API key needed)
+  * [Tavily](https://tavily.com) - Optimized for AI Agents (1000 requests/month)
+  * DuckDuckGo - Built-in fallback (no API key required)
+
+> **Note**: See `config.example.json` for a complete configuration template.
+
+**4. Chat**
+
+```bash
+picoclaw agent -m "What is 2+2?"
+```
+
+That's it! You have a working AI assistant in 2 minutes.
+
+---
diff --git a/docs/fr/ANTIGRAVITY_AUTH.md b/docs/fr/ANTIGRAVITY_AUTH.md
new file mode 100644
index 000000000..6cadf5238
--- /dev/null
+++ b/docs/fr/ANTIGRAVITY_AUTH.md
@@ -0,0 +1,809 @@
+> Retour au [README](../../README.fr.md)
+
+# Guide d'authentification et d'intégration Antigravity
+
+## Aperçu
+
+**Antigravity** (Google Cloud Code Assist) est un fournisseur de modèles IA soutenu par Google qui offre l'accès à des modèles tels que Claude Opus 4.6 et Gemini via l'infrastructure cloud de Google. Ce document fournit un guide complet sur le fonctionnement de l'authentification, la récupération des modèles et l'implémentation d'un nouveau fournisseur dans PicoClaw.
+
+---
+
+## Table des matières
+
+1. [Flux d'authentification](#flux-dauthentification)
+2. [Détails de l'implémentation OAuth](#détails-de-limplémentation-oauth)
+3. [Gestion des jetons](#gestion-des-jetons)
+4. [Récupération de la liste des modèles](#récupération-de-la-liste-des-modèles)
+5. [Suivi de l'utilisation](#suivi-de-lutilisation)
+6. [Structure du plugin fournisseur](#structure-du-plugin-fournisseur)
+7. [Exigences d'intégration](#exigences-dintégration)
+8. [Points de terminaison API](#points-de-terminaison-api)
+9. [Configuration](#configuration)
+10. [Créer un nouveau fournisseur dans PicoClaw](#créer-un-nouveau-fournisseur-dans-picoclaw)
+
+---
+
+## Flux d'authentification
+
+### 1. OAuth 2.0 avec PKCE
+
+Antigravity utilise **OAuth 2.0 avec PKCE (Proof Key for Code Exchange)** pour une authentification sécurisée :
+
+```
+┌─────────────┐                                    ┌─────────────────┐
+│   Client    │ ───(1) Generate PKCE Pair────────> │                 │
+│             │ ───(2) Open Auth URL─────────────> │  Google OAuth   │
+│             │                                    │    Server       │
+│             │ <──(3) Redirect with Code───────── │                 │
+│             │                                    └─────────────────┘
+│             │ ───(4) Exchange Code for Tokens──> │   Token URL     │
+│             │                                    │                 │
+│             │ <──(5) Access + Refresh Tokens──── │                 │
+└─────────────┘                                    └─────────────────┘
+```
+
+### 2. Étapes détaillées
+
+#### Étape 1 : Générer les paramètres PKCE
+```typescript
+function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = randomBytes(32).toString("hex");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+```
+
+#### Étape 2 : Construire l'URL d'autorisation
+```typescript
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const REDIRECT_URI = "http://localhost:51121/oauth-callback";
+
+function buildAuthUrl(params: { challenge: string; state: string }): string {
+  const url = new URL(AUTH_URL);
+  url.searchParams.set("client_id", CLIENT_ID);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("redirect_uri", REDIRECT_URI);
+  url.searchParams.set("scope", SCOPES.join(" "));
+  url.searchParams.set("code_challenge", params.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", params.state);
+  url.searchParams.set("access_type", "offline");
+  url.searchParams.set("prompt", "consent");
+  return url.toString();
+}
+```
+
+**Portées requises :**
+```typescript
+const SCOPES = [
+  "https://www.googleapis.com/auth/cloud-platform",
+  "https://www.googleapis.com/auth/userinfo.email",
+  "https://www.googleapis.com/auth/userinfo.profile",
+  "https://www.googleapis.com/auth/cclog",
+  "https://www.googleapis.com/auth/experimentsandconfigs",
+];
+```
+
+#### Étape 3 : Gérer le callback OAuth
+
+**Mode automatique (développement local) :**
+- Démarrer un serveur HTTP local sur le port 51121
+- Attendre la redirection de Google
+- Extraire le code d'autorisation des paramètres de requête
+
+**Mode manuel (distant/sans interface graphique) :**
+- Afficher l'URL d'autorisation à l'utilisateur
+- L'utilisateur complète l'authentification dans son navigateur
+- L'utilisateur colle l'URL de redirection complète dans le terminal
+- Analyser le code depuis l'URL collée
+
+#### Étape 4 : Échanger le code contre des jetons
+```typescript
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+async function exchangeCode(params: {
+  code: string;
+  verifier: string;
+}): Promise<{ access: string; refresh: string; expires: number }> {
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      code: params.code,
+      grant_type: "authorization_code",
+      redirect_uri: REDIRECT_URI,
+      code_verifier: params.verifier,
+    }),
+  });
+
+  const data = await response.json();
+  
+  return {
+    access: data.access_token,
+    refresh: data.refresh_token,
+    expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, // 5 min buffer
+  };
+}
+```
+
+#### Étape 5 : Récupérer les données utilisateur supplémentaires
+
+**E-mail de l'utilisateur :**
+```typescript
+async function fetchUserEmail(accessToken: string): Promise<string | undefined> {
+  const response = await fetch(
+    "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+    { headers: { Authorization: `Bearer ${accessToken}` } }
+  );
+  const data = await response.json();
+  return data.email;
+}
+```
+
+**ID du projet (requis pour les appels API) :**
+```typescript
+async function fetchProjectId(accessToken: string): Promise<string> {
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "google-api-nodejs-client/9.15.1",
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+    "Client-Metadata": JSON.stringify({
+      ideType: "IDE_UNSPECIFIED",
+      platform: "PLATFORM_UNSPECIFIED",
+      pluginType: "GEMINI",
+    }),
+  };
+
+  const response = await fetch(
+    "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        metadata: {
+          ideType: "IDE_UNSPECIFIED",
+          platform: "PLATFORM_UNSPECIFIED",
+          pluginType: "GEMINI",
+        },
+      }),
+    }
+  );
+
+  const data = await response.json();
+  return data.cloudaicompanionProject || "rising-fact-p41fc"; // Valeur par défaut
+}
+```
+
+---
+
+## Détails de l'implémentation OAuth
+
+### Identifiants client
+
+**Important :** Ceux-ci sont encodés en base64 dans le code source pour la synchronisation avec pi-ai :
+
+```typescript
+const decode = (s: string) => Buffer.from(s, "base64").toString();
+
+const CLIENT_ID = decode(
+  "MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ=="
+);
+const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
+```
+
+### Modes de flux OAuth
+
+1. **Flux automatique** (machines locales avec navigateur) :
+   - Ouvre le navigateur automatiquement
+   - Le serveur de callback local capture la redirection
+   - Aucune interaction utilisateur requise après l'authentification initiale
+
+2. **Flux manuel** (distant/sans interface/WSL2) :
+   - URL affichée pour copier-coller manuellement
+   - L'utilisateur complète l'authentification dans un navigateur externe
+   - L'utilisateur colle l'URL de redirection complète
+
+```typescript
+function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+  return isRemote || isWSL2Sync();
+}
+```
+
+---
+
+## Gestion des jetons
+
+### Structure du profil d'authentification
+
+```typescript
+type OAuthCredential = {
+  type: "oauth";
+  provider: "google-antigravity";
+  access: string;           // Jeton d'accès
+  refresh: string;          // Jeton de rafraîchissement
+  expires: number;          // Horodatage d'expiration (ms depuis epoch)
+  email?: string;           // E-mail de l'utilisateur
+  projectId?: string;       // ID du projet Google Cloud
+};
+```
+
+### Rafraîchissement des jetons
+
+Les identifiants incluent un jeton de rafraîchissement qui peut être utilisé pour obtenir de nouveaux jetons d'accès lorsque le jeton actuel expire. L'expiration est définie avec un tampon de 5 minutes pour éviter les conditions de concurrence.
+
+---
+
+## Récupération de la liste des modèles
+
+### Récupérer les modèles disponibles
+
+```typescript
+const BASE_URL = "https://cloudcode-pa.googleapis.com";
+
+async function fetchAvailableModels(
+  accessToken: string,
+  projectId: string
+): Promise<Model[]> {
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "antigravity",
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+  };
+
+  const response = await fetch(
+    `${BASE_URL}/v1internal:fetchAvailableModels`,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ project: projectId }),
+    }
+  );
+
+  const data = await response.json();
+  
+  // Retourne les modèles avec les informations de quota
+  return Object.entries(data.models).map(([modelId, modelInfo]) => ({
+    id: modelId,
+    displayName: modelInfo.displayName,
+    quotaInfo: {
+      remainingFraction: modelInfo.quotaInfo?.remainingFraction,
+      resetTime: modelInfo.quotaInfo?.resetTime,
+      isExhausted: modelInfo.quotaInfo?.isExhausted,
+    },
+  }));
+}
+```
+
+### Format de réponse
+
+```typescript
+type FetchAvailableModelsResponse = {
+  models?: Record<string, {
+    displayName?: string;
+    quotaInfo?: {
+      remainingFraction?: number | string;
+      resetTime?: string;      // Horodatage ISO 8601
+      isExhausted?: boolean;
+    };
+  }>;
+};
+```
+
+---
+
+## Suivi de l'utilisation
+
+### Récupérer les données d'utilisation
+
+```typescript
+export async function fetchAntigravityUsage(
+  token: string,
+  timeoutMs: number
+): Promise<ProviderUsageSnapshot> {
+  // 1. Récupérer les crédits et les informations du plan
+  const loadCodeAssistRes = await fetch(
+    `${BASE_URL}/v1internal:loadCodeAssist`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        metadata: {
+          ideType: "ANTIGRAVITY",
+          platform: "PLATFORM_UNSPECIFIED",
+          pluginType: "GEMINI",
+        },
+      }),
+    }
+  );
+
+  // Extraire les informations de crédits
+  const { availablePromptCredits, planInfo, currentTier } = data;
+  
+  // 2. Récupérer les quotas des modèles
+  const modelsRes = await fetch(
+    `${BASE_URL}/v1internal:fetchAvailableModels`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ project: projectId }),
+    }
+  );
+
+  // Construire les fenêtres d'utilisation
+  return {
+    provider: "google-antigravity",
+    displayName: "Google Antigravity",
+    windows: [
+      { label: "Credits", usedPercent: calculateUsedPercent(available, monthly) },
+      // Quotas individuels des modèles...
+    ],
+    plan: currentTier?.name || planType,
+  };
+}
+```
+
+### Structure de la réponse d'utilisation
+
+```typescript
+type ProviderUsageSnapshot = {
+  provider: "google-antigravity";
+  displayName: string;
+  windows: UsageWindow[];
+  plan?: string;
+  error?: string;
+};
+
+type UsageWindow = {
+  label: string;           // "Credits" ou ID du modèle
+  usedPercent: number;     // 0-100
+  resetAt?: number;        // Horodatage de réinitialisation du quota
+};
+```
+
+---
+
+## Structure du plugin fournisseur
+
+### Définition du plugin
+
+```typescript
+const antigravityPlugin = {
+  id: "google-antigravity-auth",
+  name: "Google Antigravity Auth",
+  description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
+  configSchema: emptyPluginConfigSchema(),
+  
+  register(api: PicoClawPluginApi) {
+    api.registerProvider({
+      id: "google-antigravity",
+      label: "Google Antigravity",
+      docsPath: "/providers/models",
+      aliases: ["antigravity"],
+      
+      auth: [
+        {
+          id: "oauth",
+          label: "Google OAuth",
+          hint: "PKCE + localhost callback",
+          kind: "oauth",
+          run: async (ctx: ProviderAuthContext) => {
+            // Implémentation OAuth ici
+          },
+        },
+      ],
+    });
+  },
+};
+```
+
+### ProviderAuthContext
+
+```typescript
+type ProviderAuthContext = {
+  config: PicoClawConfig;
+  agentDir?: string;
+  workspaceDir?: string;
+  prompter: WizardPrompter;      // Invites/notifications UI
+  runtime: RuntimeEnv;           // Journalisation, etc.
+  isRemote: boolean;             // Exécution à distance ou non
+  openUrl: (url: string) => Promise<void>;  // Ouverture du navigateur
+  oauth: {
+    createVpsAwareHandlers: Function;
+  };
+};
+```
+
+### ProviderAuthResult
+
+```typescript
+type ProviderAuthResult = {
+  profiles: Array<{
+    profileId: string;
+    credential: AuthProfileCredential;
+  }>;
+  configPatch?: Partial<PicoClawConfig>;
+  defaultModel?: string;
+  notes?: string[];
+};
+```
+
+---
+
+## Exigences d'intégration
+
+### 1. Environnement/dépendances requis
+
+- Go ≥ 1.25
+- Base de code PicoClaw (`pkg/providers/` et `pkg/auth/`)
+- Packages de la bibliothèque standard `crypto` et `net/http`
+
+### 2. En-têtes requis pour les appels API
+
+```typescript
+const REQUIRED_HEADERS = {
+  "Authorization": `Bearer ${accessToken}`,
+  "Content-Type": "application/json",
+  "User-Agent": "antigravity",  // ou "google-api-nodejs-client/9.15.1"
+  "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+};
+
+// Pour les appels loadCodeAssist, inclure également :
+const CLIENT_METADATA = {
+  ideType: "ANTIGRAVITY",  // ou "IDE_UNSPECIFIED"
+  platform: "PLATFORM_UNSPECIFIED",
+  pluginType: "GEMINI",
+};
+```
+
+### 3. Assainissement des schémas de modèles
+
+Antigravity utilise des modèles compatibles Gemini, les schémas d'outils doivent donc être assainis :
+
+```typescript
+const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
+  "patternProperties",
+  "additionalProperties",
+  "$schema",
+  "$id",
+  "$ref",
+  "$defs",
+  "definitions",
+  "examples",
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+  "multipleOf",
+  "pattern",
+  "format",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minProperties",
+  "maxProperties",
+]);
+
+// Nettoyer le schéma avant l'envoi
+function cleanToolSchemaForGemini(schema: Record<string, unknown>): unknown {
+  // Supprimer les mots-clés non supportés
+  // S'assurer que le niveau supérieur a type: "object"
+  // Aplatir les unions anyOf/oneOf
+}
+```
+
+### 4. Gestion des blocs de réflexion (modèles Claude)
+
+Pour les modèles Claude via Antigravity, les blocs de réflexion nécessitent un traitement spécial :
+
+```typescript
+const ANTIGRAVITY_SIGNATURE_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+export function sanitizeAntigravityThinkingBlocks(
+  messages: AgentMessage[]
+): AgentMessage[] {
+  // Valider les signatures de réflexion
+  // Normaliser les champs de signature
+  // Rejeter les blocs de réflexion non signés
+}
+```
+
+---
+
+## Points de terminaison API
+
+### Points de terminaison d'authentification
+
+| Point de terminaison | Méthode | Objectif |
+|---------------------|---------|----------|
+| `https://accounts.google.com/o/oauth2/v2/auth` | GET | Autorisation OAuth |
+| `https://oauth2.googleapis.com/token` | POST | Échange de jetons |
+| `https://www.googleapis.com/oauth2/v1/userinfo` | GET | Informations utilisateur (e-mail) |
+
+### Points de terminaison Cloud Code Assist
+
+| Point de terminaison | Méthode | Objectif |
+|---------------------|---------|----------|
+| `https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` | POST | Charger les infos du projet, crédits, plan |
+| `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` | POST | Lister les modèles disponibles avec quotas |
+| `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse` | POST | Point de terminaison de streaming de chat |
+
+**Format de requête API (chat) :**
+Le point de terminaison `v1internal:streamGenerateContent` attend une enveloppe encapsulant la requête Gemini standard :
+
+```json
+{
+  "project": "your-project-id",
+  "model": "model-id",
+  "request": {
+    "contents": [...],
+    "systemInstruction": {...},
+    "generationConfig": {...},
+    "tools": [...]
+  },
+  "requestType": "agent",
+  "userAgent": "antigravity",
+  "requestId": "agent-timestamp-random"
+}
+```
+
+**Format de réponse API (SSE) :**
+Chaque message SSE (`data: {...}`) est encapsulé dans un champ `response` :
+
+```json
+{
+  "response": {
+    "candidates": [...],
+    "usageMetadata": {...},
+    "modelVersion": "...",
+    "responseId": "..."
+  },
+  "traceId": "...",
+  "metadata": {}
+}
+```
+
+---
+
+## Configuration
+
+### Configuration config.json
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gemini-flash",
+      "model": "antigravity/gemini-3-flash",
+      "auth_method": "oauth"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "gemini-flash"
+    }
+  }
+}
+```
+
+### Stockage du profil d'authentification
+
+Les profils d'authentification sont stockés dans `~/.picoclaw/auth.json` :
+
+```json
+{
+  "credentials": {
+    "google-antigravity": {
+      "access_token": "ya29...",
+      "refresh_token": "1//...",
+      "expires_at": "2026-01-01T00:00:00Z",
+      "provider": "google-antigravity",
+      "auth_method": "oauth",
+      "email": "user@example.com",
+      "project_id": "my-project-id"
+    }
+  }
+}
+```
+
+---
+
+## Créer un nouveau fournisseur dans PicoClaw
+
+Les fournisseurs PicoClaw sont implémentés en tant que packages Go sous `pkg/providers/`. Pour ajouter un nouveau fournisseur :
+
+### Implémentation étape par étape
+
+#### 1. Créer le fichier du fournisseur
+
+Créez un nouveau fichier Go dans `pkg/providers/` :
+
+```
+pkg/providers/
+└── your_provider.go
+```
+
+#### 2. Implémenter l'interface Provider
+
+Votre fournisseur doit implémenter l'interface `Provider` définie dans `pkg/providers/types.go` :
+
+```go
+package providers
+
+type YourProvider struct {
+    apiKey  string
+    apiBase string
+}
+
+func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
+    if apiBase == "" {
+        apiBase = "https://api.your-provider.com/v1"
+    }
+    return &YourProvider{apiKey: apiKey, apiBase: apiBase}
+}
+
+func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
+    // Implémenter la complétion de chat avec streaming
+}
+```
+
+#### 3. Enregistrer dans la factory
+
+Ajoutez votre fournisseur au switch de protocole dans `pkg/providers/factory.go` :
+
+```go
+case "your-provider":
+    return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
+```
+
+#### 4. Ajouter la configuration par défaut (optionnel)
+
+Ajoutez une entrée par défaut dans `pkg/config/defaults.go` :
+
+```go
+{
+    ModelName: "your-model",
+    Model:     "your-provider/model-name",
+    APIKey:    "",
+},
+```
+
+#### 5. Ajouter le support d'authentification (optionnel)
+
+Si votre fournisseur nécessite OAuth ou une authentification spéciale, ajoutez un cas dans `cmd/picoclaw/internal/auth/helpers.go` :
+
+```go
+case "your-provider":
+    authLoginYourProvider()
+```
+
+#### 6. Configurer via `config.json`
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "your-model",
+      "model": "your-provider/model-name",
+      "api_key": "your-api-key",
+      "api_base": "https://api.your-provider.com/v1"
+    }
+  ]
+}
+```
+
+---
+
+## Tester votre implémentation
+
+### Commandes CLI
+
+```bash
+# S'authentifier avec un fournisseur
+picoclaw auth login --provider your-provider
+
+# Lister les modèles (pour Antigravity)
+picoclaw auth models
+
+# Démarrer la passerelle
+picoclaw gateway
+
+# Exécuter un agent avec un modèle spécifique
+picoclaw agent -m "Hello" --model your-model
+```
+
+### Variables d'environnement pour les tests
+
+```bash
+# Remplacer le modèle par défaut
+export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
+
+# Remplacer les paramètres du fournisseur
+export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
+```
+
+---
+
+## Références
+
+- **Fichiers source :**
+  - `pkg/providers/antigravity_provider.go` - Implémentation du fournisseur Antigravity
+  - `pkg/auth/oauth.go` - Implémentation du flux OAuth
+  - `pkg/auth/store.go` - Stockage des identifiants d'authentification (`~/.picoclaw/auth.json`)
+  - `pkg/providers/factory.go` - Factory des fournisseurs et routage de protocole
+  - `pkg/providers/types.go` - Définitions de l'interface fournisseur
+  - `cmd/picoclaw/internal/auth/helpers.go` - Commandes CLI d'authentification
+
+- **Documentation :**
+  - `docs/ANTIGRAVITY_USAGE.md` - Guide d'utilisation d'Antigravity
+  - `docs/migration/model-list-migration.md` - Guide de migration
+
+---
+
+## Notes
+
+1. **Projet Google Cloud :** Antigravity nécessite que Gemini for Google Cloud soit activé sur votre projet Google Cloud
+2. **Quotas :** Utilise les quotas du projet Google Cloud (pas de facturation séparée)
+3. **Accès aux modèles :** Les modèles disponibles dépendent de la configuration de votre projet Google Cloud
+4. **Blocs de réflexion :** Les modèles Claude via Antigravity nécessitent un traitement spécial des blocs de réflexion avec signatures
+5. **Assainissement des schémas :** Les schémas d'outils doivent être assainis pour supprimer les mots-clés JSON Schema non supportés
+
+---
+
+---
+
+## Gestion des erreurs courantes
+
+### 1. Limitation de débit (HTTP 429)
+
+Antigravity retourne une erreur 429 lorsque les quotas du projet/modèle sont épuisés. La réponse d'erreur contient souvent un `quotaResetDelay` dans le champ `details`.
+
+**Exemple d'erreur 429 :**
+```json
+{
+  "error": {
+    "code": 429,
+    "message": "You have exhausted your capacity on this model. Your quota will reset after 4h30m28s.",
+    "status": "RESOURCE_EXHAUSTED",
+    "details": [
+      {
+        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+        "metadata": {
+          "quotaResetDelay": "4h30m28.060903746s"
+        }
+      }
+    ]
+  }
+}
+```
+
+### 2. Réponses vides (modèles restreints)
+
+Certains modèles peuvent apparaître dans la liste des modèles disponibles mais retourner une réponse vide (200 OK mais flux SSE vide). Cela se produit généralement pour les modèles en préversion ou restreints que le projet actuel n'a pas la permission d'utiliser.
+
+**Traitement :** Traiter les réponses vides comme des erreurs informant l'utilisateur que le modèle pourrait être restreint ou invalide pour son projet.
+
+---
+
+## Dépannage
+
+### "Token expired" (jeton expiré)
+- Rafraîchir les jetons OAuth : `picoclaw auth login --provider antigravity`
+
+### "Gemini for Google Cloud is not enabled" (Gemini for Google Cloud n'est pas activé)
+- Activer l'API dans votre Google Cloud Console
+
+### "Project not found" (projet non trouvé)
+- Vérifier que votre projet Google Cloud a les API nécessaires activées
+- Vérifier que l'ID du projet est correctement récupéré lors de l'authentification
+
+### Les modèles n'apparaissent pas dans la liste
+- Vérifier que l'authentification OAuth s'est terminée avec succès
+- Vérifier le stockage du profil d'authentification : `~/.picoclaw/auth.json`
+- Relancer `picoclaw auth login --provider antigravity`
diff --git a/docs/fr/ANTIGRAVITY_USAGE.md b/docs/fr/ANTIGRAVITY_USAGE.md
new file mode 100644
index 000000000..d6d0a2bd4
--- /dev/null
+++ b/docs/fr/ANTIGRAVITY_USAGE.md
@@ -0,0 +1,72 @@
+> Retour au [README](../../README.fr.md)
+
+# Utiliser le fournisseur Antigravity dans PicoClaw
+
+Ce guide explique comment configurer et utiliser le fournisseur **Antigravity** (Google Cloud Code Assist) dans PicoClaw.
+
+## Prérequis
+
+1.  Un compte Google.
+2.  Google Cloud Code Assist activé (généralement disponible via l'intégration « Gemini for Google Cloud »).
+
+## 1. Authentification
+
+Pour vous authentifier avec Antigravity, exécutez la commande suivante :
+
+```bash
+picoclaw auth login --provider antigravity
+```
+
+### Authentification manuelle (Headless/VPS)
+Si vous exécutez PicoClaw sur un serveur (Coolify/Docker) et ne pouvez pas accéder à `localhost`, suivez ces étapes :
+1.  Exécutez la commande ci-dessus.
+2.  Copiez l'URL fournie et ouvrez-la dans votre navigateur local.
+3.  Complétez la connexion.
+4.  Votre navigateur sera redirigé vers une URL `localhost:51121` (qui ne se chargera pas).
+5.  **Copiez cette URL finale** depuis la barre d'adresse de votre navigateur.
+6.  **Collez-la dans le terminal** où PicoClaw attend.
+
+PicoClaw extraira automatiquement le code d'autorisation et terminera le processus.
+
+## 2. Gestion des modèles
+
+### Lister les modèles disponibles
+Pour voir quels modèles sont accessibles à votre projet et vérifier leurs quotas :
+
+```bash
+picoclaw auth models
+```
+
+### Changer de modèle
+Vous pouvez modifier le modèle par défaut dans `~/.picoclaw/config.json` ou le remplacer via le CLI :
+
+```bash
+# Remplacer pour une seule commande
+picoclaw agent -m "Hello" --model claude-opus-4-6-thinking
+```
+
+## 3. Utilisation en production (Coolify/Docker)
+
+Si vous déployez via Coolify ou Docker, suivez ces étapes pour tester :
+
+1.  **Variables d'environnement** :
+    *   `PICOCLAW_AGENTS_DEFAULTS_MODEL=gemini-flash`
+2.  **Persistance de l'authentification** :
+    Si vous vous êtes connecté localement, vous pouvez copier vos identifiants vers le serveur :
+    ```bash
+    scp ~/.picoclaw/auth.json user@your-server:~/.picoclaw/
+    ```
+    *Alternativement*, exécutez la commande `auth login` une fois sur le serveur si vous avez un accès terminal.
+
+## 4. Dépannage
+
+*   **Réponse vide** : Si un modèle renvoie une réponse vide, il peut être restreint pour votre projet. Essayez `gemini-3-flash` ou `claude-opus-4-6-thinking`.
+*   **429 Limite de débit** : Antigravity a des quotas stricts. PicoClaw affichera le « temps de réinitialisation » dans le message d'erreur si vous atteignez une limite.
+*   **404 Non trouvé** : Assurez-vous d'utiliser un ID de modèle provenant de la liste `picoclaw auth models`. Utilisez l'ID court (par ex. `gemini-3-flash`) et non le chemin complet.
+
+## 5. Résumé des modèles fonctionnels
+
+D'après les tests, les modèles suivants sont les plus fiables :
+*   `gemini-3-flash` (Rapide, haute disponibilité)
+*   `gemini-2.5-flash-lite` (Léger)
+*   `claude-opus-4-6-thinking` (Puissant, inclut le raisonnement)
diff --git a/docs/fr/chat-apps.md b/docs/fr/chat-apps.md
new file mode 100644
index 000000000..c36e002ff
--- /dev/null
+++ b/docs/fr/chat-apps.md
@@ -0,0 +1,661 @@
+# 💬 Configuration des Applications de Chat
+
+> Retour au [README](../../README.fr.md)
+
+## 💬 Applications de Chat
+
+Communiquez avec votre PicoClaw via Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, WeCom, Feishu, Slack, IRC, OneBot ou MaixCam.
+
+> **Note** : Tous les canaux basés sur les webhooks (LINE, WeCom, etc.) sont servis sur un seul serveur HTTP Gateway partagé (`gateway.host`:`gateway.port`, par défaut `127.0.0.1:18790`). Il n'y a pas de ports par canal à configurer. Note : Feishu utilise le mode WebSocket/SDK et n'utilise pas le serveur HTTP webhook partagé.
+
+| Canal                | Difficulté         | Description                                           | Documentation                                                                                                    |
+| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Telegram**         | ⭐ Facile          | Recommandé, transcription vocale, long polling (pas d'IP publique requise) | [Documentation](../channels/telegram/README.fr.md)                                                  |
+| **Discord**          | ⭐ Facile          | Socket Mode, groupes/DM, écosystème bot riche         | [Documentation](../channels/discord/README.fr.md)                                                               |
+| **WhatsApp**         | ⭐ Facile          | Natif (scan QR) ou Bridge URL                         | [Documentation](#whatsapp)                                                                                       |
+| **Weixin**           | ⭐ Facile          | Scan QR natif (API Tencent iLink)                     | [Documentation](#weixin)                                                                                         |
+| **Slack**            | ⭐ Facile          | **Socket Mode** (pas d'IP publique requise), entreprise | [Documentation](../channels/slack/README.fr.md)                                                                |
+| **Matrix**           | ⭐⭐ Moyen         | Protocole fédéré, auto-hébergement possible           | [Documentation](../channels/matrix/README.fr.md)                                                                |
+| **QQ**               | ⭐⭐ Moyen         | API bot officielle, communauté chinoise               | [Documentation](../channels/qq/README.fr.md)                                                                    |
+| **DingTalk**         | ⭐⭐ Moyen         | Mode Stream (pas d'IP publique requise), entreprise   | [Documentation](../channels/dingtalk/README.fr.md)                                                              |
+| **LINE**             | ⭐⭐⭐ Avancé      | HTTPS Webhook requis                                  | [Documentation](../channels/line/README.fr.md)                                                                  |
+| **WeCom (企业微信)** | ⭐⭐⭐ Avancé      | Bot groupe (Webhook), app personnalisée (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.fr.md) / [App](../channels/wecom/wecom_app/README.fr.md) / [AI Bot](../channels/wecom/wecom_aibot/README.fr.md) |
+| **Feishu (飞书)**    | ⭐⭐⭐ Avancé      | Collaboration entreprise, fonctionnalités riches      | [Documentation](../channels/feishu/README.fr.md)                                                                |
+| **IRC**              | ⭐⭐ Moyen         | Serveur + configuration TLS                           | [Documentation](#irc) |
+| **OneBot**           | ⭐⭐ Moyen         | Compatible NapCat/Go-CQHTTP, écosystème communautaire | [Documentation](../channels/onebot/README.fr.md)                                                                |
+| **MaixCam**          | ⭐ Facile          | Canal d'intégration matérielle pour caméras AI Sipeed | [Documentation](../channels/maixcam/README.fr.md)                                                               |
+| **Pico**             | ⭐ Facile          | Canal protocole natif PicoClaw                        |                                                                                                                  |
+
+<a id="telegram"></a>
+<details>
+<summary><b>Telegram</b> (Recommandé)</summary>
+
+**1. Créer un bot**
+
+* Ouvrez Telegram, recherchez `@BotFather`
+* Envoyez `/newbot`, suivez les instructions
+* Copiez le token
+
+**2. Configurer**
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+> Obtenez votre identifiant utilisateur via `@userinfobot` sur Telegram.
+
+**3. Lancer**
+
+```bash
+picoclaw gateway
+```
+
+**4. Menu de commandes Telegram (enregistré automatiquement au démarrage)**
+
+PicoClaw conserve les définitions de commandes dans un registre partagé unique. Au démarrage, Telegram enregistre automatiquement les commandes bot prises en charge (par exemple `/start`, `/help`, `/show`, `/list`) afin que le menu de commandes et le comportement à l'exécution restent synchronisés.
+L'enregistrement du menu de commandes Telegram reste une découverte UX locale au canal ; l'exécution générique des commandes est gérée de manière centralisée dans la boucle agent via l'exécuteur de commandes.
+
+Si l'enregistrement des commandes échoue (erreurs transitoires réseau/API), le canal démarre quand même et PicoClaw réessaie l'enregistrement en arrière-plan.
+
+</details>
+
+<a id="discord"></a>
+<details>
+<summary><b>Discord</b></summary>
+
+**1. Créer un bot**
+
+* Allez sur <https://discord.com/developers/applications>
+* Créez une application → Bot → Add Bot
+* Copiez le token du bot
+
+**2. Activer les intents**
+
+* Dans les paramètres du Bot, activez **MESSAGE CONTENT INTENT**
+* (Optionnel) Activez **SERVER MEMBERS INTENT** si vous prévoyez d'utiliser des listes d'autorisation basées sur les données des membres
+
+**3. Obtenir votre identifiant utilisateur**
+* Paramètres Discord → Avancé → activez **Developer Mode**
+* Clic droit sur votre avatar → **Copy User ID**
+
+**4. Configurer**
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**5. Inviter le bot**
+
+* OAuth2 → URL Generator
+* Scopes : `bot`
+* Bot Permissions : `Send Messages`, `Read Message History`
+* Ouvrez l'URL d'invitation générée et ajoutez le bot à votre serveur
+
+**Mode déclenchement en groupe (optionnel)**
+
+Par défaut, le bot répond à tous les messages dans un canal de serveur. Pour limiter les réponses aux @mentions uniquement, ajoutez :
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "mention_only": true }
+    }
+  }
+}
+```
+
+Vous pouvez également déclencher par préfixes de mots-clés (par ex. `!bot`) :
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "prefixes": ["!bot"] }
+    }
+  }
+}
+```
+
+**6. Lancer**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="whatsapp"></a>
+<details>
+<summary><b>WhatsApp</b> (natif via whatsmeow)</summary>
+
+PicoClaw peut se connecter à WhatsApp de deux manières :
+
+- **Natif (recommandé) :** En processus via [whatsmeow](https://github.com/tulir/whatsmeow). Pas de bridge séparé. Définissez `"use_native": true` et laissez `bridge_url` vide. Au premier lancement, scannez le code QR avec WhatsApp (Appareils liés). La session est stockée dans votre workspace (par ex. `workspace/whatsapp/`). Le canal natif est **optionnel** pour garder le binaire par défaut léger ; compilez avec `-tags whatsapp_native` (par ex. `make build-whatsapp-native` ou `go build -tags whatsapp_native ./cmd/...`).
+- **Bridge :** Connectez-vous à un bridge WebSocket externe. Définissez `bridge_url` (par ex. `ws://localhost:3001`) et gardez `use_native` à false.
+
+**Configurer (natif)**
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "use_native": true,
+      "session_store_path": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+Si `session_store_path` est vide, la session est stockée dans `<workspace>/whatsapp/`. Lancez `picoclaw gateway` ; au premier lancement, scannez le code QR affiché dans le terminal avec WhatsApp → Appareils liés.
+
+</details>
+
+<a id="weixin"></a>
+<details>
+<summary><b>Weixin</b> (WeChat Personnel)</summary>
+
+PicoClaw prend en charge la connexion à votre compte WeChat personnel via l'API officielle Tencent iLink.
+
+**1. Connexion**
+
+Lancez le flux de connexion interactif par QR code :
+```bash
+picoclaw auth weixin
+```
+Scannez le QR code affiché avec votre application WeChat mobile. Une fois connecté, le token est sauvegardé dans votre configuration.
+
+**2. Configurer**
+
+(Optionnel) Ajoutez votre identifiant utilisateur WeChat dans `allow_from` pour restreindre qui peut envoyer des messages au bot :
+```json
+{
+  "channels": {
+    "weixin": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**3. Lancer**
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="qq"></a>
+<details>
+<summary><b>QQ</b></summary>
+
+**Configuration rapide (recommandée)**
+
+QQ Open Platform propose une page de configuration en un clic pour les bots compatibles OpenClaw :
+
+1. Ouvrez [QQ Bot Quick Start](https://q.qq.com/qqbot/openclaw/index.html) et scannez le QR code pour vous connecter
+2. Un bot est créé automatiquement — copiez l'**App ID** et l'**App Secret**
+3. Configurez PicoClaw :
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+4. Lancez `picoclaw gateway` et ouvrez QQ pour discuter avec votre bot
+
+> L'App Secret n'est affiché qu'une seule fois. Enregistrez-le immédiatement — le consulter à nouveau forcera une réinitialisation.
+>
+> Les bots créés via la page de configuration rapide sont initialement réservés au créateur et ne prennent pas en charge les discussions de groupe. Pour activer l'accès en groupe, configurez le mode sandbox sur la [QQ Open Platform](https://q.qq.com/).
+
+**Configuration manuelle**
+
+Si vous préférez créer le bot manuellement :
+
+* Connectez-vous sur [QQ Open Platform](https://q.qq.com/) pour vous inscrire en tant que développeur
+* Créez un bot QQ — personnalisez son avatar et son nom
+* Copiez l'**App ID** et l'**App Secret** depuis les paramètres du bot
+* Configurez comme indiqué ci-dessus et lancez `picoclaw gateway`
+
+</details>
+
+<a id="dingtalk"></a>
+<details>
+<summary><b>DingTalk</b></summary>
+
+**1. Créer un bot**
+
+* Allez sur [Open Platform](https://open.dingtalk.com/)
+* Créez une application interne
+* Copiez le Client ID et le Client Secret
+
+**2. Configurer**
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Définissez `allow_from` vide pour autoriser tous les utilisateurs, ou spécifiez des identifiants DingTalk pour restreindre l'accès.
+
+**3. Lancer**
+
+```bash
+picoclaw gateway
+```
+</details>
+
+<a id="matrix"></a>
+<details>
+<summary><b>Matrix</b></summary>
+
+**1. Préparer le compte bot**
+
+* Utilisez votre homeserver préféré (par ex. `https://matrix.org` ou auto-hébergé)
+* Créez un utilisateur bot et obtenez son access token
+
+**2. Configurer**
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. Lancer**
+
+```bash
+picoclaw gateway
+```
+
+Pour toutes les options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), voir le [Guide de Configuration du Canal Matrix](../channels/matrix/README.md).
+
+</details>
+
+<a id="line"></a>
+<details>
+<summary><b>LINE</b></summary>
+
+**1. Créer un compte officiel LINE**
+
+- Allez sur [LINE Developers Console](https://developers.line.biz/)
+- Créez un provider → Créez un canal Messaging API
+- Copiez le **Channel Secret** et le **Channel Access Token**
+
+**2. Configurer**
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Le webhook LINE est servi sur le serveur Gateway partagé (`gateway.host`:`gateway.port`, par défaut `127.0.0.1:18790`).
+
+**3. Configurer l'URL du Webhook**
+
+LINE nécessite HTTPS pour les webhooks. Utilisez un reverse proxy ou un tunnel :
+
+```bash
+# Exemple avec ngrok (le port par défaut du gateway est 18790)
+ngrok http 18790
+```
+
+Puis définissez l'URL du Webhook dans la console LINE Developers à `https://your-domain/webhook/line` et activez **Use webhook**.
+
+**4. Lancer**
+
+```bash
+picoclaw gateway
+```
+
+> Dans les discussions de groupe, le bot ne répond que lorsqu'il est @mentionné. Les réponses citent le message original.
+
+</details>
+
+<a id="wecom"></a>
+<details>
+<summary><b>WeCom (企业微信)</b></summary>
+
+PicoClaw prend en charge trois types d'intégration WeCom :
+
+**Option 1 : WeCom Bot (Bot)** - Configuration plus facile, prend en charge les discussions de groupe
+**Option 2 : WeCom App (Application personnalisée)** - Plus de fonctionnalités, messagerie proactive, chat privé uniquement
+**Option 3 : WeCom AI Bot (Bot IA)** - Bot IA officiel, réponses en streaming, prend en charge les discussions de groupe et privées
+
+Voir le [Guide de Configuration WeCom AI Bot](../channels/wecom/wecom_aibot/README.fr.md) pour les instructions détaillées.
+
+**Configuration rapide - WeCom Bot :**
+
+**1. Créer un bot**
+
+* Allez dans la console d'administration WeCom → Discussion de groupe → Ajouter un bot de groupe
+* Copiez l'URL du webhook (format : `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
+
+**2. Configurer**
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+      "webhook_path": "/webhook/wecom",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Le webhook WeCom est servi sur le serveur Gateway partagé (`gateway.host`:`gateway.port`, par défaut `127.0.0.1:18790`).
+
+**Configuration rapide - WeCom App :**
+
+**1. Créer une application**
+
+* Allez dans la console d'administration WeCom → Gestion des applications → Créer une application
+* Copiez **AgentId** et **Secret**
+* Allez sur la page "Mon entreprise", copiez **CorpID**
+
+**2. Configurer la réception des messages**
+
+* Dans les détails de l'application, cliquez sur "Recevoir les messages" → "Configurer l'API"
+* Définissez l'URL à `http://your-server:18790/webhook/wecom-app`
+* Générez **Token** et **EncodingAESKey**
+
+**3. Configurer**
+
+```json
+{
+  "channels": {
+    "wecom_app": {
+      "enabled": true,
+      "corp_id": "wwxxxxxxxxxxxxxxxx",
+      "corp_secret": "YOUR_CORP_SECRET",
+      "agent_id": 1000002,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**4. Lancer**
+
+```bash
+picoclaw gateway
+```
+
+> **Note** : Les callbacks webhook WeCom sont servis sur le port Gateway (par défaut 18790). Utilisez un reverse proxy pour HTTPS.
+
+**Configuration rapide - WeCom AI Bot :**
+
+**1. Créer un AI Bot**
+
+* Allez dans la console d'administration WeCom → Gestion des applications → AI Bot
+* Dans les paramètres du AI Bot, configurez l'URL de callback : `http://your-server:18790/webhook/wecom-aibot`
+* Copiez **Token** et cliquez sur "Générer aléatoirement" pour **EncodingAESKey**
+
+**2. Configurer**
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-aibot",
+      "allow_from": [],
+      "welcome_message": "Hello! How can I help you?",
+      "processing_message": "⏳ Processing, please wait. The results will be sent shortly."
+    }
+  }
+}
+```
+
+**3. Lancer**
+
+```bash
+picoclaw gateway
+```
+
+> **Note** : WeCom AI Bot utilise le protocole streaming pull — pas de problème de timeout de réponse. Les tâches longues (>30 secondes) basculent automatiquement vers la livraison push via `response_url`.
+
+</details>
+
+<a id="feishu"></a>
+<details>
+<summary><b>Feishu (飞书)</b></summary>
+
+PicoClaw se connecte à Feishu via le mode WebSocket/SDK — aucune URL webhook publique ni serveur de callback nécessaire.
+
+**1. Créer une application**
+
+* Allez sur [Feishu Open Platform](https://open.feishu.cn/) et créez une application
+* Dans les paramètres de l'application, activez la capacité **Bot**
+* Créez une version et publiez l'application (l'application doit être publiée pour prendre effet)
+* Copiez l'**App ID** (commence par `cli_`) et l'**App Secret**
+
+**2. Configurer**
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "app_id": "cli_xxx",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+Optionnel : `encrypt_key` et `verification_token` pour le chiffrement des événements (recommandé en production).
+
+**3. Lancer et discuter**
+
+```bash
+picoclaw gateway
+```
+
+Ouvrez Feishu, recherchez le nom de votre bot et commencez à discuter. Vous pouvez aussi ajouter le bot à un groupe — utilisez `group_trigger.mention_only: true` pour ne répondre que lorsqu'il est @mentionné.
+
+Pour toutes les options, voir le [Guide de Configuration du Canal Feishu](../channels/feishu/README.fr.md).
+
+</details>
+
+<a id="slack"></a>
+<details>
+<summary><b>Slack</b></summary>
+
+**1. Créer une application Slack**
+
+* Allez sur [Slack API](https://api.slack.com/apps) et créez une nouvelle application
+* Sous **OAuth & Permissions**, ajoutez les scopes bot : `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write`
+* Installez l'application dans votre workspace
+* Copiez le **Bot Token** (`xoxb-...`) et l'**App-Level Token** (`xapp-...`, activez Socket Mode pour l'obtenir)
+
+**2. Configurer**
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "bot_token": "xoxb-YOUR-BOT-TOKEN",
+      "app_token": "xapp-YOUR-APP-TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. Lancer**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="irc"></a>
+<details>
+<summary><b>IRC</b></summary>
+
+**1. Configurer**
+
+```json
+{
+  "channels": {
+    "irc": {
+      "enabled": true,
+      "server": "irc.libera.chat:6697",
+      "tls": true,
+      "nick": "picoclaw-bot",
+      "channels": ["#your-channel"],
+      "password": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+Optionnel : `nickserv_password` pour l'authentification NickServ, `sasl_user`/`sasl_password` pour l'authentification SASL.
+
+**2. Lancer**
+
+```bash
+picoclaw gateway
+```
+
+Le bot se connectera au serveur IRC et rejoindra les canaux spécifiés.
+
+</details>
+
+<a id="onebot"></a>
+<details>
+<summary><b>OneBot (QQ via protocole OneBot)</b></summary>
+
+OneBot est un protocole ouvert pour les bots QQ. PicoClaw se connecte à toute implémentation compatible OneBot v11 (par ex. [Lagrange](https://github.com/LagrangeDev/Lagrange.Core), [NapCat](https://github.com/NapNeko/NapCatQQ)) via WebSocket.
+
+**1. Configurer une implémentation OneBot**
+
+Installez et exécutez un framework de bot QQ compatible OneBot v11. Activez son serveur WebSocket.
+
+**2. Configurer**
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://127.0.0.1:8080",
+      "access_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Champ | Description |
+|-------|-------------|
+| `ws_url` | URL WebSocket de l'implémentation OneBot |
+| `access_token` | Token d'accès pour l'authentification (si configuré dans OneBot) |
+| `reconnect_interval` | Intervalle de reconnexion en secondes (par défaut : 5) |
+
+**3. Lancer**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="maixcam"></a>
+<details>
+<summary><b>MaixCam</b></summary>
+
+**1. Préparer le matériel**
+
+* Obtenez un appareil [Sipeed MaixCam](https://wiki.sipeed.com/maixcam)
+
+**2. Configurer**
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true,
+      "allow_from": []
+    }
+  }
+}
+```
+
+> MaixCam est une intégration matérielle Sipeed pour l'interaction IA embarquée.
+
+**3. Lancer**
+
+```bash
+picoclaw gateway
+```
+
+</details>
diff --git a/docs/fr/configuration.md b/docs/fr/configuration.md
new file mode 100644
index 000000000..8d94620ba
--- /dev/null
+++ b/docs/fr/configuration.md
@@ -0,0 +1,363 @@
+# ⚙️ Guide de Configuration
+
+> Retour au [README](../../README.fr.md)
+
+## ⚙️ Configuration
+
+Fichier de configuration : `~/.picoclaw/config.json`
+
+### Variables d'Environnement
+
+Vous pouvez remplacer les chemins par défaut à l'aide de variables d'environnement. Ceci est utile pour les installations portables, les déploiements conteneurisés ou l'exécution de PicoClaw en tant que service système. Ces variables sont indépendantes et contrôlent des chemins différents.
+
+| Variable          | Description                                                                                                                             | Chemin par défaut         |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | Remplace le chemin vers le fichier de configuration. Indique directement à PicoClaw quel `config.json` charger, en ignorant tous les autres emplacements. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | Remplace le répertoire racine des données PicoClaw. Change l'emplacement par défaut du `workspace` et des autres répertoires de données. | `~/.picoclaw`             |
+
+**Exemples :**
+
+```bash
+# Run picoclaw using a specific config file
+# The workspace path will be read from within that config file
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Run picoclaw with all its data stored in /opt/picoclaw
+# Config will be loaded from the default ~/.picoclaw/config.json
+# Workspace will be created at /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Use both for a fully customized setup
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
+### Structure du Workspace
+
+PicoClaw stocke les données dans votre workspace configuré (par défaut : `~/.picoclaw/workspace`) :
+
+```
+~/.picoclaw/workspace/
+├── sessions/          # Sessions de conversation et historique
+├── memory/           # Mémoire à long terme (MEMORY.md)
+├── state/            # État persistant (dernier canal, etc.)
+├── cron/             # Base de données des tâches planifiées
+├── skills/           # Compétences personnalisées
+├── AGENT.md          # Guide de comportement de l'agent
+├── HEARTBEAT.md      # Invites de tâches périodiques (vérifiées toutes les 30 min)
+├── SOUL.md           # Âme de l'agent
+└── USER.md           # Préférences utilisateur
+```
+
+> **Remarque :** Les modifications apportées à `AGENT.md`, `SOUL.md`, `USER.md` et `memory/MEMORY.md` sont détectées automatiquement au moment de l'exécution via le suivi de la date de modification (mtime). Il n'est **pas nécessaire de redémarrer le gateway** après avoir modifié ces fichiers — l'agent charge le nouveau contenu à la prochaine requête.
+
+### Sources de Compétences
+
+Par défaut, les compétences sont chargées depuis :
+
+1. `~/.picoclaw/workspace/skills` (workspace)
+2. `~/.picoclaw/skills` (global)
+3. `<chemin-intégré-à-la-compilation>/skills` (intégré)
+
+Pour les configurations avancées/de test, vous pouvez remplacer la racine des compétences builtin avec :
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
+### Politique Unifiée d'Exécution des Commandes
+
+- Les commandes slash génériques sont exécutées via un chemin unique dans `pkg/agent/loop.go` via `commands.Executor`.
+- Les adaptateurs de canaux ne consomment plus les commandes génériques localement ; ils transmettent le texte entrant au chemin bus/agent. Telegram enregistre toujours automatiquement les commandes prises en charge au démarrage.
+- Une commande slash inconnue (par exemple `/foo`) passe au traitement LLM normal.
+- Une commande enregistrée mais non prise en charge sur le canal actuel (par exemple `/show` sur WhatsApp) renvoie une erreur explicite à l'utilisateur et arrête le traitement ultérieur.
+
+### 🔒 Sandbox de Sécurité
+
+PicoClaw s'exécute dans un environnement sandboxé par défaut. L'agent ne peut accéder aux fichiers et exécuter des commandes que dans le workspace configuré.
+
+#### Configuration par Défaut
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "restrict_to_workspace": true
+    }
+  }
+}
+```
+
+| Option                  | Par défaut              | Description                                       |
+| ----------------------- | ----------------------- | ------------------------------------------------- |
+| `workspace`             | `~/.picoclaw/workspace` | Répertoire de travail de l'agent                  |
+| `restrict_to_workspace` | `true`                  | Restreindre l'accès fichiers/commandes au workspace |
+
+#### Outils Protégés
+
+Lorsque `restrict_to_workspace: true`, les outils suivants sont sandboxés :
+
+| Outil         | Fonction              | Restriction                                    |
+| ------------- | --------------------- | ---------------------------------------------- |
+| `read_file`   | Lire des fichiers     | Uniquement les fichiers dans le workspace      |
+| `write_file`  | Écrire des fichiers   | Uniquement les fichiers dans le workspace      |
+| `list_dir`    | Lister les répertoires| Uniquement les répertoires dans le workspace   |
+| `edit_file`   | Modifier des fichiers | Uniquement les fichiers dans le workspace      |
+| `append_file` | Ajouter aux fichiers  | Uniquement les fichiers dans le workspace      |
+| `exec`        | Exécuter des commandes| Les chemins de commande doivent être dans le workspace |
+
+#### Protection Exec Supplémentaire
+
+Même avec `restrict_to_workspace: false`, l'outil `exec` bloque ces commandes dangereuses :
+
+* `rm -rf`, `del /f`, `rmdir /s` — Suppression en masse
+* `format`, `mkfs`, `diskpart` — Formatage de disque
+* `dd if=` — Imagerie de disque
+* Écriture vers `/dev/sd[a-z]` — Écritures directes sur disque
+* `shutdown`, `reboot`, `poweroff` — Arrêt du système
+* Fork bomb `:(){ :|:& };:`
+
+### Contrôle d'Accès aux Fichiers
+
+| Clé de configuration | Type | Par défaut | Description |
+|----------------------|------|------------|-------------|
+| `tools.allow_read_paths` | string[] | `[]` | Chemins supplémentaires autorisés en lecture en dehors du workspace |
+| `tools.allow_write_paths` | string[] | `[]` | Chemins supplémentaires autorisés en écriture en dehors du workspace |
+
+### Sécurité Exec
+
+| Clé de configuration | Type | Par défaut | Description |
+|----------------------|------|------------|-------------|
+| `tools.exec.allow_remote` | bool | `false` | Autoriser l'outil exec depuis les canaux distants (Telegram/Discord etc.) |
+| `tools.exec.enable_deny_patterns` | bool | `true` | Activer l'interception des commandes dangereuses |
+| `tools.exec.custom_deny_patterns` | string[] | `[]` | Patterns regex personnalisés à bloquer |
+| `tools.exec.custom_allow_patterns` | string[] | `[]` | Patterns regex personnalisés à autoriser |
+
+> **Note de sécurité :** La protection Symlink est activée par défaut — tous les chemins de fichiers sont résolus via `filepath.EvalSymlinks` avant la correspondance avec la liste blanche, empêchant les attaques d'évasion par symlink.
+
+#### Limitation Connue : Processus Enfants des Outils de Build
+
+Le garde de sécurité exec n'inspecte que la ligne de commande lancée directement par PicoClaw. Il n'inspecte pas récursivement les processus enfants générés par les outils de développement autorisés tels que `make`, `go run`, `cargo`, `npm run` ou les scripts de build personnalisés.
+
+Cela signifie qu'une commande de niveau supérieur peut toujours compiler ou lancer d'autres binaires après avoir passé la vérification initiale du garde. En pratique, traitez les scripts de build, les Makefiles, les scripts de packages et les binaires générés comme du code exécutable nécessitant le même niveau de revue qu'une commande shell directe.
+
+Pour les environnements à haut risque :
+
+* Examinez les scripts de build avant l'exécution.
+* Préférez l'approbation/revue manuelle pour les workflows de compilation et d'exécution.
+* Exécutez PicoClaw dans un conteneur ou une VM si vous avez besoin d'une isolation plus forte que celle fournie par le garde intégré.
+
+#### Exemples d'Erreurs
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (path outside working dir)}
+```
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
+```
+
+#### Désactiver les Restrictions (Risque de Sécurité)
+
+Si vous avez besoin que l'agent accède à des chemins en dehors du workspace :
+
+**Méthode 1 : Fichier de configuration**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "restrict_to_workspace": false
+    }
+  }
+}
+```
+
+**Méthode 2 : Variable d'environnement**
+
+```bash
+export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
+```
+
+> ⚠️ **Avertissement** : Désactiver cette restriction permet à l'agent d'accéder à n'importe quel chemin sur votre système. À utiliser avec précaution dans des environnements contrôlés uniquement.
+
+#### Cohérence des Limites de Sécurité
+
+Le paramètre `restrict_to_workspace` s'applique de manière cohérente à tous les chemins d'exécution :
+
+| Chemin d'exécution | Limite de sécurité               |
+| ------------------ | -------------------------------- |
+| Main Agent         | `restrict_to_workspace` ✅       |
+| Subagent / Spawn   | Hérite de la même restriction ✅ |
+| Heartbeat tasks    | Hérite de la même restriction ✅ |
+
+Tous les chemins partagent la même restriction de workspace — il n'y a aucun moyen de contourner la limite de sécurité via les subagents ou les tâches planifiées.
+
+### Heartbeat (Tâches Périodiques)
+
+PicoClaw peut effectuer des tâches périodiques automatiquement. Créez un fichier `HEARTBEAT.md` dans votre workspace :
+
+```markdown
+# Periodic Tasks
+
+- Check my email for important messages
+- Review my calendar for upcoming events
+- Check the weather forecast
+```
+
+L'agent lira ce fichier toutes les 30 minutes (configurable) et exécutera toutes les tâches en utilisant les outils disponibles.
+
+#### Tâches Asynchrones avec Spawn
+
+Pour les tâches longues (recherche web, appels API), utilisez l'outil `spawn` pour créer un **subagent** :
+
+```markdown
+# Tâches Périodiques
+
+## Tâches Rapides (répondre directement)
+
+- Indiquer l'heure actuelle
+
+## Tâches Longues (utiliser spawn pour l'asynchrone)
+
+- Rechercher les actualités IA sur le web et résumer
+- Vérifier les e-mails et signaler les messages importants
+```
+
+**Comportements clés :**
+
+| Fonctionnalité   | Description                                                        |
+| ---------------- | ------------------------------------------------------------------ |
+| **spawn**        | Crée un subagent asynchrone, ne bloque pas le heartbeat            |
+| **Contexte indépendant** | Le subagent a son propre contexte, sans historique de session |
+| **message tool** | Le subagent communique directement avec l'utilisateur              |
+| **Non-bloquant** | Après le spawn, le heartbeat continue vers la tâche suivante       |
+
+#### Flux de Communication du Subagent
+
+```
+Heartbeat déclenché
+    ↓
+Agent lit HEARTBEAT.md
+    ↓
+Tâche longue : spawn subagent
+    ↓                           ↓
+Continue tâche suivante    Subagent travaille indépendamment
+    ↓                           ↓
+Toutes tâches terminées    Subagent utilise "message" tool
+    ↓                           ↓
+Répond HEARTBEAT_OK        Utilisateur reçoit le résultat
+```
+
+**Configuration :**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| Option     | Défaut | Description                              |
+| ---------- | ------ | ---------------------------------------- |
+| `enabled`  | `true` | Activer/désactiver le heartbeat          |
+| `interval` | `30`   | Intervalle en minutes (minimum : 5)      |
+
+**Variables d'environnement :**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` pour désactiver
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` pour changer l'intervalle
+
+### Providers
+
+> [!NOTE]
+> Groq fournit une transcription vocale gratuite via Whisper. Si configuré, les messages audio de n'importe quel canal seront automatiquement transcrits au niveau de l'agent.
+
+| Provider     | Usage                                   | Obtenir une clé API                                          |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini`     | LLM (Gemini direct)                     | [aistudio.google.com](https://aistudio.google.com)           |
+| `zhipu`      | LLM (Zhipu direct)                      | [bigmodel.cn](https://bigmodel.cn)                           |
+| `volcengine` | LLM (Volcengine direct)                 | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter` | LLM (recommandé, accès à tous modèles)  | [openrouter.ai](https://openrouter.ai)                       |
+| `anthropic`  | LLM (Claude direct)                     | [console.anthropic.com](https://console.anthropic.com)       |
+| `openai`     | LLM (GPT direct)                        | [platform.openai.com](https://platform.openai.com)           |
+| `deepseek`   | LLM (DeepSeek direct)                   | [platform.deepseek.com](https://platform.deepseek.com)       |
+| `qwen`       | LLM (Qwen direct)                       | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq`       | LLM + **Transcription vocale** (Whisper)| [console.groq.com](https://console.groq.com)                 |
+| `cerebras`   | LLM (Cerebras direct)                   | [cerebras.ai](https://cerebras.ai)                           |
+| `vivgrid`    | LLM (Vivgrid direct)                    | [vivgrid.com](https://vivgrid.com)                           |
+
+### Configuration des Modèles (model_list)
+
+> **Nouveauté :** PicoClaw utilise désormais une approche **centrée sur le modèle**. Spécifiez simplement le format `vendor/model` (ex. `zhipu/glm-4.7`) pour ajouter de nouveaux providers — **aucune modification de code requise !**
+
+#### Tous les Vendors Supportés
+
+| Vendor                  | Préfixe `model` | API Base par défaut                                 | Protocole | API Key                                                          |
+| ----------------------- | --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
+| **OpenAI**              | `openai/`       | `https://api.openai.com/v1`                         | OpenAI    | [Obtenir](https://platform.openai.com)                           |
+| **Anthropic**           | `anthropic/`    | `https://api.anthropic.com/v1`                      | Anthropic | [Obtenir](https://console.anthropic.com)                         |
+| **智谱 AI (GLM)**       | `zhipu/`        | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Obtenir](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek**            | `deepseek/`     | `https://api.deepseek.com/v1`                       | OpenAI    | [Obtenir](https://platform.deepseek.com)                         |
+| **Google Gemini**       | `gemini/`       | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI    | [Obtenir](https://aistudio.google.com/api-keys)                  |
+| **Groq**                | `groq/`         | `https://api.groq.com/openai/v1`                    | OpenAI    | [Obtenir](https://console.groq.com)                              |
+| **通义千问 (Qwen)**     | `qwen/`         | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Obtenir](https://dashscope.console.aliyun.com)                  |
+| **Ollama**              | `ollama/`       | `http://localhost:11434/v1`                         | OpenAI    | Local (pas de clé)                                               |
+| **OpenRouter**          | `openrouter/`   | `https://openrouter.ai/api/v1`                      | OpenAI    | [Obtenir](https://openrouter.ai/keys)                            |
+| **VolcEngine (Doubao)** | `volcengine/`   | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Obtenir](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **Antigravity**         | `antigravity/`  | Google Cloud                                        | Custom    | OAuth uniquement                                                 |
+
+#### Équilibrage de Charge
+
+Configurez plusieurs endpoints pour le même nom de modèle — PicoClaw effectuera automatiquement un round-robin :
+
+```json
+{
+  "model_list": [
+    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" },
+    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" }
+  ]
+}
+```
+
+#### Migration depuis l'ancienne config `providers`
+
+L'ancienne configuration `providers` est **dépréciée** mais toujours supportée. Voir [docs/migration/model-list-migration.md](../migration/model-list-migration.md).
+
+### Architecture des Providers
+
+PicoClaw route les providers par famille de protocole :
+
+- **Compatible OpenAI** : OpenRouter, Groq, Zhipu, endpoints vLLM et la plupart des autres.
+- **Anthropic** : Comportement natif de l'API Claude.
+- **Codex/OAuth** : Route d'authentification OAuth/token OpenAI.
+
+### Tâches Planifiées / Rappels
+
+PicoClaw supporte les tâches planifiées via l'outil `cron`. L'agent peut définir, lister et annuler des rappels ou tâches récurrentes.
+
+```json
+{
+  "tools": {
+    "cron": {
+      "enabled": true,
+      "exec_timeout_minutes": 5
+    }
+  }
+}
+```
+
+Les tâches planifiées persistent après redémarrage dans `~/.picoclaw/workspace/cron/`.
+
+### Sujets Avancés
+
+| Sujet | Description |
+| ----- | ----------- |
+| [Système de Hooks](../hooks/README.md) | Hooks événementiels : observateurs, intercepteurs, hooks d'approbation |
+| [Steering](../steering.md) | Injecter des messages dans une boucle agent en cours d'exécution |
+| [SubTurn](../subturn.md) | Coordination de subagents, contrôle de concurrence, cycle de vie |
+| [Gestion du Contexte](../agent-refactor/context.md) | Détection des limites de contexte, compression |
diff --git a/docs/fr/credential_encryption.md b/docs/fr/credential_encryption.md
new file mode 100644
index 000000000..eec765039
--- /dev/null
+++ b/docs/fr/credential_encryption.md
@@ -0,0 +1,159 @@
+> Retour au [README](../../README.fr.md)
+
+# Chiffrement des identifiants
+
+PicoClaw prend en charge le chiffrement des valeurs `api_key` dans les entrées de configuration `model_list`.
+Les clés chiffrées sont stockées sous forme de chaînes `enc://<base64>` et déchiffrées automatiquement au démarrage.
+
+---
+
+## Démarrage rapide
+
+**1. Définir votre phrase secrète**
+
+```bash
+export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
+```
+
+**2. Chiffrer une clé API**
+
+Exécutez `picoclaw onboard` — il vous demande votre phrase secrète et génère la clé SSH,
+puis re-chiffre automatiquement toutes les entrées `api_key` en clair dans votre configuration
+lors du prochain appel à `SaveConfig`. La valeur `enc://` résultante ressemblera à :
+
+```
+enc://AAAA...base64...
+```
+
+**3. Coller la sortie dans votre configuration**
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-4o",
+      "model": "openai/gpt-4o",
+      "api_key": "enc://AAAA...base64...",
+      "api_base": "https://api.openai.com/v1"
+    }
+  ]
+}
+```
+
+---
+
+## Formats `api_key` pris en charge
+
+| Format | Exemple | Comportement |
+|--------|---------|--------------|
+| Texte clair | `sk-abc123` | Utilisé tel quel |
+| Référence fichier | `file://openai.key` | Contenu lu depuis le même répertoire que le fichier de configuration |
+| Chiffré | `enc://<base64>` | Déchiffré au démarrage avec `PICOCLAW_KEY_PASSPHRASE` |
+| Vide | `""` | Transmis tel quel (utilisé avec `auth_method: oauth`) |
+
+---
+
+## Conception cryptographique
+
+### Dérivation de clé
+
+Le chiffrement utilise **HKDF-SHA256** avec une clé privée SSH comme second facteur.
+
+```
+sshHash = SHA256(ssh_private_key_file_bytes)
+ikm     = HMAC-SHA256(key=sshHash, message=passphrase)
+aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+```
+
+### Chiffrement
+
+```
+AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
+```
+
+### Format de transmission
+
+```
+enc://<base64( salt[16] + nonce[12] + ciphertext )>
+```
+
+| Champ | Taille | Description |
+|-------|--------|-------------|
+| `salt` | 16 octets | Aléatoire par chiffrement ; fourni à HKDF |
+| `nonce` | 12 octets | Aléatoire par chiffrement ; IV AES-GCM |
+| `ciphertext` | variable | Texte chiffré AES-256-GCM + tag d'authentification de 16 octets |
+
+Le tag d'authentification GCM est automatiquement ajouté au texte chiffré. Toute altération provoque l'échec du déchiffrement avec une erreur plutôt que de retourner un texte clair corrompu.
+
+### Performance
+
+| Opération | Durée (ARM Cortex-A) |
+|-----------|----------------------|
+| Dérivation de clé (HKDF) | < 1 ms |
+| Déchiffrement AES-256-GCM | < 1 ms |
+| **Surcoût total au démarrage** | **< 2 ms par clé** |
+
+---
+
+## Sécurité à deux facteurs avec clé SSH
+
+Lorsqu'une clé privée SSH est fournie, casser le chiffrement nécessite **les deux** :
+
+1. La **phrase secrète** (`PICOCLAW_KEY_PASSPHRASE`)
+2. Le **fichier de clé privée SSH**
+
+Cela signifie qu'un fichier de configuration divulgué seul ne suffit pas pour récupérer la clé API, même si la phrase secrète est faible. La clé SSH apporte 256 bits d'entropie (Ed25519) indépendamment de la force de la phrase secrète.
+
+### Modèle de menace
+
+| Ce que l'attaquant possède | Peut-il déchiffrer ? |
+|---------------------------|---------------------|
+| Fichier de configuration uniquement | Non — nécessite la phrase secrète + la clé SSH |
+| Clé SSH uniquement | Non — nécessite la phrase secrète |
+| Phrase secrète uniquement | Non — nécessite la clé SSH |
+| Fichier de configuration + clé SSH + phrase secrète | Oui — compromission totale |
+
+---
+
+## Variables d'environnement
+
+| Variable | Requis | Description |
+|----------|--------|-------------|
+| `PICOCLAW_KEY_PASSPHRASE` | Oui (pour `enc://`) | Phrase secrète utilisée pour la dérivation de clé |
+| `PICOCLAW_SSH_KEY_PATH` | Non | Chemin vers la clé privée SSH. Si non défini, détection automatique depuis `~/.ssh/picoclaw_ed25519.key` |
+
+### Détection automatique de la clé SSH
+
+Si `PICOCLAW_SSH_KEY_PATH` n'est pas défini, PicoClaw recherche la clé dédiée :
+
+```
+~/.ssh/picoclaw_ed25519.key
+```
+
+Ce fichier dédié évite les conflits avec les clés SSH existantes de l'utilisateur.
+Exécutez `picoclaw onboard` pour le générer automatiquement.
+
+`os.UserHomeDir()` est utilisé pour la résolution multiplateforme du répertoire personnel (lit `USERPROFILE` sous Windows, `HOME` sous Unix/macOS).
+
+> **Remarque :** Un fichier de clé SSH est requis pour le chiffrement des identifiants. Si aucune clé n'est trouvée et que `PICOCLAW_SSH_KEY_PATH` n'est pas défini, le chiffrement/déchiffrement échouera. Exécutez `picoclaw onboard` pour générer la clé automatiquement.
+
+---
+
+## Migration
+
+Étant donné que les seuls éléments secrets sont `PICOCLAW_KEY_PASSPHRASE` et le fichier de clé privée SSH, la migration est simple :
+
+1. Copiez le fichier de configuration sur la nouvelle machine.
+2. Définissez `PICOCLAW_KEY_PASSPHRASE` avec la même valeur.
+3. Copiez le fichier de clé privée SSH au même chemin (ou définissez `PICOCLAW_SSH_KEY_PATH` vers son nouvel emplacement).
+
+Aucun re-chiffrement n'est nécessaire.
+
+---
+
+## Considérations de sécurité
+
+- **La phrase secrète et la clé SSH sont toutes deux requises.** La clé SSH agit comme un second facteur — sans elle, le chiffrement/déchiffrement échouera. Exécutez `picoclaw onboard` pour générer la clé si elle n'existe pas.
+- **La clé SSH est en lecture seule à l'exécution.** PicoClaw n'écrit ni ne modifie jamais le fichier de clé SSH.
+- **Les clés en texte clair restent prises en charge.** Les configurations existantes sans `enc://` ne sont pas affectées.
+- **Le format `enc://` est versionné** via le champ `info` de HKDF (`picoclaw-credential-v1`), permettant de futures mises à niveau d'algorithme sans casser les valeurs chiffrées existantes.
diff --git a/docs/fr/debug.md b/docs/fr/debug.md
new file mode 100644
index 000000000..5753ccf8c
--- /dev/null
+++ b/docs/fr/debug.md
@@ -0,0 +1,36 @@
+# Débogage de PicoClaw
+
+> Retour au [README](../../README.fr.md)
+
+PicoClaw effectue de multiples interactions complexes en arrière-plan pour chaque requête qu'il reçoit — du routage des messages et de l'évaluation de la complexité, à l'exécution des outils et à l'adaptation aux défaillances de modèle. Pouvoir voir exactement ce qui se passe est crucial, non seulement pour résoudre les problèmes potentiels, mais aussi pour véritablement comprendre le fonctionnement de l'agent.
+
+## Démarrer PicoClaw en mode débogage
+
+Pour obtenir des informations détaillées sur ce que fait l'agent (requêtes LLM, appels d'outils, routage des messages), vous pouvez démarrer la passerelle PicoClaw avec le drapeau de débogage :
+
+```bash
+picoclaw gateway --debug
+# or
+picoclaw gateway -d
+```
+
+Dans ce mode, le système formate les logs de manière détaillée et affiche des aperçus des prompts système et des résultats d'exécution des outils.
+
+## Désactiver la troncature des logs (logs complets)
+
+Par défaut, PicoClaw tronque les chaînes très longues (comme le *Prompt Système* ou les résultats JSON volumineux) dans les logs de débogage afin de garder la console lisible.
+
+Si vous avez besoin d'inspecter la sortie complète d'une commande ou le payload exact envoyé au modèle LLM, vous pouvez utiliser le drapeau `--no-truncate`.
+
+**Remarque :** Ce drapeau fonctionne *uniquement* en combinaison avec le mode `--debug`.
+
+```bash
+picoclaw gateway --debug --no-truncate
+
+```
+
+Lorsque ce drapeau est actif, la fonction de troncature globale est désactivée. Cela est extrêmement utile pour :
+
+* Vérifier la syntaxe exacte des messages envoyés au fournisseur.
+* Lire la sortie complète d'outils comme `exec`, `web_fetch` ou `read_file`.
+* Déboguer l'historique de session sauvegardé en mémoire.
diff --git a/docs/fr/docker.md b/docs/fr/docker.md
new file mode 100644
index 000000000..432edb1b2
--- /dev/null
+++ b/docs/fr/docker.md
@@ -0,0 +1,167 @@
+# 🐳 Docker et Démarrage Rapide
+
+> Retour au [README](../../README.fr.md)
+
+## 🐳 Docker Compose
+
+Vous pouvez également exécuter PicoClaw avec Docker Compose sans rien installer localement.
+
+```bash
+# 1. Cloner ce dépôt
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. Premier lancement — génère automatiquement docker/data/config.json puis s'arrête
+#    (se déclenche uniquement quand config.json et workspace/ sont tous deux absents)
+docker compose -f docker/docker-compose.yml --profile gateway up
+# Le conteneur affiche "First-run setup complete." et s'arrête.
+
+# 3. Configurer vos clés API
+vim docker/data/config.json   # Set provider API keys, bot tokens, etc.
+
+# 4. Démarrer
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+> [!TIP]
+> **Utilisateurs Docker** : Par défaut, le Gateway écoute sur `127.0.0.1`, ce qui n'est pas accessible depuis l'hôte. Si vous devez accéder aux endpoints de santé ou exposer des ports, définissez `PICOCLAW_GATEWAY_HOST=0.0.0.0` dans votre environnement ou mettez à jour `config.json`.
+
+```bash
+# 5. Vérifier les logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. Arrêter
+docker compose -f docker/docker-compose.yml --profile gateway down
+```
+
+### Mode Launcher (Console Web)
+
+L'image `launcher` inclut les trois binaires (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) et démarre la console web par défaut, qui fournit une interface navigateur pour la configuration et le chat.
+
+```bash
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+```
+
+Ouvrez http://localhost:18800 dans votre navigateur. Le launcher gère automatiquement le processus gateway.
+
+> [!WARNING]
+> La console web ne prend pas encore en charge l'authentification. Évitez de l'exposer sur Internet public.
+
+### Mode Agent (One-shot)
+
+```bash
+# Poser une question
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
+
+# Mode interactif
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+```
+
+### Mise à jour
+
+```bash
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+### 🚀 Démarrage Rapide
+
+> [!TIP]
+> Configurez votre clé API dans `~/.picoclaw/config.json`. Obtenir des clés API : [Volcengine (CodingPlan)](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM). La recherche web est optionnelle — obtenez gratuitement une [API Tavily](https://tavily.com) (1000 requêtes gratuites/mois) ou une [API Brave Search](https://brave.com/search/api) (2000 requêtes gratuites/mois).
+
+**1. Initialiser**
+
+```bash
+picoclaw onboard
+```
+
+**2. Configurer** (`~/.picoclaw/config.json`)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "gpt-5.4",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key",
+      "api_base":"https://ark.cn-beijing.volces.com/api/coding/v3"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "your-api-key",
+      "request_timeout": 300
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "your-anthropic-key"
+    }
+  ],
+  "tools": {
+    "web": {
+      "enabled": true,
+      "fetch_limit_bytes": 10485760,
+      "format": "plaintext",
+      "brave": {
+        "enabled": false,
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      },
+      "tavily": {
+        "enabled": false,
+        "api_key": "YOUR_TAVILY_API_KEY",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "YOUR_PERPLEXITY_API_KEY",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://your-searxng-instance:8888",
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+> **Nouveau** : Le format de configuration `model_list` permet l'ajout de fournisseurs sans modification de code. Voir [Configuration des Modèles](#configuration-des-modèles-model_list) pour plus de détails.
+> `request_timeout` est optionnel et utilise les secondes. S'il est omis ou défini à `<= 0`, PicoClaw utilise le timeout par défaut (120s).
+
+**3. Obtenir des clés API**
+
+* **Fournisseur LLM** : [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
+* **Recherche Web** (optionnel) :
+  * [Brave Search](https://brave.com/search/api) - Payant ($5/1000 requêtes, ~$5-6/mois)
+  * [Perplexity](https://www.perplexity.ai) - Recherche alimentée par l'IA avec interface de chat
+  * [SearXNG](https://github.com/searxng/searxng) - Métamoteur auto-hébergé (gratuit, pas de clé API nécessaire)
+  * [Tavily](https://tavily.com) - Optimisé pour les agents IA (1000 requêtes/mois)
+  * DuckDuckGo - Solution de repli intégrée (pas de clé API requise)
+
+> **Note** : Voir `config.example.json` pour un modèle de configuration complet.
+
+**4. Discuter**
+
+```bash
+picoclaw agent -m "What is 2+2?"
+```
+
+C'est tout ! Vous avez un assistant IA fonctionnel en 2 minutes.
+
+---
diff --git a/docs/fr/hardware-compatibility.md b/docs/fr/hardware-compatibility.md
new file mode 100644
index 000000000..c1f397e80
--- /dev/null
+++ b/docs/fr/hardware-compatibility.md
@@ -0,0 +1,152 @@
+> Retour au [README](../../README.fr.md)
+
+# 🖥️ PicoClaw Liste de compatibilité matérielle
+
+PicoClaw fonctionne sur pratiquement n'importe quel appareil Linux. Cette page répertorie les puces, produits et cartes de développement vérifiés.
+
+**Votre matériel n'est pas listé ?** Soumettez une PR pour l'ajouter ! Les fabricants de matériel sont invités à contribuer et à co-promouvoir.
+
+---
+
+## 1. Support de puces vérifié
+
+### x86
+
+| Fabricant | Puce | Notes |
+|-----------|------|-------|
+| Intel | Any x86 CPU (i386+) | Tous les processeurs de bureau/serveur/portable |
+| AMD | Any x86 CPU | Tous les processeurs de bureau/serveur/portable |
+
+### ARM
+
+| Sous-arch | Puces typiques | Notes |
+|-----------|----------------|-------|
+| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | Monocœur ARM1176JZF-S |
+| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | Monocœur Cortex-A7, utilisé dans LicheePi Zero |
+| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | Quadricœur Cortex-A53, utilisé dans Orange Pi Zero 3 |
+| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | Quadricœur Cortex-A72 |
+| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | Quadricœur Cortex-A76 |
+| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | Bicœur Cortex-A53 + NPU, utilisé dans NanoKVM-Pro / MaixCAM2 |
+
+### RISC-V (riscv64)
+
+| Fabricant | Puce | Cœur | Notes |
+|-----------|------|------|-------|
+| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 intégré, utilisé dans LicheeRV-Nano / NanoKVM / MaixCAM |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L intégré, 1 TOPS NPU, caméra AI 4K SiP |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | Série de caméras AI RISC-V |
+| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | Utilisé dans HaaS506-LD1 RTU industriel |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Utilisé dans Milk-V Jupiter, BananaPi BPI-F3 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | Conforme RVA23, RVV 1024 bits, inférence AI FP8 |
+| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8 cœurs, 16MB cache L3, classe bureau |
+| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU, utilisé dans CanMV-K230 |
+
+### MIPS
+
+| Fabricant | Puce | Notes |
+|-----------|------|-------|
+| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz, utilisé dans de nombreux routeurs OpenWrt (ex. Xiaomi Router 3G) |
+
+### LoongArch (loong64)
+
+| Fabricant | Puce | Notes |
+|-----------|------|-------|
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | Quadricœur LA464 @ 2.5GHz, bureau/station de travail |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | Quadricœur 4C/8T @ 2.5GHz, IPC comparable à Intel 10e génération |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | Bicœur @ 1GHz, applications industrielles/IoT |
+
+---
+
+## 2. Produits vérifiés (par date de sortie)
+
+Produits grand public, routeurs et appareils industriels testés avec PicoClaw.
+
+| Année | Produit | Arch | SoC | RAM | Catégorie |
+|-------|---------|------|-----|-----|-----------|
+| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | Smartphone |
+| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | Tablette |
+| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | Routeur (OpenWrt) |
+| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | Boîtier TV / Serveur domestique |
+| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | Enceinte connectée |
+| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
+| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | RTU industriel |
+| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | IP-KVM Pro |
+| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | Caméra AI 4K |
+
+---
+
+## 3. Cartes de développement vérifiées (par date de sortie)
+
+| Année | Carte | Arch | SoC | RAM | Lien d'achat |
+|-------|-------|------|-----|-----|--------------|
+| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
+| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
+| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
+| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
+| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
+| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
+| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
+| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
+| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
+
+---
+
+## 4. Fonctionne également sur
+
+### Téléphones Android (via Termux)
+
+Tout téléphone Android ARM64 (2015+) avec 1 Go+ de RAM. Installez [Termux](https://github.com/termux/termux-app), utilisez `proot` pour exécuter PicoClaw.
+
+> Voir [README : Exécuter sur d'anciens téléphones Android](../../README.fr.md#-run-on-old-android-phones) pour les instructions de configuration.
+
+### Bureau / Serveur / Cloud
+
+| Plateforme | Notes |
+|------------|-------|
+| x86_64 Linux | Binaire natif, aucune dépendance |
+| x86_64 Windows | Binaire natif |
+| macOS (Intel / Apple Silicon) | Binaire natif |
+| Docker (any platform) | `docker compose` en une ligne, voir [Guide Docker](docker.md) |
+| OpenWrt routers | Builds MIPS/ARM, nécessite >32 Mo de RAM libre |
+| FreeBSD / NetBSD | Builds x86_64 et arm64 disponibles |
+
+---
+
+## 5. Configuration minimale requise
+
+| Ressource | Minimum | Recommandé |
+|-----------|---------|------------|
+| RAM | 10 Mo libres | 32 Mo+ libres |
+| Stockage | 20 Mo (binaire) | 50 Mo+ (avec espace de travail) |
+| CPU | N'importe lequel (monocœur 0,6 GHz+) | — |
+| OS | Linux (kernel 3.x+) | Linux 5.x+ |
+| Réseau | Requis (pour les appels API LLM) | Ethernet ou WiFi |
+
+---
+
+## 6. Comment tester et contribuer
+
+```bash
+# 1. Télécharger pour votre architecture
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+
+# 2. Initialiser
+./picoclaw onboard
+
+# 3. Tester
+./picoclaw agent -m "Hello, what board am I running on?"
+```
+
+Builds disponibles : `linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
+
+### Ajouter votre matériel
+
+1. Forkez ce dépôt
+2. Ajoutez votre puce / produit / carte dans le tableau approprié
+3. Incluez : nom, architecture, SoC, RAM, année et un lien si disponible
+4. Soumettez une PR
+
+Fabricants de matériel : vous souhaitez ajouter un support officiel ou co-promouvoir ? Ouvrez une issue ou contactez-nous via [Discord](https://discord.gg/V4sAZ9XWpN).
diff --git a/docs/fr/providers.md b/docs/fr/providers.md
new file mode 100644
index 000000000..39f5cf36a
--- /dev/null
+++ b/docs/fr/providers.md
@@ -0,0 +1,433 @@
+# 🔌 Fournisseurs et Configuration des Modèles
+
+> Retour au [README](../../README.fr.md)
+
+### Fournisseurs
+
+> [!NOTE]
+> Groq fournit la transcription vocale gratuite via Whisper. Si configuré, les messages audio de n'importe quel canal seront automatiquement transcrits au niveau de l'agent.
+
+| Provider     | Purpose                                 | Get API Key                                                  |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini`     | LLM (Gemini direct)                     | [aistudio.google.com](https://aistudio.google.com)           |
+| `zhipu`      | LLM (Zhipu direct)                      | [bigmodel.cn](https://bigmodel.cn)                           |
+| `volcengine` | LLM (Volcengine direct)                 | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw)                 |
+| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai)                       |
+| `anthropic`  | LLM (Claude direct)                     | [console.anthropic.com](https://console.anthropic.com)       |
+| `openai`     | LLM (GPT direct)                        | [platform.openai.com](https://platform.openai.com)           |
+| `deepseek`   | LLM (DeepSeek direct)                   | [platform.deepseek.com](https://platform.deepseek.com)       |
+| `qwen`       | LLM (Qwen direct)                       | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq`       | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com)                 |
+| `cerebras`   | LLM (Cerebras direct)                   | [cerebras.ai](https://cerebras.ai)                           |
+| `vivgrid`    | LLM (Vivgrid direct)                    | [vivgrid.com](https://vivgrid.com)                           |
+| `moonshot`   | LLM (Kimi/Moonshot direct)              | [platform.moonshot.cn](https://platform.moonshot.cn)         |
+| `minimax`    | LLM (Minimax direct)                    | [platform.minimaxi.com](https://platform.minimaxi.com)      |
+| `avian`      | LLM (Avian direct)                      | [avian.io](https://avian.io)                                 |
+| `mistral`    | LLM (Mistral direct)                    | [console.mistral.ai](https://console.mistral.ai)            |
+| `longcat`    | LLM (Longcat direct)                    | [longcat.ai](https://longcat.ai)                             |
+| `modelscope` | LLM (ModelScope direct)                 | [modelscope.cn](https://modelscope.cn)                       |
+
+### Configuration des Modèles (model_list)
+
+> **Nouveauté** PicoClaw utilise désormais une approche de configuration **centrée sur le modèle**. Spécifiez simplement le format `vendor/model` (par ex. `zhipu/glm-4.7`) pour ajouter de nouveaux fournisseurs — **aucune modification de code requise !**
+
+Cette conception permet également le **support multi-agents** avec une sélection flexible de fournisseurs :
+
+- **Différents agents, différents fournisseurs** : Chaque agent peut utiliser son propre fournisseur LLM
+- **Modèles de repli** : Configurez des modèles principaux et de repli pour la résilience
+- **Répartition de charge** : Distribuez les requêtes entre plusieurs endpoints
+- **Configuration centralisée** : Gérez tous les fournisseurs en un seul endroit
+
+#### 📋 Tous les Vendors Supportés
+
+| Vendor              | `model` Prefix    | Default API Base                                    | Protocol  | API Key                                                          |
+| ------------------- | ----------------- |-----------------------------------------------------| --------- | ---------------------------------------------------------------- |
+| **OpenAI**          | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [Get Key](https://platform.openai.com)                           |
+| **Anthropic**       | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [Get Key](https://console.anthropic.com)                         |
+| **智谱 AI (GLM)**   | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek**        | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [Get Key](https://platform.deepseek.com)                         |
+| **Google Gemini**   | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI    | [Get Key](https://aistudio.google.com/api-keys)                  |
+| **Groq**            | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [Get Key](https://console.groq.com)                              |
+| **Moonshot**        | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [Get Key](https://platform.moonshot.cn)                          |
+| **通义千问 (Qwen)** | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Get Key](https://dashscope.console.aliyun.com)                  |
+| **NVIDIA**          | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [Get Key](https://build.nvidia.com)                              |
+| **Ollama**          | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | Local (no key needed)                                            |
+| **OpenRouter**      | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [Get Key](https://openrouter.ai/keys)                            |
+| **LiteLLM Proxy**   | `litellm/`        | `http://localhost:4000/v1`                          | OpenAI    | Your LiteLLM proxy key                                            |
+| **VLLM**            | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | Local                                                            |
+| **Cerebras**        | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [Get Key](https://cerebras.ai)                                   |
+| **VolcEngine (Doubao)** | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw)                        |
+| **神算云**          | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                |
+| **BytePlus**        | `byteplus/`       | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [Get Key](https://www.byteplus.com)                        |
+| **Vivgrid**         | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [Get Key](https://vivgrid.com)                                   |
+| **LongCat**         | `longcat/`        | `https://api.longcat.chat/openai`                   | OpenAI    | [Get Key](https://longcat.chat/platform)                         |
+| **ModelScope (魔搭)**| `modelscope/`    | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [Get Token](https://modelscope.cn/my/tokens)                     |
+| **Antigravity**     | `antigravity/`    | Google Cloud                                        | Custom    | OAuth only                                                       |
+| **GitHub Copilot**  | `github-copilot/` | `localhost:4321`                                    | gRPC      | -                                                                |
+
+#### Configuration de Base
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-openai-key"
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "sk-ant-your-key"
+    },
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-zhipu-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "gpt-5.4"
+    }
+  }
+}
+```
+
+#### Exemples par Vendor
+
+**OpenAI**
+
+```json
+{
+  "model_name": "gpt-5.4",
+  "model": "openai/gpt-5.4",
+  "api_key": "sk-..."
+}
+```
+
+**VolcEngine (Doubao)**
+
+```json
+{
+  "model_name": "ark-code-latest",
+  "model": "volcengine/ark-code-latest",
+  "api_key": "sk-..."
+}
+```
+
+**智谱 AI (GLM)**
+
+```json
+{
+  "model_name": "glm-4.7",
+  "model": "zhipu/glm-4.7",
+  "api_key": "your-key"
+}
+```
+
+**DeepSeek**
+
+```json
+{
+  "model_name": "deepseek-chat",
+  "model": "deepseek/deepseek-chat",
+  "api_key": "sk-..."
+}
+```
+
+**Anthropic (avec clé API)**
+
+```json
+{
+  "model_name": "claude-sonnet-4.6",
+  "model": "anthropic/claude-sonnet-4.6",
+  "api_key": "sk-ant-your-key"
+}
+```
+
+> Exécutez `picoclaw auth login --provider anthropic` pour coller votre token API.
+
+**API Anthropic Messages (format natif)**
+
+Pour l'accès direct à l'API Anthropic ou les endpoints personnalisés qui ne prennent en charge que le format de message natif d'Anthropic :
+
+```json
+{
+  "model_name": "claude-opus-4-6",
+  "model": "anthropic-messages/claude-opus-4-6",
+  "api_key": "sk-ant-your-key",
+  "api_base": "https://api.anthropic.com"
+}
+```
+
+> Utilisez le protocole `anthropic-messages` lorsque :
+> - Vous utilisez des proxys tiers qui ne prennent en charge que l'endpoint natif `/v1/messages` d'Anthropic (pas le format compatible OpenAI `/v1/chat/completions`)
+> - Vous vous connectez à des services comme MiniMax, Synthetic qui nécessitent le format de message natif d'Anthropic
+> - Le protocole `anthropic` existant renvoie des erreurs 404 (indiquant que l'endpoint ne prend pas en charge le format compatible OpenAI)
+>
+> **Note :** Le protocole `anthropic` utilise le format compatible OpenAI (`/v1/chat/completions`), tandis que `anthropic-messages` utilise le format natif d'Anthropic (`/v1/messages`). Choisissez en fonction du format pris en charge par votre endpoint.
+
+**Ollama (local)**
+
+```json
+{
+  "model_name": "llama3",
+  "model": "ollama/llama3"
+}
+```
+
+**Proxy/API Personnalisé**
+
+```json
+{
+  "model_name": "my-custom-model",
+  "model": "openai/custom-model",
+  "api_base": "https://my-proxy.com/v1",
+  "api_key": "sk-...",
+  "request_timeout": 300
+}
+```
+
+**LiteLLM Proxy**
+
+```json
+{
+  "model_name": "lite-gpt4",
+  "model": "litellm/lite-gpt4",
+  "api_base": "http://localhost:4000/v1",
+  "api_key": "sk-..."
+}
+```
+
+PicoClaw ne supprime que le préfixe externe `litellm/` avant d'envoyer la requête, donc les alias de proxy comme `litellm/lite-gpt4` envoient `lite-gpt4`, tandis que `litellm/openai/gpt-4o` envoie `openai/gpt-4o`.
+
+#### Répartition de Charge
+
+Configurez plusieurs endpoints pour le même nom de modèle — PicoClaw effectuera automatiquement un round-robin entre eux :
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api1.example.com/v1",
+      "api_key": "sk-key1"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api2.example.com/v1",
+      "api_key": "sk-key2"
+    }
+  ]
+}
+```
+
+#### Migration depuis l'Ancienne Configuration `providers`
+
+L'ancienne configuration `providers` est **dépréciée** mais toujours prise en charge pour la compatibilité ascendante.
+
+**Ancienne configuration (dépréciée) :**
+
+```json
+{
+  "providers": {
+    "zhipu": {
+      "api_key": "your-key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  },
+  "agents": {
+    "defaults": {
+      "provider": "zhipu",
+      "model": "glm-4.7"
+    }
+  }
+}
+```
+
+**Nouvelle configuration (recommandée) :**
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "glm-4.7"
+    }
+  }
+}
+```
+
+Pour un guide de migration détaillé, voir [migration/model-list-migration.md](../migration/model-list-migration.md).
+
+### Architecture des Fournisseurs
+
+PicoClaw route les fournisseurs par famille de protocoles :
+
+- Protocole compatible OpenAI : OpenRouter, passerelles compatibles OpenAI, Groq, Zhipu et endpoints de type vLLM.
+- Protocole Anthropic : Comportement natif de l'API Claude.
+- Chemin Codex/OAuth : Route d'authentification OAuth/token OpenAI.
+
+Cela maintient le runtime léger tout en faisant des nouveaux backends compatibles OpenAI principalement une opération de configuration (`api_base` + `api_key`).
+
+<details>
+<summary><b>Zhipu</b></summary>
+
+**1. Obtenir la clé API et l'URL de base**
+
+* Obtenir la [clé API](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
+
+**2. Configurer**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "providers": {
+    "zhipu": {
+      "api_key": "Your API Key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  }
+}
+```
+
+**3. Lancer**
+
+```bash
+picoclaw agent -m "Hello"
+```
+
+</details>
+
+<details>
+<summary><b>Exemple de configuration complète</b></summary>
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "anthropic/claude-opus-4-5"
+    }
+  },
+  "session": {
+    "dm_scope": "per-channel-peer"
+  },
+  "providers": {
+    "openrouter": {
+      "api_key": "sk-or-v1-xxx"
+    },
+    "groq": {
+      "api_key": "gsk_xxx"
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456:ABC...",
+      "allow_from": ["123456789"]
+    },
+    "discord": {
+      "enabled": true,
+      "token": "",
+      "allow_from": [""]
+    },
+    "whatsapp": {
+      "enabled": false,
+      "bridge_url": "ws://localhost:3001",
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": []
+    },
+    "feishu": {
+      "enabled": false,
+      "app_id": "cli_xxx",
+      "app_secret": "xxx",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    },
+    "qq": {
+      "enabled": false,
+      "app_id": "",
+      "app_secret": "",
+      "allow_from": []
+    }
+  },
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": false,
+        "api_key": "BSA...",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://localhost:8888",
+        "max_results": 5
+      }
+    },
+    "cron": {
+      "exec_timeout_minutes": 5
+    }
+  },
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+</details>
+
+---
+
+## 📝 Comparaison des Clés API
+
+| Service          | Pricing                  | Use Case                              |
+| ---------------- | ------------------------ | ------------------------------------- |
+| **OpenRouter**   | Free: 200K tokens/month  | Multiple models (Claude, GPT-4, etc.) |
+| **Volcengine CodingPlan** | ¥9.9/first month | Best for Chinese users, multiple SOTA models (Doubao, DeepSeek, etc.) |
+| **Zhipu**        | Free: 200K tokens/month  | Suitable for Chinese users                |
+| **Brave Search** | $5/1000 queries          | Web search functionality              |
+| **SearXNG**      | Free (self-hosted)       | Privacy-focused metasearch (70+ engines) |
+| **Groq**         | Free tier available      | Fast inference (Llama, Mixtral)       |
+| **Cerebras**     | Free tier available      | Fast inference (Llama, Qwen, etc.)    |
+| **LongCat**      | Free: up to 5M tokens/day | Fast inference                       |
+| **ModelScope**   | Free: 2000 requests/day  | Inference (Qwen, GLM, DeepSeek, etc.) |
+
+---
+
+<div align="center">
+  <img src="assets/logo.jpg" alt="PicoClaw Meme" width="512">
+</div>
diff --git a/docs/fr/spawn-tasks.md b/docs/fr/spawn-tasks.md
new file mode 100644
index 000000000..5635cd645
--- /dev/null
+++ b/docs/fr/spawn-tasks.md
@@ -0,0 +1,61 @@
+# 🔄 Tâches Asynchrones et Spawn
+
+> Retour au [README](../../README.fr.md)
+
+## Tâches Rapides (réponse directe)
+
+- Rapporter l'heure actuelle
+
+## Tâches Longues (utiliser spawn pour l'asynchrone)
+
+- Rechercher sur le web des actualités IA et résumer
+- Vérifier les emails et rapporter les messages importants
+```
+
+**Comportements clés :**
+
+| Fonctionnalité          | Description                                                     |
+| ----------------------- | --------------------------------------------------------------- |
+| **spawn**               | Crée un subagent asynchrone, ne bloque pas le heartbeat         |
+| **Independent context** | Le subagent a son propre contexte, pas d'historique de session  |
+| **message tool**        | Le subagent communique directement avec l'utilisateur via l'outil message |
+| **Non-blocking**        | Après le spawn, le heartbeat continue à la tâche suivante       |
+
+#### Fonctionnement de la Communication du Subagent
+
+```
+Heartbeat se déclenche
+    ↓
+L'agent lit HEARTBEAT.md
+    ↓
+Pour une tâche longue : spawn subagent
+    ↓                           ↓
+Continue à la tâche suivante  Le subagent travaille indépendamment
+    ↓                           ↓
+Toutes les tâches terminées  Le subagent utilise l'outil "message"
+    ↓                           ↓
+Répond HEARTBEAT_OK          L'utilisateur reçoit le résultat directement
+```
+
+Le subagent a accès aux outils (message, web_search, etc.) et peut communiquer avec l'utilisateur indépendamment sans passer par l'agent principal.
+
+**Configuration :**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| Option     | Par défaut | Description                                    |
+| ---------- | ---------- | ---------------------------------------------- |
+| `enabled`  | `true`     | Activer/désactiver le heartbeat                |
+| `interval` | `30`       | Intervalle de vérification en minutes (min: 5) |
+
+**Variables d'environnement :**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` pour désactiver
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` pour changer l'intervalle
diff --git a/docs/fr/tools_configuration.md b/docs/fr/tools_configuration.md
new file mode 100644
index 000000000..1324d49e5
--- /dev/null
+++ b/docs/fr/tools_configuration.md
@@ -0,0 +1,412 @@
+# 🔧 Configuration des Outils
+
+> Retour au [README](../../README.fr.md)
+
+La configuration des outils de PicoClaw se trouve dans le champ `tools` de `config.json`.
+
+## Structure du répertoire
+
+```json
+{
+  "tools": {
+    "web": {
+      ...
+    },
+    "mcp": {
+      ...
+    },
+    "exec": {
+      ...
+    },
+    "cron": {
+      ...
+    },
+    "skills": {
+      ...
+    }
+  }
+}
+```
+
+## Outils Web
+
+Les outils web sont utilisés pour la recherche et la récupération de pages web.
+
+### Web Fetcher
+Paramètres généraux pour la récupération et le traitement du contenu des pages web.
+
+| Config              | Type   | Par défaut    | Description                                                                                   |
+|---------------------|--------|---------------|-----------------------------------------------------------------------------------------------|
+| `enabled`           | bool   | true          | Activer la capacité de récupération de pages web.                                             |
+| `fetch_limit_bytes` | int    | 10485760      | Taille maximale du contenu de la page web à récupérer, en octets (par défaut 10 Mo).          |
+| `format`            | string | "plaintext"   | Format de sortie du contenu récupéré. Options : `plaintext` ou `markdown` (recommandé).       |
+
+### DuckDuckGo
+
+| Config        | Type | Par défaut | Description                    |
+|---------------|------|------------|--------------------------------|
+| `enabled`     | bool | true       | Activer la recherche DuckDuckGo |
+| `max_results` | int  | 5          | Nombre maximum de résultats    |
+
+### Baidu Search
+
+| Config        | Type   | Par défaut                                                      | Description                        |
+|---------------|--------|-----------------------------------------------------------------|------------------------------------|
+| `enabled`     | bool   | false                                                           | Activer la recherche Baidu         |
+| `api_key`     | string | -                                                               | Clé API Qianfan                    |
+| `base_url`    | string | `https://qianfan.baidubce.com/v2/ai_search/web_search`         | URL de l'API Baidu Search          |
+| `max_results` | int    | 10                                                              | Nombre maximum de résultats        |
+
+```json
+{
+  "tools": {
+    "web": {
+      "baidu_search": {
+        "enabled": true,
+        "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
+        "max_results": 10
+      }
+    }
+  }
+}
+```
+
+### Perplexity
+
+| Config        | Type   | Par défaut | Description                    |
+|---------------|--------|------------|--------------------------------|
+| `enabled`     | bool     | false      | Activer la recherche Perplexity                              |
+| `api_key`     | string   | -          | Clé API Perplexity                                           |
+| `api_keys`    | string[] | -          | Plusieurs clés API Perplexity pour la rotation (`api_key` prioritaire) |
+| `max_results` | int      | 5          | Nombre maximum de résultats                                  |
+
+### Brave
+
+| Config        | Type   | Par défaut | Description               |
+|---------------|--------|------------|---------------------------|
+| `enabled`     | bool     | false      | Activer la recherche Brave                                   |
+| `api_key`     | string   | -          | Clé API Brave Search                                         |
+| `api_keys`    | string[] | -          | Plusieurs clés API Brave Search pour la rotation (`api_key` prioritaire) |
+| `max_results` | int      | 5          | Nombre maximum de résultats                                  |
+
+### Tavily
+
+| Config        | Type   | Par défaut | Description                        |
+|---------------|--------|------------|------------------------------------|
+| `enabled`     | bool   | false      | Activer la recherche Tavily        |
+| `api_key`     | string | -          | Clé API Tavily                     |
+| `base_url`    | string | -          | URL de base Tavily personnalisée   |
+| `max_results` | int    | 0          | Nombre maximum de résultats (0 = défaut) |
+
+### SearXNG
+
+| Config        | Type   | Par défaut               | Description                    |
+|---------------|--------|--------------------------|--------------------------------|
+| `enabled`     | bool   | false                    | Activer la recherche SearXNG   |
+| `base_url`    | string | `http://localhost:8888`  | URL de l'instance SearXNG      |
+| `max_results` | int    | 5                        | Nombre maximum de résultats    |
+
+### GLM Search
+
+| Config          | Type   | Par défaut                                           | Description               |
+|-----------------|--------|------------------------------------------------------|---------------------------|
+| `enabled`       | bool   | false                                                | Activer GLM Search        |
+| `api_key`       | string | -                                                    | Clé API GLM               |
+| `base_url`      | string | `https://open.bigmodel.cn/api/paas/v4/web_search`   | URL de l'API GLM Search   |
+| `search_engine` | string | `search_std`                                         | Type de moteur de recherche |
+| `max_results`   | int    | 5                                                    | Nombre maximum de résultats |
+
+## Outil Exec
+
+L'outil exec est utilisé pour exécuter des commandes shell.
+
+| Config                 | Type  | Par défaut | Description                                    |
+|------------------------|-------|------------|------------------------------------------------|
+| `enabled`              | bool  | true       | Activer l'outil exec                           |
+| `enable_deny_patterns` | bool  | true       | Activer le blocage par défaut des commandes dangereuses |
+| `custom_deny_patterns` | array | []         | Modèles de refus personnalisés (expressions régulières) |
+
+### Désactivation de l'Outil Exec
+
+Pour désactiver complètement l'outil `exec`, définissez `enabled` à `false` :
+
+**Via le fichier de configuration :**
+```json
+{
+  "tools": {
+    "exec": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**Via la variable d'environnement :**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **Note :** Lorsqu'il est désactivé, l'agent ne pourra pas exécuter de commandes shell. Cela affecte également la capacité de l'outil Cron à exécuter des commandes shell planifiées.
+
+### Fonctionnalité
+
+- **`enable_deny_patterns`** : Définir à `false` pour désactiver complètement les modèles de blocage par défaut des commandes dangereuses
+- **`custom_deny_patterns`** : Ajouter des modèles regex de refus personnalisés ; les commandes correspondantes seront bloquées
+
+### Modèles de commandes bloquées par défaut
+
+Par défaut, PicoClaw bloque les commandes dangereuses suivantes :
+
+- Commandes de suppression : `rm -rf`, `del /f/q`, `rmdir /s`
+- Opérations disque : `format`, `mkfs`, `diskpart`, `dd if=`, écriture vers `/dev/sd*`
+- Opérations système : `shutdown`, `reboot`, `poweroff`
+- Substitution de commandes : `$()`, `${}`, backticks
+- Pipe vers shell : `| sh`, `| bash`
+- Élévation de privilèges : `sudo`, `chmod`, `chown`
+- Contrôle de processus : `pkill`, `killall`, `kill -9`
+- Opérations distantes : `curl | sh`, `wget | sh`, `ssh`
+- Gestion de paquets : `apt`, `yum`, `dnf`, `npm install -g`, `pip install --user`
+- Conteneurs : `docker run`, `docker exec`
+- Git : `git push`, `git force`
+- Autres : `eval`, `source *.sh`
+
+### Limitation architecturale connue
+
+Le garde exec ne valide que la commande de niveau supérieur envoyée à PicoClaw. Il n'inspecte **pas** récursivement les processus enfants générés par les outils de build ou les scripts après le démarrage de cette commande.
+
+Exemples de workflows pouvant contourner le garde de commande directe une fois la commande initiale autorisée :
+
+- `make run`
+- `go run ./cmd/...`
+- `cargo run`
+- `npm run build`
+
+Cela signifie que le garde est utile pour bloquer les commandes directes manifestement dangereuses, mais ce n'est **pas** un bac à sable complet pour les pipelines de build non vérifiés. Si votre modèle de menace inclut du code non fiable dans l'espace de travail, utilisez une isolation plus forte comme des conteneurs, des VM ou un flux d'approbation autour des commandes de build et d'exécution.
+
+### Exemple de configuration
+
+```json
+{
+  "tools": {
+    "exec": {
+      "enable_deny_patterns": true,
+      "custom_deny_patterns": [
+        "\\brm\\s+-r\\b",
+        "\\bkillall\\s+python"
+      ]
+    }
+  }
+}
+```
+
+## Outil Cron
+
+L'outil cron est utilisé pour planifier des tâches périodiques.
+
+| Config                 | Type | Par défaut | Description                                        |
+|------------------------|------|------------|----------------------------------------------------|
+| `exec_timeout_minutes` | int  | 5          | Délai d'expiration en minutes, 0 signifie sans limite |
+
+## Outil MCP
+
+L'outil MCP permet l'intégration avec des serveurs Model Context Protocol externes.
+
+### Découverte d'outils (chargement paresseux)
+
+Lors de la connexion à plusieurs serveurs MCP, exposer simultanément des centaines d'outils peut épuiser la fenêtre de contexte du LLM et augmenter les coûts API. La fonctionnalité **Discovery** résout ce problème en gardant les outils MCP *masqués* par défaut.
+
+Au lieu de charger tous les outils, le LLM reçoit un outil de recherche léger (utilisant la correspondance par mots-clés BM25 ou les expressions régulières). Lorsque le LLM a besoin d'une capacité spécifique, il recherche dans la bibliothèque masquée. Les outils correspondants sont alors temporairement « déverrouillés » et injectés dans le contexte pour un nombre configuré de tours (`ttl`).
+
+### Configuration globale
+
+| Config      | Type   | Par défaut | Description                                  |
+|-------------|--------|------------|----------------------------------------------|
+| `enabled`   | bool   | false      | Activer l'intégration MCP globalement        |
+| `discovery` | object | `{}`       | Configuration de la découverte d'outils (voir ci-dessous) |
+| `servers`   | object | `{}`       | Mappage du nom de serveur à la configuration du serveur |
+
+### Configuration Discovery (`discovery`)
+
+| Config               | Type | Par défaut | Description                                                                                                                       |
+|----------------------|------|------------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `enabled`            | bool | false      | Si true, les outils MCP sont masqués et chargés à la demande via la recherche. Si false, tous les outils sont chargés             |
+| `ttl`                | int  | 5          | Nombre de tours de conversation pendant lesquels un outil découvert reste déverrouillé                                            |
+| `max_search_results` | int  | 5          | Nombre maximum d'outils retournés par requête de recherche                                                                        |
+| `use_bm25`           | bool | true       | Activer l'outil de recherche par langage naturel/mots-clés (`tool_search_tool_bm25`). **Attention** : consomme plus de ressources que la recherche regex |
+| `use_regex`          | bool | false      | Activer l'outil de recherche par motif regex (`tool_search_tool_regex`)                                                           |
+
+> **Note :** Si `discovery.enabled` est `true`, vous **devez** activer au moins un moteur de recherche (`use_bm25` ou `use_regex`),
+> sinon l'application ne démarrera pas.
+
+### Configuration par serveur
+
+| Config     | Type   | Requis   | Description                                |
+|------------|--------|----------|--------------------------------------------|
+| `enabled`  | bool   | oui      | Activer ce serveur MCP                     |
+| `type`     | string | non      | Type de transport : `stdio`, `sse`, `http` |
+| `command`  | string | stdio    | Commande exécutable pour le transport stdio |
+| `args`     | array  | non      | Arguments de commande pour le transport stdio |
+| `env`      | object | non      | Variables d'environnement pour le processus stdio |
+| `env_file` | string | non      | Chemin vers le fichier d'environnement pour le processus stdio |
+| `url`      | string | sse/http | URL du point de terminaison pour le transport `sse`/`http` |
+| `headers`  | object | non      | En-têtes HTTP pour le transport `sse`/`http` |
+
+### Comportement du transport
+
+- Si `type` est omis, le transport est détecté automatiquement :
+    - `url` est défini → `sse`
+    - `command` est défini → `stdio`
+- `http` et `sse` utilisent tous deux `url` + `headers` optionnels.
+- `env` et `env_file` ne sont appliqués qu'aux serveurs `stdio`.
+
+### Exemples de configuration
+
+#### 1) Serveur MCP Stdio
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-filesystem",
+            "/tmp"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+#### 2) Serveur MCP distant SSE/HTTP
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "remote-mcp": {
+          "enabled": true,
+          "type": "sse",
+          "url": "https://example.com/mcp",
+          "headers": {
+            "Authorization": "Bearer YOUR_TOKEN"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### 3) Configuration MCP massive avec découverte d'outils activée
+
+*Dans cet exemple, le LLM ne verra que `tool_search_tool_bm25`. Il recherchera et déverrouillera dynamiquement les outils Github ou Postgres uniquement lorsque l'utilisateur le demande.*
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "discovery": {
+        "enabled": true,
+        "ttl": 5,
+        "max_search_results": 5,
+        "use_bm25": true,
+        "use_regex": false
+      },
+      "servers": {
+        "github": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-github"
+          ],
+          "env": {
+            "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
+          }
+        },
+        "postgres": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-postgres",
+            "postgresql://user:password@localhost/dbname"
+          ]
+        },
+        "slack": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-slack"
+          ],
+          "env": {
+            "SLACK_BOT_TOKEN": "YOUR_SLACK_BOT_TOKEN",
+            "SLACK_TEAM_ID": "YOUR_SLACK_TEAM_ID"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Outil Skills
+
+L'outil skills configure la découverte et l'installation de compétences via des registres comme ClawHub.
+
+### Registres
+
+| Config                             | Type   | Par défaut           | Description                                  |
+|------------------------------------|--------|----------------------|----------------------------------------------|
+| `registries.clawhub.enabled`       | bool   | true                 | Activer le registre ClawHub                  |
+| `registries.clawhub.base_url`      | string | `https://clawhub.ai` | URL de base ClawHub                          |
+| `registries.clawhub.auth_token`    | string | `""`                 | Jeton Bearer optionnel pour des limites de débit plus élevées |
+| `registries.clawhub.search_path`   | string | `/api/v1/search`     | Chemin de l'API de recherche                 |
+| `registries.clawhub.skills_path`   | string | `/api/v1/skills`     | Chemin de l'API Skills                       |
+| `registries.clawhub.download_path` | string | `/api/v1/download`   | Chemin de l'API de téléchargement            |
+
+### Exemple de configuration
+
+```json
+{
+  "tools": {
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "enabled": true,
+          "base_url": "https://clawhub.ai",
+          "auth_token": "",
+          "search_path": "/api/v1/search",
+          "skills_path": "/api/v1/skills",
+          "download_path": "/api/v1/download"
+        }
+      }
+    }
+  }
+}
+```
+
+## Variables d'environnement
+
+Toutes les options de configuration peuvent être remplacées via des variables d'environnement au format `PICOCLAW_TOOLS_<SECTION>_<KEY>` :
+
+Par exemple :
+
+- `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
+- `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
+- `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
+- `PICOCLAW_TOOLS_MCP_ENABLED=true`
+
+Note : La configuration de type map imbriquée (par exemple `tools.mcp.servers.<name>.*`) est configurée dans `config.json` plutôt que via des variables d'environnement.
diff --git a/docs/fr/troubleshooting.md b/docs/fr/troubleshooting.md
new file mode 100644
index 000000000..d2d099ad3
--- /dev/null
+++ b/docs/fr/troubleshooting.md
@@ -0,0 +1,45 @@
+# 🐛 Dépannage
+
+> Retour au [README](../../README.fr.md)
+
+## "model ... not found in model_list" ou OpenRouter "free is not a valid model ID"
+
+**Symptôme :** Vous voyez l'une des erreurs suivantes :
+
+- `Error creating provider: model "openrouter/free" not found in model_list`
+- OpenRouter retourne 400 : `"free is not a valid model ID"`
+
+**Cause :** Le champ `model` dans votre entrée `model_list` est ce qui est envoyé à l'API. Pour OpenRouter, vous devez utiliser l'identifiant de modèle **complet**, pas un raccourci.
+
+- **Incorrect :** `"model": "free"` → OpenRouter reçoit `free` et le rejette.
+- **Correct :** `"model": "openrouter/free"` → OpenRouter reçoit `openrouter/free` (routage automatique du niveau gratuit).
+
+**Correction :** Dans `~/.picoclaw/config.json` (ou votre chemin de configuration) :
+
+1. **agents.defaults.model_name** doit correspondre à un `model_name` dans `model_list` (par ex. `"openrouter-free"`).
+2. Le **model** de cette entrée doit être un identifiant de modèle OpenRouter valide, par exemple :
+   - `"openrouter/free"` – niveau gratuit automatique
+   - `"google/gemini-2.0-flash-exp:free"`
+   - `"meta-llama/llama-3.1-8b-instruct:free"`
+
+Exemple :
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "openrouter-free"
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "openrouter-free",
+      "model": "openrouter/free",
+      "api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
+      "api_base": "https://openrouter.ai/api/v1"
+    }
+  ]
+}
+```
+
+Obtenez votre clé sur [OpenRouter Keys](https://openrouter.ai/keys).
diff --git a/docs/hardware-compatibility.md b/docs/hardware-compatibility.md
new file mode 100644
index 000000000..c11849822
--- /dev/null
+++ b/docs/hardware-compatibility.md
@@ -0,0 +1,150 @@
+# 🖥️ PicoClaw Hardware Compatibility List
+
+PicoClaw runs on virtually any Linux device. This page tracks verified chips, products, and development boards.
+
+**Your hardware not listed?** Submit a PR to add it! Hardware vendors are welcome to contribute and co-promote.
+
+---
+
+## 1. Verified Chip Support
+
+### x86
+
+| Vendor | Chip | Notes |
+|--------|------|-------|
+| Intel | Any x86 CPU (i386+) | All desktop/server/laptop processors |
+| AMD | Any x86 CPU | All desktop/server/laptop processors |
+
+### ARM
+
+| Sub-arch | Typical Chips | Notes |
+|----------|--------------|-------|
+| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | Single-core ARM1176JZF-S |
+| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | Single-core Cortex-A7, used in LicheePi Zero |
+| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | Quad-core Cortex-A53, used in Orange Pi Zero 3 |
+| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | Quad-core Cortex-A72 |
+| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | Quad-core Cortex-A76 |
+| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | Dual-core Cortex-A53 + NPU, used in NanoKVM-Pro / MaixCAM2 |
+
+### RISC-V (riscv64)
+
+| Vendor | Chip | Core | Notes |
+|--------|------|------|-------|
+| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 on-chip, used in LicheeRV-Nano / NanoKVM / MaixCAM |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L on-chip, 1 TOPS NPU, 4K AI camera SiP |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | RISC-V AI camera series |
+| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | Used in HaaS506-LD1 industrial RTU |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Used in Milk-V Jupiter, BananaPi BPI-F3 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | RVA23 compliant, 1024-bit RVV, FP8 AI inference |
+| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8-core, 16MB L3 cache, desktop-class |
+| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU, used in CanMV-K230 |
+
+### MIPS
+
+| Vendor | Chip | Notes |
+|--------|------|-------|
+| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz, used in many OpenWrt routers (e.g. Xiaomi Router 3G) |
+
+### LoongArch (loong64)
+
+| Vendor | Chip | Notes |
+|--------|------|-------|
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | Quad-core LA464 @ 2.5GHz, desktop/workstation |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | Quad-core 4C/8T @ 2.5GHz, IPC comparable to Intel 10th gen |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | Dual-core @ 1GHz, industrial/IoT applications |
+
+---
+
+## 2. Verified Products (by release date)
+
+Consumer products, routers, and industrial devices that have been tested with PicoClaw.
+
+| Year | Product | Arch | SoC | RAM | Category |
+|------|---------|------|-----|-----|----------|
+| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | Smartphone |
+| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | Tablet |
+| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | Router (OpenWrt) |
+| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | TV Box / Home Server |
+| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | Smart Speaker |
+| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
+| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | Industrial RTU |
+| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | Pro IP-KVM |
+| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | 4K AI Camera |
+
+---
+
+## 3. Verified Development Boards (by release date)
+
+| Year | Board | Arch | SoC | RAM | Buy Link |
+|------|-------|------|-----|-----|----------|
+| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
+| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
+| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
+| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
+| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
+| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
+| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
+| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
+| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
+
+---
+
+## 4. Also Works On
+
+### Android Phones (via Termux)
+
+Any ARM64 Android phone (2015+) with 1GB+ RAM. Install [Termux](https://github.com/termux/termux-app), use `proot` to run PicoClaw.
+
+> See [README: Run on old Android Phones](../README.md#-run-on-old-android-phones) for setup instructions.
+
+### Desktop / Server / Cloud
+
+| Platform | Notes |
+|----------|-------|
+| x86_64 Linux | Native binary, no dependencies |
+| x86_64 Windows | Native binary |
+| macOS (Intel / Apple Silicon) | Native binary |
+| Docker (any platform) | `docker compose` one-liner, see [Docker Guide](docker.md) |
+| OpenWrt routers | MIPS/ARM builds, requires >32MB free RAM |
+| FreeBSD / NetBSD | x86_64 and arm64 builds available |
+
+---
+
+## 5. Minimum Requirements
+
+| Resource | Minimum | Recommended |
+|----------|---------|-------------|
+| RAM | 10MB free | 32MB+ free |
+| Storage | 20MB (binary) | 50MB+ (with workspace) |
+| CPU | Any (single core 0.6GHz+) | — |
+| OS | Linux (kernel 3.x+) | Linux 5.x+ |
+| Network | Required (for LLM API calls) | Ethernet or WiFi |
+
+---
+
+## 6. How to Test & Contribute
+
+```bash
+# 1. Download for your architecture
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+
+# 2. Initialize
+./picoclaw onboard
+
+# 3. Test
+./picoclaw agent -m "Hello, what board am I running on?"
+```
+
+Available builds: `linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
+
+### Add Your Hardware
+
+1. Fork this repo
+2. Add your chip / product / board to the appropriate table
+3. Include: name, arch, SoC, RAM, year, and a link if available
+4. Submit a PR
+
+Hardware vendors: want to add official support or co-promote? Open an issue or reach out via [Discord](https://discord.gg/V4sAZ9XWpN).
diff --git a/docs/hooks/README.md b/docs/hooks/README.md
new file mode 100644
index 000000000..ec3bbc46a
--- /dev/null
+++ b/docs/hooks/README.md
@@ -0,0 +1,679 @@
+# Hook System Guide
+
+This document describes the hook system that is implemented in the current repository, not the older design draft.
+
+The current implementation supports two mounting modes:
+
+1. In-process hooks
+2. Out-of-process process hooks (`JSON-RPC over stdio`)
+
+The repository no longer ships standalone example source files. The Go and Python examples below are embedded directly in this document. If you want to use them, copy them into your own local files first.
+
+## Supported Hook Types
+
+| Type | Interface | Stage | Can modify data |
+| --- | --- | --- | --- |
+| Observer | `EventObserver` | EventBus broadcast | No |
+| LLM interceptor | `LLMInterceptor` | `before_llm` / `after_llm` | Yes |
+| Tool interceptor | `ToolInterceptor` | `before_tool` / `after_tool` | Yes |
+| Tool approver | `ToolApprover` | `approve_tool` | No, returns allow/deny |
+
+The currently exposed synchronous hook points are:
+
+- `before_llm`
+- `after_llm`
+- `before_tool`
+- `after_tool`
+- `approve_tool`
+
+Everything else is exposed as read-only events.
+
+## Execution Order
+
+`HookManager` sorts hooks like this:
+
+1. In-process hooks first
+2. Process hooks second
+3. Lower `priority` first within the same source
+4. Name order as the final tie-breaker
+
+## Timeouts
+
+Global defaults live under `hooks.defaults`:
+
+- `observer_timeout_ms`
+- `interceptor_timeout_ms`
+- `approval_timeout_ms`
+
+Note: the current implementation does not support per-process-hook `timeout_ms`. Timeouts are global defaults.
+
+## Quick Start
+
+If your first goal is simply to prove that the hook flow works and observe real requests, the easiest path is the Python process-hook example below:
+
+1. Enable `hooks.enabled`
+2. Save the Python example from this document to a local file, for example `/tmp/review_gate.py`
+3. Set `PICOCLAW_HOOK_LOG_FILE`
+4. Restart the gateway
+5. Watch the log file with `tail -f`
+
+Example:
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "processes": {
+      "py_review_gate": {
+        "enabled": true,
+        "priority": 100,
+        "transport": "stdio",
+        "command": [
+          "python3",
+          "/tmp/review_gate.py"
+        ],
+        "observe": [
+          "tool_exec_start",
+          "tool_exec_end",
+          "tool_exec_skipped"
+        ],
+        "intercept": [
+          "before_tool",
+          "approve_tool"
+        ],
+        "env": {
+          "PICOCLAW_HOOK_LOG_FILE": "/tmp/picoclaw-hook-review-gate.log"
+        }
+      }
+    }
+  }
+}
+```
+
+Watch it with:
+
+```bash
+tail -f /tmp/picoclaw-hook-review-gate.log
+```
+
+If you are developing PicoClaw itself rather than only validating the protocol, continue with the Go in-process example as well.
+
+## What The Two Examples Are For
+
+- Go in-process example
+  Best for validating the host-side hook chain and understanding `MountHook()` plus the synchronous stages
+- Python process example
+  Best for understanding the `JSON-RPC over stdio` protocol and verifying the message flow between PicoClaw and an external process
+
+Both examples are intentionally safe: they only log, never rewrite, and never deny.
+
+## Go In-Process Example
+
+The following is a minimal logging hook for in-process use. It implements:
+
+1. `EventObserver`
+2. `LLMInterceptor`
+3. `ToolInterceptor`
+4. `ToolApprover`
+
+It only records activity. It does not rewrite requests or reject tools.
+
+You can save it as your own Go file, for example `pkg/myhooks/example_logger.go`:
+
+```go
+package myhooks
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/agent"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+type ExampleLoggerHookOptions struct {
+	LogFile   string `json:"log_file,omitempty"`
+	LogEvents bool   `json:"log_events,omitempty"`
+}
+
+type ExampleLoggerHook struct {
+	logFile   string
+	logEvents bool
+	mu        sync.Mutex
+}
+
+func NewExampleLoggerHook(opts ExampleLoggerHookOptions) *ExampleLoggerHook {
+	return &ExampleLoggerHook{
+		logFile:   strings.TrimSpace(opts.LogFile),
+		logEvents: opts.LogEvents,
+	}
+}
+
+func (h *ExampleLoggerHook) OnEvent(ctx context.Context, evt agent.Event) error {
+	_ = ctx
+	if h == nil || !h.logEvents {
+		return nil
+	}
+	h.record("event", evt.Meta, map[string]any{
+		"event":   evt.Kind.String(),
+		"payload": evt.Payload,
+	}, nil)
+	return nil
+}
+
+func (h *ExampleLoggerHook) BeforeLLM(
+	ctx context.Context,
+	req *agent.LLMHookRequest,
+) (*agent.LLMHookRequest, agent.HookDecision, error) {
+	_ = ctx
+	h.record("before_llm", req.Meta, req, agent.HookDecision{Action: agent.HookActionContinue})
+	return req, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) AfterLLM(
+	ctx context.Context,
+	resp *agent.LLMHookResponse,
+) (*agent.LLMHookResponse, agent.HookDecision, error) {
+	_ = ctx
+	h.record("after_llm", resp.Meta, resp, agent.HookDecision{Action: agent.HookActionContinue})
+	return resp, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) BeforeTool(
+	ctx context.Context,
+	call *agent.ToolCallHookRequest,
+) (*agent.ToolCallHookRequest, agent.HookDecision, error) {
+	_ = ctx
+	h.record("before_tool", call.Meta, call, agent.HookDecision{Action: agent.HookActionContinue})
+	return call, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) AfterTool(
+	ctx context.Context,
+	result *agent.ToolResultHookResponse,
+) (*agent.ToolResultHookResponse, agent.HookDecision, error) {
+	_ = ctx
+	h.record("after_tool", result.Meta, result, agent.HookDecision{Action: agent.HookActionContinue})
+	return result, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) ApproveTool(
+	ctx context.Context,
+	req *agent.ToolApprovalRequest,
+) (agent.ApprovalDecision, error) {
+	_ = ctx
+	decision := agent.ApprovalDecision{Approved: true}
+	h.record("approve_tool", req.Meta, req, decision)
+	return decision, nil
+}
+
+func (h *ExampleLoggerHook) record(stage string, meta agent.EventMeta, payload any, decision any) {
+	logger.InfoCF("hooks", "Example hook observed", map[string]any{
+		"stage": stage,
+	})
+	if h == nil || h.logFile == "" {
+		return
+	}
+
+	entry := map[string]any{
+		"ts":       time.Now().UTC(),
+		"stage":    stage,
+		"meta":     meta,
+		"payload":  payload,
+		"decision": decision,
+	}
+
+	body, err := json.Marshal(entry)
+	if err != nil {
+		logger.WarnCF("hooks", "Example hook log encode failed", map[string]any{
+			"stage": stage,
+			"error": err.Error(),
+		})
+		return
+	}
+
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	if dir := filepath.Dir(h.logFile); dir != "" && dir != "." {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			logger.WarnCF("hooks", "Example hook log mkdir failed", map[string]any{
+				"stage": stage,
+				"path":  h.logFile,
+				"error": err.Error(),
+			})
+			return
+		}
+	}
+
+	file, err := os.OpenFile(h.logFile, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
+	if err != nil {
+		logger.WarnCF("hooks", "Example hook log open failed", map[string]any{
+			"stage": stage,
+			"path":  h.logFile,
+			"error": err.Error(),
+		})
+		return
+	}
+	defer func() { _ = file.Close() }()
+
+	if _, err := file.Write(append(body, '\n')); err != nil {
+		logger.WarnCF("hooks", "Example hook log write failed", map[string]any{
+			"stage": stage,
+			"path":  h.logFile,
+			"error": err.Error(),
+		})
+	}
+}
+```
+
+### Mounting It In Code
+
+If code mounting is enough, call this after `AgentLoop` is initialized:
+
+```go
+hook := myhooks.NewExampleLoggerHook(myhooks.ExampleLoggerHookOptions{
+    LogFile:   "/tmp/picoclaw-hook-example-logger.log",
+    LogEvents: true,
+})
+
+if err := al.MountHook(agent.NamedHook("example-logger", hook)); err != nil {
+    panic(err)
+}
+```
+
+### If You Also Want Config Mounting
+
+The hook system supports builtin hooks, but that requires you to compile the factory into your binary. In practice, that means you need registration code like this alongside the hook definition above:
+
+```go
+package myhooks
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/sipeed/picoclaw/pkg/agent"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	if err := agent.RegisterBuiltinHook("example_logger", func(
+		ctx context.Context,
+		spec config.BuiltinHookConfig,
+	) (any, error) {
+		_ = ctx
+
+		var opts ExampleLoggerHookOptions
+		if len(spec.Config) > 0 {
+			if err := json.Unmarshal(spec.Config, &opts); err != nil {
+				return nil, fmt.Errorf("decode example_logger config: %w", err)
+			}
+		}
+		return NewExampleLoggerHook(opts), nil
+	}); err != nil {
+		panic(err)
+	}
+}
+```
+
+Only after you register that builtin will the following config work:
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "builtins": {
+      "example_logger": {
+        "enabled": true,
+        "priority": 10,
+        "config": {
+          "log_file": "/tmp/picoclaw-hook-example-logger.log",
+          "log_events": true
+        }
+      }
+    }
+  }
+}
+```
+
+### How To Observe It
+
+- If `log_file` is set, each hook call is appended as JSON Lines
+- If `log_file` is not set, the hook still writes summaries to the gateway log
+- Requests that only hit the LLM path usually show `before_llm` and `after_llm`
+- Requests that trigger tools usually also show `before_tool`, `approve_tool`, and `after_tool`
+- If `log_events=true`, you will also see `event`
+
+Typical log lines:
+
+```json
+{"ts":"2026-03-21T14:10:00Z","stage":"before_tool","meta":{"session_key":"session-1"},"payload":{"tool":"echo_text","arguments":{"text":"hello"}},"decision":{"action":"continue"}}
+{"ts":"2026-03-21T14:10:00Z","stage":"approve_tool","meta":{"session_key":"session-1"},"payload":{"tool":"echo_text","arguments":{"text":"hello"}},"decision":{"approved":true}}
+```
+
+If you only see `before_llm` and `after_llm`, that usually means the request did not trigger any tool call, not that the hook failed to mount.
+
+## Python Process-Hook Example
+
+The following script is a minimal process-hook example. It uses only the Python standard library and supports:
+
+1. `hook.hello`
+2. `hook.event`
+3. `hook.before_tool`
+4. `hook.approve_tool`
+
+It only records activity. It does not rewrite or deny anything.
+
+Save it to any local path, for example `/tmp/review_gate.py`:
+
+```python
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import signal
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+LOG_EVENTS = os.getenv("PICOCLAW_HOOK_LOG_EVENTS", "1").lower() not in {"0", "false", "no"}
+LOG_FILE = os.getenv("PICOCLAW_HOOK_LOG_FILE", "").strip()
+
+
+def append_log(entry: dict[str, Any]) -> None:
+    if not LOG_FILE:
+        return
+
+    payload = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        **entry,
+    }
+    try:
+        log_dir = os.path.dirname(LOG_FILE)
+        if log_dir:
+            os.makedirs(log_dir, exist_ok=True)
+        with open(LOG_FILE, "a", encoding="utf-8") as handle:
+            handle.write(json.dumps(payload, ensure_ascii=True) + "\n")
+    except OSError as exc:
+        log_stderr(f"failed to write hook log file {LOG_FILE}: {exc}")
+
+
+def send_response(message_id: int, result: Any | None = None, error: str | None = None) -> None:
+    payload: dict[str, Any] = {
+        "jsonrpc": "2.0",
+        "id": message_id,
+    }
+    if error is not None:
+        payload["error"] = {"code": -32000, "message": error}
+    else:
+        payload["result"] = result if result is not None else {}
+
+    append_log({
+        "direction": "out",
+        "id": message_id,
+        "response": payload.get("result"),
+        "error": payload.get("error"),
+    })
+
+    try:
+        sys.stdout.write(json.dumps(payload, ensure_ascii=True) + "\n")
+        sys.stdout.flush()
+    except BrokenPipeError:
+        raise SystemExit(0) from None
+
+
+def log_stderr(message: str) -> None:
+    try:
+        sys.stderr.write(message + "\n")
+        sys.stderr.flush()
+    except BrokenPipeError:
+        raise SystemExit(0) from None
+
+
+def handle_shutdown_signal(signum: int, _frame: Any) -> None:
+    raise KeyboardInterrupt(f"received signal {signum}")
+
+
+def handle_before_tool(params: dict[str, Any]) -> dict[str, Any]:
+    _ = params
+    return {"action": "continue"}
+
+
+def handle_approve_tool(params: dict[str, Any]) -> dict[str, Any]:
+    _ = params
+    return {"approved": True}
+
+
+def handle_request(method: str, params: dict[str, Any]) -> dict[str, Any]:
+    if method == "hook.hello":
+        return {"ok": True, "name": "python-review-gate"}
+    if method == "hook.before_tool":
+        return handle_before_tool(params)
+    if method == "hook.approve_tool":
+        return handle_approve_tool(params)
+    if method == "hook.before_llm":
+        return {"action": "continue"}
+    if method == "hook.after_llm":
+        return {"action": "continue"}
+    if method == "hook.after_tool":
+        return {"action": "continue"}
+    raise KeyError(f"method not found: {method}")
+
+
+def main() -> int:
+    try:
+        for raw_line in sys.stdin:
+            line = raw_line.strip()
+            if not line:
+                continue
+
+            try:
+                message = json.loads(line)
+            except json.JSONDecodeError as exc:
+                log_stderr(f"failed to decode request: {exc}")
+                append_log({
+                    "direction": "in",
+                    "decode_error": str(exc),
+                    "raw": line,
+                })
+                continue
+
+            method = message.get("method")
+            message_id = message.get("id", 0)
+            params = message.get("params") or {}
+            if not isinstance(params, dict):
+                params = {}
+
+            append_log({
+                "direction": "in",
+                "id": message_id,
+                "method": method,
+                "params": params,
+                "notification": not bool(message_id),
+            })
+
+            if not message_id:
+                if method == "hook.event" and LOG_EVENTS:
+                    log_stderr(f"observed event: {params.get('Kind')}")
+                continue
+
+            try:
+                result = handle_request(str(method or ""), params)
+            except KeyError as exc:
+                send_response(int(message_id), error=str(exc))
+                continue
+            except Exception as exc:
+                send_response(int(message_id), error=f"unexpected error: {exc}")
+                continue
+
+            send_response(int(message_id), result=result)
+    except KeyboardInterrupt:
+        return 0
+
+    return 0
+
+
+if __name__ == "__main__":
+    signal.signal(signal.SIGINT, handle_shutdown_signal)
+    signal.signal(signal.SIGTERM, handle_shutdown_signal)
+    raise SystemExit(main())
+```
+
+### Configuration
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "processes": {
+      "py_review_gate": {
+        "enabled": true,
+        "priority": 100,
+        "transport": "stdio",
+        "command": [
+          "python3",
+          "/abs/path/to/review_gate.py"
+        ],
+        "observe": [
+          "tool_exec_start",
+          "tool_exec_end",
+          "tool_exec_skipped"
+        ],
+        "intercept": [
+          "before_tool",
+          "approve_tool"
+        ],
+        "env": {
+          "PICOCLAW_HOOK_LOG_FILE": "/tmp/picoclaw-hook-review-gate.log"
+        }
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+- `PICOCLAW_HOOK_LOG_EVENTS`
+  Whether to write `hook.event` summaries to `stderr`, enabled by default
+- `PICOCLAW_HOOK_LOG_FILE`
+  Path to an external log file. When set, the script appends inbound hook requests, notifications, and outbound responses as JSON Lines
+
+Note: `PICOCLAW_HOOK_LOG_FILE` has no default. If you do not set it, the script does not write any file logs.
+
+### How To Confirm It Received Hooks
+
+Watch two places:
+
+- Gateway logs
+  Useful for confirming that the host successfully started the process and for seeing event summaries written to `stderr`
+- `PICOCLAW_HOOK_LOG_FILE`
+  Useful for seeing the exact requests the script received and the exact responses it returned
+
+Typical interpretation:
+
+- Only `hook.hello`
+  The process started and completed the handshake, but no business hook request has arrived yet
+- `hook.event`
+  The `observe` configuration is working
+- `hook.before_tool`
+  The `intercept: ["before_tool", ...]` configuration is working
+- `hook.approve_tool`
+  The approval hook path is working
+
+Because this example never rewrites or denies, the expected responses look like:
+
+```json
+{"direction":"out","id":7,"response":{"action":"continue"},"error":null}
+{"direction":"out","id":8,"response":{"approved":true},"error":null}
+```
+
+A complete sample:
+
+```json
+{"ts":"2026-03-21T14:12:00+00:00","direction":"in","id":1,"method":"hook.hello","params":{"name":"py_review_gate","version":1,"modes":["observe","tool","approve"]},"notification":false}
+{"ts":"2026-03-21T14:12:00+00:00","direction":"out","id":1,"response":{"ok":true,"name":"python-review-gate"},"error":null}
+{"ts":"2026-03-21T14:12:05+00:00","direction":"in","id":0,"method":"hook.event","params":{"Kind":"tool_exec_start"},"notification":true}
+{"ts":"2026-03-21T14:12:05+00:00","direction":"in","id":7,"method":"hook.before_tool","params":{"tool":"echo_text","arguments":{"text":"hello"}},"notification":false}
+{"ts":"2026-03-21T14:12:05+00:00","direction":"out","id":7,"response":{"action":"continue"},"error":null}
+```
+
+Additional notes:
+
+- Timestamps are UTC
+- `notification=true` means it was a notification such as `hook.event`, which does not expect a response
+- `id` increases within a single hook process; if the process restarts, the counter starts over
+
+## Process-Hook Protocol
+
+Current process hooks use `JSON-RPC over stdio`:
+
+- PicoClaw starts the external process
+- Requests and responses are exchanged as one JSON message per line
+- `hook.event` is a notification and does not need a response
+- `hook.before_llm`, `hook.after_llm`, `hook.before_tool`, `hook.after_tool`, and `hook.approve_tool` are request/response calls
+
+The host does not currently accept new RPCs initiated by the process hook. In practice, that means an external hook can only respond to PicoClaw calls; it cannot call back into the host to send channel messages.
+
+## Configuration Fields
+
+### `hooks.builtins.<name>`
+
+- `enabled`
+- `priority`
+- `config`
+
+### `hooks.processes.<name>`
+
+- `enabled`
+- `priority`
+- `transport`
+  Currently only `stdio` is supported
+- `command`
+- `dir`
+- `env`
+- `observe`
+- `intercept`
+
+## Troubleshooting
+
+If a hook looks like it is not firing, check these in order:
+
+1. `hooks.enabled`
+2. Whether the target builtin or process hook is `enabled`
+3. Whether the process-hook `command` path is correct
+4. Whether you are watching the correct log file
+5. Whether the current request actually reached the stage you care about
+6. Whether `observe` or `intercept` contains the hook point you want
+
+A practical minimal troubleshooting pair is:
+
+- Use the Python process-hook example from this document to validate the external protocol
+- Use the Go in-process example from this document to validate the host-side chain
+
+If the Python side shows `hook.hello` but no business hook requests, the protocol is usually fine; the current request simply did not trigger the stage you expected.
+
+## Scope And Limits
+
+The current hook system is best suited for:
+
+- LLM request rewriting
+- Tool argument normalization
+- Pre-execution tool approval
+- Auditing and observability
+
+It is not yet well suited for:
+
+- External hooks actively sending channel messages
+- Suspending a turn and waiting for human approval replies
+- Full inbound/outbound message interception across the whole platform
+
+If you want a real human approval workflow, use hooks as the approval entry point and keep the state machine plus channel interaction in a separate `ApprovalManager`.
diff --git a/docs/hooks/README.zh.md b/docs/hooks/README.zh.md
new file mode 100644
index 000000000..46c7c9392
--- /dev/null
+++ b/docs/hooks/README.zh.md
@@ -0,0 +1,679 @@
+# Hook 系统使用说明
+
+这份文档对应当前仓库里已经实现的 hook 系统，而不是设计草案。
+
+当前实现支持两类挂载方式：
+
+1. 进程内 hook
+2. 进程外 process hook（`JSON-RPC over stdio`）
+
+当前仓库不再内置示例代码文件。下面的 Go / Python 示例都直接写在本文档里；如果你要使用它们，需要先复制到你自己的文件路径。
+
+## 支持的 hook 类型
+
+| 类型 | 接口 | 作用阶段 | 能否改写 |
+| --- | --- | --- | --- |
+| 观察型 | `EventObserver` | EventBus 广播事件时 | 否 |
+| LLM 拦截型 | `LLMInterceptor` | `before_llm` / `after_llm` | 是 |
+| Tool 拦截型 | `ToolInterceptor` | `before_tool` / `after_tool` | 是 |
+| Tool 审批型 | `ToolApprover` | `approve_tool` | 否，返回批准/拒绝 |
+
+当前公开的同步点位只有：
+
+- `before_llm`
+- `after_llm`
+- `before_tool`
+- `after_tool`
+- `approve_tool`
+
+其余 lifecycle 通过事件形式只读暴露。
+
+## 执行顺序
+
+HookManager 的排序规则是：
+
+1. 先执行进程内 hook
+2. 再执行 process hook
+3. 同一来源内按 `priority` 从小到大
+4. 若 `priority` 相同，再按名字排序
+
+## 超时
+
+当前配置在 `hooks.defaults` 中统一设置：
+
+- `observer_timeout_ms`
+- `interceptor_timeout_ms`
+- `approval_timeout_ms`
+
+注意：当前实现还没有单个 process hook 自己的 `timeout_ms` 字段，超时配置是全局默认值。
+
+## 快速开始
+
+如果你的目标只是先把当前 hook 流程跑通并观察到实际请求，最省事的是先用下面的 Python process hook 示例：
+
+1. 打开 `hooks.enabled`
+2. 把下面文档里的 Python 示例保存到本地文件，例如 `/tmp/review_gate.py`
+3. 给它配置 `PICOCLAW_HOOK_LOG_FILE`
+4. 重启 gateway
+5. 用 `tail -f` 观察日志文件
+
+例如：
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "processes": {
+      "py_review_gate": {
+        "enabled": true,
+        "priority": 100,
+        "transport": "stdio",
+        "command": [
+          "python3",
+          "/tmp/review_gate.py"
+        ],
+        "observe": [
+          "tool_exec_start",
+          "tool_exec_end",
+          "tool_exec_skipped"
+        ],
+        "intercept": [
+          "before_tool",
+          "approve_tool"
+        ],
+        "env": {
+          "PICOCLAW_HOOK_LOG_FILE": "/tmp/picoclaw-hook-review-gate.log"
+        }
+      }
+    }
+  }
+}
+```
+
+观察方式：
+
+```bash
+tail -f /tmp/picoclaw-hook-review-gate.log
+```
+
+如果你是在开发 PicoClaw 本体，而不是只想验证协议，那么再看后面的 Go in-process 示例。
+
+## 两个示例的定位
+
+- Go in-process 示例
+  适合验证宿主内的 hook 链路、理解 `MountHook()` 和各个同步点位
+- Python process 示例
+  适合理解 `JSON-RPC over stdio` 协议、确认宿主和外部进程之间的消息来回是否正常
+
+这两个示例都刻意保持为“只记录、不改写、不拒绝”的安全模式。它们的目的不是提供策略能力，而是帮你观察当前 hook 系统。
+
+## Go 进程内示例
+
+下面这段代码是一个最小的“记录型” in-process hook。它实现了：
+
+1. `EventObserver`
+2. `LLMInterceptor`
+3. `ToolInterceptor`
+4. `ToolApprover`
+
+它只记录，不改写请求，也不拒绝工具。
+
+你可以把它保存成你自己的 Go 文件，例如 `pkg/myhooks/example_logger.go`：
+
+```go
+package myhooks
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/agent"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+type ExampleLoggerHookOptions struct {
+	LogFile   string `json:"log_file,omitempty"`
+	LogEvents bool   `json:"log_events,omitempty"`
+}
+
+type ExampleLoggerHook struct {
+	logFile   string
+	logEvents bool
+	mu        sync.Mutex
+}
+
+func NewExampleLoggerHook(opts ExampleLoggerHookOptions) *ExampleLoggerHook {
+	return &ExampleLoggerHook{
+		logFile:   strings.TrimSpace(opts.LogFile),
+		logEvents: opts.LogEvents,
+	}
+}
+
+func (h *ExampleLoggerHook) OnEvent(ctx context.Context, evt agent.Event) error {
+	_ = ctx
+	if h == nil || !h.logEvents {
+		return nil
+	}
+	h.record("event", evt.Meta, map[string]any{
+		"event":   evt.Kind.String(),
+		"payload": evt.Payload,
+	}, nil)
+	return nil
+}
+
+func (h *ExampleLoggerHook) BeforeLLM(
+	ctx context.Context,
+	req *agent.LLMHookRequest,
+) (*agent.LLMHookRequest, agent.HookDecision, error) {
+	_ = ctx
+	h.record("before_llm", req.Meta, req, agent.HookDecision{Action: agent.HookActionContinue})
+	return req, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) AfterLLM(
+	ctx context.Context,
+	resp *agent.LLMHookResponse,
+) (*agent.LLMHookResponse, agent.HookDecision, error) {
+	_ = ctx
+	h.record("after_llm", resp.Meta, resp, agent.HookDecision{Action: agent.HookActionContinue})
+	return resp, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) BeforeTool(
+	ctx context.Context,
+	call *agent.ToolCallHookRequest,
+) (*agent.ToolCallHookRequest, agent.HookDecision, error) {
+	_ = ctx
+	h.record("before_tool", call.Meta, call, agent.HookDecision{Action: agent.HookActionContinue})
+	return call, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) AfterTool(
+	ctx context.Context,
+	result *agent.ToolResultHookResponse,
+) (*agent.ToolResultHookResponse, agent.HookDecision, error) {
+	_ = ctx
+	h.record("after_tool", result.Meta, result, agent.HookDecision{Action: agent.HookActionContinue})
+	return result, agent.HookDecision{Action: agent.HookActionContinue}, nil
+}
+
+func (h *ExampleLoggerHook) ApproveTool(
+	ctx context.Context,
+	req *agent.ToolApprovalRequest,
+) (agent.ApprovalDecision, error) {
+	_ = ctx
+	decision := agent.ApprovalDecision{Approved: true}
+	h.record("approve_tool", req.Meta, req, decision)
+	return decision, nil
+}
+
+func (h *ExampleLoggerHook) record(stage string, meta agent.EventMeta, payload any, decision any) {
+	logger.InfoCF("hooks", "Example hook observed", map[string]any{
+		"stage": stage,
+	})
+	if h == nil || h.logFile == "" {
+		return
+	}
+
+	entry := map[string]any{
+		"ts":       time.Now().UTC(),
+		"stage":    stage,
+		"meta":     meta,
+		"payload":  payload,
+		"decision": decision,
+	}
+
+	body, err := json.Marshal(entry)
+	if err != nil {
+		logger.WarnCF("hooks", "Example hook log encode failed", map[string]any{
+			"stage": stage,
+			"error": err.Error(),
+		})
+		return
+	}
+
+	h.mu.Lock()
+	defer h.mu.Unlock()
+
+	if dir := filepath.Dir(h.logFile); dir != "" && dir != "." {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			logger.WarnCF("hooks", "Example hook log mkdir failed", map[string]any{
+				"stage": stage,
+				"path":  h.logFile,
+				"error": err.Error(),
+			})
+			return
+		}
+	}
+
+	file, err := os.OpenFile(h.logFile, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
+	if err != nil {
+		logger.WarnCF("hooks", "Example hook log open failed", map[string]any{
+			"stage": stage,
+			"path":  h.logFile,
+			"error": err.Error(),
+		})
+		return
+	}
+	defer func() { _ = file.Close() }()
+
+	if _, err := file.Write(append(body, '\n')); err != nil {
+		logger.WarnCF("hooks", "Example hook log write failed", map[string]any{
+			"stage": stage,
+			"path":  h.logFile,
+			"error": err.Error(),
+		})
+	}
+}
+```
+
+### 如何挂载
+
+如果你只需要代码挂载，直接在 `AgentLoop` 初始化后调用：
+
+```go
+hook := myhooks.NewExampleLoggerHook(myhooks.ExampleLoggerHookOptions{
+    LogFile:   "/tmp/picoclaw-hook-example-logger.log",
+    LogEvents: true,
+})
+
+if err := al.MountHook(agent.NamedHook("example-logger", hook)); err != nil {
+    panic(err)
+}
+```
+
+### 如果你还想用配置挂载
+
+当前 hook 系统支持 builtin hook，但这要求你自己把 factory 编进二进制。也就是说，下面这段注册代码需要和上面的 hook 定义一起放进你的工程里：
+
+```go
+package myhooks
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"github.com/sipeed/picoclaw/pkg/agent"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	if err := agent.RegisterBuiltinHook("example_logger", func(
+		ctx context.Context,
+		spec config.BuiltinHookConfig,
+	) (any, error) {
+		_ = ctx
+
+		var opts ExampleLoggerHookOptions
+		if len(spec.Config) > 0 {
+			if err := json.Unmarshal(spec.Config, &opts); err != nil {
+				return nil, fmt.Errorf("decode example_logger config: %w", err)
+			}
+		}
+		return NewExampleLoggerHook(opts), nil
+	}); err != nil {
+		panic(err)
+	}
+}
+```
+
+只有在你自己注册了 builtin 之后，下面的配置才会生效：
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "builtins": {
+      "example_logger": {
+        "enabled": true,
+        "priority": 10,
+        "config": {
+          "log_file": "/tmp/picoclaw-hook-example-logger.log",
+          "log_events": true
+        }
+      }
+    }
+  }
+}
+```
+
+### 如何观察它是否生效
+
+- 如果设置了 `log_file`，它会把每次 hook 调用按 JSON Lines 写入文件
+- 如果没有设置 `log_file`，它仍然会把摘要写到 gateway 日志
+- 普通只走 LLM 的请求，通常会看到 `before_llm` 和 `after_llm`
+- 触发工具调用的请求，通常还会看到 `before_tool`、`approve_tool`、`after_tool`
+- 如果 `log_events=true`，还会额外看到 `event`
+
+典型日志：
+
+```json
+{"ts":"2026-03-21T14:10:00Z","stage":"before_tool","meta":{"session_key":"session-1"},"payload":{"tool":"echo_text","arguments":{"text":"hello"}},"decision":{"action":"continue"}}
+{"ts":"2026-03-21T14:10:00Z","stage":"approve_tool","meta":{"session_key":"session-1"},"payload":{"tool":"echo_text","arguments":{"text":"hello"}},"decision":{"approved":true}}
+```
+
+如果你只看到了 `before_llm` / `after_llm`，没有看到 tool 相关阶段，通常不是 hook 没挂上，而是这次请求本身没有触发工具调用。
+
+## Python process hook 示例
+
+下面这段脚本是一个最小的 `process hook` 示例。它只使用 Python 标准库，支持：
+
+1. `hook.hello`
+2. `hook.event`
+3. `hook.before_tool`
+4. `hook.approve_tool`
+
+它默认只记录，不改写，也不拒绝。
+
+你可以把它保存到任意本地路径，例如 `/tmp/review_gate.py`：
+
+```python
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import signal
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+LOG_EVENTS = os.getenv("PICOCLAW_HOOK_LOG_EVENTS", "1").lower() not in {"0", "false", "no"}
+LOG_FILE = os.getenv("PICOCLAW_HOOK_LOG_FILE", "").strip()
+
+
+def append_log(entry: dict[str, Any]) -> None:
+    if not LOG_FILE:
+        return
+
+    payload = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        **entry,
+    }
+    try:
+        log_dir = os.path.dirname(LOG_FILE)
+        if log_dir:
+            os.makedirs(log_dir, exist_ok=True)
+        with open(LOG_FILE, "a", encoding="utf-8") as handle:
+            handle.write(json.dumps(payload, ensure_ascii=True) + "\n")
+    except OSError as exc:
+        log_stderr(f"failed to write hook log file {LOG_FILE}: {exc}")
+
+
+def send_response(message_id: int, result: Any | None = None, error: str | None = None) -> None:
+    payload: dict[str, Any] = {
+        "jsonrpc": "2.0",
+        "id": message_id,
+    }
+    if error is not None:
+        payload["error"] = {"code": -32000, "message": error}
+    else:
+        payload["result"] = result if result is not None else {}
+
+    append_log({
+        "direction": "out",
+        "id": message_id,
+        "response": payload.get("result"),
+        "error": payload.get("error"),
+    })
+
+    try:
+        sys.stdout.write(json.dumps(payload, ensure_ascii=True) + "\n")
+        sys.stdout.flush()
+    except BrokenPipeError:
+        raise SystemExit(0) from None
+
+
+def log_stderr(message: str) -> None:
+    try:
+        sys.stderr.write(message + "\n")
+        sys.stderr.flush()
+    except BrokenPipeError:
+        raise SystemExit(0) from None
+
+
+def handle_shutdown_signal(signum: int, _frame: Any) -> None:
+    raise KeyboardInterrupt(f"received signal {signum}")
+
+
+def handle_before_tool(params: dict[str, Any]) -> dict[str, Any]:
+    _ = params
+    return {"action": "continue"}
+
+
+def handle_approve_tool(params: dict[str, Any]) -> dict[str, Any]:
+    _ = params
+    return {"approved": True}
+
+
+def handle_request(method: str, params: dict[str, Any]) -> dict[str, Any]:
+    if method == "hook.hello":
+        return {"ok": True, "name": "python-review-gate"}
+    if method == "hook.before_tool":
+        return handle_before_tool(params)
+    if method == "hook.approve_tool":
+        return handle_approve_tool(params)
+    if method == "hook.before_llm":
+        return {"action": "continue"}
+    if method == "hook.after_llm":
+        return {"action": "continue"}
+    if method == "hook.after_tool":
+        return {"action": "continue"}
+    raise KeyError(f"method not found: {method}")
+
+
+def main() -> int:
+    try:
+        for raw_line in sys.stdin:
+            line = raw_line.strip()
+            if not line:
+                continue
+
+            try:
+                message = json.loads(line)
+            except json.JSONDecodeError as exc:
+                log_stderr(f"failed to decode request: {exc}")
+                append_log({
+                    "direction": "in",
+                    "decode_error": str(exc),
+                    "raw": line,
+                })
+                continue
+
+            method = message.get("method")
+            message_id = message.get("id", 0)
+            params = message.get("params") or {}
+            if not isinstance(params, dict):
+                params = {}
+
+            append_log({
+                "direction": "in",
+                "id": message_id,
+                "method": method,
+                "params": params,
+                "notification": not bool(message_id),
+            })
+
+            if not message_id:
+                if method == "hook.event" and LOG_EVENTS:
+                    log_stderr(f"observed event: {params.get('Kind')}")
+                continue
+
+            try:
+                result = handle_request(str(method or ""), params)
+            except KeyError as exc:
+                send_response(int(message_id), error=str(exc))
+                continue
+            except Exception as exc:
+                send_response(int(message_id), error=f"unexpected error: {exc}")
+                continue
+
+            send_response(int(message_id), result=result)
+    except KeyboardInterrupt:
+        return 0
+
+    return 0
+
+
+if __name__ == "__main__":
+    signal.signal(signal.SIGINT, handle_shutdown_signal)
+    signal.signal(signal.SIGTERM, handle_shutdown_signal)
+    raise SystemExit(main())
+```
+
+### 如何配置
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "processes": {
+      "py_review_gate": {
+        "enabled": true,
+        "priority": 100,
+        "transport": "stdio",
+        "command": [
+          "python3",
+          "/abs/path/to/review_gate.py"
+        ],
+        "observe": [
+          "tool_exec_start",
+          "tool_exec_end",
+          "tool_exec_skipped"
+        ],
+        "intercept": [
+          "before_tool",
+          "approve_tool"
+        ],
+        "env": {
+          "PICOCLAW_HOOK_LOG_FILE": "/tmp/picoclaw-hook-review-gate.log"
+        }
+      }
+    }
+  }
+}
+```
+
+### 环境变量
+
+- `PICOCLAW_HOOK_LOG_EVENTS`
+  是否把 `hook.event` 写到 `stderr`，默认开启
+- `PICOCLAW_HOOK_LOG_FILE`
+  外部日志文件路径。设置后，脚本会把收到的 hook 请求、notification 和返回结果按 JSON Lines 追加到该文件
+
+注意：`PICOCLAW_HOOK_LOG_FILE` 没有默认值。不设置时，脚本不会自动落盘日志。
+
+### 如何确认它收到了 hook
+
+推荐同时看两个地方：
+
+- gateway 日志
+  用来观察宿主是否成功启动了外部进程，以及脚本写到 `stderr` 的事件摘要
+- `PICOCLAW_HOOK_LOG_FILE`
+  用来观察脚本实际收到了什么请求、返回了什么响应
+
+典型判断方式：
+
+- 只看到 `hook.hello`
+  说明进程启动并完成握手了，但还没有新的业务 hook 请求真正打进来
+- 看到 `hook.event`
+  说明 `observe` 配置生效了
+- 看到 `hook.before_tool`
+  说明 `intercept: ["before_tool", ...]` 生效了
+- 看到 `hook.approve_tool`
+  说明审批 hook 生效了
+
+这份示例脚本不会改写任何参数，也不会拒绝工具，所以你应该看到的典型返回是：
+
+```json
+{"direction":"out","id":7,"response":{"action":"continue"},"error":null}
+{"direction":"out","id":8,"response":{"approved":true},"error":null}
+```
+
+一组完整样例：
+
+```json
+{"ts":"2026-03-21T14:12:00+00:00","direction":"in","id":1,"method":"hook.hello","params":{"name":"py_review_gate","version":1,"modes":["observe","tool","approve"]},"notification":false}
+{"ts":"2026-03-21T14:12:00+00:00","direction":"out","id":1,"response":{"ok":true,"name":"python-review-gate"},"error":null}
+{"ts":"2026-03-21T14:12:05+00:00","direction":"in","id":0,"method":"hook.event","params":{"Kind":"tool_exec_start"},"notification":true}
+{"ts":"2026-03-21T14:12:05+00:00","direction":"in","id":7,"method":"hook.before_tool","params":{"tool":"echo_text","arguments":{"text":"hello"}},"notification":false}
+{"ts":"2026-03-21T14:12:05+00:00","direction":"out","id":7,"response":{"action":"continue"},"error":null}
+```
+
+补充说明：
+
+- 时间戳是 UTC，不是本地时区
+- `notification=true` 表示这是 `hook.event` 这类不需要响应的通知
+- `id` 会随着当前进程内的请求递增；如果 hook 进程重启，计数会重新开始
+
+## Process Hook 协议约定
+
+当前 process hook 使用 `JSON-RPC over stdio`：
+
+- PicoClaw 启动外部进程
+- 请求和响应都按“一行一个 JSON 消息”传输
+- `hook.event` 是 notification，不需要响应
+- `hook.before_llm` / `hook.after_llm` / `hook.before_tool` / `hook.after_tool` / `hook.approve_tool` 是 request/response
+
+当前宿主不会接受 process hook 主动发起的新 RPC。也就是说，外部 hook 现在只能“响应 PicoClaw 的调用”，不能反向调用宿主去发送 channel 消息。
+
+## 配置字段
+
+### `hooks.builtins.<name>`
+
+- `enabled`
+- `priority`
+- `config`
+
+### `hooks.processes.<name>`
+
+- `enabled`
+- `priority`
+- `transport`
+  当前只支持 `stdio`
+- `command`
+- `dir`
+- `env`
+- `observe`
+- `intercept`
+
+## 排查建议
+
+当你觉得“hook 没触发”时，优先按这个顺序排查：
+
+1. `hooks.enabled` 是否为 `true`
+2. 对应的 builtin/process hook 是否 `enabled`
+3. process hook 的 `command` 路径是否正确
+4. 你看的是否是正确的日志文件
+5. 当前请求是否真的走到了对应阶段
+6. `observe` / `intercept` 是否包含了你想看的点位
+
+一个很实用的最小排查组合是：
+
+- 先用文档里的 Python process 示例确认外部协议没问题
+- 再用文档里的 Go in-process 示例确认宿主内的 hook 链路没问题
+
+如果前者有 `hook.hello` 但没有业务请求，通常不是协议挂了，而是当前这次请求没有真正触发对应的 hook 点位。
+
+## 适用边界
+
+当前 hook 系统最适合做这些事：
+
+- LLM 请求改写
+- 工具参数规范化
+- 工具执行前审批
+- 审计和观测
+
+当前还不适合直接承载这些需求：
+
+- 外部 hook 主动发 channel 消息
+- 挂起 turn 并等待人工审批回复
+- inbound/outbound 全链路消息拦截
+
+如果你要做人审流转，推荐把 hook 作为审批入口，把审批状态机和 channel 交互放到独立的 `ApprovalManager`。
diff --git a/docs/it/configuration.md b/docs/it/configuration.md
new file mode 100644
index 000000000..6a79a9543
--- /dev/null
+++ b/docs/it/configuration.md
@@ -0,0 +1,219 @@
+# ⚙️ Guida alla Configurazione
+
+> Torna al [README](../../README.md)
+
+## ⚙️ Configurazione
+
+File di configurazione: `~/.picoclaw/config.json`
+
+### Variabili d'Ambiente
+
+Puoi sovrascrivere i percorsi predefiniti usando variabili d'ambiente. Questo è utile per installazioni portatili, distribuzioni containerizzate, o per eseguire picoclaw come servizio di sistema. Queste variabili sono indipendenti e controllano percorsi diversi.
+
+| Variabile         | Descrizione                                                                                                                             | Percorso Predefinito      |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | Sovrascrive il percorso al file di configurazione. Indica direttamente a picoclaw quale `config.json` caricare, ignorando tutte le altre posizioni. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | Sovrascrive la directory radice per i dati di picoclaw. Modifica la posizione predefinita del `workspace` e delle altre directory dati.  | `~/.picoclaw`             |
+
+**Esempi:**
+
+```bash
+# Esegui picoclaw usando un file di configurazione specifico
+# Il percorso del workspace verrà letto da quel file di configurazione
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Esegui picoclaw con tutti i dati salvati in /opt/picoclaw
+# La configurazione verrà caricata dal percorso predefinito ~/.picoclaw/config.json
+# Il workspace verrà creato in /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Usa entrambi per un setup completamente personalizzato
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
+### Struttura del Workspace
+
+PicoClaw salva i dati nel workspace configurato (predefinito: `~/.picoclaw/workspace`):
+
+```
+~/.picoclaw/workspace/
+├── sessions/          # Sessioni di conversazione e cronologia
+├── memory/           # Memoria a lungo termine (MEMORY.md)
+├── state/            # Stato persistente (ultimo canale, ecc.)
+├── cron/             # Database dei job pianificati
+├── skills/           # Skill personalizzate
+├── AGENTS.md         # Guida al comportamento dell'agent
+├── HEARTBEAT.md      # Prompt per task periodici (controllato ogni 30 min)
+├── IDENTITY.md       # Identità dell'agent
+├── SOUL.md           # Anima dell'agent
+└── USER.md           # Preferenze dell'utente
+```
+
+> **Nota:** Le modifiche a `AGENTS.md`, `SOUL.md`, `USER.md`, `IDENTITY.md` e `memory/MEMORY.md` vengono rilevate automaticamente a runtime tramite il tracciamento della data di modifica (mtime). **Non è necessario riavviare il gateway** dopo aver modificato questi file — l'agent caricherà il nuovo contenuto alla prossima richiesta.
+
+### Sorgenti delle Skill
+
+Per impostazione predefinita, le skill vengono caricate da:
+
+1. `~/.picoclaw/workspace/skills` (workspace)
+2. `~/.picoclaw/skills` (globale)
+3. `<current-working-directory>/skills` (builtin)
+
+Per configurazioni avanzate/di test, puoi sovrascrivere la directory radice delle skill builtin con:
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
+### Politica Unificata di Esecuzione dei Comandi
+
+- I comandi slash generici vengono eseguiti tramite un unico percorso in `pkg/agent/loop.go` via `commands.Executor`.
+- Gli adattatori dei canali non consumano più localmente i comandi generici; inoltrano il testo in entrata al percorso bus/agent. Telegram registra ancora automaticamente i comandi supportati all'avvio.
+- Un comando slash sconosciuto (ad esempio `/foo`) viene passato all'elaborazione LLM come se fosse un messaggio dell'utente.
+- Un comando registrato ma non supportato sul canale corrente (ad esempio `/show` su WhatsApp) restituisce un errore esplicito all'utente e interrompe l'elaborazione.
+
+### 🔒 Sandbox di Sicurezza
+
+PicoClaw esegue in un ambiente sandboxed per impostazione predefinita. L'agent può accedere solo ai file ed eseguire comandi all'interno del workspace configurato.
+
+#### Configurazione Predefinita
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "restrict_to_workspace": true
+    }
+  }
+}
+```
+
+| Opzione                 | Predefinito             | Descrizione                                          |
+| ----------------------- | ----------------------- | ---------------------------------------------------- |
+| `workspace`             | `~/.picoclaw/workspace` | Directory di lavoro dell'agent                       |
+| `restrict_to_workspace` | `true`                  | Limita l'accesso a file/comandi al workspace         |
+
+#### Strumenti Protetti
+
+Quando `restrict_to_workspace: true`, i seguenti strumenti sono in sandbox:
+
+| Strumento     | Funzione                  | Restrizione                                          |
+| ------------- | ------------------------- | ---------------------------------------------------- |
+| `read_file`   | Legge file                | Solo file all'interno del workspace                  |
+| `write_file`  | Scrive file               | Solo file all'interno del workspace                  |
+| `list_dir`    | Elenca directory          | Solo directory all'interno del workspace             |
+| `edit_file`   | Modifica file             | Solo file all'interno del workspace                  |
+| `append_file` | Aggiunge ai file          | Solo file all'interno del workspace                  |
+| `exec`        | Esegue comandi            | I percorsi dei comandi devono essere nel workspace   |
+
+#### Protezione Exec Aggiuntiva
+
+Anche con `restrict_to_workspace: false`, lo strumento `exec` blocca questi comandi pericolosi:
+
+* `rm -rf`, `del /f`, `rmdir /s` — Cancellazione di massa
+* `format`, `mkfs`, `diskpart` — Formattazione del disco
+* `dd if=` — Imaging del disco
+* Scrittura su `/dev/sd[a-z]` — Scritture dirette su disco
+* `shutdown`, `reboot`, `poweroff` — Spegnimento del sistema
+* Fork bomb `:(){ :|:& };:`
+
+### Controllo Accesso ai File
+
+| Chiave di configurazione | Tipo | Predefinito | Descrizione |
+|--------------------------|------|-------------|-------------|
+| `tools.allow_read_paths` | string[] | `[]` | Percorsi aggiuntivi consentiti per la lettura al di fuori del workspace |
+| `tools.allow_write_paths` | string[] | `[]` | Percorsi aggiuntivi consentiti per la scrittura al di fuori del workspace |
+
+### Sicurezza Exec
+
+| Chiave di configurazione | Tipo | Predefinito | Descrizione |
+|--------------------------|------|-------------|-------------|
+| `tools.exec.allow_remote` | bool | `false` | Consente lo strumento exec da canali remoti (Telegram/Discord ecc.) |
+| `tools.exec.enable_deny_patterns` | bool | `true` | Abilita l'intercettazione dei comandi pericolosi |
+| `tools.exec.custom_deny_patterns` | string[] | `[]` | Pattern regex personalizzati da bloccare |
+| `tools.exec.custom_allow_patterns` | string[] | `[]` | Pattern regex personalizzati da consentire |
+
+> **Nota di sicurezza:** La protezione dei symlink è abilitata per impostazione predefinita — tutti i percorsi file vengono risolti tramite `filepath.EvalSymlinks` prima del confronto con la whitelist, prevenendo attacchi di escape tramite symlink.
+
+#### Limitazione Nota: Processi Figlio degli Strumenti di Build
+
+Il controllo di sicurezza exec ispeziona solo la riga di comando avviata direttamente da PicoClaw. Non ispeziona ricorsivamente i processi figlio generati da strumenti di sviluppo consentiti come `make`, `go run`, `cargo`, `npm run` o script di build personalizzati.
+
+Ciò significa che un comando di primo livello può comunque compilare o avviare altri binari dopo aver superato il controllo iniziale. In pratica, tratta gli script di build, i Makefile, gli script di pacchetti e i binari generati come codice eseguibile che richiede lo stesso livello di revisione di un comando shell diretto.
+
+Per ambienti ad alto rischio:
+
+* Esamina gli script di build prima dell'esecuzione.
+* Preferisci l'approvazione/revisione manuale per i workflow di compilazione ed esecuzione.
+* Esegui PicoClaw in un container o VM se hai bisogno di un isolamento più forte di quello fornito dal controllo integrato.
+
+#### Esempi di Errore
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (path outside working dir)}
+```
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
+```
+
+#### Disabilitare le Restrizioni (Rischio di Sicurezza)
+
+Se hai bisogno che l'agent acceda a percorsi al di fuori del workspace:
+
+**Metodo 1: File di configurazione**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "restrict_to_workspace": false
+    }
+  }
+}
+```
+
+**Metodo 2: Variabile d'ambiente**
+
+```bash
+export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
+```
+
+> ⚠️ **Attenzione**: Disabilitare questa restrizione consente all'agent di accedere a qualsiasi percorso sul tuo sistema. Usare con cautela solo in ambienti controllati.
+
+#### Coerenza dei Confini di Sicurezza
+
+L'impostazione `restrict_to_workspace` si applica in modo coerente a tutti i percorsi di esecuzione:
+
+| Percorso di esecuzione | Confine di sicurezza              |
+| ---------------------- | --------------------------------- |
+| Main Agent             | `restrict_to_workspace` ✅        |
+| Subagent / Spawn       | Eredita la stessa restrizione ✅  |
+| Heartbeat tasks        | Eredita la stessa restrizione ✅  |
+
+Tutti i percorsi condividono la stessa restrizione del workspace — non è possibile aggirare il confine di sicurezza tramite subagent o task pianificati.
+
+### Heartbeat (Task Periodici)
+
+PicoClaw può eseguire task periodici automaticamente. Crea un file `HEARTBEAT.md` nel tuo workspace:
+
+```markdown
+# Periodic Tasks
+
+- Check my email for important messages
+- Review my calendar for upcoming events
+- Check the weather forecast
+```
+
+L'agent leggerà questo file ogni 30 minuti (configurabile) ed eseguirà tutti i task usando gli strumenti disponibili.
+
+#### Task Asincroni con Spawn
+
+Per task di lunga durata (ricerca web, chiamate API), usa lo strumento `spawn` per creare un **subagent**:
+
+```markdown
+# Periodic Tasks
+```
diff --git a/docs/ja/ANTIGRAVITY_AUTH.md b/docs/ja/ANTIGRAVITY_AUTH.md
new file mode 100644
index 000000000..b55e4ab1b
--- /dev/null
+++ b/docs/ja/ANTIGRAVITY_AUTH.md
@@ -0,0 +1,809 @@
+> [README](../../README.ja.md) に戻る
+
+# Antigravity 認証・統合ガイド
+
+## 概要
+
+**Antigravity**（Google Cloud Code Assist）は、Google が提供する AI モデルプロバイダーで、Google のクラウドインフラストラクチャを通じて Claude Opus 4.6 や Gemini などのモデルへのアクセスを提供します。本ドキュメントでは、認証の仕組み、モデルの取得方法、PicoClaw での新しいプロバイダーの実装方法について完全なガイドを提供します。
+
+---
+
+## 目次
+
+1. [認証フロー](#認証フロー)
+2. [OAuth 実装の詳細](#oauth-実装の詳細)
+3. [トークン管理](#トークン管理)
+4. [モデルリストの取得](#モデルリストの取得)
+5. [使用量トラッキング](#使用量トラッキング)
+6. [プロバイダープラグイン構造](#プロバイダープラグイン構造)
+7. [統合要件](#統合要件)
+8. [API エンドポイント](#api-エンドポイント)
+9. [設定](#設定)
+10. [PicoClaw での新しいプロバイダーの作成](#picoclaw-での新しいプロバイダーの作成)
+
+---
+
+## 認証フロー
+
+### 1. PKCE 付き OAuth 2.0
+
+Antigravity はセキュアな認証のために **OAuth 2.0 with PKCE（Proof Key for Code Exchange）** を使用します：
+
+```
+┌─────────────┐                                    ┌─────────────────┐
+│   Client    │ ───(1) Generate PKCE Pair────────> │                 │
+│             │ ───(2) Open Auth URL─────────────> │  Google OAuth   │
+│             │                                    │    Server       │
+│             │ <──(3) Redirect with Code───────── │                 │
+│             │                                    └─────────────────┘
+│             │ ───(4) Exchange Code for Tokens──> │   Token URL     │
+│             │                                    │                 │
+│             │ <──(5) Access + Refresh Tokens──── │                 │
+└─────────────┘                                    └─────────────────┘
+```
+
+### 2. 詳細手順
+
+#### ステップ 1：PKCE パラメータの生成
+```typescript
+function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = randomBytes(32).toString("hex");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+```
+
+#### ステップ 2：認可 URL の構築
+```typescript
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const REDIRECT_URI = "http://localhost:51121/oauth-callback";
+
+function buildAuthUrl(params: { challenge: string; state: string }): string {
+  const url = new URL(AUTH_URL);
+  url.searchParams.set("client_id", CLIENT_ID);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("redirect_uri", REDIRECT_URI);
+  url.searchParams.set("scope", SCOPES.join(" "));
+  url.searchParams.set("code_challenge", params.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", params.state);
+  url.searchParams.set("access_type", "offline");
+  url.searchParams.set("prompt", "consent");
+  return url.toString();
+}
+```
+
+**必要なスコープ：**
+```typescript
+const SCOPES = [
+  "https://www.googleapis.com/auth/cloud-platform",
+  "https://www.googleapis.com/auth/userinfo.email",
+  "https://www.googleapis.com/auth/userinfo.profile",
+  "https://www.googleapis.com/auth/cclog",
+  "https://www.googleapis.com/auth/experimentsandconfigs",
+];
+```
+
+#### ステップ 3：OAuth コールバックの処理
+
+**自動モード（ローカル開発）：**
+- ポート 51121 でローカル HTTP サーバーを起動
+- Google からのリダイレクトを待機
+- クエリパラメータから認可コードを抽出
+
+**手動モード（リモート/ヘッドレス）：**
+- ユーザーに認可 URL を表示
+- ユーザーがブラウザで認証を完了
+- ユーザーが完全なリダイレクト URL をターミナルに貼り付け
+- 貼り付けられた URL からコードを解析
+
+#### ステップ 4：コードをトークンに交換
+```typescript
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+async function exchangeCode(params: {
+  code: string;
+  verifier: string;
+}): Promise<{ access: string; refresh: string; expires: number }> {
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      code: params.code,
+      grant_type: "authorization_code",
+      redirect_uri: REDIRECT_URI,
+      code_verifier: params.verifier,
+    }),
+  });
+
+  const data = await response.json();
+  
+  return {
+    access: data.access_token,
+    refresh: data.refresh_token,
+    expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, // 5 min buffer
+  };
+}
+```
+
+#### ステップ 5：追加のユーザーデータの取得
+
+**ユーザーメール：**
+```typescript
+async function fetchUserEmail(accessToken: string): Promise<string | undefined> {
+  const response = await fetch(
+    "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+    { headers: { Authorization: `Bearer ${accessToken}` } }
+  );
+  const data = await response.json();
+  return data.email;
+}
+```
+
+**プロジェクト ID（API 呼び出しに必須）：**
+```typescript
+async function fetchProjectId(accessToken: string): Promise<string> {
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "google-api-nodejs-client/9.15.1",
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+    "Client-Metadata": JSON.stringify({
+      ideType: "IDE_UNSPECIFIED",
+      platform: "PLATFORM_UNSPECIFIED",
+      pluginType: "GEMINI",
+    }),
+  };
+
+  const response = await fetch(
+    "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        metadata: {
+          ideType: "IDE_UNSPECIFIED",
+          platform: "PLATFORM_UNSPECIFIED",
+          pluginType: "GEMINI",
+        },
+      }),
+    }
+  );
+
+  const data = await response.json();
+  return data.cloudaicompanionProject || "rising-fact-p41fc"; // デフォルトのフォールバック
+}
+```
+
+---
+
+## OAuth 実装の詳細
+
+### クライアント認証情報
+
+**重要：** これらは pi-ai との同期のためにソースコード内で base64 エンコードされています：
+
+```typescript
+const decode = (s: string) => Buffer.from(s, "base64").toString();
+
+const CLIENT_ID = decode(
+  "MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ=="
+);
+const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
+```
+
+### OAuth フローモード
+
+1. **自動フロー**（ブラウザのあるローカルマシン）：
+   - ブラウザを自動的に開く
+   - ローカルコールバックサーバーがリダイレクトをキャプチャ
+   - 初回認証後はユーザー操作不要
+
+2. **手動フロー**（リモート/ヘッドレス/WSL2）：
+   - 手動コピー＆ペースト用の URL を表示
+   - ユーザーが外部ブラウザで認証を完了
+   - ユーザーが完全なリダイレクト URL を貼り付け
+
+```typescript
+function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+  return isRemote || isWSL2Sync();
+}
+```
+
+---
+
+## トークン管理
+
+### 認証プロファイル構造
+
+```typescript
+type OAuthCredential = {
+  type: "oauth";
+  provider: "google-antigravity";
+  access: string;           // アクセストークン
+  refresh: string;          // リフレッシュトークン
+  expires: number;          // 有効期限タイムスタンプ（エポックからのミリ秒）
+  email?: string;           // ユーザーメール
+  projectId?: string;       // Google Cloud プロジェクト ID
+};
+```
+
+### トークンの更新
+
+認証情報にはリフレッシュトークンが含まれており、現在のアクセストークンが期限切れになった際に新しいアクセストークンを取得するために使用できます。有効期限は競合状態を防ぐために 5 分のバッファを設けています。
+
+---
+
+## モデルリストの取得
+
+### 利用可能なモデルの取得
+
+```typescript
+const BASE_URL = "https://cloudcode-pa.googleapis.com";
+
+async function fetchAvailableModels(
+  accessToken: string,
+  projectId: string
+): Promise<Model[]> {
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "antigravity",
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+  };
+
+  const response = await fetch(
+    `${BASE_URL}/v1internal:fetchAvailableModels`,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ project: projectId }),
+    }
+  );
+
+  const data = await response.json();
+  
+  // クォータ情報付きのモデルを返す
+  return Object.entries(data.models).map(([modelId, modelInfo]) => ({
+    id: modelId,
+    displayName: modelInfo.displayName,
+    quotaInfo: {
+      remainingFraction: modelInfo.quotaInfo?.remainingFraction,
+      resetTime: modelInfo.quotaInfo?.resetTime,
+      isExhausted: modelInfo.quotaInfo?.isExhausted,
+    },
+  }));
+}
+```
+
+### レスポンス形式
+
+```typescript
+type FetchAvailableModelsResponse = {
+  models?: Record<string, {
+    displayName?: string;
+    quotaInfo?: {
+      remainingFraction?: number | string;
+      resetTime?: string;      // ISO 8601 タイムスタンプ
+      isExhausted?: boolean;
+    };
+  }>;
+};
+```
+
+---
+
+## 使用量トラッキング
+
+### 使用量データの取得
+
+```typescript
+export async function fetchAntigravityUsage(
+  token: string,
+  timeoutMs: number
+): Promise<ProviderUsageSnapshot> {
+  // 1. クレジットとプラン情報を取得
+  const loadCodeAssistRes = await fetch(
+    `${BASE_URL}/v1internal:loadCodeAssist`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        metadata: {
+          ideType: "ANTIGRAVITY",
+          platform: "PLATFORM_UNSPECIFIED",
+          pluginType: "GEMINI",
+        },
+      }),
+    }
+  );
+
+  // クレジット情報を抽出
+  const { availablePromptCredits, planInfo, currentTier } = data;
+  
+  // 2. モデルクォータを取得
+  const modelsRes = await fetch(
+    `${BASE_URL}/v1internal:fetchAvailableModels`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ project: projectId }),
+    }
+  );
+
+  // 使用量ウィンドウを構築
+  return {
+    provider: "google-antigravity",
+    displayName: "Google Antigravity",
+    windows: [
+      { label: "Credits", usedPercent: calculateUsedPercent(available, monthly) },
+      // 個別モデルクォータ...
+    ],
+    plan: currentTier?.name || planType,
+  };
+}
+```
+
+### 使用量レスポンス構造
+
+```typescript
+type ProviderUsageSnapshot = {
+  provider: "google-antigravity";
+  displayName: string;
+  windows: UsageWindow[];
+  plan?: string;
+  error?: string;
+};
+
+type UsageWindow = {
+  label: string;           // "Credits" またはモデル ID
+  usedPercent: number;     // 0-100
+  resetAt?: number;        // クォータがリセットされるタイムスタンプ
+};
+```
+
+---
+
+## プロバイダープラグイン構造
+
+### プラグイン定義
+
+```typescript
+const antigravityPlugin = {
+  id: "google-antigravity-auth",
+  name: "Google Antigravity Auth",
+  description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
+  configSchema: emptyPluginConfigSchema(),
+  
+  register(api: PicoClawPluginApi) {
+    api.registerProvider({
+      id: "google-antigravity",
+      label: "Google Antigravity",
+      docsPath: "/providers/models",
+      aliases: ["antigravity"],
+      
+      auth: [
+        {
+          id: "oauth",
+          label: "Google OAuth",
+          hint: "PKCE + localhost callback",
+          kind: "oauth",
+          run: async (ctx: ProviderAuthContext) => {
+            // OAuth 実装はここに記述
+          },
+        },
+      ],
+    });
+  },
+};
+```
+
+### ProviderAuthContext
+
+```typescript
+type ProviderAuthContext = {
+  config: PicoClawConfig;
+  agentDir?: string;
+  workspaceDir?: string;
+  prompter: WizardPrompter;      // UI プロンプト/通知
+  runtime: RuntimeEnv;           // ログなど
+  isRemote: boolean;             // リモート実行かどうか
+  openUrl: (url: string) => Promise<void>;  // ブラウザオープナー
+  oauth: {
+    createVpsAwareHandlers: Function;
+  };
+};
+```
+
+### ProviderAuthResult
+
+```typescript
+type ProviderAuthResult = {
+  profiles: Array<{
+    profileId: string;
+    credential: AuthProfileCredential;
+  }>;
+  configPatch?: Partial<PicoClawConfig>;
+  defaultModel?: string;
+  notes?: string[];
+};
+```
+
+---
+
+## 統合要件
+
+### 1. 必要な環境/依存関係
+
+- Go ≥ 1.25
+- PicoClaw コードベース（`pkg/providers/` および `pkg/auth/`）
+- `crypto` および `net/http` 標準ライブラリパッケージ
+
+### 2. API 呼び出しに必要なヘッダー
+
+```typescript
+const REQUIRED_HEADERS = {
+  "Authorization": `Bearer ${accessToken}`,
+  "Content-Type": "application/json",
+  "User-Agent": "antigravity",  // または "google-api-nodejs-client/9.15.1"
+  "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+};
+
+// loadCodeAssist 呼び出しには以下も含める：
+const CLIENT_METADATA = {
+  ideType: "ANTIGRAVITY",  // または "IDE_UNSPECIFIED"
+  platform: "PLATFORM_UNSPECIFIED",
+  pluginType: "GEMINI",
+};
+```
+
+### 3. モデルスキーマのサニタイズ
+
+Antigravity は Gemini 互換モデルを使用するため、ツールスキーマのサニタイズが必要です：
+
+```typescript
+const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
+  "patternProperties",
+  "additionalProperties",
+  "$schema",
+  "$id",
+  "$ref",
+  "$defs",
+  "definitions",
+  "examples",
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+  "multipleOf",
+  "pattern",
+  "format",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minProperties",
+  "maxProperties",
+]);
+
+// 送信前にスキーマをクリーンアップ
+function cleanToolSchemaForGemini(schema: Record<string, unknown>): unknown {
+  // サポートされていないキーワードを削除
+  // トップレベルに type: "object" があることを確認
+  // anyOf/oneOf ユニオンをフラット化
+}
+```
+
+### 4. 思考ブロックの処理（Claude モデル）
+
+Antigravity の Claude モデルでは、思考ブロックに特別な処理が必要です：
+
+```typescript
+const ANTIGRAVITY_SIGNATURE_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+export function sanitizeAntigravityThinkingBlocks(
+  messages: AgentMessage[]
+): AgentMessage[] {
+  // 思考シグネチャを検証
+  // シグネチャフィールドを正規化
+  // 署名されていない思考ブロックを破棄
+}
+```
+
+---
+
+## API エンドポイント
+
+### 認証エンドポイント
+
+| エンドポイント | メソッド | 用途 |
+|---------------|---------|------|
+| `https://accounts.google.com/o/oauth2/v2/auth` | GET | OAuth 認可 |
+| `https://oauth2.googleapis.com/token` | POST | トークン交換 |
+| `https://www.googleapis.com/oauth2/v1/userinfo` | GET | ユーザー情報（メール） |
+
+### Cloud Code Assist エンドポイント
+
+| エンドポイント | メソッド | 用途 |
+|---------------|---------|------|
+| `https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` | POST | プロジェクト情報、クレジット、プランの読み込み |
+| `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` | POST | クォータ付き利用可能モデルの一覧 |
+| `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse` | POST | チャットストリーミングエンドポイント |
+
+**API リクエスト形式（チャット）：**
+`v1internal:streamGenerateContent` エンドポイントは、標準の Gemini リクエストをラップするエンベロープ形式を期待します：
+
+```json
+{
+  "project": "your-project-id",
+  "model": "model-id",
+  "request": {
+    "contents": [...],
+    "systemInstruction": {...},
+    "generationConfig": {...},
+    "tools": [...]
+  },
+  "requestType": "agent",
+  "userAgent": "antigravity",
+  "requestId": "agent-timestamp-random"
+}
+```
+
+**API レスポンス形式（SSE）：**
+各 SSE メッセージ（`data: {...}`）は `response` フィールドでラップされます：
+
+```json
+{
+  "response": {
+    "candidates": [...],
+    "usageMetadata": {...},
+    "modelVersion": "...",
+    "responseId": "..."
+  },
+  "traceId": "...",
+  "metadata": {}
+}
+```
+
+---
+
+## 設定
+
+### config.json の設定
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gemini-flash",
+      "model": "antigravity/gemini-3-flash",
+      "auth_method": "oauth"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "gemini-flash"
+    }
+  }
+}
+```
+
+### 認証プロファイルの保存
+
+認証プロファイルは `~/.picoclaw/auth.json` に保存されます：
+
+```json
+{
+  "credentials": {
+    "google-antigravity": {
+      "access_token": "ya29...",
+      "refresh_token": "1//...",
+      "expires_at": "2026-01-01T00:00:00Z",
+      "provider": "google-antigravity",
+      "auth_method": "oauth",
+      "email": "user@example.com",
+      "project_id": "my-project-id"
+    }
+  }
+}
+```
+
+---
+
+## PicoClaw での新しいプロバイダーの作成
+
+PicoClaw のプロバイダーは `pkg/providers/` 配下の Go パッケージとして実装されます。新しいプロバイダーを追加するには：
+
+### ステップバイステップの実装
+
+#### 1. プロバイダーファイルの作成
+
+`pkg/providers/` に新しい Go ファイルを作成します：
+
+```
+pkg/providers/
+└── your_provider.go
+```
+
+#### 2. Provider インターフェースの実装
+
+プロバイダーは `pkg/providers/types.go` で定義された `Provider` インターフェースを実装する必要があります：
+
+```go
+package providers
+
+type YourProvider struct {
+    apiKey  string
+    apiBase string
+}
+
+func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
+    if apiBase == "" {
+        apiBase = "https://api.your-provider.com/v1"
+    }
+    return &YourProvider{apiKey: apiKey, apiBase: apiBase}
+}
+
+func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
+    // ストリーミング付きチャット補完を実装
+}
+```
+
+#### 3. ファクトリーへの登録
+
+`pkg/providers/factory.go` のプロトコルスイッチにプロバイダーを追加します：
+
+```go
+case "your-provider":
+    return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
+```
+
+#### 4. デフォルト設定の追加（オプション）
+
+`pkg/config/defaults.go` にデフォルトエントリを追加します：
+
+```go
+{
+    ModelName: "your-model",
+    Model:     "your-provider/model-name",
+    APIKey:    "",
+},
+```
+
+#### 5. 認証サポートの追加（オプション）
+
+プロバイダーが OAuth や特別な認証を必要とする場合、`cmd/picoclaw/internal/auth/helpers.go` にケースを追加します：
+
+```go
+case "your-provider":
+    authLoginYourProvider()
+```
+
+#### 6. `config.json` での設定
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "your-model",
+      "model": "your-provider/model-name",
+      "api_key": "your-api-key",
+      "api_base": "https://api.your-provider.com/v1"
+    }
+  ]
+}
+```
+
+---
+
+## 実装のテスト
+
+### CLI コマンド
+
+```bash
+# プロバイダーで認証
+picoclaw auth login --provider your-provider
+
+# モデルの一覧表示（Antigravity 用）
+picoclaw auth models
+
+# ゲートウェイの起動
+picoclaw gateway
+
+# 特定のモデルでエージェントを実行
+picoclaw agent -m "Hello" --model your-model
+```
+
+### テスト用環境変数
+
+```bash
+# デフォルトモデルの上書き
+export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
+
+# プロバイダー設定の上書き
+export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
+```
+
+---
+
+## 参考資料
+
+- **ソースファイル：**
+  - `pkg/providers/antigravity_provider.go` - Antigravity プロバイダー実装
+  - `pkg/auth/oauth.go` - OAuth フロー実装
+  - `pkg/auth/store.go` - 認証情報ストレージ（`~/.picoclaw/auth.json`）
+  - `pkg/providers/factory.go` - プロバイダーファクトリーとプロトコルルーティング
+  - `pkg/providers/types.go` - プロバイダーインターフェース定義
+  - `cmd/picoclaw/internal/auth/helpers.go` - 認証 CLI コマンド
+
+- **ドキュメント：**
+  - `docs/ANTIGRAVITY_USAGE.md` - Antigravity 使用ガイド
+  - `docs/migration/model-list-migration.md` - 移行ガイド
+
+---
+
+## 注意事項
+
+1. **Google Cloud プロジェクト：** Antigravity は Google Cloud プロジェクトで Gemini for Google Cloud が有効になっている必要があります
+2. **クォータ：** Google Cloud プロジェクトのクォータを使用します（個別の課金ではありません）
+3. **モデルアクセス：** 利用可能なモデルは Google Cloud プロジェクトの設定に依存します
+4. **思考ブロック：** Antigravity 経由の Claude モデルは、署名付き思考ブロックの特別な処理が必要です
+5. **スキーマサニタイズ：** ツールスキーマはサポートされていない JSON Schema キーワードを削除するためにサニタイズが必要です
+
+---
+
+---
+
+## 一般的なエラー処理
+
+### 1. レート制限（HTTP 429）
+
+プロジェクト/モデルのクォータが枯渇すると、Antigravity は 429 エラーを返します。エラーレスポンスには通常、`details` フィールドに `quotaResetDelay` が含まれます。
+
+**429 エラーの例：**
+```json
+{
+  "error": {
+    "code": 429,
+    "message": "You have exhausted your capacity on this model. Your quota will reset after 4h30m28s.",
+    "status": "RESOURCE_EXHAUSTED",
+    "details": [
+      {
+        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+        "metadata": {
+          "quotaResetDelay": "4h30m28.060903746s"
+        }
+      }
+    ]
+  }
+}
+```
+
+### 2. 空のレスポンス（制限付きモデル）
+
+一部のモデルは利用可能モデルリストに表示されますが、空のレスポンスを返す場合があります（200 OK だが SSE ストリームが空）。これは通常、現在のプロジェクトに使用権限がないプレビュー版または制限付きモデルで発生します。
+
+**対処法：** 空のレスポンスをエラーとして扱い、そのモデルがプロジェクトに対して制限されているか無効である可能性があることをユーザーに通知します。
+
+---
+
+## トラブルシューティング
+
+### "Token expired"（トークン期限切れ）
+- OAuth トークンを更新：`picoclaw auth login --provider antigravity`
+
+### "Gemini for Google Cloud is not enabled"（Gemini for Google Cloud が有効になっていない）
+- Google Cloud Console で API を有効にしてください
+
+### "Project not found"（プロジェクトが見つからない）
+- Google Cloud プロジェクトで必要な API が有効になっていることを確認してください
+- 認証中にプロジェクト ID が正しく取得されているか確認してください
+
+### モデルがリストに表示されない
+- OAuth 認証が正常に完了したことを確認してください
+- 認証プロファイルストレージを確認：`~/.picoclaw/auth.json`
+- `picoclaw auth login --provider antigravity` を再実行してください
diff --git a/docs/ja/ANTIGRAVITY_USAGE.md b/docs/ja/ANTIGRAVITY_USAGE.md
new file mode 100644
index 000000000..c044c1970
--- /dev/null
+++ b/docs/ja/ANTIGRAVITY_USAGE.md
@@ -0,0 +1,72 @@
+> [README](../../README.ja.md) に戻る
+
+# PicoClaw で Antigravity プロバイダーを使用する
+
+このガイドでは、PicoClaw で **Antigravity**（Google Cloud Code Assist）プロバイダーをセットアップして使用する方法を説明します。
+
+## 前提条件
+
+1.  Google アカウント。
+2.  Google Cloud Code Assist が有効であること（通常「Gemini for Google Cloud」のオンボーディングから利用可能）。
+
+## 1. 認証
+
+Antigravity で認証するには、以下のコマンドを実行します：
+
+```bash
+picoclaw auth login --provider antigravity
+```
+
+### 手動認証（ヘッドレス/VPS）
+サーバー（Coolify/Docker）上で実行しており、`localhost` にアクセスできない場合は、以下の手順に従ってください：
+1.  上記のコマンドを実行します。
+2.  表示された URL をコピーし、ローカルブラウザで開きます。
+3.  ログインを完了します。
+4.  ブラウザが `localhost:51121` URL にリダイレクトされます（ページは読み込めません）。
+5.  **ブラウザのアドレスバーからその最終 URL をコピーします**。
+6.  **PicoClaw が待機しているターミナルにそれを貼り付けます**。
+
+PicoClaw が自動的に認証コードを抽出し、プロセスを完了します。
+
+## 2. モデルの管理
+
+### 利用可能なモデルの一覧
+プロジェクトがアクセスできるモデルとそのクォータを確認するには：
+
+```bash
+picoclaw auth models
+```
+
+### モデルの切り替え
+`~/.picoclaw/config.json` でデフォルトモデルを変更するか、CLI でオーバーライドできます：
+
+```bash
+# 単一コマンドでオーバーライド
+picoclaw agent -m "Hello" --model claude-opus-4-6-thinking
+```
+
+## 3. 実際の使用方法（Coolify/Docker）
+
+Coolify または Docker でデプロイしている場合、以下の手順でテストしてください：
+
+1.  **環境変数**：
+    *   `PICOCLAW_AGENTS_DEFAULTS_MODEL=gemini-flash`
+2.  **認証の永続化**：
+    ローカルでログイン済みの場合、認証情報をサーバーにコピーできます：
+    ```bash
+    scp ~/.picoclaw/auth.json user@your-server:~/.picoclaw/
+    ```
+    *または*、ターミナルアクセスがある場合、サーバー上で `auth login` コマンドを一度実行してください。
+
+## 4. トラブルシューティング
+
+*   **空のレスポンス**：モデルが空の応答を返す場合、プロジェクトで制限されている可能性があります。`gemini-3-flash` または `claude-opus-4-6-thinking` を試してください。
+*   **429 レート制限**：Antigravity には厳格なクォータがあります。制限に達した場合、PicoClaw はエラーメッセージに「リセット時間」を表示します。
+*   **404 Not Found**：`picoclaw auth models` リストのモデル ID を使用していることを確認してください。フルパスではなく、短い ID（例：`gemini-3-flash`）を使用してください。
+
+## 5. 動作確認済みモデルのまとめ
+
+テストに基づき、以下のモデルが最も信頼性が高いです：
+*   `gemini-3-flash`（高速、高可用性）
+*   `gemini-2.5-flash-lite`（軽量）
+*   `claude-opus-4-6-thinking`（高性能、推論機能を含む）
diff --git a/docs/ja/chat-apps.md b/docs/ja/chat-apps.md
new file mode 100644
index 000000000..341dc4aba
--- /dev/null
+++ b/docs/ja/chat-apps.md
@@ -0,0 +1,658 @@
+# 💬 チャットアプリ設定
+
+> [README](../../README.ja.md) に戻る
+
+## 💬 チャットアプリ連携
+
+PicoClaw は複数のチャットプラットフォームをサポートしており、Agent をどこにでも接続できます。
+
+> **注意**: すべての Webhook ベースのチャネル（LINE、WeCom など）は、共有 Gateway HTTP サーバー（`gateway.host`:`gateway.port`、デフォルト `127.0.0.1:18790`）上で提供されます。チャネルごとにポートを設定する必要はありません。注意：飛書（Feishu）は WebSocket/SDK モードを使用し、共有 HTTP Webhook サーバーは使用しません。
+
+### チャネル一覧
+
+| チャネル             | セットアップ難易度 | 特徴                                      | ドキュメント                                                                                                    |
+| -------------------- | ------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **Telegram**         | ⭐ 簡単            | 推奨、音声テキスト変換対応、ロングポーリング（公開 IP 不要） | [ドキュメント](../channels/telegram/README.ja.md)                                                             |
+| **Discord**          | ⭐ 簡単            | Socket Mode、グループ/DM 対応、Bot エコシステム充実 | [ドキュメント](../channels/discord/README.ja.md)                                                              |
+| **WhatsApp**         | ⭐ 簡単            | ネイティブ (QR スキャン) または Bridge URL | [ドキュメント](#whatsapp)                                                             |
+| **微信 (Weixin)**    | ⭐ 簡単            | ネイティブ QR スキャン（Tencent iLink API）| [ドキュメント](#weixin)                                                               |
+| **Slack**            | ⭐ 簡単            | **Socket Mode** (公開 IP 不要)、エンタープライズ対応 | [ドキュメント](../channels/slack/README.ja.md)                                                                |
+| **Matrix**           | ⭐⭐ 中程度        | フェデレーションプロトコル、セルフホスト対応 | [ドキュメント](../channels/matrix/README.ja.md)                                                              |
+| **QQ**               | ⭐⭐ 中程度        | 公式ボット API、中国コミュニティ向け       | [ドキュメント](../channels/qq/README.ja.md)                                                                   |
+| **DingTalk**         | ⭐⭐ 中程度        | Stream モード（公開 IP 不要）、企業向け    | [ドキュメント](../channels/dingtalk/README.ja.md)                                                             |
+| **LINE**             | ⭐⭐⭐ やや難      | HTTPS Webhook が必要                       | [ドキュメント](../channels/line/README.ja.md)                                                                 |
+| **WeCom (企業微信)** | ⭐⭐⭐ やや難      | グループ Bot (Webhook)、カスタムアプリ (API)、AI Bot 対応 | [Bot](../channels/wecom/wecom_bot/README.ja.md) / [App](../channels/wecom/wecom_app/README.ja.md) / [AI Bot](../channels/wecom/wecom_aibot/README.ja.md) |
+| **Feishu (飛書)**    | ⭐⭐⭐ やや難      | エンタープライズコラボレーション、機能豊富 | [ドキュメント](../channels/feishu/README.ja.md)                                                               |
+| **IRC**              | ⭐⭐ 中程度        | サーバー + TLS 設定                        | [ドキュメント](#irc) |
+| **OneBot**           | ⭐⭐ 中程度        | NapCat/Go-CQHTTP 互換、コミュニティエコシステム充実 | [ドキュメント](../channels/onebot/README.ja.md)                                                               |
+| **MaixCam**          | ⭐ 簡単            | Sipeed AI カメラハードウェア統合チャネル   | [ドキュメント](../channels/maixcam/README.ja.md)                                                              |
+| **Pico**             | ⭐ 簡単            | PicoClaw ネイティブプロトコルチャネル     |                                                                                                               |
+
+---
+
+<a id="telegram"></a>
+<details>
+<summary><b>Telegram</b>（推奨）</summary>
+
+**1. Bot を作成**
+
+* Telegram を開き、`@BotFather` を検索
+* `/newbot` を送信し、プロンプトに従う
+* Token をコピー
+
+**2. 設定**
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+> Telegram の `@userinfobot` から User ID を取得できます。
+
+**3. 実行**
+
+```bash
+picoclaw gateway
+```
+
+**4. Telegram コマンドメニュー（起動時に自動登録）**
+
+PicoClaw は統一されたコマンド定義を使用します。起動時に Telegram がサポートするコマンド（例: `/start`、`/help`、`/show`、`/list`）を Bot コマンドメニューに自動登録し、メニュー表示と実際の動作を一致させます。
+Telegram 側はコマンドメニュー登録機能を保持し、汎用コマンドの実行は Agent Loop 内の commands executor で統一的に処理されます。
+
+ネットワークや API の一時的なエラーで登録に失敗しても、チャネルの起動はブロックされません。システムがバックグラウンドで自動リトライします。
+
+</details>
+
+<a id="discord"></a>
+<details>
+<summary><b>Discord</b></summary>
+
+**1. Bot を作成**
+
+* <https://discord.com/developers/applications> にアクセス
+* アプリケーションを作成 → Bot → Bot を追加
+* Bot Token をコピー
+
+**2. Intents を有効化**
+
+* Bot 設定で **MESSAGE CONTENT INTENT** を有効化
+* （オプション）メンバーデータに基づくホワイトリストが必要な場合は **SERVER MEMBERS INTENT** を有効化
+
+**3. User ID を取得**
+
+* Discord 設定 → 詳細設定 → **開発者モード** を有効化
+* アバターを右クリック → **ユーザー ID をコピー**
+
+**4. 設定**
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**5. Bot を招待**
+
+* OAuth2 → URL Generator
+* Scopes: `bot`
+* Bot Permissions: `Send Messages`, `Read Message History`
+* 生成された招待リンクを開き、Bot をサーバーに追加
+
+**オプション：グループトリガーモード**
+
+デフォルトでは Bot はサーバーチャネル内のすべてのメッセージに応答します。@メンション時のみ応答するには：
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "mention_only": true }
+    }
+  }
+}
+```
+
+キーワードプレフィックスでトリガーすることもできます（例: `!bot`）：
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "prefixes": ["!bot"] }
+    }
+  }
+}
+```
+
+**6. 実行**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="whatsapp"></a>
+<details>
+<summary><b>WhatsApp</b>（ネイティブ whatsmeow）</summary>
+
+PicoClaw は 2 つの WhatsApp 接続方式をサポートしています：
+
+- **ネイティブ（推奨）：** プロセス内で [whatsmeow](https://github.com/tulir/whatsmeow) を使用。独立した Bridge は不要です。`"use_native": true` に設定し、`bridge_url` を空にします。初回実行時に WhatsApp で QR コードをスキャン（リンクデバイス）。セッションはワークスペース配下（例: `workspace/whatsapp/`）に保存されます。ネイティブチャネルは**オプション**ビルドで、`-tags whatsapp_native` でコンパイルします（例: `make build-whatsapp-native` または `go build -tags whatsapp_native ./cmd/...`）。
+- **Bridge：** 外部 WebSocket Bridge に接続。`bridge_url`（例: `ws://localhost:3001`）を設定し、`use_native` を false のままにします。
+
+**設定（ネイティブ）**
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "use_native": true,
+      "session_store_path": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+`session_store_path` が空の場合、セッションは `<workspace>/whatsapp/` に保存されます。`picoclaw gateway` を実行し、初回実行時にターミナルに表示される QR コードをスキャンしてください（WhatsApp → リンクデバイス）。
+
+</details>
+
+<a id="weixin"></a>
+<details>
+<summary><b>微信 (Weixin)</b></summary>
+
+PicoClaw は Tencent iLink 公式 API を使用して WeChat 個人アカウントへの接続をサポートしています。
+
+**1. ログイン**
+
+インタラクティブな QR ログインフローを実行します：
+```bash
+picoclaw auth weixin
+```
+WeChat モバイルアプリで表示された QR コードをスキャンしてください。ログイン成功後、トークンが設定ファイルに保存されます。
+
+**2. 設定**
+
+（オプション）ボットと会話できるユーザーを制限するために `allow_from` に WeChat ユーザー ID を追加します：
+```json
+{
+  "channels": {
+    "weixin": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**3. 実行**
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="matrix"></a>
+<details>
+<summary><b>Matrix</b></summary>
+
+**1. Bot アカウントを準備**
+
+* お好みの homeserver（例: `https://matrix.org` またはセルフホスト）を使用
+* Bot ユーザーを作成し、access token を取得
+
+**2. 設定**
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. 実行**
+
+```bash
+picoclaw gateway
+```
+
+すべてのオプション（`device_id`、`join_on_invite`、`group_trigger`、`placeholder`、`reasoning_channel_id`）については [Matrix チャネル設定ガイド](../channels/matrix/README.md) を参照してください。
+
+</details>
+
+<a id="qq"></a>
+<details>
+<summary><b>QQ</b></summary>
+
+**クイックセットアップ（推奨）**
+
+QQ 開放プラットフォームでは、OpenClaw 互換ボットのワンクリックセットアップページが提供されています：
+
+1. [QQ Bot クイックスタート](https://q.qq.com/qqbot/openclaw/index.html) を開き、QR コードをスキャンしてログイン
+2. ボットが自動的に作成されます — **App ID** と **App Secret** をコピー
+3. PicoClaw を設定：
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+4. `picoclaw gateway` を実行し、QQ を開いてボットとチャット
+
+> App Secret は一度しか表示されません。すぐに保存してください — 再度表示するとリセットされます。
+>
+> クイックセットアップで作成されたボットは、最初は作成者のみが使用でき、グループチャットには対応していません。グループアクセスを有効にするには、[QQ 開放プラットフォーム](https://q.qq.com/) でサンドボックスモードを設定してください。
+
+**手動セットアップ**
+
+ボットを手動で作成する場合：
+
+* [QQ 開放プラットフォーム](https://q.qq.com/) にログインして開発者登録
+* QQ ボットを作成 — アバターと名前をカスタマイズ
+* ボット設定から **App ID** と **App Secret** をコピー
+* 上記の設定を行い、`picoclaw gateway` を実行
+
+</details>
+
+<a id="slack"></a>
+<details>
+<summary><b>Slack</b></summary>
+
+**1. Slack App を作成**
+
+* [Slack API](https://api.slack.com/apps) にアクセスして新しいアプリを作成
+* **OAuth & Permissions** で Bot スコープを追加：`chat:write`、`app_mentions:read`、`im:history`、`im:read`、`im:write`
+* アプリをワークスペースにインストール
+* **Bot Token**（`xoxb-...`）と **App-Level Token**（`xapp-...`、Socket Mode を有効にして取得）をコピー
+
+**2. 設定**
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "bot_token": "xoxb-YOUR-BOT-TOKEN",
+      "app_token": "xapp-YOUR-APP-TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. 実行**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="irc"></a>
+<details>
+<summary><b>IRC</b></summary>
+
+**1. 設定**
+
+```json
+{
+  "channels": {
+    "irc": {
+      "enabled": true,
+      "server": "irc.libera.chat:6697",
+      "tls": true,
+      "nick": "picoclaw-bot",
+      "channels": ["#your-channel"],
+      "password": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+オプション：NickServ 認証用の `nickserv_password`、SASL 認証用の `sasl_user`/`sasl_password`。
+
+**2. 実行**
+
+```bash
+picoclaw gateway
+```
+
+ボットは IRC サーバーに接続し、指定されたチャネルに参加します。
+
+</details>
+
+<a id="dingtalk"></a>
+<details>
+<summary><b>DingTalk</b></summary>
+
+**1. Bot を作成**
+
+* [開放プラットフォーム](https://open.dingtalk.com/) にアクセス
+* 内部アプリを作成
+* Client ID と Client Secret をコピー
+
+**2. 設定**
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> `allow_from` を空にするとすべてのユーザーを許可します。DingTalk ユーザー ID を指定してアクセスを制限することもできます。
+
+**3. 実行**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="line"></a>
+<details>
+<summary><b>LINE</b></summary>
+
+**1. LINE 公式アカウントを作成**
+
+- [LINE Developers Console](https://developers.line.biz/) にアクセス
+- Provider を作成 → Messaging API チャネルを作成
+- **Channel Secret** と **Channel Access Token** をコピー
+
+**2. 設定**
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> LINE Webhook は共有 Gateway サーバー（`gateway.host`:`gateway.port`、デフォルト `127.0.0.1:18790`）上で提供されます。
+
+**3. Webhook URL を設定**
+
+LINE は HTTPS Webhook が必要です。リバースプロキシまたはトンネルを使用してください：
+
+```bash
+# 例：ngrok を使用（Gateway デフォルトポートは 18790）
+ngrok http 18790
+```
+
+LINE Developers Console で Webhook URL を `https://your-domain/webhook/line` に設定し、**Use webhook** を有効にしてください。
+
+**4. 実行**
+
+```bash
+picoclaw gateway
+```
+
+> グループチャットでは、Bot は @メンション時のみ応答します。返信は元のメッセージを引用します。
+
+</details>
+
+<a id="feishu"></a>
+<details>
+<summary><b>Feishu (飛書)</b></summary>
+
+PicoClaw は WebSocket/SDK モードで飛書に接続します — 公開 Webhook URL やコールバックサーバーは不要です。
+
+**1. アプリを作成**
+
+* [飛書開放プラットフォーム](https://open.feishu.cn/) にアクセスしてアプリケーションを作成
+* アプリ設定で **ボット** 機能を有効化
+* バージョンを作成してアプリを公開（アプリは公開しないと有効になりません）
+* **App ID**（`cli_` で始まる）と **App Secret** をコピー
+
+**2. 設定**
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "app_id": "cli_xxx",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+オプション：`encrypt_key` と `verification_token` でイベント暗号化（本番環境推奨）。
+
+**3. 実行してチャット**
+
+```bash
+picoclaw gateway
+```
+
+飛書を開き、ボット名を検索してチャットを開始できます。ボットをグループに追加することもできます — `group_trigger.mention_only: true` を設定すると @メンション時のみ応答します。
+
+詳細なオプションについては [飛書チャネル設定ガイド](../channels/feishu/README.ja.md) を参照してください。
+
+</details>
+
+<a id="wecom"></a>
+<details>
+<summary><b>WeCom (企業微信)</b></summary>
+
+PicoClaw は 3 種類の WeCom 統合をサポートしています：
+
+**方式 1: グループ Bot (Bot)** — セットアップ簡単、グループチャット対応
+**方式 2: カスタムアプリ (App)** — より多機能、プロアクティブメッセージング、プライベートチャットのみ
+**方式 3: AI Bot** — 公式 AI Bot、ストリーミング返信、グループ・プライベートチャット対応
+
+詳細なセットアップ手順は [WeCom AI Bot 設定ガイド](../channels/wecom/wecom_aibot/README.ja.md) を参照してください。
+
+**クイックセットアップ — グループ Bot：**
+
+**1. Bot を作成**
+
+* WeCom 管理コンソール → グループチャット → グループ Bot を追加
+* Webhook URL をコピー（形式：`https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`）
+
+**2. 設定**
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+      "webhook_path": "/webhook/wecom",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> WeCom Webhook は共有 Gateway サーバー（`gateway.host`:`gateway.port`、デフォルト `127.0.0.1:18790`）上で提供されます。
+
+**クイックセットアップ — カスタムアプリ：**
+
+**1. アプリを作成**
+
+* WeCom 管理コンソール → アプリ管理 → アプリを作成
+* **AgentId** と **Secret** をコピー
+* 「マイ企業」ページで **CorpID** をコピー
+
+**2. メッセージ受信を設定**
+
+* アプリ詳細で「メッセージ受信」→「API を設定」をクリック
+* URL を `http://your-server:18790/webhook/wecom-app` に設定
+* **Token** と **EncodingAESKey** を生成
+
+**3. 設定**
+
+```json
+{
+  "channels": {
+    "wecom_app": {
+      "enabled": true,
+      "corp_id": "wwxxxxxxxxxxxxxxxx",
+      "corp_secret": "YOUR_CORP_SECRET",
+      "agent_id": 1000002,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**4. 実行**
+
+```bash
+picoclaw gateway
+```
+
+> **注意**: WeCom Webhook コールバックは Gateway ポート（デフォルト 18790）で提供されます。HTTPS にはリバースプロキシを使用してください。
+
+**クイックセットアップ — AI Bot：**
+
+**1. AI Bot を作成**
+
+* WeCom 管理コンソール → アプリ管理 → AI Bot
+* AI Bot 設定でコールバック URL を設定：`http://your-server:18790/webhook/wecom-aibot`
+* **Token** をコピーし、「ランダム生成」をクリックして **EncodingAESKey** を取得
+
+**2. 設定**
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-aibot",
+      "allow_from": [],
+      "welcome_message": "こんにちは！何かお手伝いできますか？",
+      "processing_message": "⏳ Processing, please wait. The results will be sent shortly."
+    }
+  }
+}
+```
+
+**3. 実行**
+
+```bash
+picoclaw gateway
+```
+
+> **注意**: WeCom AI Bot はストリーミングプルプロトコルを使用しており、返信タイムアウトの心配はありません。長時間タスク（30 秒超）は自動的に `response_url` プッシュ配信に切り替わります。
+
+</details>
+
+<a id="onebot"></a>
+<details>
+<summary><b>OneBot（OneBot プロトコル経由の QQ）</b></summary>
+
+OneBot は QQ ボット向けのオープンプロトコルです。PicoClaw は OneBot v11 互換の実装（例：[Lagrange](https://github.com/LagrangeDev/Lagrange.Core)、[NapCat](https://github.com/NapNeko/NapCatQQ)）に WebSocket で接続します。
+
+**1. OneBot 実装をセットアップ**
+
+OneBot v11 互換の QQ ボットフレームワークをインストールして実行します。WebSocket サーバーを有効にしてください。
+
+**2. 設定**
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://127.0.0.1:8080",
+      "access_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| フィールド | 説明 |
+|-------|-------------|
+| `ws_url` | OneBot 実装の WebSocket URL |
+| `access_token` | 認証用アクセストークン（OneBot 側で設定している場合） |
+| `reconnect_interval` | 再接続間隔（秒）（デフォルト：5） |
+
+**3. 実行**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="maixcam"></a>
+<details>
+<summary><b>MaixCam</b></summary>
+
+Sipeed AI カメラハードウェア向けの統合チャネルです。
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true
+    }
+  }
+}
+```
+
+```bash
+picoclaw gateway
+```
+
+</details>
diff --git a/docs/ja/configuration.md b/docs/ja/configuration.md
new file mode 100644
index 000000000..35676809e
--- /dev/null
+++ b/docs/ja/configuration.md
@@ -0,0 +1,364 @@
+# ⚙️ 設定ガイド
+
+> [README](../../README.ja.md) に戻る
+
+## ⚙️ 設定詳細
+
+設定ファイルパス: `~/.picoclaw/config.json`
+
+### 環境変数
+
+環境変数を使用してデフォルトパスを上書きできます。ポータブルインストール、コンテナ化デプロイ、または picoclaw をシステムサービスとして実行する場合に便利です。これらの変数は独立しており、異なるパスを制御します。
+
+| 変数              | 説明                                                                                                                             | デフォルトパス            |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | 設定ファイルのパスを上書きします。picoclaw がどの `config.json` を読み込むかを直接指定し、他のすべての場所を無視します。 | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | picoclaw データのルートディレクトリを上書きします。`workspace` やその他のデータディレクトリのデフォルト場所を変更します。          | `~/.picoclaw`             |
+
+**例：**
+
+```bash
+# 特定の設定ファイルで picoclaw を実行
+# ワークスペースパスはその設定ファイル内から読み込まれます
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# /opt/picoclaw にすべてのデータを保存して picoclaw を実行
+# 設定はデフォルトの ~/.picoclaw/config.json から読み込まれます
+# ワークスペースは /opt/picoclaw/workspace に作成されます
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# 両方を使用して完全にカスタマイズ
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
+### ワークスペースレイアウト
+
+PicoClaw は設定されたワークスペース（デフォルト: `~/.picoclaw/workspace`）にデータを保存します：
+
+```
+~/.picoclaw/workspace/
+├── sessions/          # 会話セッションと履歴
+├── memory/           # 長期記憶 (MEMORY.md)
+├── state/            # 永続化状態 (最後のチャネルなど)
+├── cron/             # スケジュールジョブデータベース
+├── skills/           # カスタムスキル
+├── AGENT.md          # Agent 動作ガイド
+├── HEARTBEAT.md      # 定期タスクプロンプト (30 分ごとにチェック)
+├── IDENTITY.md       # Agent アイデンティティ
+├── SOUL.md           # Agent ソウル/性格
+└── USER.md           # ユーザー設定
+```
+
+> **注意：** `AGENT.md`、`SOUL.md`、`USER.md` および `memory/MEMORY.md` への変更は、ファイル更新時刻（mtime）の追跡により実行時に自動検出されます。これらのファイルを編集した後に **gateway を再起動する必要はありません** — Agent は次のリクエスト時に最新の内容を自動的に読み込みます。
+
+### スキルソース
+
+デフォルトでは、スキルは以下の順序で読み込まれます：
+
+1. `~/.picoclaw/workspace/skills`（ワークスペース）
+2. `~/.picoclaw/skills`（グローバル）
+3. `<ビルド時埋め込みパス>/skills`（ビルトイン）
+
+高度な/テスト用セットアップでは、以下の環境変数でビルトインスキルのルートを上書きできます：
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
+### 統一コマンド実行ポリシー
+
+- 汎用スラッシュコマンドは `pkg/agent/loop.go` 内の `commands.Executor` を通じて統一的に実行されます。
+- チャネルアダプターはローカルで汎用コマンドを消費しなくなりました。受信テキストを bus/agent パスに転送するだけです。Telegram は起動時にサポートするコマンドメニューを自動登録します。
+- 未登録のスラッシュコマンド（例: `/foo`）は通常の LLM 処理にパススルーされます。
+- 登録済みだが現在のチャネルでサポートされていないコマンド（例: WhatsApp での `/show`）は、明示的なユーザー向けエラーを返し、以降の処理を停止します。
+
+### 🔒 セキュリティサンドボックス
+
+PicoClaw はデフォルトでサンドボックス環境で実行されます。Agent は設定されたワークスペース内のファイルアクセスとコマンド実行のみが可能です。
+
+#### デフォルト設定
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "restrict_to_workspace": true
+    }
+  }
+}
+```
+
+| オプション              | デフォルト値            | 説明                                  |
+| ----------------------- | ----------------------- | ------------------------------------- |
+| `workspace`             | `~/.picoclaw/workspace` | Agent の作業ディレクトリ              |
+| `restrict_to_workspace` | `true`                  | ファイル/コマンドアクセスをワークスペース内に制限 |
+
+#### 保護されたツール
+
+`restrict_to_workspace: true` の場合、以下のツールがサンドボックス化されます：
+
+| ツール        | 機能             | 制限                               |
+| ------------- | ---------------- | ---------------------------------- |
+| `read_file`   | ファイル読み取り | ワークスペース内のファイルのみ     |
+| `write_file`  | ファイル書き込み | ワークスペース内のファイルのみ     |
+| `list_dir`    | ディレクトリ一覧 | ワークスペース内のディレクトリのみ |
+| `edit_file`   | ファイル編集     | ワークスペース内のファイルのみ     |
+| `append_file` | ファイル追記     | ワークスペース内のファイルのみ     |
+| `exec`        | コマンド実行     | コマンドパスはワークスペース内必須 |
+
+#### 追加の Exec 保護
+
+`restrict_to_workspace: false` の場合でも、`exec` ツールは以下の危険なコマンドをブロックします：
+
+* `rm -rf`、`del /f`、`rmdir /s` — 一括削除
+* `format`、`mkfs`、`diskpart` — ディスクフォーマット
+* `dd if=` — ディスクイメージング
+* `/dev/sd[a-z]` への書き込み — 直接ディスク書き込み
+* `shutdown`、`reboot`、`poweroff` — システムシャットダウン
+* Fork bomb `:(){ :|:& };:`
+
+### ファイルアクセス制御
+
+| 設定キー | 型 | デフォルト値 | 説明 |
+|----------|------|-------------|------|
+| `tools.allow_read_paths` | string[] | `[]` | ワークスペース外で読み取りを許可する追加パス |
+| `tools.allow_write_paths` | string[] | `[]` | ワークスペース外で書き込みを許可する追加パス |
+
+### Exec セキュリティ設定
+
+| 設定キー | 型 | デフォルト値 | 説明 |
+|----------|------|-------------|------|
+| `tools.exec.allow_remote` | bool | `false` | リモートチャネル（Telegram/Discord など）からの exec ツール実行を許可 |
+| `tools.exec.enable_deny_patterns` | bool | `true` | 危険なコマンドのインターセプトを有効化 |
+| `tools.exec.custom_deny_patterns` | string[] | `[]` | カスタムブロック正規表現パターン |
+| `tools.exec.custom_allow_patterns` | string[] | `[]` | カスタム許可正規表現パターン |
+
+> **セキュリティ注意:** Symlink 保護はデフォルトで有効です。すべてのファイルパスはホワイトリストマッチング前に `filepath.EvalSymlinks` で解決され、シンボリックリンクエスケープ攻撃を防止します。
+
+#### 既知の制限：ビルドツールの子プロセス
+
+exec セキュリティガードは PicoClaw が直接起動するコマンドラインのみを検査します。`make`、`go run`、`cargo`、`npm run`、またはカスタムビルドスクリプトなどの開発ツールが生成する子プロセスは再帰的に検査しません。
+
+つまり、トップレベルのコマンドが初期ガードチェックを通過した後、他のバイナリをコンパイルまたは起動できます。実際には、ビルドスクリプト、Makefile、パッケージスクリプト、生成されたバイナリを、直接のシェルコマンドと同等レベルの実行可能コードとしてレビューする必要があります。
+
+高リスク環境の場合：
+
+* 実行前にビルドスクリプトをレビューしてください。
+* コンパイル・実行ワークフローには承認/手動レビューを優先してください。
+* ビルトインガードより強力な分離が必要な場合は、コンテナまたは VM 内で PicoClaw を実行してください。
+
+#### エラー例
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (path outside working dir)}
+```
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
+```
+
+#### 制限の無効化（セキュリティリスク）
+
+Agent がワークスペース外のパスにアクセスする必要がある場合：
+
+**方法 1: 設定ファイル**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "restrict_to_workspace": false
+    }
+  }
+}
+```
+
+**方法 2: 環境変数**
+
+```bash
+export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
+```
+
+> ⚠️ **警告**: この制限を無効にすると、Agent がシステム上の任意のパスにアクセスできるようになります。管理された環境でのみ慎重に使用してください。
+
+#### セキュリティ境界の一貫性
+
+`restrict_to_workspace` 設定はすべての実行パスで一貫して適用されます：
+
+| 実行パス         | セキュリティ境界             |
+| ---------------- | ---------------------------- |
+| メイン Agent     | `restrict_to_workspace` ✅   |
+| サブ Agent / Spawn | 同じ制限を継承 ✅           |
+| ハートビートタスク | 同じ制限を継承 ✅           |
+
+すべてのパスは同じワークスペース制限を共有しており、サブ Agent やスケジュールタスクを通じてセキュリティ境界を回避することはできません。
+
+### ハートビート（定期タスク）
+
+PicoClaw は定期タスクを自動実行できます。ワークスペースに `HEARTBEAT.md` ファイルを作成してください：
+
+```markdown
+# Periodic Tasks
+
+- Check my email for important messages
+- Review my calendar for upcoming events
+- Check the weather forecast
+```
+
+Agent は 30 分ごと（設定可能）にこのファイルを読み取り、利用可能なツールを使用してタスクを実行します。
+
+#### Spawn を使用した非同期タスク
+
+長時間実行タスク（Web 検索、API 呼び出し）には、`spawn` ツールを使用して**サブ Agent (subagent)** を作成します：
+
+```markdown
+# Periodic Tasks
+
+## Quick Tasks (respond directly)
+
+- Report current time
+
+## Long Tasks (use spawn for async)
+
+- Search the web for AI news and summarize
+- Check email and report important messages
+```
+
+**主な動作：**
+
+| 特性             | 説明                                         |
+| ---------------- | -------------------------------------------- |
+| **spawn**        | 非同期サブ Agent を作成、メインハートビートをブロックしない |
+| **独立コンテキスト** | サブ Agent は独自のコンテキストを持ち、セッション履歴なし |
+| **message tool** | サブ Agent は message ツールでユーザーと直接通信 |
+| **ノンブロッキング** | spawn 後、ハートビートは次のタスクに進む     |
+
+**設定：**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| オプション | デフォルト値 | 説明                           |
+| ---------- | ------------ | ------------------------------ |
+| `enabled`  | `true`       | ハートビートの有効/無効        |
+| `interval` | `30`         | チェック間隔（分単位、最小: 5）|
+
+**環境変数:**
+
+- `PICOCLAW_HEARTBEAT_ENABLED=false` で無効化
+- `PICOCLAW_HEARTBEAT_INTERVAL=60` で間隔を変更
+
+#### サブ Agent の通信フロー
+
+```
+ハートビート起動
+    ↓
+Agent が HEARTBEAT.md を読む
+    ↓
+長時間タスク：spawn サブ Agent
+    ↓                           ↓
+次のタスクへ継続           サブ Agent が独立して動作
+    ↓                           ↓
+全タスク完了               サブ Agent が "message" ツールを使用
+    ↓                           ↓
+HEARTBEAT_OK を返信        ユーザーが直接結果を受信
+```
+
+### Providers
+
+> [!NOTE]
+> Groq は Whisper による無料音声文字起こしを提供します。設定すると、任意のチャンネルの音声メッセージが Agent レベルで自動的に文字起こしされます。
+
+| Provider     | 用途                                    | API キー取得                                                 |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini`     | LLM（Gemini 直接）                      | [aistudio.google.com](https://aistudio.google.com)           |
+| `zhipu`      | LLM（Zhipu 直接）                       | [bigmodel.cn](https://bigmodel.cn)                           |
+| `volcengine` | LLM（Volcengine 直接）                  | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter` | LLM（推奨、全モデルにアクセス可能）     | [openrouter.ai](https://openrouter.ai)                       |
+| `anthropic`  | LLM（Claude 直接）                      | [console.anthropic.com](https://console.anthropic.com)       |
+| `openai`     | LLM（GPT 直接）                         | [platform.openai.com](https://platform.openai.com)           |
+| `deepseek`   | LLM（DeepSeek 直接）                    | [platform.deepseek.com](https://platform.deepseek.com)       |
+| `qwen`       | LLM（Qwen 直接）                        | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq`       | LLM + **音声文字起こし**（Whisper）     | [console.groq.com](https://console.groq.com)                 |
+| `cerebras`   | LLM（Cerebras 直接）                    | [cerebras.ai](https://cerebras.ai)                           |
+| `vivgrid`    | LLM（Vivgrid 直接）                     | [vivgrid.com](https://vivgrid.com)                           |
+
+### モデル設定 (model_list)
+
+> **新機能：** PicoClaw は**モデル中心**の設定アプローチを採用しました。`vendor/model` 形式（例：`zhipu/glm-4.7`）を指定するだけで新しい Provider を追加できます — **コード変更不要！**
+
+#### サポートされている全 Vendor
+
+| Vendor                  | `model` プレフィックス | デフォルト API Base                                 | プロトコル | API Key                                                          |
+| ----------------------- | ---------------------- | --------------------------------------------------- | ---------- | ---------------------------------------------------------------- |
+| **OpenAI**              | `openai/`              | `https://api.openai.com/v1`                         | OpenAI     | [取得](https://platform.openai.com)                              |
+| **Anthropic**           | `anthropic/`           | `https://api.anthropic.com/v1`                      | Anthropic  | [取得](https://console.anthropic.com)                            |
+| **智谱 AI (GLM)**       | `zhipu/`               | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI     | [取得](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys)    |
+| **DeepSeek**            | `deepseek/`            | `https://api.deepseek.com/v1`                       | OpenAI     | [取得](https://platform.deepseek.com)                            |
+| **Google Gemini**       | `gemini/`              | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI     | [取得](https://aistudio.google.com/api-keys)                     |
+| **Groq**                | `groq/`                | `https://api.groq.com/openai/v1`                    | OpenAI     | [取得](https://console.groq.com)                                 |
+| **通義千問 (Qwen)**     | `qwen/`                | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI     | [取得](https://dashscope.console.aliyun.com)                     |
+| **Ollama**              | `ollama/`              | `http://localhost:11434/v1`                         | OpenAI     | ローカル（キー不要）                                             |
+| **OpenRouter**          | `openrouter/`          | `https://openrouter.ai/api/v1`                      | OpenAI     | [取得](https://openrouter.ai/keys)                               |
+| **VolcEngine (Doubao)** | `volcengine/`          | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI     | [取得](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **Antigravity**         | `antigravity/`         | Google Cloud                                        | Custom     | OAuth のみ                                                       |
+
+#### ロードバランシング
+
+同じモデル名に複数のエンドポイントを設定すると、PicoClaw が自動的にラウンドロビンします：
+
+```json
+{
+  "model_list": [
+    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" },
+    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" }
+  ]
+}
+```
+
+#### 旧 `providers` 設定からの移行
+
+旧 `providers` 設定は**非推奨**ですが後方互換性のためサポートされています。[docs/migration/model-list-migration.md](../migration/model-list-migration.md) を参照してください。
+
+### Provider アーキテクチャ
+
+PicoClaw はプロトコルファミリーで Provider をルーティングします：
+
+- **OpenAI 互換**：OpenRouter、Groq、Zhipu、vLLM スタイルのエンドポイントなど。
+- **Anthropic**：Claude ネイティブ API の動作。
+- **Codex/OAuth**：OpenAI OAuth/トークン認証ルート。
+
+### スケジュールタスク / リマインダー
+
+PicoClaw は `cron` ツールを通じて cron スタイルのスケジュールタスクをサポートします。
+
+```json
+{
+  "tools": {
+    "cron": {
+      "enabled": true,
+      "exec_timeout_minutes": 5
+    }
+  }
+}
+```
+
+スケジュールタスクは再起動後も `~/.picoclaw/workspace/cron/` に保存されます。
+
+### 高度なトピック
+
+| トピック | 説明 |
+| -------- | ---- |
+| [Hook システム](../hooks/README.md) | イベント駆動 Hook：オブザーバー、インターセプター、承認 Hook |
+| [Steering](../steering.md) | 実行中の Agent ループにメッセージを注入 |
+| [SubTurn](../subturn.md) | サブ Agent の調整、並行制御、ライフサイクル |
+| [コンテキスト管理](../agent-refactor/context.md) | コンテキスト境界検出、圧縮戦略 |
diff --git a/docs/ja/credential_encryption.md b/docs/ja/credential_encryption.md
new file mode 100644
index 000000000..ea74b65d2
--- /dev/null
+++ b/docs/ja/credential_encryption.md
@@ -0,0 +1,158 @@
+> [README](../../README.ja.md) に戻る
+
+# クレデンシャル暗号化
+
+PicoClaw は `model_list` 設定エントリの `api_key` 値の暗号化をサポートしています。
+暗号化されたキーは `enc://<base64>` 文字列として保存され、起動時に自動的に復号されます。
+
+---
+
+## クイックスタート
+
+**1. パスフレーズを設定する**
+
+```bash
+export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
+```
+
+**2. API キーを暗号化する**
+
+`picoclaw onboard` を実行します — パスフレーズの入力を求められ、SSH キーが生成されます。
+その後、次の `SaveConfig` 呼び出し時に、設定内のすべての平文 `api_key` エントリが自動的に再暗号化されます。生成される `enc://` 値は以下のようになります：
+
+```
+enc://AAAA...base64...
+```
+
+**3. 出力を設定に貼り付ける**
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-4o",
+      "model": "openai/gpt-4o",
+      "api_key": "enc://AAAA...base64...",
+      "api_base": "https://api.openai.com/v1"
+    }
+  ]
+}
+```
+
+---
+
+## サポートされる `api_key` 形式
+
+| 形式 | 例 | 動作 |
+|------|---|------|
+| 平文 | `sk-abc123` | そのまま使用 |
+| ファイル参照 | `file://openai.key` | 設定ファイルと同じディレクトリから内容を読み取り |
+| 暗号化 | `enc://<base64>` | 起動時に `PICOCLAW_KEY_PASSPHRASE` を使用して復号 |
+| 空 | `""` | そのまま渡される（`auth_method: oauth` で使用） |
+
+---
+
+## 暗号設計
+
+### 鍵導出
+
+暗号化には **HKDF-SHA256** を使用し、SSH 秘密鍵を第二要素とします。
+
+```
+sshHash = SHA256(ssh_private_key_file_bytes)
+ikm     = HMAC-SHA256(key=sshHash, message=passphrase)
+aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+```
+
+### 暗号化
+
+```
+AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
+```
+
+### ワイヤーフォーマット
+
+```
+enc://<base64( salt[16] + nonce[12] + ciphertext )>
+```
+
+| フィールド | サイズ | 説明 |
+|-----------|--------|------|
+| `salt` | 16 バイト | 暗号化ごとにランダム生成；HKDF に入力 |
+| `nonce` | 12 バイト | 暗号化ごとにランダム生成；AES-GCM IV |
+| `ciphertext` | 可変 | AES-256-GCM 暗号文 + 16 バイト認証タグ |
+
+GCM 認証タグは暗号文に自動的に付加されます。改ざんがあった場合、破損した平文を返すのではなく、エラーで復号が失敗します。
+
+### パフォーマンス
+
+| 操作 | 所要時間 (ARM Cortex-A) |
+|------|------------------------|
+| 鍵導出 (HKDF) | < 1 ms |
+| AES-256-GCM 復号 | < 1 ms |
+| **起動時の総オーバーヘッド** | **キーあたり < 2 ms** |
+
+---
+
+## SSH キーによる二要素セキュリティ
+
+SSH 秘密鍵が提供されている場合、暗号を破るには**両方**が必要です：
+
+1. **パスフレーズ** (`PICOCLAW_KEY_PASSPHRASE`)
+2. **SSH 秘密鍵ファイル**
+
+これは、設定ファイルが漏洩しただけでは、パスフレーズが弱い場合でも API キーを復元できないことを意味します。SSH キーはパスフレーズの強度に関係なく、256 ビットのエントロピー（Ed25519）を提供します。
+
+### 脅威モデル
+
+| 攻撃者が持っているもの | 復号可能か？ |
+|----------------------|-------------|
+| 設定ファイルのみ | いいえ — パスフレーズ + SSH キーが必要 |
+| SSH キーのみ | いいえ — パスフレーズが必要 |
+| パスフレーズのみ | いいえ — SSH キーが必要 |
+| 設定ファイル + SSH キー + パスフレーズ | はい — 完全な侵害 |
+
+---
+
+## 環境変数
+
+| 変数 | 必須 | 説明 |
+|------|------|------|
+| `PICOCLAW_KEY_PASSPHRASE` | はい（`enc://` 使用時） | 鍵導出に使用するパスフレーズ |
+| `PICOCLAW_SSH_KEY_PATH` | いいえ | SSH 秘密鍵のパス。未設定の場合、`~/.ssh/picoclaw_ed25519.key` から自動検出 |
+
+### SSH キーの自動検出
+
+`PICOCLAW_SSH_KEY_PATH` が設定されていない場合、PicoClaw は専用キーを探します：
+
+```
+~/.ssh/picoclaw_ed25519.key
+```
+
+この専用ファイルにより、ユーザーの既存の SSH キーとの競合を回避します。
+`picoclaw onboard` を実行すると自動的に生成されます。
+
+`os.UserHomeDir()` はクロスプラットフォームのホームディレクトリ解決に使用されます（Windows では `USERPROFILE`、Unix/macOS では `HOME` を読み取ります）。
+
+> **注意：** SSH キーファイルはクレデンシャル暗号化に必須です。キーが見つからず `PICOCLAW_SSH_KEY_PATH` も設定されていない場合、暗号化/復号は失敗します。`picoclaw onboard` を実行してキーを自動生成してください。
+
+---
+
+## 移行
+
+唯一の秘密情報は `PICOCLAW_KEY_PASSPHRASE` と SSH 秘密鍵ファイルであるため、移行は簡単です：
+
+1. 設定ファイルを新しいマシンにコピーします。
+2. `PICOCLAW_KEY_PASSPHRASE` を同じ値に設定します。
+3. SSH 秘密鍵ファイルを同じパスにコピーします（または `PICOCLAW_SSH_KEY_PATH` を新しい場所に設定します）。
+
+再暗号化は不要です。
+
+---
+
+## セキュリティに関する考慮事項
+
+- **パスフレーズと SSH キーの両方が必須です。** SSH キーは第二要素として機能します — これがなければ暗号化/復号は失敗します。キーが存在しない場合は `picoclaw onboard` を実行して生成してください。
+- **SSH キーは実行時に読み取り専用です。** PicoClaw は SSH キーファイルへの書き込みや変更を行いません。
+- **平文キーは引き続きサポートされます。** `enc://` を使用しない既存の設定は影響を受けません。
+- **`enc://` 形式はバージョン管理されています。** HKDF `info` フィールド（`picoclaw-credential-v1`）により、既存の暗号化値を壊すことなく将来のアルゴリズムアップグレードが可能です。
diff --git a/docs/ja/debug.md b/docs/ja/debug.md
new file mode 100644
index 000000000..ecc52f454
--- /dev/null
+++ b/docs/ja/debug.md
@@ -0,0 +1,36 @@
+# PicoClaw のデバッグ
+
+> [README](../../README.ja.md) に戻る
+
+PicoClaw は、受信するすべてのリクエストに対して、メッセージのルーティングや複雑度の評価、ツールの実行、モデル障害への適応など、多くの複雑な処理をバックグラウンドで実行しています。何が起きているかを正確に把握できることは、潜在的な問題のトラブルシューティングだけでなく、エージェントの動作を真に理解するためにも非常に重要です。
+
+## デバッグモードで PicoClaw を起動する
+
+エージェントの動作に関する詳細情報（LLM リクエスト、ツール呼び出し、メッセージルーティング）を取得するには、デバッグフラグを付けて PicoClaw ゲートウェイを起動します：
+
+```bash
+picoclaw gateway --debug
+# or
+picoclaw gateway -d
+```
+
+このモードでは、システムがログを詳細にフォーマットし、システムプロンプトやツール実行結果のプレビューを表示します。
+
+## ログの切り詰めを無効にする（完全なログ）
+
+デフォルトでは、PicoClaw はコンソールの可読性を保つために、デバッグログ内の非常に長い文字列（*システムプロンプト*や大きな JSON 出力結果など）を切り詰めます。
+
+コマンドの完全な出力や、LLM モデルに送信された正確なペイロードを確認する必要がある場合は、`--no-truncate` フラグを使用できます。
+
+**注意：** このフラグは `--debug` モードと組み合わせた場合に*のみ*機能します。
+
+```bash
+picoclaw gateway --debug --no-truncate
+
+```
+
+このフラグが有効な場合、グローバルな切り詰め機能が無効になります。これは以下の場合に非常に便利です：
+
+* プロバイダーに送信されるメッセージの正確な構文を確認する。
+* `exec`、`web_fetch`、`read_file` などのツールの完全な出力を読む。
+* メモリに保存されたセッション履歴をデバッグする。
diff --git a/docs/ja/docker.md b/docs/ja/docker.md
new file mode 100644
index 000000000..31ed17ec5
--- /dev/null
+++ b/docs/ja/docker.md
@@ -0,0 +1,169 @@
+# 🐳 Docker とクイックスタート
+
+> [README](../../README.ja.md) に戻る
+
+## 🐳 Docker Compose
+
+Docker Compose を使用して PicoClaw を実行できます。ローカルに何もインストールする必要はありません。
+
+```bash
+# 1. リポジトリをクローン
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. 初回実行 — docker/data/config.json を自動生成して終了
+#    （config.json と workspace/ の両方が存在しない場合のみ実行）
+docker compose -f docker/docker-compose.yml --profile gateway up
+# コンテナが "First-run setup complete." と表示して停止します
+
+# 3. API Key を設定
+vim docker/data/config.json   # provider API key、Bot Token などを設定
+
+# 4. 起動
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+> [!TIP]
+> **Docker ユーザー**: デフォルトでは Gateway は `127.0.0.1` でリッスンしており、コンテナ外からはアクセスできません。ヘルスチェックエンドポイントへのアクセスやポート公開が必要な場合は、環境変数で `PICOCLAW_GATEWAY_HOST=0.0.0.0` を設定するか、`config.json` を更新してください。
+
+```bash
+# 5. ログを確認
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. 停止
+docker compose -f docker/docker-compose.yml --profile gateway down
+```
+
+### Launcher モード (Web コンソール)
+
+`launcher` イメージには 3 つのバイナリ（`picoclaw`、`picoclaw-launcher`、`picoclaw-launcher-tui`）がすべて含まれており、デフォルトで Web コンソールを起動します。ブラウザベースの設定・チャット画面を提供します。
+
+```bash
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+```
+
+ブラウザで http://localhost:18800 を開いてください。Launcher が Gateway プロセスを自動管理します。
+
+> [!WARNING]
+> Web コンソールはまだ認証をサポートしていません。公開インターネットに公開しないでください。
+
+### Agent モード (ワンショット)
+
+```bash
+# 質問する
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2は？"
+
+# インタラクティブモード
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+```
+
+### イメージの更新
+
+```bash
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+---
+
+## 🚀 クイックスタート
+
+> [!TIP]
+> `~/.picoclaw/config.json` に API Key を設定してください。API Key の取得先: [Volcengine (CodingPlan)](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)。Web 検索は**オプション**です — 無料の [Tavily API](https://tavily.com) (月 1000 回無料) または [Brave Search API](https://brave.com/search/api) (月 2000 回無料) を取得できます。
+
+**1. 初期化**
+
+```bash
+picoclaw onboard
+```
+
+**2. 設定** (`~/.picoclaw/config.json`)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "gpt-5.4",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key",
+      "api_base":"https://ark.cn-beijing.volces.com/api/coding/v3"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "your-api-key",
+      "request_timeout": 300
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "your-anthropic-key"
+    }
+  ],
+  "tools": {
+    "web": {
+      "enabled": true,
+      "fetch_limit_bytes": 10485760,
+      "format": "plaintext",
+      "brave": {
+        "enabled": false,
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      },
+      "tavily": {
+        "enabled": false,
+        "api_key": "YOUR_TAVILY_API_KEY",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "YOUR_PERPLEXITY_API_KEY",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://your-searxng-instance:8888",
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+> **新機能**: `model_list` 設定形式により、コード変更なしで provider を追加できます。詳細は[モデル設定](providers.md#モデル設定-model_list)を参照してください。
+> `request_timeout` はオプションで、単位は秒です。省略または `<= 0` に設定した場合、PicoClaw はデフォルトのタイムアウト（120 秒）を使用します。
+
+**3. API Key の取得**
+
+* **LLM プロバイダー**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
+* **Web 検索** (オプション):
+  * [Brave Search](https://brave.com/search/api) - 有料 ($5/1000 queries, ~$5-6/month)
+  * [Perplexity](https://www.perplexity.ai) - AI 搭載の検索・チャットインターフェース
+  * [SearXNG](https://github.com/searxng/searxng) - セルフホスト型メタ検索エンジン（無料、API Key 不要）
+  * [Tavily](https://tavily.com) - AI Agent 向けに最適化 (1000 requests/month)
+  * DuckDuckGo - 組み込みフォールバック（API Key 不要）
+
+> **注意**: 完全な設定テンプレートは `config.example.json` を参照してください。
+
+**4. チャット**
+
+```bash
+picoclaw agent -m "2+2は？"
+```
+
+以上です！2 分で動作する AI アシスタントが手に入ります。
+
+---
diff --git a/docs/ja/hardware-compatibility.md b/docs/ja/hardware-compatibility.md
new file mode 100644
index 000000000..96ccd1cd1
--- /dev/null
+++ b/docs/ja/hardware-compatibility.md
@@ -0,0 +1,152 @@
+> [README](../../README.ja.md) に戻る
+
+# 🖥️ PicoClaw ハードウェア互換性リスト
+
+PicoClaw はほぼすべての Linux デバイスで動作します。このページでは、検証済みのチップ、製品、開発ボードを記録しています。
+
+**お使いのハードウェアがリストにない場合は？** PR を送信して追加してください！ハードウェアベンダーの貢献と共同プロモーションを歓迎します。
+
+---
+
+## 1. 検証済みチップサポート
+
+### x86
+
+| ベンダー | チップ | 備考 |
+|----------|--------|------|
+| Intel | Any x86 CPU (i386+) | すべてのデスクトップ/サーバー/ノートPC プロセッサ |
+| AMD | Any x86 CPU | すべてのデスクトップ/サーバー/ノートPC プロセッサ |
+
+### ARM
+
+| サブアーキテクチャ | 代表的なチップ | 備考 |
+|--------------------|----------------|------|
+| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | シングルコア ARM1176JZF-S |
+| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | シングルコア Cortex-A7、LicheePi Zero で使用 |
+| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | クアッドコア Cortex-A53、Orange Pi Zero 3 で使用 |
+| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | クアッドコア Cortex-A72 |
+| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | クアッドコア Cortex-A76 |
+| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | デュアルコア Cortex-A53 + NPU、NanoKVM-Pro / MaixCAM2 で使用 |
+
+### RISC-V (riscv64)
+
+| ベンダー | チップ | コア | 備考 |
+|----------|--------|------|------|
+| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 オンチップ、LicheeRV-Nano / NanoKVM / MaixCAM で使用 |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L オンチップ、1 TOPS NPU、4K AI カメラ SiP |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | RISC-V AI カメラシリーズ |
+| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | HaaS506-LD1 産業用 RTU で使用 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Milk-V Jupiter, BananaPi BPI-F3 で使用 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | RVA23 準拠、1024 ビット RVV、FP8 AI 推論 |
+| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8 コア、16MB L3 キャッシュ、デスクトップクラス |
+| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU、CanMV-K230 で使用 |
+
+### MIPS
+
+| ベンダー | チップ | 備考 |
+|----------|--------|------|
+| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz、多くの OpenWrt ルーターで使用（例：Xiaomi Router 3G） |
+
+### LoongArch (loong64)
+
+| ベンダー | チップ | 備考 |
+|----------|--------|------|
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | クアッドコア LA464 @ 2.5GHz、デスクトップ/ワークステーション |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | クアッドコア 4C/8T @ 2.5GHz、IPC は Intel 第10世代に匹敵 |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | デュアルコア @ 1GHz、産業/IoT アプリケーション |
+
+---
+
+## 2. 検証済み製品（発売日順）
+
+PicoClaw でテスト済みのコンシューマー製品、ルーター、産業用デバイス。
+
+| 年 | 製品 | アーキテクチャ | SoC | RAM | カテゴリ |
+|----|------|----------------|-----|-----|----------|
+| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | スマートフォン |
+| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | タブレット |
+| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | ルーター (OpenWrt) |
+| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | TV ボックス / ホームサーバー |
+| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | スマートスピーカー |
+| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
+| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | 産業用 RTU |
+| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | プロ IP-KVM |
+| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | 4K AI カメラ |
+
+---
+
+## 3. 検証済み開発ボード（発売日順）
+
+| 年 | ボード | アーキテクチャ | SoC | RAM | 購入リンク |
+|----|--------|----------------|-----|-----|------------|
+| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
+| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
+| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
+| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
+| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
+| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
+| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
+| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
+| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
+
+---
+
+## 4. その他の対応環境
+
+### Android スマートフォン（Termux 経由）
+
+1GB 以上の RAM を搭載した ARM64 Android スマートフォン（2015年以降）。[Termux](https://github.com/termux/termux-app) をインストールし、`proot` を使用して PicoClaw を実行します。
+
+> セットアップ手順は [README：古い Android スマートフォンで実行](../../README.ja.md#-run-on-old-android-phones) を参照してください。
+
+### デスクトップ / サーバー / クラウド
+
+| プラットフォーム | 備考 |
+|------------------|------|
+| x86_64 Linux | ネイティブバイナリ、依存関係なし |
+| x86_64 Windows | ネイティブバイナリ |
+| macOS (Intel / Apple Silicon) | ネイティブバイナリ |
+| Docker (any platform) | `docker compose` ワンライナー、[Docker ガイド](docker.md) を参照 |
+| OpenWrt routers | MIPS/ARM ビルド、32MB 以上の空きメモリが必要 |
+| FreeBSD / NetBSD | x86_64 および arm64 ビルドが利用可能 |
+
+---
+
+## 5. 最小要件
+
+| リソース | 最小 | 推奨 |
+|----------|------|------|
+| RAM | 10MB 空き | 32MB 以上空き |
+| ストレージ | 20MB（バイナリ） | 50MB 以上（ワークスペース含む） |
+| CPU | 任意（シングルコア 0.6GHz 以上） | — |
+| OS | Linux (kernel 3.x+) | Linux 5.x+ |
+| ネットワーク | 必須（LLM API 呼び出し用） | イーサネットまたは WiFi |
+
+---
+
+## 6. テストと貢献の方法
+
+```bash
+# 1. お使いのアーキテクチャ向けをダウンロード
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+
+# 2. 初期化
+./picoclaw onboard
+
+# 3. テスト
+./picoclaw agent -m "Hello, what board am I running on?"
+```
+
+利用可能なビルド：`linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
+
+### ハードウェアを追加する
+
+1. このリポジトリをフォーク
+2. 該当するテーブルにチップ/製品/ボードを追加
+3. 名前、アーキテクチャ、SoC、RAM、年、リンク（あれば）を含める
+4. PR を送信
+
+ハードウェアベンダーの方へ：公式サポートの追加や共同プロモーションをご希望ですか？Issue を作成するか、[Discord](https://discord.gg/V4sAZ9XWpN) でお問い合わせください。
diff --git a/docs/ja/providers.md b/docs/ja/providers.md
new file mode 100644
index 000000000..9a53a4b69
--- /dev/null
+++ b/docs/ja/providers.md
@@ -0,0 +1,433 @@
+# 🔌 プロバイダーとモデル設定
+
+> [README](../../README.ja.md) に戻る
+
+### プロバイダー
+
+> [!NOTE]
+> Groq は Whisper による無料の音声文字起こしを提供しています。Groq を設定すると、任意のチャネルからの音声メッセージが Agent レベルで自動的にテキストに変換されます。
+
+| プロバイダー         | 用途                         | API Key の取得                                                       |
+| -------------------- | ---------------------------- | -------------------------------------------------------------------- |
+| `gemini`             | LLM (Gemini 直接接続)       | [aistudio.google.com](https://aistudio.google.com)                   |
+| `zhipu`              | LLM (Zhipu 直接接続)        | [bigmodel.cn](https://bigmodel.cn)                                   |
+| `volcengine`         | LLM (Volcengine 直接接続)   | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter`         | LLM (推奨、全モデルアクセス可) | [openrouter.ai](https://openrouter.ai)                               |
+| `anthropic`          | LLM (Claude 直接接続)       | [console.anthropic.com](https://console.anthropic.com)               |
+| `openai`             | LLM (GPT 直接接続)          | [platform.openai.com](https://platform.openai.com)                   |
+| `deepseek`           | LLM (DeepSeek 直接接続)     | [platform.deepseek.com](https://platform.deepseek.com)               |
+| `qwen`               | LLM (Qwen 直接接続)         | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq`               | LLM + **音声文字起こし** (Whisper) | [console.groq.com](https://console.groq.com)                         |
+| `cerebras`           | LLM (Cerebras 直接接続)     | [cerebras.ai](https://cerebras.ai)                                   |
+| `vivgrid`            | LLM (Vivgrid 直接接続)      | [vivgrid.com](https://vivgrid.com)                                   |
+| `moonshot`           | LLM (Kimi/Moonshot 直接接続) | [platform.moonshot.cn](https://platform.moonshot.cn)                 |
+| `minimax`            | LLM (Minimax 直接接続)      | [platform.minimaxi.com](https://platform.minimaxi.com)              |
+| `avian`              | LLM (Avian 直接接続)        | [avian.io](https://avian.io)                                         |
+| `mistral`            | LLM (Mistral 直接接続)      | [console.mistral.ai](https://console.mistral.ai)                    |
+| `longcat`            | LLM (Longcat 直接接続)      | [longcat.ai](https://longcat.ai)                                     |
+| `modelscope`         | LLM (ModelScope 直接接続)   | [modelscope.cn](https://modelscope.cn)                               |
+
+### モデル設定 (model_list)
+
+> **新機能！** PicoClaw は**モデル中心**の設定方式を採用しました。`ベンダー/モデル` 形式（例: `zhipu/glm-4.7`）を指定するだけで新しい provider を追加できます——**コード変更は一切不要です！**
+
+この設計は**マルチ Agent シナリオ**もサポートし、柔軟な Provider 選択を提供します：
+
+- **Agent ごとに異なる Provider**: 各 Agent が独自の LLM provider を使用可能
+- **モデルフォールバック**: プライマリモデルとフォールバックモデルを設定し、信頼性を向上
+- **ロードバランシング**: 複数の API エンドポイント間でリクエストを分散
+- **一元管理**: すべての provider を一箇所で管理
+
+#### 📋 サポートされている全ベンダー
+
+| ベンダー            | `model` プレフィックス | デフォルト API Base                                 | プロトコル | API Key の取得                                                    |
+| ------------------- | --------------------- | --------------------------------------------------- | ---------- | ----------------------------------------------------------------- |
+| **OpenAI**          | `openai/`             | `https://api.openai.com/v1`                         | OpenAI     | [キーを取得](https://platform.openai.com)                         |
+| **Anthropic**       | `anthropic/`          | `https://api.anthropic.com/v1`                      | Anthropic  | [キーを取得](https://console.anthropic.com)                       |
+| **智谱 AI (GLM)**   | `zhipu/`              | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI     | [キーを取得](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek**        | `deepseek/`           | `https://api.deepseek.com/v1`                       | OpenAI     | [キーを取得](https://platform.deepseek.com)                       |
+| **Google Gemini**   | `gemini/`             | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI     | [キーを取得](https://aistudio.google.com/api-keys)                |
+| **Groq**            | `groq/`               | `https://api.groq.com/openai/v1`                    | OpenAI     | [キーを取得](https://console.groq.com)                            |
+| **Moonshot**        | `moonshot/`           | `https://api.moonshot.cn/v1`                        | OpenAI     | [キーを取得](https://platform.moonshot.cn)                        |
+| **通義千問 (Qwen)** | `qwen/`               | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI     | [キーを取得](https://dashscope.console.aliyun.com)                |
+| **NVIDIA**          | `nvidia/`             | `https://integrate.api.nvidia.com/v1`               | OpenAI     | [キーを取得](https://build.nvidia.com)                            |
+| **Ollama**          | `ollama/`             | `http://localhost:11434/v1`                         | OpenAI     | ローカル（キー不要）                                              |
+| **OpenRouter**      | `openrouter/`         | `https://openrouter.ai/api/v1`                      | OpenAI     | [キーを取得](https://openrouter.ai/keys)                          |
+| **LiteLLM Proxy**   | `litellm/`            | `http://localhost:4000/v1`                          | OpenAI     | LiteLLM プロキシキー                                              |
+| **VLLM**            | `vllm/`               | `http://localhost:8000/v1`                          | OpenAI     | ローカル                                                          |
+| **Cerebras**        | `cerebras/`           | `https://api.cerebras.ai/v1`                        | OpenAI     | [キーを取得](https://cerebras.ai)                                 |
+| **VolcEngine (Doubao)** | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI     | [キーを取得](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **神算云**          | `shengsuanyun/`       | `https://router.shengsuanyun.com/api/v1`            | OpenAI     | -                                                                 |
+| **BytePlus**        | `byteplus/`           | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI     | [キーを取得](https://www.byteplus.com)                            |
+| **Vivgrid**         | `vivgrid/`            | `https://api.vivgrid.com/v1`                        | OpenAI     | [キーを取得](https://vivgrid.com)                                 |
+| **LongCat**         | `longcat/`            | `https://api.longcat.chat/openai`                   | OpenAI     | [キーを取得](https://longcat.chat/platform)                       |
+| **ModelScope (魔搭)**| `modelscope/`        | `https://api-inference.modelscope.cn/v1`            | OpenAI     | [トークンを取得](https://modelscope.cn/my/tokens)                |
+| **Antigravity**     | `antigravity/`        | Google Cloud                                        | カスタム   | OAuth のみ                                                        |
+| **GitHub Copilot**  | `github-copilot/`     | `localhost:4321`                                    | gRPC       | -                                                                 |
+
+#### 基本設定
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-openai-key"
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "sk-ant-your-key"
+    },
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-zhipu-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "gpt-5.4"
+    }
+  }
+}
+```
+
+#### ベンダー別設定例
+
+**OpenAI**
+
+```json
+{
+  "model_name": "gpt-5.4",
+  "model": "openai/gpt-5.4",
+  "api_key": "sk-..."
+}
+```
+
+**VolcEngine (Doubao)**
+
+```json
+{
+  "model_name": "ark-code-latest",
+  "model": "volcengine/ark-code-latest",
+  "api_key": "sk-..."
+}
+```
+
+**智谱 AI (GLM)**
+
+```json
+{
+  "model_name": "glm-4.7",
+  "model": "zhipu/glm-4.7",
+  "api_key": "your-key"
+}
+```
+
+**DeepSeek**
+
+```json
+{
+  "model_name": "deepseek-chat",
+  "model": "deepseek/deepseek-chat",
+  "api_key": "sk-..."
+}
+```
+
+**Anthropic (API キー使用)**
+
+```json
+{
+  "model_name": "claude-sonnet-4.6",
+  "model": "anthropic/claude-sonnet-4.6",
+  "api_key": "sk-ant-your-key"
+}
+```
+
+> `picoclaw auth login --provider anthropic` を実行して API トークンを設定してください。
+
+**Anthropic Messages API（ネイティブ形式）**
+
+Anthropic API への直接アクセスや、Anthropic のネイティブメッセージ形式のみをサポートするカスタムエンドポイント向け：
+
+```json
+{
+  "model_name": "claude-opus-4-6",
+  "model": "anthropic-messages/claude-opus-4-6",
+  "api_key": "sk-ant-your-key",
+  "api_base": "https://api.anthropic.com"
+}
+```
+
+> `anthropic-messages` プロトコルを使用するケース：
+> - Anthropic のネイティブ `/v1/messages` エンドポイントのみをサポートするサードパーティプロキシを使用する場合（OpenAI 互換の `/v1/chat/completions` 非対応）
+> - MiniMax、Synthetic など Anthropic のネイティブメッセージ形式を必要とするサービスに接続する場合
+> - 既存の `anthropic` プロトコルが 404 エラーを返す場合（エンドポイントが OpenAI 互換形式をサポートしていないことを示す）
+>
+> **注意:** `anthropic` プロトコルは OpenAI 互換形式（`/v1/chat/completions`）を使用し、`anthropic-messages` は Anthropic のネイティブ形式（`/v1/messages`）を使用します。エンドポイントがサポートする形式に応じて選択してください。
+
+**Ollama (ローカル)**
+
+```json
+{
+  "model_name": "llama3",
+  "model": "ollama/llama3"
+}
+```
+
+**カスタムプロキシ/API**
+
+```json
+{
+  "model_name": "my-custom-model",
+  "model": "openai/custom-model",
+  "api_base": "https://my-proxy.com/v1",
+  "api_key": "sk-...",
+  "request_timeout": 300
+}
+```
+
+**LiteLLM Proxy**
+
+```json
+{
+  "model_name": "lite-gpt4",
+  "model": "litellm/lite-gpt4",
+  "api_base": "http://localhost:4000/v1",
+  "api_key": "sk-..."
+}
+```
+
+PicoClaw はリクエスト送信前に外側の `litellm/` プレフィックスのみを除去するため、`litellm/lite-gpt4` は `lite-gpt4` を送信し、`litellm/openai/gpt-4o` は `openai/gpt-4o` を送信します。
+
+#### ロードバランシング
+
+同じモデル名に複数のエンドポイントを設定すると、PicoClaw が自動的にラウンドロビンで分散します：
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api1.example.com/v1",
+      "api_key": "sk-key1"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api2.example.com/v1",
+      "api_key": "sk-key2"
+    }
+  ]
+}
+```
+
+#### レガシー `providers` 設定からの移行
+
+旧 `providers` 設定形式は**非推奨**ですが、後方互換性のためまだサポートされています。
+
+**旧設定（非推奨）：**
+
+```json
+{
+  "providers": {
+    "zhipu": {
+      "api_key": "your-key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  },
+  "agents": {
+    "defaults": {
+      "provider": "zhipu",
+      "model": "glm-4.7"
+    }
+  }
+}
+```
+
+**新設定（推奨）：**
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "glm-4.7"
+    }
+  }
+}
+```
+
+詳細な移行ガイドは [docs/migration/model-list-migration.md](../migration/model-list-migration.md) を参照してください。
+
+### Provider アーキテクチャ
+
+PicoClaw はプロトコルファミリーごとに Provider をルーティングします：
+
+- OpenAI 互換プロトコル：OpenRouter、OpenAI 互換ゲートウェイ、Groq、Zhipu、vLLM スタイルのエンドポイント。
+- Anthropic プロトコル：Claude ネイティブ API 動作。
+- Codex/OAuth パス：OpenAI OAuth/Token 認証ルート。
+
+これによりランタイムを軽量に保ちつつ、新しい OpenAI 互換バックエンドの追加をほぼ設定操作（`api_base` + `api_key`）のみで実現しています。
+
+<details>
+<summary><b>Zhipu 設定例</b></summary>
+
+**1. API key と base URL を取得**
+
+- [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) を取得
+
+**2. 設定**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "providers": {
+    "zhipu": {
+      "api_key": "Your API Key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  }
+}
+```
+
+**3. 実行**
+
+```bash
+picoclaw agent -m "こんにちは"
+```
+
+</details>
+
+<details>
+<summary><b>完全な設定例</b></summary>
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "anthropic/claude-opus-4-5"
+    }
+  },
+  "session": {
+    "dm_scope": "per-channel-peer"
+  },
+  "providers": {
+    "openrouter": {
+      "api_key": "sk-or-v1-xxx"
+    },
+    "groq": {
+      "api_key": "gsk_xxx"
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456:ABC...",
+      "allow_from": ["123456789"]
+    },
+    "discord": {
+      "enabled": true,
+      "token": "",
+      "allow_from": [""]
+    },
+    "whatsapp": {
+      "enabled": false,
+      "bridge_url": "ws://localhost:3001",
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": []
+    },
+    "feishu": {
+      "enabled": false,
+      "app_id": "cli_xxx",
+      "app_secret": "xxx",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    },
+    "qq": {
+      "enabled": false,
+      "app_id": "",
+      "app_secret": "",
+      "allow_from": []
+    }
+  },
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": false,
+        "api_key": "BSA...",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://localhost:8888",
+        "max_results": 5
+      }
+    },
+    "cron": {
+      "exec_timeout_minutes": 5
+    }
+  },
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+</details>
+
+---
+
+## 📝 API Key 比較表
+
+| サービス         | Pricing                  | ユースケース                          |
+| ---------------- | ------------------------ | ------------------------------------- |
+| **OpenRouter**   | Free: 200K tokens/month  | マルチモデル (Claude, GPT-4 など)     |
+| **Volcengine CodingPlan** | ¥9.9/first month | 中国ユーザー向け、複数の SOTA モデル (Doubao, DeepSeek など) |
+| **Zhipu**        | Free: 200K tokens/month  | 中国ユーザー向け                      |
+| **Brave Search** | $5/1000 queries          | Web 検索機能                          |
+| **SearXNG**      | Free (self-hosted)       | プライバシー重視のメタ検索 (70+ engines) |
+| **Groq**         | Free tier available      | 高速推論 (Llama, Mixtral)             |
+| **Cerebras**     | Free tier available      | 高速推論 (Llama, Qwen など)           |
+| **LongCat**      | Free: up to 5M tokens/day | 高速推論                             |
+| **ModelScope**   | Free: 2000 requests/day  | 推論 (Qwen, GLM, DeepSeek など)       |
+
+---
+
+<div align="center">
+  <img src="assets/logo.jpg" alt="PicoClaw Meme" width="512">
+</div>
diff --git a/docs/ja/spawn-tasks.md b/docs/ja/spawn-tasks.md
new file mode 100644
index 000000000..a13aab9eb
--- /dev/null
+++ b/docs/ja/spawn-tasks.md
@@ -0,0 +1,68 @@
+# 🔄 非同期タスクと Spawn
+
+> [README](../../README.ja.md) に戻る
+
+### Spawn を使用した非同期タスク
+
+長時間実行タスク（Web 検索、API 呼び出し）には、`spawn` ツールを使用して**サブ Agent (subagent)** を作成します：
+
+```markdown
+# Periodic Tasks
+
+## Quick Tasks (respond directly)
+
+- Report current time
+
+## Long Tasks (use spawn for async)
+
+- Search the web for AI news and summarize
+- Check email and report important messages
+```
+
+**主な動作：**
+
+| 特性             | 説明                                             |
+| ---------------- | ------------------------------------------------ |
+| **spawn**        | 非同期サブ Agent を作成、メインハートビートをブロックしない |
+| **独立コンテキスト** | サブ Agent は独自のコンテキストを持ち、セッション履歴なし |
+| **message tool** | サブ Agent は message ツールでユーザーと直接通信   |
+| **ノンブロッキング** | spawn 後、ハートビートは次のタスクに進む         |
+
+#### サブ Agent の通信の仕組み
+
+```
+ハートビートトリガー (Heartbeat triggers)
+    ↓
+Agent が HEARTBEAT.md を読み取り
+    ↓
+長時間タスクの場合: サブ Agent を spawn
+    ↓                           ↓
+次のタスクに進む             サブ Agent が独立して作業
+    ↓                           ↓
+すべてのタスク完了           サブ Agent が "message" ツールを使用
+    ↓                           ↓
+HEARTBEAT_OK を応答          ユーザーが直接結果を受信
+```
+
+サブ Agent はツール（message、web_search など）にアクセスでき、メイン Agent を経由せずにユーザーと独立して通信できます。
+
+**設定：**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| オプション | デフォルト値 | 説明                           |
+| ---------- | ------------ | ------------------------------ |
+| `enabled`  | `true`       | ハートビートの有効/無効        |
+| `interval` | `30`         | チェック間隔（分単位、最小: 5）|
+
+**環境変数:**
+
+- `PICOCLAW_HEARTBEAT_ENABLED=false` で無効化
+- `PICOCLAW_HEARTBEAT_INTERVAL=60` で間隔を変更
diff --git a/docs/ja/tools_configuration.md b/docs/ja/tools_configuration.md
new file mode 100644
index 000000000..c946bf088
--- /dev/null
+++ b/docs/ja/tools_configuration.md
@@ -0,0 +1,412 @@
+# 🔧 ツール設定
+
+> [README](../../README.ja.md) に戻る
+
+PicoClaw のツール設定は `config.json` の `tools` フィールドにあります。
+
+## ディレクトリ構造
+
+```json
+{
+  "tools": {
+    "web": {
+      ...
+    },
+    "mcp": {
+      ...
+    },
+    "exec": {
+      ...
+    },
+    "cron": {
+      ...
+    },
+    "skills": {
+      ...
+    }
+  }
+}
+```
+
+## Web ツール
+
+Web ツールはウェブ検索とフェッチに使用されます。
+
+### Web Fetcher
+ウェブページコンテンツの取得と処理に関する一般設定。
+
+| 設定項目            | 型     | デフォルト    | 説明                                                                                   |
+|---------------------|--------|---------------|----------------------------------------------------------------------------------------|
+| `enabled`           | bool   | true          | ウェブページ取得機能を有効にする。                                                     |
+| `fetch_limit_bytes` | int    | 10485760      | 取得するウェブページペイロードの最大サイズ（バイト単位、デフォルトは10MB）。            |
+| `format`            | string | "plaintext"   | 取得コンテンツの出力形式。オプション：`plaintext` または `markdown`（推奨）。           |
+
+### DuckDuckGo
+
+| 設定項目      | 型   | デフォルト | 説明                      |
+|---------------|------|------------|---------------------------|
+| `enabled`     | bool | true       | DuckDuckGo 検索を有効にする |
+| `max_results` | int  | 5          | 最大結果数                |
+
+### Baidu Search
+
+| 設定項目      | 型     | デフォルト                                                      | 説明                          |
+|---------------|--------|-----------------------------------------------------------------|-------------------------------|
+| `enabled`     | bool   | false                                                           | Baidu 検索を有効にする        |
+| `api_key`     | string | -                                                               | Qianfan API キー              |
+| `base_url`    | string | `https://qianfan.baidubce.com/v2/ai_search/web_search`         | Baidu Search API URL          |
+| `max_results` | int    | 10                                                              | 最大結果数                    |
+
+```json
+{
+  "tools": {
+    "web": {
+      "baidu_search": {
+        "enabled": true,
+        "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
+        "max_results": 10
+      }
+    }
+  }
+}
+```
+
+### Perplexity
+
+| 設定項目      | 型     | デフォルト | 説明                      |
+|---------------|--------|------------|---------------------------|
+| `enabled`     | bool     | false      | Perplexity 検索を有効にする                          |
+| `api_key`     | string   | -          | Perplexity API キー                                  |
+| `api_keys`    | string[] | -          | 複数の Perplexity API キー（ローテーション用、`api_key` より優先） |
+| `max_results` | int      | 5          | 最大結果数                                           |
+
+### Brave
+
+| 設定項目      | 型     | デフォルト | 説明                  |
+|---------------|--------|------------|-----------------------|
+| `enabled`     | bool     | false      | Brave 検索を有効にする                               |
+| `api_key`     | string   | -          | Brave Search API キー                                |
+| `api_keys`    | string[] | -          | 複数の Brave Search API キー（ローテーション用、`api_key` より優先） |
+| `max_results` | int      | 5          | 最大結果数                                           |
+
+### Tavily
+
+| 設定項目      | 型     | デフォルト | 説明                              |
+|---------------|--------|------------|-----------------------------------|
+| `enabled`     | bool   | false      | Tavily 検索を有効にする           |
+| `api_key`     | string | -          | Tavily API キー                   |
+| `base_url`    | string | -          | カスタム Tavily API ベース URL    |
+| `max_results` | int    | 0          | 最大結果数（0 = デフォルト）      |
+
+### SearXNG
+
+| 設定項目      | 型     | デフォルト               | 説明                      |
+|---------------|--------|--------------------------|---------------------------|
+| `enabled`     | bool   | false                    | SearXNG 検索を有効にする  |
+| `base_url`    | string | `http://localhost:8888`  | SearXNG インスタンス URL  |
+| `max_results` | int    | 5                        | 最大結果数                |
+
+### GLM Search
+
+| 設定項目        | 型     | デフォルト                                           | 説明                      |
+|-----------------|--------|------------------------------------------------------|---------------------------|
+| `enabled`       | bool   | false                                                | GLM Search を有効にする   |
+| `api_key`       | string | -                                                    | GLM API キー              |
+| `base_url`      | string | `https://open.bigmodel.cn/api/paas/v4/web_search`   | GLM Search API URL        |
+| `search_engine` | string | `search_std`                                         | 検索エンジンタイプ        |
+| `max_results`   | int    | 5                                                    | 最大結果数                |
+
+## Exec ツール
+
+Exec ツールはシェルコマンドの実行に使用されます。
+
+| 設定項目               | 型    | デフォルト | 説明                               |
+|------------------------|-------|------------|------------------------------------|
+| `enabled`              | bool  | true       | Exec ツールを有効にする            |
+| `enable_deny_patterns` | bool  | true       | デフォルトの危険コマンドブロックを有効にする |
+| `custom_deny_patterns` | array | []         | カスタム拒否パターン（正規表現）   |
+
+### Exec ツールの無効化
+
+`exec` ツールを完全に無効にするには、`enabled` を `false` に設定します：
+
+**設定ファイル経由：**
+```json
+{
+  "tools": {
+    "exec": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**環境変数経由：**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **注意：** 無効にすると、エージェントはシェルコマンドを実行できなくなります。これは Cron ツールがスケジュールされたシェルコマンドを実行する能力にも影響します。
+
+### 機能
+
+- **`enable_deny_patterns`**：`false` に設定すると、デフォルトの危険コマンドブロックパターンを完全に無効にします
+- **`custom_deny_patterns`**：カスタム拒否正規表現パターンを追加します。一致するコマンドはブロックされます
+
+### デフォルトでブロックされるコマンドパターン
+
+デフォルトで、PicoClaw は以下の危険なコマンドをブロックします：
+
+- 削除コマンド：`rm -rf`、`del /f/q`、`rmdir /s`
+- ディスク操作：`format`、`mkfs`、`diskpart`、`dd if=`、`/dev/sd*` への書き込み
+- システム操作：`shutdown`、`reboot`、`poweroff`
+- コマンド置換：`$()`、`${}`、バッククォート
+- シェルへのパイプ：`| sh`、`| bash`
+- 権限昇格：`sudo`、`chmod`、`chown`
+- プロセス制御：`pkill`、`killall`、`kill -9`
+- リモート操作：`curl | sh`、`wget | sh`、`ssh`
+- パッケージ管理：`apt`、`yum`、`dnf`、`npm install -g`、`pip install --user`
+- コンテナ：`docker run`、`docker exec`
+- Git：`git push`、`git force`
+- その他：`eval`、`source *.sh`
+
+### 既知のアーキテクチャ上の制限
+
+exec ガードは PicoClaw に送信されたトップレベルのコマンドのみを検証します。そのコマンドの実行開始後にビルドツールやスクリプトが生成する子プロセスを再帰的に検査することは**ありません**。
+
+初期コマンドが許可された後、直接コマンドガードをバイパスできるワークフローの例：
+
+- `make run`
+- `go run ./cmd/...`
+- `cargo run`
+- `npm run build`
+
+これは、明らかに危険な直接コマンドのブロックには有用ですが、未レビューのビルドパイプラインに対する完全なサンドボックスでは**ありません**。脅威モデルにワークスペース内の信頼できないコードが含まれる場合は、コンテナ、VM、またはビルド・実行コマンドに対する承認フローなど、より強力な分離を使用してください。
+
+### 設定例
+
+```json
+{
+  "tools": {
+    "exec": {
+      "enable_deny_patterns": true,
+      "custom_deny_patterns": [
+        "\\brm\\s+-r\\b",
+        "\\bkillall\\s+python"
+      ]
+    }
+  }
+}
+```
+
+## Cron ツール
+
+Cron ツールは定期タスクのスケジューリングに使用されます。
+
+| 設定項目               | 型  | デフォルト | 説明                                    |
+|------------------------|-----|------------|-----------------------------------------|
+| `exec_timeout_minutes` | int | 5          | 実行タイムアウト（分）、0 は無制限      |
+
+## MCP ツール
+
+MCP ツールは外部の Model Context Protocol サーバーとの統合を可能にします。
+
+### ツールディスカバリ（遅延読み込み）
+
+複数の MCP サーバーに接続する場合、数百のツールを同時に公開すると LLM のコンテキストウィンドウを使い果たし、API コストが増加する可能性があります。**Discovery** 機能は、MCP ツールをデフォルトで*非表示*にすることでこの問題を解決します。
+
+すべてのツールを読み込む代わりに、LLM には軽量な検索ツール（BM25 キーワードマッチングまたは正規表現を使用）が提供されます。LLM が特定の機能を必要とする場合、非表示のライブラリを検索します。一致するツールは一時的に「アンロック」され、設定されたターン数（`ttl`）の間コンテキストに注入されます。
+
+### グローバル設定
+
+| 設定項目    | 型     | デフォルト | 説明                                 |
+|-------------|--------|------------|--------------------------------------|
+| `enabled`   | bool   | false      | MCP 統合をグローバルに有効にする     |
+| `discovery` | object | `{}`       | ツールディスカバリ設定（下記参照）   |
+| `servers`   | object | `{}`       | サーバー名からサーバー設定へのマップ |
+
+### Discovery 設定（`discovery`）
+
+| 設定項目             | 型   | デフォルト | 説明                                                                                                          |
+|----------------------|------|------------|---------------------------------------------------------------------------------------------------------------|
+| `enabled`            | bool | false      | true の場合、MCP ツールは非表示になり、検索を通じてオンデマンドで読み込まれます。false の場合、すべてのツールが読み込まれます |
+| `ttl`                | int  | 5          | 発見されたツールがアンロック状態を維持する会話ターン数                                                        |
+| `max_search_results` | int  | 5          | 検索クエリごとに返されるツールの最大数                                                                        |
+| `use_bm25`           | bool | true       | 自然言語/キーワード検索ツール（`tool_search_tool_bm25`）を有効にする。**警告**：正規表現検索よりリソースを消費します |
+| `use_regex`          | bool | false      | 正規表現パターン検索ツール（`tool_search_tool_regex`）を有効にする                                            |
+
+> **注意：** `discovery.enabled` が `true` の場合、少なくとも1つの検索エンジン（`use_bm25` または `use_regex`）を有効にする**必要があります**。
+> そうしないとアプリケーションの起動に失敗します。
+
+### サーバーごとの設定
+
+| 設定項目   | 型     | 必須     | 説明                                   |
+|------------|--------|----------|----------------------------------------|
+| `enabled`  | bool   | はい     | この MCP サーバーを有効にする          |
+| `type`     | string | いいえ   | トランスポートタイプ：`stdio`、`sse`、`http` |
+| `command`  | string | stdio    | stdio トランスポートの実行コマンド     |
+| `args`     | array  | いいえ   | stdio トランスポートのコマンド引数     |
+| `env`      | object | いいえ   | stdio プロセスの環境変数               |
+| `env_file` | string | いいえ   | stdio プロセスの環境ファイルパス       |
+| `url`      | string | sse/http | `sse`/`http` トランスポートのエンドポイント URL |
+| `headers`  | object | いいえ   | `sse`/`http` トランスポートの HTTP ヘッダー |
+
+### トランスポートの動作
+
+- `type` を省略した場合、トランスポートは自動検出されます：
+    - `url` が設定されている → `sse`
+    - `command` が設定されている → `stdio`
+- `http` と `sse` はどちらも `url` + オプションの `headers` を使用します。
+- `env` と `env_file` は `stdio` サーバーにのみ適用されます。
+
+### 設定例
+
+#### 1) Stdio MCP サーバー
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-filesystem",
+            "/tmp"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+#### 2) リモート SSE/HTTP MCP サーバー
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "remote-mcp": {
+          "enabled": true,
+          "type": "sse",
+          "url": "https://example.com/mcp",
+          "headers": {
+            "Authorization": "Bearer YOUR_TOKEN"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### 3) ツールディスカバリを有効にした大規模 MCP セットアップ
+
+*この例では、LLM は `tool_search_tool_bm25` のみを認識します。ユーザーからリクエストがあった場合にのみ、Github や Postgres のツールを動的に検索してアンロックします。*
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "discovery": {
+        "enabled": true,
+        "ttl": 5,
+        "max_search_results": 5,
+        "use_bm25": true,
+        "use_regex": false
+      },
+      "servers": {
+        "github": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-github"
+          ],
+          "env": {
+            "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
+          }
+        },
+        "postgres": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-postgres",
+            "postgresql://user:password@localhost/dbname"
+          ]
+        },
+        "slack": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-slack"
+          ],
+          "env": {
+            "SLACK_BOT_TOKEN": "YOUR_SLACK_BOT_TOKEN",
+            "SLACK_TEAM_ID": "YOUR_SLACK_TEAM_ID"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Skills ツール
+
+Skills ツールは ClawHub などのレジストリを通じたスキルの発見とインストールを設定します。
+
+### レジストリ
+
+| 設定項目                           | 型     | デフォルト           | 説明                                         |
+|------------------------------------|--------|----------------------|----------------------------------------------|
+| `registries.clawhub.enabled`       | bool   | true                 | ClawHub レジストリを有効にする               |
+| `registries.clawhub.base_url`      | string | `https://clawhub.ai` | ClawHub ベース URL                           |
+| `registries.clawhub.auth_token`    | string | `""`                 | より高いレート制限のためのオプションの Bearer トークン |
+| `registries.clawhub.search_path`   | string | `/api/v1/search`     | 検索 API パス                                |
+| `registries.clawhub.skills_path`   | string | `/api/v1/skills`     | Skills API パス                              |
+| `registries.clawhub.download_path` | string | `/api/v1/download`   | ダウンロード API パス                        |
+
+### 設定例
+
+```json
+{
+  "tools": {
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "enabled": true,
+          "base_url": "https://clawhub.ai",
+          "auth_token": "",
+          "search_path": "/api/v1/search",
+          "skills_path": "/api/v1/skills",
+          "download_path": "/api/v1/download"
+        }
+      }
+    }
+  }
+}
+```
+
+## 環境変数
+
+すべての設定オプションは `PICOCLAW_TOOLS_<SECTION>_<KEY>` 形式の環境変数で上書きできます：
+
+例：
+
+- `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
+- `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
+- `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
+- `PICOCLAW_TOOLS_MCP_ENABLED=true`
+
+注意：ネストされたマップ形式の設定（例：`tools.mcp.servers.<name>.*`）は環境変数ではなく `config.json` で設定します。
diff --git a/docs/ja/troubleshooting.md b/docs/ja/troubleshooting.md
new file mode 100644
index 000000000..f18b456db
--- /dev/null
+++ b/docs/ja/troubleshooting.md
@@ -0,0 +1,45 @@
+# 🐛 トラブルシューティング
+
+> [README](../../README.ja.md) に戻る
+
+## "model ... not found in model_list" または OpenRouter "free is not a valid model ID"
+
+**症状：** 以下のいずれかのエラーが表示されます：
+
+- `Error creating provider: model "openrouter/free" not found in model_list`
+- OpenRouter が 400 を返す：`"free is not a valid model ID"`
+
+**原因：** `model_list` エントリの `model` フィールドは API に送信される値です。OpenRouter では省略形ではなく、**完全な**モデル ID を使用する必要があります。
+
+- **誤り：** `"model": "free"` → OpenRouter は `free` を受け取り、拒否します。
+- **正しい：** `"model": "openrouter/free"` → OpenRouter は `openrouter/free` を受け取ります（自動無料枠ルーティング）。
+
+**修正方法：** `~/.picoclaw/config.json`（またはお使いの設定パス）で：
+
+1. **agents.defaults.model_name** は `model_list` 内の `model_name` と一致する必要があります（例：`"openrouter-free"`）。
+2. そのエントリの **model** は有効な OpenRouter モデル ID である必要があります。例：
+   - `"openrouter/free"` – 自動無料枠
+   - `"google/gemini-2.0-flash-exp:free"`
+   - `"meta-llama/llama-3.1-8b-instruct:free"`
+
+設定例：
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "openrouter-free"
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "openrouter-free",
+      "model": "openrouter/free",
+      "api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
+      "api_base": "https://openrouter.ai/api/v1"
+    }
+  ]
+}
+```
+
+キーは [OpenRouter Keys](https://openrouter.ai/keys) で取得できます。
diff --git a/docs/migration/model-list-migration.md b/docs/migration/model-list-migration.md
index 0d4af719c..9d05ac599 100644
--- a/docs/migration/model-list-migration.md
+++ b/docs/migration/model-list-migration.md
@@ -40,7 +40,7 @@ The new `model_list` configuration offers several advantages:
   "agents": {
     "defaults": {
       "provider": "openai",
-      "model": "gpt-5.2"
+      "model": "gpt-5.4"
     }
   }
 }
@@ -53,7 +53,7 @@ The new `model_list` configuration offers several advantages:
   "model_list": [
     {
       "model_name": "gpt4",
-      "model": "openai/gpt-5.2",
+      "model": "openai/gpt-5.4",
       "api_key": "sk-your-openai-key",
       "api_base": "https://api.openai.com/v1"
     },
@@ -70,7 +70,7 @@ The new `model_list` configuration offers several advantages:
   ],
   "agents": {
     "defaults": {
-      "model": "gpt4"
+      "model_name": "gpt4"
     }
   }
 }
@@ -82,7 +82,7 @@ The `model` field uses a protocol prefix format: `[protocol/]model-identifier`
 
 | Prefix | Description | Example |
 |--------|-------------|---------|
-| `openai/` | OpenAI API (default) | `openai/gpt-5.2` |
+| `openai/` | OpenAI API (default) | `openai/gpt-5.4` |
 | `anthropic/` | Anthropic API | `anthropic/claude-opus-4` |
 | `antigravity/` | Google via Antigravity OAuth | `antigravity/gemini-2.0-flash` |
 | `gemini/` | Google Gemini API | `gemini/gemini-2.0-flash-exp` |
@@ -109,7 +109,7 @@ The `model` field uses a protocol prefix format: `[protocol/]model-identifier`
 | Field | Required | Description |
 |-------|----------|-------------|
 | `model_name` | Yes | User-facing alias for the model |
-| `model` | Yes | Protocol and model identifier (e.g., `openai/gpt-5.2`) |
+| `model` | Yes | Protocol and model identifier (e.g., `openai/gpt-5.4`) |
 | `api_base` | No | API endpoint URL |
 | `api_key` | No* | API authentication key |
 | `proxy` | No | HTTP proxy URL |
@@ -130,19 +130,19 @@ Configure multiple endpoints for the same model to distribute load:
   "model_list": [
     {
       "model_name": "gpt4",
-      "model": "openai/gpt-5.2",
+      "model": "openai/gpt-5.4",
       "api_key": "sk-key1",
       "api_base": "https://api1.example.com/v1"
     },
     {
       "model_name": "gpt4",
-      "model": "openai/gpt-5.2",
+      "model": "openai/gpt-5.4",
       "api_key": "sk-key2",
       "api_base": "https://api2.example.com/v1"
     },
     {
       "model_name": "gpt4",
-      "model": "openai/gpt-5.2",
+      "model": "openai/gpt-5.4",
       "api_key": "sk-key3",
       "api_base": "https://api3.example.com/v1"
     }
@@ -184,7 +184,7 @@ During the migration period, your existing `providers` configuration will contin
 - [ ] Identify all providers you're currently using
 - [ ] Create `model_list` entries for each provider
 - [ ] Use appropriate protocol prefixes
-- [ ] Update `agents.defaults.model` to reference the new `model_name`
+- [ ] Update `agents.defaults.model_name` to reference the new `model_name`
 - [ ] Test that all models work correctly
 - [ ] Remove or comment out the old `providers` section
 
@@ -196,7 +196,7 @@ During the migration period, your existing `providers` configuration will contin
 model "xxx" not found in model_list or providers
 ```
 
-**Solution**: Ensure the `model_name` in `model_list` matches the value in `agents.defaults.model`.
+**Solution**: Ensure the `model_name` in `model_list` matches the value in `agents.defaults.model_name`.
 
 ### Unknown protocol error
 
diff --git a/docs/providers.md b/docs/providers.md
new file mode 100644
index 000000000..3a740d3b8
--- /dev/null
+++ b/docs/providers.md
@@ -0,0 +1,466 @@
+# 🔌 Providers & Model Configuration
+
+> Back to [README](../README.md)
+
+### Providers
+
+> [!NOTE]
+> Voice transcription can use a configured multimodal model via `voice.model_name`. Groq Whisper remains available as a fallback when no voice model is configured.
+
+| Provider     | Purpose                                 | Get API Key                                                  |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini`     | LLM (Gemini direct)                     | [aistudio.google.com](https://aistudio.google.com)           |
+| `zhipu`      | LLM (Zhipu direct)                      | [bigmodel.cn](https://bigmodel.cn)                           |
+| `volcengine` | LLM(Volcengine direct)                  | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw)                 |
+| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai)                       |
+| `anthropic`  | LLM (Claude direct)                     | [console.anthropic.com](https://console.anthropic.com)       |
+| `openai`     | LLM (GPT direct)                        | [platform.openai.com](https://platform.openai.com)           |
+| `deepseek`   | LLM (DeepSeek direct)                   | [platform.deepseek.com](https://platform.deepseek.com)       |
+| `qwen`       | LLM (Qwen direct)                       | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq`       | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com)                 |
+| `cerebras`   | LLM (Cerebras direct)                   | [cerebras.ai](https://cerebras.ai)                           |
+| `vivgrid`    | LLM (Vivgrid direct)                    | [vivgrid.com](https://vivgrid.com)                           |
+| `nvidia`     | LLM (NVIDIA NIM)                        | [build.nvidia.com](https://build.nvidia.com)                 |
+| `moonshot`   | LLM (Kimi/Moonshot direct)              | [platform.moonshot.cn](https://platform.moonshot.cn)         |
+| `minimax`    | LLM (Minimax direct)                    | [platform.minimaxi.com](https://platform.minimaxi.com)      |
+| `avian`      | LLM (Avian direct)                      | [avian.io](https://avian.io)                                 |
+| `mistral`    | LLM (Mistral direct)                    | [console.mistral.ai](https://console.mistral.ai)            |
+| `longcat`    | LLM (Longcat direct)                    | [longcat.ai](https://longcat.ai)                             |
+| `modelscope` | LLM (ModelScope direct)                 | [modelscope.cn](https://modelscope.cn)                       |
+
+### Model Configuration (model_list)
+
+> **What's New?** PicoClaw now uses a **model-centric** configuration approach. Simply specify `vendor/model` format (e.g., `zhipu/glm-4.7`) to add new providers—**zero code changes required!**
+
+This design also enables **multi-agent support** with flexible provider selection:
+
+- **Different agents, different providers**: Each agent can use its own LLM provider
+- **Model fallbacks**: Configure primary and fallback models for resilience
+- **Load balancing**: Distribute requests across multiple endpoints
+- **Centralized configuration**: Manage all providers in one place
+
+#### 📋 All Supported Vendors
+
+| Vendor              | `model` Prefix    | Default API Base                                    | Protocol  | API Key                                                          |
+| ------------------- | ----------------- |-----------------------------------------------------| --------- | ---------------------------------------------------------------- |
+| **OpenAI**          | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [Get Key](https://platform.openai.com)                           |
+| **Anthropic**       | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [Get Key](https://console.anthropic.com)                         |
+| **智谱 AI (GLM)**   | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek**        | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [Get Key](https://platform.deepseek.com)                         |
+| **Google Gemini**   | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI    | [Get Key](https://aistudio.google.com/api-keys)                  |
+| **Groq**            | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [Get Key](https://console.groq.com)                              |
+| **Moonshot**        | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [Get Key](https://platform.moonshot.cn)                          |
+| **通义千问 (Qwen)** | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Get Key](https://dashscope.console.aliyun.com)                  |
+| **NVIDIA**          | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [Get Key](https://build.nvidia.com)                              |
+| **Ollama**          | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | Local (no key needed)                                            |
+| **OpenRouter**      | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [Get Key](https://openrouter.ai/keys)                            |
+| **LiteLLM Proxy**   | `litellm/`        | `http://localhost:4000/v1`                          | OpenAI    | Your LiteLLM proxy key                                            |
+| **VLLM**            | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | Local                                                            |
+| **Cerebras**        | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [Get Key](https://cerebras.ai)                                   |
+| **VolcEngine (Doubao)** | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw)                        |
+| **神算云**          | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                |
+| **BytePlus**        | `byteplus/`       | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [Get Key](https://www.byteplus.com)                        |
+| **Vivgrid**         | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [Get Key](https://vivgrid.com)                                   |
+| **LongCat**         | `longcat/`        | `https://api.longcat.chat/openai`                   | OpenAI    | [Get Key](https://longcat.chat/platform)                         |
+| **ModelScope (魔搭)**| `modelscope/`    | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [Get Token](https://modelscope.cn/my/tokens)                     |
+| **Azure OpenAI**    | `azure/`          | `https://{resource}.openai.azure.com`               | Azure     | [Get Key](https://portal.azure.com)                              |
+| **Antigravity**     | `antigravity/`    | Google Cloud                                        | Custom    | OAuth only                                                       |
+| **GitHub Copilot**  | `github-copilot/` | `localhost:4321`                                    | gRPC      | -                                                                |
+
+#### Basic Configuration
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-openai-key"
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "sk-ant-your-key"
+    },
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-zhipu-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "gpt-5.4"
+    }
+  }
+}
+```
+
+#### Voice Transcription
+
+You can configure a dedicated model for audio transcription with `voice.model_name`. This lets you reuse existing multimodal providers that support audio input instead of relying only on Groq.
+
+If `voice.model_name` is not configured, PicoClaw will continue to fall back to Groq transcription when a Groq API key is available.
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "voice-gemini",
+      "model": "gemini/gemini-2.5-flash",
+      "api_key": "your-gemini-key"
+    }
+  ],
+  "voice": {
+    "model_name": "voice-gemini",
+    "echo_transcription": false
+  },
+  "providers": {
+    "groq": {
+      "api_key": "gsk_xxx"
+    }
+  }
+}
+```
+
+#### Vendor-Specific Examples
+
+**OpenAI**
+
+```json
+{
+  "model_name": "gpt-5.4",
+  "model": "openai/gpt-5.4",
+  "api_key": "sk-..."
+}
+```
+
+**VolcEngine (Doubao)**
+
+```json
+{
+  "model_name": "ark-code-latest",
+  "model": "volcengine/ark-code-latest",
+  "api_key": "sk-..."
+}
+```
+
+**智谱 AI (GLM)**
+
+```json
+{
+  "model_name": "glm-4.7",
+  "model": "zhipu/glm-4.7",
+  "api_key": "your-key"
+}
+```
+
+**DeepSeek**
+
+```json
+{
+  "model_name": "deepseek-chat",
+  "model": "deepseek/deepseek-chat",
+  "api_key": "sk-..."
+}
+```
+
+**Anthropic (with API key)**
+
+```json
+{
+  "model_name": "claude-sonnet-4.6",
+  "model": "anthropic/claude-sonnet-4.6",
+  "api_key": "sk-ant-your-key"
+}
+```
+
+> Run `picoclaw auth login --provider anthropic` to paste your API token.
+
+**Anthropic Messages API (native format)**
+
+For direct Anthropic API access or custom endpoints that only support Anthropic's native message format:
+
+```json
+{
+  "model_name": "claude-opus-4-6",
+  "model": "anthropic-messages/claude-opus-4-6",
+  "api_key": "sk-ant-your-key",
+  "api_base": "https://api.anthropic.com"
+}
+```
+
+> Use `anthropic-messages` protocol when:
+> - Using third-party proxies that only support Anthropic's native `/v1/messages` endpoint (not OpenAI-compatible `/v1/chat/completions`)
+> - Connecting to services like MiniMax, Synthetic that require Anthropic's native message format
+> - The existing `anthropic` protocol returns 404 errors (indicating the endpoint doesn't support OpenAI-compatible format)
+>
+> **Note:** The `anthropic` protocol uses OpenAI-compatible format (`/v1/chat/completions`), while `anthropic-messages` uses Anthropic's native format (`/v1/messages`). Choose based on your endpoint's supported format.
+
+**Ollama (local)**
+
+```json
+{
+  "model_name": "llama3",
+  "model": "ollama/llama3"
+}
+```
+
+**Custom Proxy/API**
+
+```json
+{
+  "model_name": "my-custom-model",
+  "model": "openai/custom-model",
+  "api_base": "https://my-proxy.com/v1",
+  "api_key": "sk-...",
+  "request_timeout": 300
+}
+```
+
+**LiteLLM Proxy**
+
+```json
+{
+  "model_name": "lite-gpt4",
+  "model": "litellm/lite-gpt4",
+  "api_base": "http://localhost:4000/v1",
+  "api_key": "sk-..."
+}
+```
+
+PicoClaw strips only the outer `litellm/` prefix before sending the request, so proxy aliases like `litellm/lite-gpt4` send `lite-gpt4`, while `litellm/openai/gpt-4o` sends `openai/gpt-4o`.
+
+#### Load Balancing
+
+Configure multiple endpoints for the same model name—PicoClaw will automatically round-robin between them:
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api1.example.com/v1",
+      "api_key": "sk-key1"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api2.example.com/v1",
+      "api_key": "sk-key2"
+    }
+  ]
+}
+```
+
+#### Migration from Legacy `providers` Config
+
+The old `providers` configuration is **deprecated** but still supported for backward compatibility.
+
+**Old Config (deprecated):**
+
+```json
+{
+  "providers": {
+    "zhipu": {
+      "api_key": "your-key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  },
+  "agents": {
+    "defaults": {
+      "provider": "zhipu",
+      "model": "glm-4.7"
+    }
+  }
+}
+```
+
+**New Config (recommended):**
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "glm-4.7"
+    }
+  }
+}
+```
+
+For detailed migration guide, see [migration/model-list-migration.md](migration/model-list-migration.md).
+
+### Provider Architecture
+
+PicoClaw routes providers by protocol family:
+
+- OpenAI-compatible protocol: OpenRouter, OpenAI-compatible gateways, Groq, Zhipu, and vLLM-style endpoints.
+- Anthropic protocol: Claude-native API behavior.
+- Codex/OAuth path: OpenAI OAuth/token authentication route.
+
+This keeps the runtime lightweight while making new OpenAI-compatible backends mostly a config operation (`api_base` + `api_key`).
+
+<details>
+<summary><b>Zhipu</b></summary>
+
+**1. Get API key and base URL**
+
+* Get [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
+
+**2. Configure**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "providers": {
+    "zhipu": {
+      "api_key": "Your API Key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  }
+}
+```
+
+**3. Run**
+
+```bash
+picoclaw agent -m "Hello"
+```
+
+</details>
+
+<details>
+<summary><b>Full config example</b></summary>
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "anthropic/claude-opus-4-5"
+    }
+  },
+  "session": {
+    "dm_scope": "per-channel-peer"
+  },
+  "providers": {
+    "openrouter": {
+      "api_key": "sk-or-v1-xxx"
+    },
+    "groq": {
+      "api_key": "gsk_xxx"
+    }
+  },
+  "voice": {
+    "model_name": "voice-gemini",
+    "echo_transcription": false
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456:ABC...",
+      "allow_from": ["123456789"]
+    },
+    "discord": {
+      "enabled": true,
+      "token": "",
+      "allow_from": [""]
+    },
+    "whatsapp": {
+      "enabled": false,
+      "bridge_url": "ws://localhost:3001",
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": []
+    },
+    "feishu": {
+      "enabled": false,
+      "app_id": "cli_xxx",
+      "app_secret": "xxx",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    },
+    "qq": {
+      "enabled": false,
+      "app_id": "",
+      "app_secret": "",
+      "allow_from": []
+    }
+  },
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": false,
+        "api_key": "BSA...",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://localhost:8888",
+        "max_results": 5
+      }
+    },
+    "cron": {
+      "exec_timeout_minutes": 5
+    }
+  },
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+</details>
+
+---
+
+## 📝 API Key Comparison
+
+| Service          | Pricing                  | Use Case                              |
+| ---------------- | ------------------------ | ------------------------------------- |
+| **OpenRouter**   | Free: 200K tokens/month  | Multiple models (Claude, GPT-4, etc.) |
+| **Volcengine CodingPlan** | ¥9.9/first month | Best for Chinese users, multiple SOTA models (Doubao, DeepSeek, etc.) |
+| **Zhipu**        | Free: 200K tokens/month  | Suitable for Chinese users                |
+| **Brave Search** | $5/1000 queries          | Web search functionality              |
+| **SearXNG**      | Free (self-hosted)       | Privacy-focused metasearch (70+ engines) |
+| **Groq**         | Free tier available      | Fast inference (Llama, Mixtral)       |
+| **Cerebras**     | Free tier available      | Fast inference (Llama, Qwen, etc.)    |
+| **LongCat**      | Free: up to 5M tokens/day | Fast inference                       |
+| **ModelScope**   | Free: 2000 requests/day  | Inference (Qwen, GLM, DeepSeek, etc.) |
+
+---
+
+<div align="center">
+  <img src="assets/logo.jpg" alt="PicoClaw Meme" width="512">
+</div>
diff --git a/docs/pt-br/ANTIGRAVITY_AUTH.md b/docs/pt-br/ANTIGRAVITY_AUTH.md
new file mode 100644
index 000000000..d243783cb
--- /dev/null
+++ b/docs/pt-br/ANTIGRAVITY_AUTH.md
@@ -0,0 +1,809 @@
+> Voltar ao [README](../../README.pt-br.md)
+
+# Guia de Autenticação e Integração do Antigravity
+
+## Visão Geral
+
+**Antigravity** (Google Cloud Code Assist) é um provedor de modelos de IA apoiado pelo Google que oferece acesso a modelos como Claude Opus 4.6 e Gemini através da infraestrutura de nuvem do Google. Este documento fornece um guia completo sobre como a autenticação funciona, como buscar modelos e como implementar um novo provedor no PicoClaw.
+
+---
+
+## Índice
+
+1. [Fluxo de Autenticação](#fluxo-de-autenticação)
+2. [Detalhes da Implementação OAuth](#detalhes-da-implementação-oauth)
+3. [Gerenciamento de Tokens](#gerenciamento-de-tokens)
+4. [Busca da Lista de Modelos](#busca-da-lista-de-modelos)
+5. [Rastreamento de Uso](#rastreamento-de-uso)
+6. [Estrutura do Plugin do Provedor](#estrutura-do-plugin-do-provedor)
+7. [Requisitos de Integração](#requisitos-de-integração)
+8. [Endpoints da API](#endpoints-da-api)
+9. [Configuração](#configuração)
+10. [Criando um Novo Provedor no PicoClaw](#criando-um-novo-provedor-no-picoclaw)
+
+---
+
+## Fluxo de Autenticação
+
+### 1. OAuth 2.0 com PKCE
+
+O Antigravity utiliza **OAuth 2.0 com PKCE (Proof Key for Code Exchange)** para autenticação segura:
+
+```
+┌─────────────┐                                    ┌─────────────────┐
+│   Client    │ ───(1) Generate PKCE Pair────────> │                 │
+│             │ ───(2) Open Auth URL─────────────> │  Google OAuth   │
+│             │                                    │    Server       │
+│             │ <──(3) Redirect with Code───────── │                 │
+│             │                                    └─────────────────┘
+│             │ ───(4) Exchange Code for Tokens──> │   Token URL     │
+│             │                                    │                 │
+│             │ <──(5) Access + Refresh Tokens──── │                 │
+└─────────────┘                                    └─────────────────┘
+```
+
+### 2. Etapas Detalhadas
+
+#### Etapa 1: Gerar Parâmetros PKCE
+```typescript
+function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = randomBytes(32).toString("hex");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+```
+
+#### Etapa 2: Construir a URL de Autorização
+```typescript
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const REDIRECT_URI = "http://localhost:51121/oauth-callback";
+
+function buildAuthUrl(params: { challenge: string; state: string }): string {
+  const url = new URL(AUTH_URL);
+  url.searchParams.set("client_id", CLIENT_ID);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("redirect_uri", REDIRECT_URI);
+  url.searchParams.set("scope", SCOPES.join(" "));
+  url.searchParams.set("code_challenge", params.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", params.state);
+  url.searchParams.set("access_type", "offline");
+  url.searchParams.set("prompt", "consent");
+  return url.toString();
+}
+```
+
+**Escopos Necessários:**
+```typescript
+const SCOPES = [
+  "https://www.googleapis.com/auth/cloud-platform",
+  "https://www.googleapis.com/auth/userinfo.email",
+  "https://www.googleapis.com/auth/userinfo.profile",
+  "https://www.googleapis.com/auth/cclog",
+  "https://www.googleapis.com/auth/experimentsandconfigs",
+];
+```
+
+#### Etapa 3: Tratar o Callback OAuth
+
+**Modo Automático (Desenvolvimento Local):**
+- Iniciar um servidor HTTP local na porta 51121
+- Aguardar o redirecionamento do Google
+- Extrair o código de autorização dos parâmetros da query
+
+**Modo Manual (Remoto/Sem Interface Gráfica):**
+- Exibir a URL de autorização para o usuário
+- O usuário completa a autenticação no navegador
+- O usuário cola a URL de redirecionamento completa no terminal
+- Analisar o código da URL colada
+
+#### Etapa 4: Trocar o Código por Tokens
+```typescript
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+async function exchangeCode(params: {
+  code: string;
+  verifier: string;
+}): Promise<{ access: string; refresh: string; expires: number }> {
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      code: params.code,
+      grant_type: "authorization_code",
+      redirect_uri: REDIRECT_URI,
+      code_verifier: params.verifier,
+    }),
+  });
+
+  const data = await response.json();
+  
+  return {
+    access: data.access_token,
+    refresh: data.refresh_token,
+    expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, // 5 min buffer
+  };
+}
+```
+
+#### Etapa 5: Buscar Dados Adicionais do Usuário
+
+**E-mail do Usuário:**
+```typescript
+async function fetchUserEmail(accessToken: string): Promise<string | undefined> {
+  const response = await fetch(
+    "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+    { headers: { Authorization: `Bearer ${accessToken}` } }
+  );
+  const data = await response.json();
+  return data.email;
+}
+```
+
+**ID do Projeto (Necessário para chamadas de API):**
+```typescript
+async function fetchProjectId(accessToken: string): Promise<string> {
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "google-api-nodejs-client/9.15.1",
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+    "Client-Metadata": JSON.stringify({
+      ideType: "IDE_UNSPECIFIED",
+      platform: "PLATFORM_UNSPECIFIED",
+      pluginType: "GEMINI",
+    }),
+  };
+
+  const response = await fetch(
+    "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        metadata: {
+          ideType: "IDE_UNSPECIFIED",
+          platform: "PLATFORM_UNSPECIFIED",
+          pluginType: "GEMINI",
+        },
+      }),
+    }
+  );
+
+  const data = await response.json();
+  return data.cloudaicompanionProject || "rising-fact-p41fc"; // Valor padrão de fallback
+}
+```
+
+---
+
+## Detalhes da Implementação OAuth
+
+### Credenciais do Cliente
+
+**Importante:** Estas são codificadas em base64 no código-fonte para sincronização com pi-ai:
+
+```typescript
+const decode = (s: string) => Buffer.from(s, "base64").toString();
+
+const CLIENT_ID = decode(
+  "MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ=="
+);
+const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
+```
+
+### Modos do Fluxo OAuth
+
+1. **Fluxo Automático** (máquinas locais com navegador):
+   - Abre o navegador automaticamente
+   - O servidor de callback local captura o redirecionamento
+   - Nenhuma interação do usuário necessária após a autenticação inicial
+
+2. **Fluxo Manual** (remoto/sem interface/WSL2):
+   - URL exibida para copiar e colar manualmente
+   - O usuário completa a autenticação em um navegador externo
+   - O usuário cola a URL de redirecionamento completa de volta
+
+```typescript
+function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+  return isRemote || isWSL2Sync();
+}
+```
+
+---
+
+## Gerenciamento de Tokens
+
+### Estrutura do Perfil de Autenticação
+
+```typescript
+type OAuthCredential = {
+  type: "oauth";
+  provider: "google-antigravity";
+  access: string;           // Token de acesso
+  refresh: string;          // Token de atualização
+  expires: number;          // Timestamp de expiração (ms desde epoch)
+  email?: string;           // E-mail do usuário
+  projectId?: string;       // ID do projeto Google Cloud
+};
+```
+
+### Atualização de Tokens
+
+A credencial inclui um token de atualização que pode ser usado para obter novos tokens de acesso quando o atual expira. A expiração é definida com um buffer de 5 minutos para evitar condições de corrida.
+
+---
+
+## Busca da Lista de Modelos
+
+### Buscar Modelos Disponíveis
+
+```typescript
+const BASE_URL = "https://cloudcode-pa.googleapis.com";
+
+async function fetchAvailableModels(
+  accessToken: string,
+  projectId: string
+): Promise<Model[]> {
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "antigravity",
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+  };
+
+  const response = await fetch(
+    `${BASE_URL}/v1internal:fetchAvailableModels`,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ project: projectId }),
+    }
+  );
+
+  const data = await response.json();
+  
+  // Retorna modelos com informações de cota
+  return Object.entries(data.models).map(([modelId, modelInfo]) => ({
+    id: modelId,
+    displayName: modelInfo.displayName,
+    quotaInfo: {
+      remainingFraction: modelInfo.quotaInfo?.remainingFraction,
+      resetTime: modelInfo.quotaInfo?.resetTime,
+      isExhausted: modelInfo.quotaInfo?.isExhausted,
+    },
+  }));
+}
+```
+
+### Formato da Resposta
+
+```typescript
+type FetchAvailableModelsResponse = {
+  models?: Record<string, {
+    displayName?: string;
+    quotaInfo?: {
+      remainingFraction?: number | string;
+      resetTime?: string;      // Timestamp ISO 8601
+      isExhausted?: boolean;
+    };
+  }>;
+};
+```
+
+---
+
+## Rastreamento de Uso
+
+### Buscar Dados de Uso
+
+```typescript
+export async function fetchAntigravityUsage(
+  token: string,
+  timeoutMs: number
+): Promise<ProviderUsageSnapshot> {
+  // 1. Buscar créditos e informações do plano
+  const loadCodeAssistRes = await fetch(
+    `${BASE_URL}/v1internal:loadCodeAssist`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        metadata: {
+          ideType: "ANTIGRAVITY",
+          platform: "PLATFORM_UNSPECIFIED",
+          pluginType: "GEMINI",
+        },
+      }),
+    }
+  );
+
+  // Extrair informações de créditos
+  const { availablePromptCredits, planInfo, currentTier } = data;
+  
+  // 2. Buscar cotas dos modelos
+  const modelsRes = await fetch(
+    `${BASE_URL}/v1internal:fetchAvailableModels`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ project: projectId }),
+    }
+  );
+
+  // Construir janelas de uso
+  return {
+    provider: "google-antigravity",
+    displayName: "Google Antigravity",
+    windows: [
+      { label: "Credits", usedPercent: calculateUsedPercent(available, monthly) },
+      // Cotas individuais dos modelos...
+    ],
+    plan: currentTier?.name || planType,
+  };
+}
+```
+
+### Estrutura da Resposta de Uso
+
+```typescript
+type ProviderUsageSnapshot = {
+  provider: "google-antigravity";
+  displayName: string;
+  windows: UsageWindow[];
+  plan?: string;
+  error?: string;
+};
+
+type UsageWindow = {
+  label: string;           // "Credits" ou ID do modelo
+  usedPercent: number;     // 0-100
+  resetAt?: number;        // Timestamp de quando a cota é redefinida
+};
+```
+
+---
+
+## Estrutura do Plugin do Provedor
+
+### Definição do Plugin
+
+```typescript
+const antigravityPlugin = {
+  id: "google-antigravity-auth",
+  name: "Google Antigravity Auth",
+  description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
+  configSchema: emptyPluginConfigSchema(),
+  
+  register(api: PicoClawPluginApi) {
+    api.registerProvider({
+      id: "google-antigravity",
+      label: "Google Antigravity",
+      docsPath: "/providers/models",
+      aliases: ["antigravity"],
+      
+      auth: [
+        {
+          id: "oauth",
+          label: "Google OAuth",
+          hint: "PKCE + localhost callback",
+          kind: "oauth",
+          run: async (ctx: ProviderAuthContext) => {
+            // Implementação OAuth aqui
+          },
+        },
+      ],
+    });
+  },
+};
+```
+
+### ProviderAuthContext
+
+```typescript
+type ProviderAuthContext = {
+  config: PicoClawConfig;
+  agentDir?: string;
+  workspaceDir?: string;
+  prompter: WizardPrompter;      // Prompts/notificações da UI
+  runtime: RuntimeEnv;           // Logging, etc.
+  isRemote: boolean;             // Se está executando remotamente
+  openUrl: (url: string) => Promise<void>;  // Abridor de navegador
+  oauth: {
+    createVpsAwareHandlers: Function;
+  };
+};
+```
+
+### ProviderAuthResult
+
+```typescript
+type ProviderAuthResult = {
+  profiles: Array<{
+    profileId: string;
+    credential: AuthProfileCredential;
+  }>;
+  configPatch?: Partial<PicoClawConfig>;
+  defaultModel?: string;
+  notes?: string[];
+};
+```
+
+---
+
+## Requisitos de Integração
+
+### 1. Ambiente/Dependências Necessários
+
+- Go ≥ 1.25
+- Base de código do PicoClaw (`pkg/providers/` e `pkg/auth/`)
+- Pacotes da biblioteca padrão `crypto` e `net/http`
+
+### 2. Cabeçalhos Necessários para Chamadas de API
+
+```typescript
+const REQUIRED_HEADERS = {
+  "Authorization": `Bearer ${accessToken}`,
+  "Content-Type": "application/json",
+  "User-Agent": "antigravity",  // ou "google-api-nodejs-client/9.15.1"
+  "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+};
+
+// Para chamadas loadCodeAssist, incluir também:
+const CLIENT_METADATA = {
+  ideType: "ANTIGRAVITY",  // ou "IDE_UNSPECIFIED"
+  platform: "PLATFORM_UNSPECIFIED",
+  pluginType: "GEMINI",
+};
+```
+
+### 3. Sanitização de Schemas de Modelos
+
+O Antigravity usa modelos compatíveis com Gemini, então os schemas de ferramentas devem ser sanitizados:
+
+```typescript
+const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
+  "patternProperties",
+  "additionalProperties",
+  "$schema",
+  "$id",
+  "$ref",
+  "$defs",
+  "definitions",
+  "examples",
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+  "multipleOf",
+  "pattern",
+  "format",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minProperties",
+  "maxProperties",
+]);
+
+// Limpar schema antes de enviar
+function cleanToolSchemaForGemini(schema: Record<string, unknown>): unknown {
+  // Remover palavras-chave não suportadas
+  // Garantir que o nível superior tenha type: "object"
+  // Achatar uniões anyOf/oneOf
+}
+```
+
+### 4. Tratamento de Blocos de Pensamento (Modelos Claude)
+
+Para modelos Claude via Antigravity, os blocos de pensamento requerem tratamento especial:
+
+```typescript
+const ANTIGRAVITY_SIGNATURE_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+export function sanitizeAntigravityThinkingBlocks(
+  messages: AgentMessage[]
+): AgentMessage[] {
+  // Validar assinaturas de pensamento
+  // Normalizar campos de assinatura
+  // Descartar blocos de pensamento não assinados
+}
+```
+
+---
+
+## Endpoints da API
+
+### Endpoints de Autenticação
+
+| Endpoint | Método | Finalidade |
+|----------|--------|-----------|
+| `https://accounts.google.com/o/oauth2/v2/auth` | GET | Autorização OAuth |
+| `https://oauth2.googleapis.com/token` | POST | Troca de tokens |
+| `https://www.googleapis.com/oauth2/v1/userinfo` | GET | Informações do usuário (e-mail) |
+
+### Endpoints do Cloud Code Assist
+
+| Endpoint | Método | Finalidade |
+|----------|--------|-----------|
+| `https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` | POST | Carregar informações do projeto, créditos, plano |
+| `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` | POST | Listar modelos disponíveis com cotas |
+| `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse` | POST | Endpoint de streaming de chat |
+
+**Formato de Requisição da API (Chat):**
+O endpoint `v1internal:streamGenerateContent` espera um envelope encapsulando a requisição Gemini padrão:
+
+```json
+{
+  "project": "your-project-id",
+  "model": "model-id",
+  "request": {
+    "contents": [...],
+    "systemInstruction": {...},
+    "generationConfig": {...},
+    "tools": [...]
+  },
+  "requestType": "agent",
+  "userAgent": "antigravity",
+  "requestId": "agent-timestamp-random"
+}
+```
+
+**Formato de Resposta da API (SSE):**
+Cada mensagem SSE (`data: {...}`) é encapsulada em um campo `response`:
+
+```json
+{
+  "response": {
+    "candidates": [...],
+    "usageMetadata": {...},
+    "modelVersion": "...",
+    "responseId": "..."
+  },
+  "traceId": "...",
+  "metadata": {}
+}
+```
+
+---
+
+## Configuração
+
+### Configuração do config.json
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gemini-flash",
+      "model": "antigravity/gemini-3-flash",
+      "auth_method": "oauth"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "gemini-flash"
+    }
+  }
+}
+```
+
+### Armazenamento do Perfil de Autenticação
+
+Os perfis de autenticação são armazenados em `~/.picoclaw/auth.json`:
+
+```json
+{
+  "credentials": {
+    "google-antigravity": {
+      "access_token": "ya29...",
+      "refresh_token": "1//...",
+      "expires_at": "2026-01-01T00:00:00Z",
+      "provider": "google-antigravity",
+      "auth_method": "oauth",
+      "email": "user@example.com",
+      "project_id": "my-project-id"
+    }
+  }
+}
+```
+
+---
+
+## Criando um Novo Provedor no PicoClaw
+
+Os provedores do PicoClaw são implementados como pacotes Go em `pkg/providers/`. Para adicionar um novo provedor:
+
+### Implementação Passo a Passo
+
+#### 1. Criar o Arquivo do Provedor
+
+Crie um novo arquivo Go em `pkg/providers/`:
+
+```
+pkg/providers/
+└── your_provider.go
+```
+
+#### 2. Implementar a Interface Provider
+
+Seu provedor deve implementar a interface `Provider` definida em `pkg/providers/types.go`:
+
+```go
+package providers
+
+type YourProvider struct {
+    apiKey  string
+    apiBase string
+}
+
+func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
+    if apiBase == "" {
+        apiBase = "https://api.your-provider.com/v1"
+    }
+    return &YourProvider{apiKey: apiKey, apiBase: apiBase}
+}
+
+func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
+    // Implementar conclusão de chat com streaming
+}
+```
+
+#### 3. Registrar na Factory
+
+Adicione seu provedor ao switch de protocolo em `pkg/providers/factory.go`:
+
+```go
+case "your-provider":
+    return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
+```
+
+#### 4. Adicionar Configuração Padrão (Opcional)
+
+Adicione uma entrada padrão em `pkg/config/defaults.go`:
+
+```go
+{
+    ModelName: "your-model",
+    Model:     "your-provider/model-name",
+    APIKey:    "",
+},
+```
+
+#### 5. Adicionar Suporte de Autenticação (Opcional)
+
+Se seu provedor requer OAuth ou autenticação especial, adicione um caso em `cmd/picoclaw/internal/auth/helpers.go`:
+
+```go
+case "your-provider":
+    authLoginYourProvider()
+```
+
+#### 6. Configurar via `config.json`
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "your-model",
+      "model": "your-provider/model-name",
+      "api_key": "your-api-key",
+      "api_base": "https://api.your-provider.com/v1"
+    }
+  ]
+}
+```
+
+---
+
+## Testando Sua Implementação
+
+### Comandos CLI
+
+```bash
+# Autenticar com um provedor
+picoclaw auth login --provider your-provider
+
+# Listar modelos (para Antigravity)
+picoclaw auth models
+
+# Iniciar o gateway
+picoclaw gateway
+
+# Executar um agente com um modelo específico
+picoclaw agent -m "Hello" --model your-model
+```
+
+### Variáveis de Ambiente para Testes
+
+```bash
+# Substituir o modelo padrão
+export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
+
+# Substituir configurações do provedor
+export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
+```
+
+---
+
+## Referências
+
+- **Arquivos Fonte:**
+  - `pkg/providers/antigravity_provider.go` - Implementação do provedor Antigravity
+  - `pkg/auth/oauth.go` - Implementação do fluxo OAuth
+  - `pkg/auth/store.go` - Armazenamento de credenciais de autenticação (`~/.picoclaw/auth.json`)
+  - `pkg/providers/factory.go` - Factory de provedores e roteamento de protocolo
+  - `pkg/providers/types.go` - Definições da interface do provedor
+  - `cmd/picoclaw/internal/auth/helpers.go` - Comandos CLI de autenticação
+
+- **Documentação:**
+  - `docs/ANTIGRAVITY_USAGE.md` - Guia de uso do Antigravity
+  - `docs/migration/model-list-migration.md` - Guia de migração
+
+---
+
+## Observações
+
+1. **Projeto Google Cloud:** O Antigravity requer que o Gemini for Google Cloud esteja habilitado no seu projeto Google Cloud
+2. **Cotas:** Usa cotas do projeto Google Cloud (sem cobrança separada)
+3. **Acesso a Modelos:** Os modelos disponíveis dependem da configuração do seu projeto Google Cloud
+4. **Blocos de Pensamento:** Modelos Claude via Antigravity requerem tratamento especial de blocos de pensamento com assinaturas
+5. **Sanitização de Schemas:** Os schemas de ferramentas devem ser sanitizados para remover palavras-chave JSON Schema não suportadas
+
+---
+
+---
+
+## Tratamento de Erros Comuns
+
+### 1. Limitação de Taxa (HTTP 429)
+
+O Antigravity retorna um erro 429 quando as cotas do projeto/modelo estão esgotadas. A resposta de erro frequentemente contém um `quotaResetDelay` no campo `details`.
+
+**Exemplo de Erro 429:**
+```json
+{
+  "error": {
+    "code": 429,
+    "message": "You have exhausted your capacity on this model. Your quota will reset after 4h30m28s.",
+    "status": "RESOURCE_EXHAUSTED",
+    "details": [
+      {
+        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+        "metadata": {
+          "quotaResetDelay": "4h30m28.060903746s"
+        }
+      }
+    ]
+  }
+}
+```
+
+### 2. Respostas Vazias (Modelos Restritos)
+
+Alguns modelos podem aparecer na lista de modelos disponíveis, mas retornar uma resposta vazia (200 OK mas stream SSE vazio). Isso geralmente acontece com modelos em preview ou restritos que o projeto atual não tem permissão para usar.
+
+**Tratamento:** Tratar respostas vazias como erros informando ao usuário que o modelo pode estar restrito ou inválido para seu projeto.
+
+---
+
+## Solução de Problemas
+
+### "Token expired" (token expirado)
+- Atualizar tokens OAuth: `picoclaw auth login --provider antigravity`
+
+### "Gemini for Google Cloud is not enabled" (Gemini for Google Cloud não está habilitado)
+- Habilitar a API no seu Google Cloud Console
+
+### "Project not found" (projeto não encontrado)
+- Verificar se seu projeto Google Cloud tem as APIs necessárias habilitadas
+- Verificar se o ID do projeto foi obtido corretamente durante a autenticação
+
+### Modelos não aparecem na lista
+- Verificar se a autenticação OAuth foi concluída com sucesso
+- Verificar o armazenamento do perfil de autenticação: `~/.picoclaw/auth.json`
+- Executar novamente `picoclaw auth login --provider antigravity`
diff --git a/docs/pt-br/ANTIGRAVITY_USAGE.md b/docs/pt-br/ANTIGRAVITY_USAGE.md
new file mode 100644
index 000000000..d4b681ad0
--- /dev/null
+++ b/docs/pt-br/ANTIGRAVITY_USAGE.md
@@ -0,0 +1,72 @@
+> Voltar ao [README](../../README.pt-br.md)
+
+# Usando o provedor Antigravity no PicoClaw
+
+Este guia explica como configurar e usar o provedor **Antigravity** (Google Cloud Code Assist) no PicoClaw.
+
+## Pré-requisitos
+
+1.  Uma conta Google.
+2.  Google Cloud Code Assist habilitado (geralmente disponível através da integração "Gemini for Google Cloud").
+
+## 1. Autenticação
+
+Para se autenticar com o Antigravity, execute o seguinte comando:
+
+```bash
+picoclaw auth login --provider antigravity
+```
+
+### Autenticação manual (Headless/VPS)
+Se você está executando em um servidor (Coolify/Docker) e não consegue acessar `localhost`, siga estas etapas:
+1.  Execute o comando acima.
+2.  Copie a URL fornecida e abra-a no seu navegador local.
+3.  Complete o login.
+4.  Seu navegador será redirecionado para uma URL `localhost:51121` (que não carregará).
+5.  **Copie essa URL final** da barra de endereços do seu navegador.
+6.  **Cole-a de volta no terminal** onde o PicoClaw está aguardando.
+
+O PicoClaw extrairá automaticamente o código de autorização e completará o processo.
+
+## 2. Gerenciando modelos
+
+### Listar modelos disponíveis
+Para ver quais modelos seu projeto tem acesso e verificar suas cotas:
+
+```bash
+picoclaw auth models
+```
+
+### Trocar de modelo
+Você pode alterar o modelo padrão em `~/.picoclaw/config.json` ou substituí-lo via CLI:
+
+```bash
+# Substituir para um único comando
+picoclaw agent -m "Hello" --model claude-opus-4-6-thinking
+```
+
+## 3. Uso em produção (Coolify/Docker)
+
+Se você está implantando via Coolify ou Docker, siga estas etapas para testar:
+
+1.  **Variáveis de ambiente**:
+    *   `PICOCLAW_AGENTS_DEFAULTS_MODEL=gemini-flash`
+2.  **Persistência da autenticação**:
+    Se você já fez login localmente, pode copiar suas credenciais para o servidor:
+    ```bash
+    scp ~/.picoclaw/auth.json user@your-server:~/.picoclaw/
+    ```
+    *Alternativamente*, execute o comando `auth login` uma vez no servidor se você tiver acesso ao terminal.
+
+## 4. Solução de problemas
+
+*   **Resposta vazia**: Se um modelo retorna uma resposta vazia, ele pode estar restrito para o seu projeto. Tente `gemini-3-flash` ou `claude-opus-4-6-thinking`.
+*   **429 Limite de taxa**: O Antigravity possui cotas rigorosas. O PicoClaw exibirá o "tempo de redefinição" na mensagem de erro se você atingir um limite.
+*   **404 Não encontrado**: Certifique-se de que está usando um ID de modelo da lista `picoclaw auth models`. Use o ID curto (ex.: `gemini-3-flash`) e não o caminho completo.
+
+## 5. Resumo dos modelos funcionais
+
+Com base nos testes, os seguintes modelos são os mais confiáveis:
+*   `gemini-3-flash` (Rápido, alta disponibilidade)
+*   `gemini-2.5-flash-lite` (Leve)
+*   `claude-opus-4-6-thinking` (Poderoso, inclui raciocínio)
diff --git a/docs/pt-br/chat-apps.md b/docs/pt-br/chat-apps.md
new file mode 100644
index 000000000..92fda329c
--- /dev/null
+++ b/docs/pt-br/chat-apps.md
@@ -0,0 +1,674 @@
+# 💬 Configuração de Aplicativos de Chat
+
+> Voltar ao [README](../../README.pt-br.md)
+
+## 💬 Aplicativos de Chat
+
+Converse com seu picoclaw através do Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, WeCom, Feishu, Slack, IRC, OneBot ou MaixCam
+
+> **Nota**: Todos os canais baseados em webhook (LINE, WeCom, etc.) são servidos em um único servidor HTTP Gateway compartilhado (`gateway.host`:`gateway.port`, padrão `127.0.0.1:18790`). Não há portas por canal para configurar. Nota: Feishu usa o modo WebSocket/SDK e não utiliza o servidor HTTP webhook compartilhado.
+
+| Canal                | Dificuldade        | Descrição                                             | Documentação                                                                                                     |
+| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Telegram**         | ⭐ Fácil           | Recomendado, voz para texto, long polling (sem IP público) | [Documentação](../channels/telegram/README.pt-br.md)                                                       |
+| **Discord**          | ⭐ Fácil           | Socket Mode, suporte a grupos/DM, ecossistema bot rico | [Documentação](../channels/discord/README.pt-br.md)                                                            |
+| **WhatsApp**         | ⭐ Fácil           | Nativo (scan QR) ou Bridge URL                        | [Documentação](#whatsapp)                                                                                        |
+| **Weixin**           | ⭐ Fácil           | Scan QR nativo (API Tencent iLink)                    | [Documentação](#weixin)                                                                                          |
+| **Slack**            | ⭐ Fácil           | **Socket Mode** (sem IP público), empresarial         | [Documentação](../channels/slack/README.pt-br.md)                                                               |
+| **Matrix**           | ⭐⭐ Médio         | Protocolo federado, suporte a auto-hospedagem         | [Documentação](../channels/matrix/README.pt-br.md)                                                              |
+| **QQ**               | ⭐⭐ Médio         | API bot oficial, comunidade chinesa                   | [Documentação](../channels/qq/README.pt-br.md)                                                                  |
+| **DingTalk**         | ⭐⭐ Médio         | Modo Stream (sem IP público), empresarial             | [Documentação](../channels/dingtalk/README.pt-br.md)                                                            |
+| **LINE**             | ⭐⭐⭐ Avançado    | HTTPS Webhook obrigatório                             | [Documentação](../channels/line/README.pt-br.md)                                                                |
+| **WeCom (企业微信)** | ⭐⭐⭐ Avançado    | Bot de grupo (Webhook), app personalizado (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.pt-br.md) / [App](../channels/wecom/wecom_app/README.pt-br.md) / [AI Bot](../channels/wecom/wecom_aibot/README.pt-br.md) |
+| **Feishu (飞书)**    | ⭐⭐⭐ Avançado    | Colaboração empresarial, rico em recursos             | [Documentação](../channels/feishu/README.pt-br.md)                                                              |
+| **IRC**              | ⭐⭐ Médio         | Servidor + configuração TLS                           | [Documentação](#irc) |
+| **OneBot**           | ⭐⭐ Médio         | Compatível com NapCat/Go-CQHTTP, ecossistema comunitário | [Documentação](../channels/onebot/README.pt-br.md)                                                           |
+| **MaixCam**          | ⭐ Fácil           | Canal de integração de hardware para câmeras AI Sipeed | [Documentação](../channels/maixcam/README.pt-br.md)                                                            |
+| **Pico**             | ⭐ Fácil           | Canal de protocolo nativo PicoClaw                    |                                                                                                                  |
+
+<a id="telegram"></a>
+<details>
+<summary><b>Telegram</b> (Recomendado)</summary>
+
+**1. Criar um bot**
+
+* Abra o Telegram, pesquise `@BotFather`
+* Envie `/newbot`, siga as instruções
+* Copie o token
+
+**2. Configurar**
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+> Obtenha seu ID de usuário com `@userinfobot` no Telegram.
+
+**3. Executar**
+
+```bash
+picoclaw gateway
+```
+
+**4. Menu de comandos do Telegram (registrado automaticamente na inicialização)**
+
+O PicoClaw agora mantém definições de comandos em um registro compartilhado. Na inicialização, o Telegram registrará automaticamente os comandos de bot suportados (por exemplo `/start`, `/help`, `/show`, `/list`) para que o menu de comandos e o comportamento em tempo de execução permaneçam sincronizados.
+O registro do menu de comandos do Telegram permanece como descoberta UX local do canal; a execução genérica de comandos é tratada centralmente no loop do agente via commands executor.
+
+Se o registro de comandos falhar (erros transitórios de rede/API), o canal ainda inicia e o PicoClaw tenta novamente o registro em segundo plano.
+
+</details>
+
+<a id="discord"></a>
+<details>
+<summary><b>Discord</b></summary>
+
+**1. Criar um bot**
+
+* Acesse <https://discord.com/developers/applications>
+* Crie um aplicativo → Bot → Add Bot
+* Copie o token do bot
+
+**2. Habilitar intents**
+
+* Nas configurações do Bot, habilite **MESSAGE CONTENT INTENT**
+* (Opcional) Habilite **SERVER MEMBERS INTENT** se planeja usar listas de permissão baseadas em dados de membros
+
+**3. Obter seu User ID**
+* Configurações do Discord → Avançado → habilite **Developer Mode**
+* Clique com o botão direito no seu avatar → **Copy User ID**
+
+**4. Configurar**
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**5. Convidar o bot**
+
+* OAuth2 → URL Generator
+* Scopes: `bot`
+* Bot Permissions: `Send Messages`, `Read Message History`
+* Abra a URL de convite gerada e adicione o bot ao seu servidor
+
+**Opcional: Modo de ativação em grupo**
+
+Por padrão, o bot responde a todas as mensagens em um canal do servidor. Para restringir respostas apenas a @menções, adicione:
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "mention_only": true }
+    }
+  }
+}
+```
+
+Você também pode ativar por prefixos de palavras-chave (ex.: `!bot`):
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "prefixes": ["!bot"] }
+    }
+  }
+}
+```
+
+**6. Executar**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="whatsapp"></a>
+<details>
+<summary><b>WhatsApp</b> (nativo via whatsmeow)</summary>
+
+O PicoClaw pode se conectar ao WhatsApp de duas formas:
+
+- **Nativo (recomendado):** In-process usando [whatsmeow](https://github.com/tulir/whatsmeow). Sem bridge separado. Defina `"use_native": true` e deixe `bridge_url` vazio. Na primeira execução, escaneie o QR code com o WhatsApp (Dispositivos Vinculados). A sessão é armazenada no seu workspace (ex.: `workspace/whatsapp/`). O canal nativo é **opcional** para manter o binário padrão pequeno; compile com `-tags whatsapp_native` (ex.: `make build-whatsapp-native` ou `go build -tags whatsapp_native ./cmd/...`).
+- **Bridge:** Conecte-se a um bridge WebSocket externo. Defina `bridge_url` (ex.: `ws://localhost:3001`) e mantenha `use_native` como false.
+
+**Configurar (nativo)**
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "use_native": true,
+      "session_store_path": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+Se `session_store_path` estiver vazio, a sessão é armazenada em `<workspace>/whatsapp/`. Execute `picoclaw gateway`; na primeira execução, escaneie o QR code impresso no terminal com WhatsApp → Dispositivos Vinculados.
+
+</details>
+
+<a id="weixin"></a>
+<details>
+<summary><b>Weixin</b> (WeChat Pessoal)</summary>
+
+O PicoClaw suporta conexão com sua conta pessoal do WeChat usando a API oficial Tencent iLink.
+
+**1. Login**
+
+Execute o fluxo de login interativo por QR code:
+```bash
+picoclaw auth weixin
+```
+Escaneie o QR code exibido com seu aplicativo WeChat mobile. Após o login bem-sucedido, o token é salvo na sua configuração.
+
+**2. Configurar**
+
+(Opcional) Adicione seu ID de usuário WeChat em `allow_from` para restringir quem pode enviar mensagens ao bot:
+```json
+{
+  "channels": {
+    "weixin": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**3. Executar**
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="qq"></a>
+<details>
+<summary><b>QQ</b></summary>
+
+**Configuração rápida (recomendada)**
+
+A QQ Open Platform oferece uma página de configuração com um clique para bots compatíveis com OpenClaw:
+
+1. Abra o [QQ Bot Quick Start](https://q.qq.com/qqbot/openclaw/index.html) e escaneie o QR code para fazer login
+2. Um bot é criado automaticamente — copie o **App ID** e o **App Secret**
+3. Configure o PicoClaw:
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+4. Execute `picoclaw gateway` e abra o QQ para conversar com seu bot
+
+> O App Secret é exibido apenas uma vez. Salve-o imediatamente — visualizá-lo novamente forçará uma redefinição.
+>
+> Bots criados pela página de configuração rápida são inicialmente apenas para o criador e não suportam chats de grupo. Para habilitar o acesso em grupo, configure o modo sandbox na [QQ Open Platform](https://q.qq.com/).
+
+**Configuração manual**
+
+Se preferir criar o bot manualmente:
+
+* Faça login na [QQ Open Platform](https://q.qq.com/) para se registrar como desenvolvedor
+* Crie um bot QQ — personalize seu avatar e nome
+* Copie o **App ID** e o **App Secret** nas configurações do bot
+* Configure conforme mostrado acima e execute `picoclaw gateway`
+
+</details>
+
+<a id="dingtalk"></a>
+<details>
+<summary><b>DingTalk</b></summary>
+
+**1. Criar um bot**
+
+* Acesse a [Open Platform](https://open.dingtalk.com/)
+* Crie um aplicativo interno
+* Copie o Client ID e o Client Secret
+
+**2. Configurar**
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Defina `allow_from` como vazio para permitir todos os usuários, ou especifique IDs de usuário DingTalk para restringir o acesso.
+
+**3. Executar**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="maixcam"></a>
+<details>
+<summary><b>MaixCam</b></summary>
+
+Canal de integração projetado especificamente para hardware de câmera AI Sipeed.
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true
+    }
+  }
+}
+```
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+
+<a id="matrix"></a>
+<details>
+<summary><b>Matrix</b></summary>
+
+**1. Preparar conta do bot**
+
+* Use seu homeserver preferido (ex.: `https://matrix.org` ou auto-hospedado)
+* Crie um usuário bot e obtenha seu access token
+
+**2. Configurar**
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. Executar**
+
+```bash
+picoclaw gateway
+```
+
+Para opções completas (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), veja o [Guia de Configuração do Canal Matrix](../channels/matrix/README.md).
+
+</details>
+
+<a id="line"></a>
+<details>
+<summary><b>LINE</b></summary>
+
+**1. Criar uma Conta Oficial LINE**
+
+- Acesse o [LINE Developers Console](https://developers.line.biz/)
+- Crie um provider → Crie um canal Messaging API
+- Copie o **Channel Secret** e o **Channel Access Token**
+
+**2. Configurar**
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> O webhook do LINE é servido no servidor Gateway compartilhado (`gateway.host`:`gateway.port`, padrão `127.0.0.1:18790`).
+
+**3. Configurar URL do Webhook**
+
+O LINE requer HTTPS para webhooks. Use um proxy reverso ou túnel:
+
+```bash
+# Exemplo com ngrok (porta padrão do gateway é 18790)
+ngrok http 18790
+```
+
+Em seguida, defina a URL do Webhook no LINE Developers Console como `https://your-domain/webhook/line` e habilite **Use webhook**.
+
+**4. Executar**
+
+```bash
+picoclaw gateway
+```
+
+> Em chats de grupo, o bot responde apenas quando @mencionado. As respostas citam a mensagem original.
+
+</details>
+
+<a id="wecom"></a>
+<details>
+<summary><b>WeCom (企业微信)</b></summary>
+
+O PicoClaw suporta três tipos de integração WeCom:
+
+**Opção 1: WeCom Bot (Bot)** - Configuração mais fácil, suporta chats de grupo
+**Opção 2: WeCom App (App Personalizado)** - Mais recursos, mensagens proativas, apenas chat privado
+**Opção 3: WeCom AI Bot (AI Bot)** - AI Bot oficial, respostas em streaming, suporta chat de grupo e privado
+
+Veja o [Guia de Configuração do WeCom AI Bot](../channels/wecom/wecom_aibot/README.pt-br.md) para instruções detalhadas de configuração.
+
+**Configuração Rápida - WeCom Bot:**
+
+**1. Criar um bot**
+
+* Acesse o Console de Administração WeCom → Chat de Grupo → Adicionar Bot de Grupo
+* Copie a URL do webhook (formato: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
+
+**2. Configurar**
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+      "webhook_path": "/webhook/wecom",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> O webhook do WeCom é servido no servidor Gateway compartilhado (`gateway.host`:`gateway.port`, padrão `127.0.0.1:18790`).
+
+**Configuração Rápida - WeCom App:**
+
+**1. Criar um aplicativo**
+
+* Acesse o Console de Administração WeCom → Gerenciamento de Apps → Criar App
+* Copie o **AgentId** e o **Secret**
+* Acesse a página "Minha Empresa", copie o **CorpID**
+
+**2. Configurar recebimento de mensagens**
+
+* Nos detalhes do App, clique em "Receber Mensagem" → "Configurar API"
+* Defina a URL como `http://your-server:18790/webhook/wecom-app`
+* Gere o **Token** e o **EncodingAESKey**
+
+**3. Configurar**
+
+```json
+{
+  "channels": {
+    "wecom_app": {
+      "enabled": true,
+      "corp_id": "wwxxxxxxxxxxxxxxxx",
+      "corp_secret": "YOUR_CORP_SECRET",
+      "agent_id": 1000002,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**4. Executar**
+
+```bash
+picoclaw gateway
+```
+
+> **Nota**: Os callbacks de webhook do WeCom são servidos na porta do Gateway (padrão 18790). Use um proxy reverso para HTTPS.
+
+**Configuração Rápida - WeCom AI Bot:**
+
+**1. Criar um AI Bot**
+
+* Acesse o Console de Administração WeCom → Gerenciamento de Apps → AI Bot
+* Nas configurações do AI Bot, configure a URL de callback: `http://your-server:18790/webhook/wecom-aibot`
+* Copie o **Token** e clique em "Gerar Aleatoriamente" para o **EncodingAESKey**
+
+**2. Configurar**
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-aibot",
+      "allow_from": [],
+      "welcome_message": "Hello! How can I help you?"
+    }
+  }
+}
+```
+
+**3. Executar**
+
+```bash
+picoclaw gateway
+```
+
+> **Nota**: O WeCom AI Bot usa protocolo de streaming pull — sem preocupações com timeout de resposta. Tarefas longas (>30 segundos) mudam automaticamente para entrega via `response_url` push.
+
+</details>
+
+<a id="feishu"></a>
+<details>
+<summary><b>Feishu (Lark)</b></summary>
+
+O PicoClaw se conecta ao Feishu via modo WebSocket/SDK — não é necessário URL de webhook público nem servidor de callback.
+
+**1. Criar um aplicativo**
+
+* Acesse a [Feishu Open Platform](https://open.feishu.cn/) e crie um aplicativo
+* Nas configurações do aplicativo, habilite a capacidade **Bot**
+* Crie uma versão e publique o aplicativo (o aplicativo deve ser publicado para funcionar)
+* Copie o **App ID** (começa com `cli_`) e o **App Secret**
+
+**2. Configurar**
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "app_id": "cli_xxx",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+Opcional: `encrypt_key` e `verification_token` para criptografia de eventos (recomendado para produção).
+
+**3. Executar e conversar**
+
+```bash
+picoclaw gateway
+```
+
+Abra o Feishu, pesquise o nome do seu bot e comece a conversar. Você também pode adicionar o bot a um grupo — use `group_trigger.mention_only: true` para responder apenas quando @mencionado.
+
+Para opções completas, veja o [Guia de Configuração do Canal Feishu](../channels/feishu/README.pt-br.md).
+
+</details>
+
+<a id="slack"></a>
+<details>
+<summary><b>Slack</b></summary>
+
+**1. Criar um aplicativo Slack**
+
+* Acesse a [Slack API](https://api.slack.com/apps) e crie um novo aplicativo
+* Em **OAuth & Permissions**, adicione os escopos do bot: `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write`
+* Instale o aplicativo no seu workspace
+* Copie o **Bot Token** (`xoxb-...`) e o **App-Level Token** (`xapp-...`, habilite Socket Mode para obtê-lo)
+
+**2. Configurar**
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "bot_token": "xoxb-YOUR-BOT-TOKEN",
+      "app_token": "xapp-YOUR-APP-TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. Executar**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="irc"></a>
+<details>
+<summary><b>IRC</b></summary>
+
+**1. Configurar**
+
+```json
+{
+  "channels": {
+    "irc": {
+      "enabled": true,
+      "server": "irc.libera.chat:6697",
+      "tls": true,
+      "nick": "picoclaw-bot",
+      "channels": ["#your-channel"],
+      "password": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+Opcional: `nickserv_password` para autenticação NickServ, `sasl_user`/`sasl_password` para autenticação SASL.
+
+**2. Executar**
+
+```bash
+picoclaw gateway
+```
+
+O bot se conectará ao servidor IRC e entrará nos canais especificados.
+
+</details>
+
+<a id="onebot"></a>
+<details>
+<summary><b>OneBot (QQ via protocolo OneBot)</b></summary>
+
+OneBot é um protocolo aberto para bots QQ. O PicoClaw se conecta a qualquer implementação compatível com OneBot v11 (ex.: [Lagrange](https://github.com/LagrangeDev/Lagrange.Core), [NapCat](https://github.com/NapNeko/NapCatQQ)) via WebSocket.
+
+**1. Configurar uma implementação OneBot**
+
+Instale e execute um framework de bot QQ compatível com OneBot v11. Habilite seu servidor WebSocket.
+
+**2. Configurar**
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://127.0.0.1:8080",
+      "access_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Campo | Descrição |
+|-------|-----------|
+| `ws_url` | URL WebSocket da implementação OneBot |
+| `access_token` | Token de acesso para autenticação (se configurado no OneBot) |
+| `reconnect_interval` | Intervalo de reconexão em segundos (padrão: 5) |
+
+**3. Executar**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<details>
+<summary><b>MaixCam</b></summary>
+
+Canal de integração projetado especificamente para hardware de câmera AI Sipeed.
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true
+    }
+  }
+}
+```
+
+```bash
+picoclaw gateway
+```
+
+</details>
diff --git a/docs/pt-br/configuration.md b/docs/pt-br/configuration.md
new file mode 100644
index 000000000..ff3ce2b34
--- /dev/null
+++ b/docs/pt-br/configuration.md
@@ -0,0 +1,364 @@
+# ⚙️ Guia de Configuração
+
+> Voltar ao [README](../../README.pt-br.md)
+
+## ⚙️ Configuração
+
+Arquivo de configuração: `~/.picoclaw/config.json`
+
+### Variáveis de Ambiente
+
+Você pode substituir os caminhos padrão usando variáveis de ambiente. Isso é útil para instalações portáteis, implantações em contêineres ou execução do picoclaw como serviço do sistema. Essas variáveis são independentes e controlam caminhos diferentes.
+
+| Variável          | Descrição                                                                                                                             | Caminho Padrão              |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | Substitui o caminho para o arquivo de configuração. Isso indica diretamente ao picoclaw qual `config.json` carregar, ignorando todos os outros locais. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | Substitui o diretório raiz para dados do picoclaw. Isso altera o local padrão do `workspace` e outros diretórios de dados.          | `~/.picoclaw`             |
+
+**Exemplos:**
+
+```bash
+# Executar picoclaw usando um arquivo de configuração específico
+# O caminho do workspace será lido de dentro desse arquivo de configuração
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Executar picoclaw com todos os dados armazenados em /opt/picoclaw
+# A configuração será carregada do padrão ~/.picoclaw/config.json
+# O workspace será criado em /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Usar ambos para uma configuração totalmente personalizada
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
+### Layout do Workspace
+
+O PicoClaw armazena dados no seu workspace configurado (padrão: `~/.picoclaw/workspace`):
+
+```
+~/.picoclaw/workspace/
+├── sessions/          # Sessões de conversa e histórico
+├── memory/           # Memória de longo prazo (MEMORY.md)
+├── state/            # Estado persistente (último canal, etc.)
+├── cron/             # Banco de dados de tarefas agendadas
+├── skills/           # Skills personalizadas
+├── AGENT.md          # Guia de comportamento do agente
+├── HEARTBEAT.md      # Prompts de tarefas periódicas (verificados a cada 30 min)
+├── IDENTITY.md       # Identidade do agente
+├── SOUL.md           # Alma do agente
+└── USER.md           # Preferências do usuário
+```
+
+> **Nota:** Alterações em `AGENT.md`, `SOUL.md`, `USER.md` e `memory/MEMORY.md` são detectadas automaticamente em tempo de execução via rastreamento de data de modificação (mtime). **Não é necessário reiniciar o gateway** após editar esses arquivos — o agente carrega o novo conteúdo na próxima requisição.
+
+### Fontes de Skills
+
+Por padrão, as skills são carregadas de:
+
+1. `~/.picoclaw/workspace/skills` (workspace)
+2. `~/.picoclaw/skills` (global)
+3. `<caminho-embutido-na-compilação>/skills` (embutido)
+
+Para configurações avançadas/de teste, você pode substituir o diretório raiz de skills builtin com:
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
+### Política Unificada de Execução de Comandos
+
+- Comandos slash genéricos são executados através de um único caminho em `pkg/agent/loop.go` via `commands.Executor`.
+- Os adaptadores de canal não consomem mais comandos genéricos localmente; eles encaminham o texto de entrada para o caminho bus/agent. O Telegram ainda registra automaticamente os comandos suportados na inicialização.
+- Comando slash desconhecido (por exemplo `/foo`) passa para o processamento normal do LLM.
+- Comando registrado mas não suportado no canal atual (por exemplo `/show` no WhatsApp) retorna um erro explícito ao usuário e interrompe o processamento.
+
+### 🔒 Sandbox de Segurança
+
+O PicoClaw é executado em um ambiente sandbox por padrão. O agente só pode acessar arquivos e executar comandos dentro do workspace configurado.
+
+#### Configuração Padrão
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "restrict_to_workspace": true
+    }
+  }
+}
+```
+
+| Opção                   | Padrão                  | Descrição                                 |
+| ----------------------- | ----------------------- | ----------------------------------------- |
+| `workspace`             | `~/.picoclaw/workspace` | Diretório de trabalho do agente           |
+| `restrict_to_workspace` | `true`                  | Restringir acesso a arquivos/comandos ao workspace |
+
+#### Ferramentas Protegidas
+
+Quando `restrict_to_workspace: true`, as seguintes ferramentas são isoladas:
+
+| Ferramenta    | Função           | Restrição                              |
+| ------------- | ---------------- | -------------------------------------- |
+| `read_file`   | Ler arquivos     | Apenas arquivos dentro do workspace    |
+| `write_file`  | Escrever arquivos| Apenas arquivos dentro do workspace    |
+| `list_dir`    | Listar diretórios| Apenas diretórios dentro do workspace  |
+| `edit_file`   | Editar arquivos  | Apenas arquivos dentro do workspace    |
+| `append_file` | Anexar a arquivos| Apenas arquivos dentro do workspace    |
+| `exec`        | Executar comandos| Caminhos de comando devem estar dentro do workspace |
+
+#### Proteção Adicional do Exec
+
+Mesmo com `restrict_to_workspace: false`, a ferramenta `exec` bloqueia estes comandos perigosos:
+
+* `rm -rf`, `del /f`, `rmdir /s` — Exclusão em massa
+* `format`, `mkfs`, `diskpart` — Formatação de disco
+* `dd if=` — Imagem de disco
+* Escrita em `/dev/sd[a-z]` — Escritas diretas em disco
+* `shutdown`, `reboot`, `poweroff` — Desligamento do sistema
+* Fork bomb `:(){ :|:& };:`
+
+### Controle de Acesso a Arquivos
+
+| Config Key | Type | Default | Description |
+|------------|------|---------|-------------|
+| `tools.allow_read_paths` | string[] | `[]` | Additional paths allowed for reading outside workspace |
+| `tools.allow_write_paths` | string[] | `[]` | Additional paths allowed for writing outside workspace |
+
+### Segurança do Exec
+
+| Config Key | Type | Default | Description |
+|------------|------|---------|-------------|
+| `tools.exec.allow_remote` | bool | `false` | Allow exec tool from remote channels (Telegram/Discord etc.) |
+| `tools.exec.enable_deny_patterns` | bool | `true` | Enable dangerous command interception |
+| `tools.exec.custom_deny_patterns` | string[] | `[]` | Custom regex patterns to block |
+| `tools.exec.custom_allow_patterns` | string[] | `[]` | Custom regex patterns to allow |
+
+> **Nota de Segurança:** A proteção contra symlinks é habilitada por padrão — todos os caminhos de arquivo são resolvidos através de `filepath.EvalSymlinks` antes da correspondência com a whitelist, prevenindo ataques de escape via symlink.
+
+#### Limitação Conhecida: Processos Filhos de Ferramentas de Build
+
+O guard de segurança do exec inspeciona apenas a linha de comando que o PicoClaw executa diretamente. Ele não inspeciona recursivamente processos filhos gerados por ferramentas de desenvolvimento permitidas como `make`, `go run`, `cargo`, `npm run` ou scripts de build personalizados.
+
+Isso significa que um comando de nível superior ainda pode compilar ou executar outros binários após passar pela verificação inicial do guard. Na prática, trate scripts de build, Makefiles, scripts de pacotes e binários gerados como código executável que precisa do mesmo nível de revisão que um comando shell direto.
+
+Para ambientes de maior risco:
+
+* Revise scripts de build antes da execução.
+* Prefira aprovação/revisão manual para fluxos de trabalho de compilação e execução.
+* Execute o PicoClaw dentro de um contêiner ou VM se precisar de isolamento mais forte do que o guard integrado oferece.
+
+#### Exemplos de Erro
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (path outside working dir)}
+```
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
+```
+
+#### Desabilitando Restrições (Risco de Segurança)
+
+Se você precisar que o agente acesse caminhos fora do workspace:
+
+**Método 1: Arquivo de configuração**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "restrict_to_workspace": false
+    }
+  }
+}
+```
+
+**Método 2: Variável de ambiente**
+
+```bash
+export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
+```
+
+> ⚠️ **Aviso**: Desabilitar esta restrição permite que o agente acesse qualquer caminho no seu sistema. Use com cautela apenas em ambientes controlados.
+
+#### Consistência do Limite de Segurança
+
+A configuração `restrict_to_workspace` se aplica consistentemente em todos os caminhos de execução:
+
+| Caminho de Execução | Limite de Segurança          |
+| -------------------- | ---------------------------- |
+| Main Agent           | `restrict_to_workspace` ✅   |
+| Subagent / Spawn     | Herda a mesma restrição ✅   |
+| Heartbeat tasks      | Herda a mesma restrição ✅   |
+
+Todos os caminhos compartilham a mesma restrição de workspace — não há como contornar o limite de segurança através de subagentes ou tarefas agendadas.
+
+### Heartbeat (Tarefas Periódicas)
+
+O PicoClaw pode executar tarefas periódicas automaticamente. Crie um arquivo `HEARTBEAT.md` no seu workspace:
+
+```markdown
+# Tarefas Periódicas
+
+- Verificar meu e-mail para mensagens importantes
+- Revisar meu calendário para eventos próximos
+- Verificar a previsão do tempo
+```
+
+O agente lerá este arquivo a cada 30 minutos (configurável) e executará quaisquer tarefas usando as ferramentas disponíveis.
+
+#### Tarefas Assíncronas com Spawn
+
+Para tarefas de longa duração (busca na web, chamadas de API), use a ferramenta `spawn` para criar um **subagente**:
+
+```markdown
+# Tarefas Periódicas
+
+## Tarefas Rápidas (responder diretamente)
+
+- Informar a hora atual
+
+## Tarefas Longas (usar spawn para assíncrono)
+
+- Pesquisar notícias de IA na web e resumir
+- Verificar e-mails e reportar mensagens importantes
+```
+
+**Comportamentos principais:**
+
+| Funcionalidade   | Descrição                                                          |
+| ---------------- | ------------------------------------------------------------------ |
+| **spawn**        | Cria subagente assíncrono, não bloqueia o heartbeat                |
+| **Contexto independente** | Subagente tem seu próprio contexto, sem histórico de sessão |
+| **message tool** | Subagente comunica diretamente com o usuário via message tool      |
+| **Não-bloqueante** | Após o spawn, o heartbeat continua para a próxima tarefa         |
+
+#### Fluxo de Comunicação do Subagente
+
+```
+Heartbeat disparado
+    ↓
+Agent lê HEARTBEAT.md
+    ↓
+Tarefa longa: spawn subagente
+    ↓                           ↓
+Continua próxima tarefa    Subagente trabalha independentemente
+    ↓                           ↓
+Todas tarefas concluídas   Subagente usa ferramenta "message"
+    ↓                           ↓
+Responde HEARTBEAT_OK      Usuário recebe resultado diretamente
+```
+
+**Configuração:**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| Opção      | Padrão | Descrição                              |
+| ---------- | ------ | -------------------------------------- |
+| `enabled`  | `true` | Ativar/desativar heartbeat             |
+| `interval` | `30`   | Intervalo em minutos (mínimo: 5)       |
+
+**Variáveis de ambiente:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` para desativar
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` para alterar o intervalo
+
+### Providers
+
+> [!NOTE]
+> O Groq fornece transcrição de voz gratuita via Whisper. Se configurado, mensagens de áudio de qualquer canal serão automaticamente transcritas no nível do agente.
+
+| Provider     | Finalidade                              | Obter API Key                                                |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini`     | LLM (Gemini direto)                     | [aistudio.google.com](https://aistudio.google.com)           |
+| `zhipu`      | LLM (Zhipu direto)                      | [bigmodel.cn](https://bigmodel.cn)                           |
+| `volcengine` | LLM (Volcengine direto)                 | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter` | LLM (recomendado, acesso a todos modelos) | [openrouter.ai](https://openrouter.ai)                     |
+| `anthropic`  | LLM (Claude direto)                     | [console.anthropic.com](https://console.anthropic.com)       |
+| `openai`     | LLM (GPT direto)                        | [platform.openai.com](https://platform.openai.com)           |
+| `deepseek`   | LLM (DeepSeek direto)                   | [platform.deepseek.com](https://platform.deepseek.com)       |
+| `qwen`       | LLM (Qwen direto)                       | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq`       | LLM + **Transcrição de voz** (Whisper)  | [console.groq.com](https://console.groq.com)                 |
+| `cerebras`   | LLM (Cerebras direto)                   | [cerebras.ai](https://cerebras.ai)                           |
+| `vivgrid`    | LLM (Vivgrid direto)                    | [vivgrid.com](https://vivgrid.com)                           |
+
+### Configuração de Modelos (model_list)
+
+> **Novidade:** PicoClaw agora usa uma abordagem **centrada no modelo**. Basta especificar o formato `vendor/model` (ex.: `zhipu/glm-4.7`) para adicionar novos providers — **sem alterações de código!**
+
+#### Todos os Vendors Suportados
+
+| Vendor                  | Prefixo `model` | API Base padrão                                     | Protocolo | API Key                                                          |
+| ----------------------- | --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
+| **OpenAI**              | `openai/`       | `https://api.openai.com/v1`                         | OpenAI    | [Obter](https://platform.openai.com)                             |
+| **Anthropic**           | `anthropic/`    | `https://api.anthropic.com/v1`                      | Anthropic | [Obter](https://console.anthropic.com)                           |
+| **智谱 AI (GLM)**       | `zhipu/`        | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Obter](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys)   |
+| **DeepSeek**            | `deepseek/`     | `https://api.deepseek.com/v1`                       | OpenAI    | [Obter](https://platform.deepseek.com)                           |
+| **Google Gemini**       | `gemini/`       | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI    | [Obter](https://aistudio.google.com/api-keys)                    |
+| **Groq**                | `groq/`         | `https://api.groq.com/openai/v1`                    | OpenAI    | [Obter](https://console.groq.com)                                |
+| **通义千问 (Qwen)**     | `qwen/`         | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Obter](https://dashscope.console.aliyun.com)                    |
+| **Ollama**              | `ollama/`       | `http://localhost:11434/v1`                         | OpenAI    | Local (sem chave)                                                |
+| **OpenRouter**          | `openrouter/`   | `https://openrouter.ai/api/v1`                      | OpenAI    | [Obter](https://openrouter.ai/keys)                              |
+| **VolcEngine (Doubao)** | `volcengine/`   | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Obter](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **Antigravity**         | `antigravity/`  | Google Cloud                                        | Custom    | Somente OAuth                                                    |
+
+#### Balanceamento de Carga
+
+Configure múltiplos endpoints para o mesmo nome de modelo — PicoClaw fará round-robin automaticamente:
+
+```json
+{
+  "model_list": [
+    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" },
+    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" }
+  ]
+}
+```
+
+#### Migração da Configuração Legada `providers`
+
+A configuração antiga `providers` está **depreciada** mas ainda é suportada. Veja [docs/migration/model-list-migration.md](../migration/model-list-migration.md).
+
+### Arquitetura de Providers
+
+PicoClaw roteia providers por família de protocolo:
+
+- **Compatível com OpenAI**: OpenRouter, Groq, Zhipu, endpoints vLLM e a maioria dos outros.
+- **Anthropic**: Comportamento nativo da API Claude.
+- **Codex/OAuth**: Rota de autenticação OAuth/token OpenAI.
+
+### Tarefas Agendadas / Lembretes
+
+PicoClaw suporta tarefas agendadas via ferramenta `cron`.
+
+```json
+{
+  "tools": {
+    "cron": {
+      "enabled": true,
+      "exec_timeout_minutes": 5
+    }
+  }
+}
+```
+
+As tarefas agendadas persistem após reinicializações em `~/.picoclaw/workspace/cron/`.
+
+### Tópicos Avançados
+
+| Tópico | Descrição |
+| ------ | --------- |
+| [Sistema de Hooks](../hooks/README.md) | Hooks orientados a eventos: observadores, interceptores, hooks de aprovação |
+| [Steering](../steering.md) | Injetar mensagens em um loop de agente em execução |
+| [SubTurn](../subturn.md) | Coordenação de subagentes, controle de concorrência, ciclo de vida |
+| [Gerenciamento de Contexto](../agent-refactor/context.md) | Detecção de limites de contexto, compressão |
diff --git a/docs/pt-br/credential_encryption.md b/docs/pt-br/credential_encryption.md
new file mode 100644
index 000000000..59a31e438
--- /dev/null
+++ b/docs/pt-br/credential_encryption.md
@@ -0,0 +1,159 @@
+> Voltar ao [README](../../README.pt-br.md)
+
+# Criptografia de Credenciais
+
+O PicoClaw suporta a criptografia de valores `api_key` nas entradas de configuração `model_list`.
+As chaves criptografadas são armazenadas como strings `enc://<base64>` e descriptografadas automaticamente na inicialização.
+
+---
+
+## Início Rápido
+
+**1. Defina sua frase secreta**
+
+```bash
+export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
+```
+
+**2. Criptografe uma chave de API**
+
+Execute `picoclaw onboard` — ele solicita sua frase secreta e gera a chave SSH,
+depois recriptografa automaticamente quaisquer entradas `api_key` em texto simples na sua configuração
+na próxima chamada `SaveConfig`. O valor `enc://` resultante será semelhante a:
+
+```
+enc://AAAA...base64...
+```
+
+**3. Cole a saída na sua configuração**
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-4o",
+      "model": "openai/gpt-4o",
+      "api_key": "enc://AAAA...base64...",
+      "api_base": "https://api.openai.com/v1"
+    }
+  ]
+}
+```
+
+---
+
+## Formatos de `api_key` Suportados
+
+| Formato | Exemplo | Comportamento |
+|---------|---------|---------------|
+| Texto simples | `sk-abc123` | Usado como está |
+| Referência de arquivo | `file://openai.key` | Conteúdo lido do mesmo diretório do arquivo de configuração |
+| Criptografado | `enc://<base64>` | Descriptografado na inicialização usando `PICOCLAW_KEY_PASSPHRASE` |
+| Vazio | `""` | Passado sem alteração (usado com `auth_method: oauth`) |
+
+---
+
+## Design Criptográfico
+
+### Derivação de Chave
+
+A criptografia utiliza **HKDF-SHA256** com uma chave privada SSH como segundo fator.
+
+```
+sshHash = SHA256(ssh_private_key_file_bytes)
+ikm     = HMAC-SHA256(key=sshHash, message=passphrase)
+aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+```
+
+### Criptografia
+
+```
+AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
+```
+
+### Formato de Transmissão
+
+```
+enc://<base64( salt[16] + nonce[12] + ciphertext )>
+```
+
+| Campo | Tamanho | Descrição |
+|-------|---------|-----------|
+| `salt` | 16 bytes | Aleatório por criptografia; alimentado no HKDF |
+| `nonce` | 12 bytes | Aleatório por criptografia; IV do AES-GCM |
+| `ciphertext` | variável | Texto cifrado AES-256-GCM + tag de autenticação de 16 bytes |
+
+O tag de autenticação GCM é anexado automaticamente ao texto cifrado. Qualquer adulteração faz com que a descriptografia falhe com um erro em vez de retornar texto simples corrompido.
+
+### Desempenho
+
+| Operação | Tempo (ARM Cortex-A) |
+|----------|----------------------|
+| Derivação de chave (HKDF) | < 1 ms |
+| Descriptografia AES-256-GCM | < 1 ms |
+| **Sobrecarga total na inicialização** | **< 2 ms por chave** |
+
+---
+
+## Segurança de Dois Fatores com Chave SSH
+
+Quando uma chave privada SSH é fornecida, quebrar a criptografia requer **ambos**:
+
+1. A **frase secreta** (`PICOCLAW_KEY_PASSPHRASE`)
+2. O **arquivo de chave privada SSH**
+
+Isso significa que um arquivo de configuração vazado sozinho não é suficiente para recuperar a chave de API, mesmo que a frase secreta seja fraca. A chave SSH contribui com 256 bits de entropia (Ed25519) independentemente da força da frase secreta.
+
+### Modelo de Ameaça
+
+| O que o atacante possui | Pode descriptografar? |
+|------------------------|----------------------|
+| Apenas o arquivo de configuração | Não — necessita da frase secreta + chave SSH |
+| Apenas a chave SSH | Não — necessita da frase secreta |
+| Apenas a frase secreta | Não — necessita da chave SSH |
+| Arquivo de configuração + chave SSH + frase secreta | Sim — comprometimento total |
+
+---
+
+## Variáveis de Ambiente
+
+| Variável | Obrigatório | Descrição |
+|----------|-------------|-----------|
+| `PICOCLAW_KEY_PASSPHRASE` | Sim (para `enc://`) | Frase secreta usada para derivação de chave |
+| `PICOCLAW_SSH_KEY_PATH` | Não | Caminho para a chave privada SSH. Se não definido, detecta automaticamente em `~/.ssh/picoclaw_ed25519.key` |
+
+### Detecção Automática da Chave SSH
+
+Se `PICOCLAW_SSH_KEY_PATH` não estiver definido, o PicoClaw procura a chave dedicada:
+
+```
+~/.ssh/picoclaw_ed25519.key
+```
+
+Este arquivo dedicado evita conflitos com as chaves SSH existentes do usuário.
+Execute `picoclaw onboard` para gerá-lo automaticamente.
+
+`os.UserHomeDir()` é usado para resolução multiplataforma do diretório home (lê `USERPROFILE` no Windows, `HOME` no Unix/macOS).
+
+> **Nota:** Um arquivo de chave SSH é obrigatório para a criptografia de credenciais. Se nenhuma chave for encontrada e `PICOCLAW_SSH_KEY_PATH` não estiver definido, a criptografia/descriptografia falhará. Execute `picoclaw onboard` para gerar a chave automaticamente.
+
+---
+
+## Migração
+
+Como os únicos materiais secretos são `PICOCLAW_KEY_PASSPHRASE` e o arquivo de chave privada SSH, a migração é simples:
+
+1. Copie o arquivo de configuração para a nova máquina.
+2. Defina `PICOCLAW_KEY_PASSPHRASE` com o mesmo valor.
+3. Copie o arquivo de chave privada SSH para o mesmo caminho (ou defina `PICOCLAW_SSH_KEY_PATH` para sua nova localização).
+
+Nenhuma recriptografia é necessária.
+
+---
+
+## Considerações de Segurança
+
+- **Tanto a frase secreta quanto a chave SSH são obrigatórias.** A chave SSH atua como um segundo fator — sem ela, a criptografia/descriptografia falhará. Execute `picoclaw onboard` para gerar a chave se ela não existir.
+- **A chave SSH é somente leitura em tempo de execução.** O PicoClaw nunca escreve ou modifica o arquivo de chave SSH.
+- **Chaves em texto simples continuam sendo suportadas.** Configurações existentes sem `enc://` não são afetadas.
+- **O formato `enc://` é versionado** através do campo `info` do HKDF (`picoclaw-credential-v1`), permitindo futuras atualizações de algoritmo sem quebrar valores criptografados existentes.
diff --git a/docs/pt-br/debug.md b/docs/pt-br/debug.md
new file mode 100644
index 000000000..8614cd5ed
--- /dev/null
+++ b/docs/pt-br/debug.md
@@ -0,0 +1,36 @@
+# Depuração do PicoClaw
+
+> Voltar ao [README](../../README.pt-br.md)
+
+O PicoClaw realiza múltiplas interações complexas nos bastidores para cada requisição que recebe — desde o roteamento de mensagens e avaliação de complexidade, até a execução de ferramentas e adaptação a falhas de modelo. Poder ver exatamente o que está acontecendo é crucial, não apenas para solucionar problemas potenciais, mas também para realmente entender como o agente opera.
+
+## Iniciando o PicoClaw em modo de depuração
+
+Para obter informações detalhadas sobre o que o agente está fazendo (requisições LLM, chamadas de ferramentas, roteamento de mensagens), você pode iniciar o gateway do PicoClaw com a flag de depuração:
+
+```bash
+picoclaw gateway --debug
+# or
+picoclaw gateway -d
+```
+
+Neste modo, o sistema formata os logs de forma detalhada e exibe prévias dos prompts do sistema e dos resultados de execução das ferramentas.
+
+## Desabilitando a truncagem de logs (logs completos)
+
+Por padrão, o PicoClaw trunca strings muito longas (como o *Prompt do Sistema* ou resultados JSON grandes) nos logs de depuração para manter o console legível.
+
+Se você precisar inspecionar a saída completa de um comando ou o payload exato enviado ao modelo LLM, pode usar a flag `--no-truncate`.
+
+**Nota:** Esta flag *só* funciona quando combinada com o modo `--debug`.
+
+```bash
+picoclaw gateway --debug --no-truncate
+
+```
+
+Quando esta flag está ativa, a função de truncagem global é desabilitada. Isso é extremamente útil para:
+
+* Verificar a sintaxe exata das mensagens enviadas ao provedor.
+* Ler a saída completa de ferramentas como `exec`, `web_fetch` ou `read_file`.
+* Depurar o histórico de sessão salvo na memória.
diff --git a/docs/pt-br/docker.md b/docs/pt-br/docker.md
new file mode 100644
index 000000000..bac48954b
--- /dev/null
+++ b/docs/pt-br/docker.md
@@ -0,0 +1,167 @@
+# 🐳 Docker e Início Rápido
+
+> Voltar ao [README](../../README.pt-br.md)
+
+## 🐳 Docker Compose
+
+Você também pode executar o PicoClaw usando Docker Compose sem instalar nada localmente.
+
+```bash
+# 1. Clone este repositório
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. Primeira execução — gera automaticamente docker/data/config.json e encerra
+#    (só é acionado quando config.json e workspace/ estão ambos ausentes)
+docker compose -f docker/docker-compose.yml --profile gateway up
+# O contêiner exibe "First-run setup complete." e para.
+
+# 3. Configure suas chaves de API
+vim docker/data/config.json   # Set provider API keys, bot tokens, etc.
+
+# 4. Iniciar
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+> [!TIP]
+> **Usuários Docker**: Por padrão, o Gateway escuta em `127.0.0.1`, que não é acessível a partir do host. Se você precisar acessar os endpoints de saúde ou expor portas, defina `PICOCLAW_GATEWAY_HOST=0.0.0.0` no seu ambiente ou atualize o `config.json`.
+
+```bash
+# 5. Verificar logs
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. Parar
+docker compose -f docker/docker-compose.yml --profile gateway down
+```
+
+### Modo Launcher (Console Web)
+
+A imagem `launcher` inclui os três binários (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) e inicia o console web por padrão, que fornece uma interface baseada em navegador para configuração e chat.
+
+```bash
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+```
+
+Abra http://localhost:18800 no seu navegador. O launcher gerencia o processo do gateway automaticamente.
+
+> [!WARNING]
+> O console web ainda não suporta autenticação. Evite expô-lo na internet pública.
+
+### Modo Agent (One-shot)
+
+```bash
+# Fazer uma pergunta
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
+
+# Modo interativo
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+```
+
+### Atualização
+
+```bash
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+### 🚀 Início Rápido
+
+> [!TIP]
+> Configure sua chave de API em `~/.picoclaw/config.json`. Obtenha chaves de API: [Volcengine (CodingPlan)](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM). A busca na web é opcional — obtenha gratuitamente uma [API Tavily](https://tavily.com) (1000 consultas gratuitas/mês) ou [API Brave Search](https://brave.com/search/api) (2000 consultas gratuitas/mês).
+
+**1. Inicializar**
+
+```bash
+picoclaw onboard
+```
+
+**2. Configurar** (`~/.picoclaw/config.json`)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "gpt-5.4",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key",
+      "api_base":"https://ark.cn-beijing.volces.com/api/coding/v3"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "your-api-key",
+      "request_timeout": 300
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "your-anthropic-key"
+    }
+  ],
+  "tools": {
+    "web": {
+      "enabled": true,
+      "fetch_limit_bytes": 10485760,
+      "format": "plaintext",
+      "brave": {
+        "enabled": false,
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      },
+      "tavily": {
+        "enabled": false,
+        "api_key": "YOUR_TAVILY_API_KEY",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "YOUR_PERPLEXITY_API_KEY",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://your-searxng-instance:8888",
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+> **Novo**: O formato de configuração `model_list` permite adicionar provedores sem alteração de código. Veja [Configuração de Modelos](#configuração-de-modelos-model_list) para detalhes.
+> `request_timeout` é opcional e usa segundos. Se omitido ou definido como `<= 0`, o PicoClaw usa o timeout padrão (120s).
+
+**3. Obter chaves de API**
+
+* **Provedor LLM**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
+* **Busca na Web** (opcional):
+  * [Brave Search](https://brave.com/search/api) - Pago ($5/1000 consultas, ~$5-6/mês)
+  * [Perplexity](https://www.perplexity.ai) - Busca com IA e interface de chat
+  * [SearXNG](https://github.com/searxng/searxng) - Metabuscador auto-hospedado (gratuito, sem necessidade de chave de API)
+  * [Tavily](https://tavily.com) - Otimizado para agentes de IA (1000 requisições/mês)
+  * DuckDuckGo - Fallback integrado (sem necessidade de chave de API)
+
+> **Nota**: Veja `config.example.json` para um modelo de configuração completo.
+
+**4. Conversar**
+
+```bash
+picoclaw agent -m "What is 2+2?"
+```
+
+Pronto! Você tem um assistente de IA funcionando em 2 minutos.
+
+---
diff --git a/docs/pt-br/hardware-compatibility.md b/docs/pt-br/hardware-compatibility.md
new file mode 100644
index 000000000..771621014
--- /dev/null
+++ b/docs/pt-br/hardware-compatibility.md
@@ -0,0 +1,152 @@
+> Voltar ao [README](../../README.pt-br.md)
+
+# 🖥️ PicoClaw Lista de compatibilidade de hardware
+
+O PicoClaw roda em praticamente qualquer dispositivo Linux. Esta página registra chips, produtos e placas de desenvolvimento verificados.
+
+**Seu hardware não está na lista?** Envie um PR para adicioná-lo! Fabricantes de hardware são bem-vindos para contribuir e co-promover.
+
+---
+
+## 1. Suporte a chips verificado
+
+### x86
+
+| Fabricante | Chip | Notas |
+|------------|------|-------|
+| Intel | Any x86 CPU (i386+) | Todos os processadores desktop/servidor/notebook |
+| AMD | Any x86 CPU | Todos os processadores desktop/servidor/notebook |
+
+### ARM
+
+| Sub-arq | Chips típicos | Notas |
+|---------|---------------|-------|
+| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | Single-core ARM1176JZF-S |
+| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | Single-core Cortex-A7, usado no LicheePi Zero |
+| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | Quad-core Cortex-A53, usado no Orange Pi Zero 3 |
+| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | Quad-core Cortex-A72 |
+| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | Quad-core Cortex-A76 |
+| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | Dual-core Cortex-A53 + NPU, usado no NanoKVM-Pro / MaixCAM2 |
+
+### RISC-V (riscv64)
+
+| Fabricante | Chip | Núcleo | Notas |
+|------------|------|--------|-------|
+| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 integrado, usado no LicheeRV-Nano / NanoKVM / MaixCAM |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L integrado, 1 TOPS NPU, câmera AI 4K SiP |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | Série de câmeras AI RISC-V |
+| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | Usado no HaaS506-LD1 RTU industrial |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Usado no Milk-V Jupiter, BananaPi BPI-F3 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | Compatível com RVA23, RVV de 1024 bits, inferência AI FP8 |
+| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8 núcleos, 16MB cache L3, classe desktop |
+| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU, usado no CanMV-K230 |
+
+### MIPS
+
+| Fabricante | Chip | Notas |
+|------------|------|-------|
+| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz, usado em muitos roteadores OpenWrt (ex. Xiaomi Router 3G) |
+
+### LoongArch (loong64)
+
+| Fabricante | Chip | Notas |
+|------------|------|-------|
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | Quad-core LA464 @ 2.5GHz, desktop/estação de trabalho |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | Quad-core 4C/8T @ 2.5GHz, IPC comparável ao Intel 10ª geração |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | Dual-core @ 1GHz, aplicações industriais/IoT |
+
+---
+
+## 2. Produtos verificados (por data de lançamento)
+
+Produtos de consumo, roteadores e dispositivos industriais testados com o PicoClaw.
+
+| Ano | Produto | Arq | SoC | RAM | Categoria |
+|-----|---------|-----|-----|-----|-----------|
+| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | Smartphone |
+| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | Tablet |
+| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | Roteador (OpenWrt) |
+| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | TV Box / Servidor doméstico |
+| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | Alto-falante inteligente |
+| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
+| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | RTU industrial |
+| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | IP-KVM Pro |
+| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | Câmera AI 4K |
+
+---
+
+## 3. Placas de desenvolvimento verificadas (por data de lançamento)
+
+| Ano | Placa | Arq | SoC | RAM | Link de compra |
+|-----|-------|-----|-----|-----|----------------|
+| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
+| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
+| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
+| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
+| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
+| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
+| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
+| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
+| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
+
+---
+
+## 4. Também funciona em
+
+### Celulares Android (via Termux)
+
+Qualquer celular Android ARM64 (2015+) com 1GB+ de RAM. Instale o [Termux](https://github.com/termux/termux-app), use `proot` para rodar o PicoClaw.
+
+> Veja [README: Rodar em celulares Android antigos](../../README.pt-br.md#-run-on-old-android-phones) para instruções de configuração.
+
+### Desktop / Servidor / Nuvem
+
+| Plataforma | Notas |
+|------------|-------|
+| x86_64 Linux | Binário nativo, sem dependências |
+| x86_64 Windows | Binário nativo |
+| macOS (Intel / Apple Silicon) | Binário nativo |
+| Docker (any platform) | `docker compose` em uma linha, veja [Guia Docker](docker.md) |
+| OpenWrt routers | Builds MIPS/ARM, requer >32MB de RAM livre |
+| FreeBSD / NetBSD | Builds x86_64 e arm64 disponíveis |
+
+---
+
+## 5. Requisitos mínimos
+
+| Recurso | Mínimo | Recomendado |
+|---------|--------|-------------|
+| RAM | 10MB livres | 32MB+ livres |
+| Armazenamento | 20MB (binário) | 50MB+ (com workspace) |
+| CPU | Qualquer (single-core 0,6GHz+) | — |
+| OS | Linux (kernel 3.x+) | Linux 5.x+ |
+| Rede | Necessária (para chamadas de API LLM) | Ethernet ou WiFi |
+
+---
+
+## 6. Como testar e contribuir
+
+```bash
+# 1. Baixar para sua arquitetura
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+
+# 2. Inicializar
+./picoclaw onboard
+
+# 3. Testar
+./picoclaw agent -m "Hello, what board am I running on?"
+```
+
+Builds disponíveis: `linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
+
+### Adicionar seu hardware
+
+1. Faça fork deste repositório
+2. Adicione seu chip / produto / placa na tabela apropriada
+3. Inclua: nome, arquitetura, SoC, RAM, ano e um link se disponível
+4. Envie um PR
+
+Fabricantes de hardware: deseja adicionar suporte oficial ou co-promover? Abra uma issue ou entre em contato via [Discord](https://discord.gg/V4sAZ9XWpN).
diff --git a/docs/pt-br/providers.md b/docs/pt-br/providers.md
new file mode 100644
index 000000000..0f7a4b5a1
--- /dev/null
+++ b/docs/pt-br/providers.md
@@ -0,0 +1,433 @@
+# 🔌 Provedores e Configuração de Modelos
+
+> Voltar ao [README](../../README.pt-br.md)
+
+### Provedores
+
+> [!NOTE]
+> O Groq fornece transcrição de voz gratuita via Whisper. Se configurado, mensagens de áudio de qualquer canal serão automaticamente transcritas no nível do agente.
+
+| Provider     | Purpose                                 | Get API Key                                                  |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini`     | LLM (Gemini direct)                     | [aistudio.google.com](https://aistudio.google.com)           |
+| `zhipu`      | LLM (Zhipu direct)                      | [bigmodel.cn](https://bigmodel.cn)                           |
+| `volcengine` | LLM(Volcengine direct)                  | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw)                 |
+| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai)                       |
+| `anthropic`  | LLM (Claude direct)                     | [console.anthropic.com](https://console.anthropic.com)       |
+| `openai`     | LLM (GPT direct)                        | [platform.openai.com](https://platform.openai.com)           |
+| `deepseek`   | LLM (DeepSeek direct)                   | [platform.deepseek.com](https://platform.deepseek.com)       |
+| `qwen`       | LLM (Qwen direct)                       | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq`       | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com)                 |
+| `cerebras`   | LLM (Cerebras direct)                   | [cerebras.ai](https://cerebras.ai)                           |
+| `vivgrid`    | LLM (Vivgrid direct)                    | [vivgrid.com](https://vivgrid.com)                           |
+| `moonshot`   | LLM (Kimi/Moonshot direct)              | [platform.moonshot.cn](https://platform.moonshot.cn)         |
+| `minimax`    | LLM (Minimax direct)                    | [platform.minimaxi.com](https://platform.minimaxi.com)      |
+| `avian`      | LLM (Avian direct)                      | [avian.io](https://avian.io)                                 |
+| `mistral`    | LLM (Mistral direct)                    | [console.mistral.ai](https://console.mistral.ai)            |
+| `longcat`    | LLM (Longcat direct)                    | [longcat.ai](https://longcat.ai)                             |
+| `modelscope` | LLM (ModelScope direct)                 | [modelscope.cn](https://modelscope.cn)                       |
+
+### Configuração de Modelos (model_list)
+
+> **Novidade?** O PicoClaw agora usa uma abordagem de configuração **centrada no modelo**. Basta especificar o formato `vendor/model` (ex.: `zhipu/glm-4.7`) para adicionar novos provedores — **sem necessidade de alteração de código!**
+
+Este design também permite **suporte multi-agente** com seleção flexível de provedores:
+
+- **Agentes diferentes, provedores diferentes**: Cada agente pode usar seu próprio provedor LLM
+- **Fallback de modelos**: Configure modelos primários e de fallback para resiliência
+- **Balanceamento de carga**: Distribua requisições entre múltiplos endpoints
+- **Configuração centralizada**: Gerencie todos os provedores em um só lugar
+
+#### 📋 Todos os Vendors Suportados
+
+| Vendor              | `model` Prefix    | Default API Base                                    | Protocol  | API Key                                                          |
+| ------------------- | ----------------- |-----------------------------------------------------| --------- | ---------------------------------------------------------------- |
+| **OpenAI**          | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [Get Key](https://platform.openai.com)                           |
+| **Anthropic**       | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [Get Key](https://console.anthropic.com)                         |
+| **智谱 AI (GLM)**   | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek**        | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [Get Key](https://platform.deepseek.com)                         |
+| **Google Gemini**   | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI    | [Get Key](https://aistudio.google.com/api-keys)                  |
+| **Groq**            | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [Get Key](https://console.groq.com)                              |
+| **Moonshot**        | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [Get Key](https://platform.moonshot.cn)                          |
+| **通义千问 (Qwen)** | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Get Key](https://dashscope.console.aliyun.com)                  |
+| **NVIDIA**          | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [Get Key](https://build.nvidia.com)                              |
+| **Ollama**          | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | Local (no key needed)                                            |
+| **OpenRouter**      | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [Get Key](https://openrouter.ai/keys)                            |
+| **LiteLLM Proxy**   | `litellm/`        | `http://localhost:4000/v1`                          | OpenAI    | Your LiteLLM proxy key                                            |
+| **VLLM**            | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | Local                                                            |
+| **Cerebras**        | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [Get Key](https://cerebras.ai)                                   |
+| **VolcEngine (Doubao)** | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw)                        |
+| **神算云**          | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                |
+| **BytePlus**        | `byteplus/`       | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [Get Key](https://www.byteplus.com)                        |
+| **Vivgrid**         | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [Get Key](https://vivgrid.com)                                   |
+| **LongCat**         | `longcat/`        | `https://api.longcat.chat/openai`                   | OpenAI    | [Get Key](https://longcat.chat/platform)                         |
+| **ModelScope (魔搭)**| `modelscope/`    | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [Get Token](https://modelscope.cn/my/tokens)                     |
+| **Antigravity**     | `antigravity/`    | Google Cloud                                        | Custom    | OAuth only                                                       |
+| **GitHub Copilot**  | `github-copilot/` | `localhost:4321`                                    | gRPC      | -                                                                |
+
+#### Configuração Básica
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-openai-key"
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "sk-ant-your-key"
+    },
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-zhipu-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "gpt-5.4"
+    }
+  }
+}
+```
+
+#### Exemplos por Vendor
+
+**OpenAI**
+
+```json
+{
+  "model_name": "gpt-5.4",
+  "model": "openai/gpt-5.4",
+  "api_key": "sk-..."
+}
+```
+
+**VolcEngine (Doubao)**
+
+```json
+{
+  "model_name": "ark-code-latest",
+  "model": "volcengine/ark-code-latest",
+  "api_key": "sk-..."
+}
+```
+
+**智谱 AI (GLM)**
+
+```json
+{
+  "model_name": "glm-4.7",
+  "model": "zhipu/glm-4.7",
+  "api_key": "your-key"
+}
+```
+
+**DeepSeek**
+
+```json
+{
+  "model_name": "deepseek-chat",
+  "model": "deepseek/deepseek-chat",
+  "api_key": "sk-..."
+}
+```
+
+**Anthropic (com chave de API)**
+
+```json
+{
+  "model_name": "claude-sonnet-4.6",
+  "model": "anthropic/claude-sonnet-4.6",
+  "api_key": "sk-ant-your-key"
+}
+```
+
+> Execute `picoclaw auth login --provider anthropic` para colar seu token de API.
+
+**Anthropic Messages API (formato nativo)**
+
+Para acesso direto à API Anthropic ou endpoints personalizados que suportam apenas o formato de mensagem nativo da Anthropic:
+
+```json
+{
+  "model_name": "claude-opus-4-6",
+  "model": "anthropic-messages/claude-opus-4-6",
+  "api_key": "sk-ant-your-key",
+  "api_base": "https://api.anthropic.com"
+}
+```
+
+> Use o protocolo `anthropic-messages` quando:
+> - Usar proxies de terceiros que suportam apenas o endpoint nativo `/v1/messages` da Anthropic (não o compatível com OpenAI `/v1/chat/completions`)
+> - Conectar a serviços como MiniMax, Synthetic que requerem o formato de mensagem nativo da Anthropic
+> - O protocolo `anthropic` existente retorna erros 404 (indicando que o endpoint não suporta formato compatível com OpenAI)
+>
+> **Nota:** O protocolo `anthropic` usa formato compatível com OpenAI (`/v1/chat/completions`), enquanto `anthropic-messages` usa o formato nativo da Anthropic (`/v1/messages`). Escolha com base no formato suportado pelo seu endpoint.
+
+**Ollama (local)**
+
+```json
+{
+  "model_name": "llama3",
+  "model": "ollama/llama3"
+}
+```
+
+**Proxy/API Personalizado**
+
+```json
+{
+  "model_name": "my-custom-model",
+  "model": "openai/custom-model",
+  "api_base": "https://my-proxy.com/v1",
+  "api_key": "sk-...",
+  "request_timeout": 300
+}
+```
+
+**LiteLLM Proxy**
+
+```json
+{
+  "model_name": "lite-gpt4",
+  "model": "litellm/lite-gpt4",
+  "api_base": "http://localhost:4000/v1",
+  "api_key": "sk-..."
+}
+```
+
+O PicoClaw remove apenas o prefixo externo `litellm/` antes de enviar a requisição, então aliases de proxy como `litellm/lite-gpt4` enviam `lite-gpt4`, enquanto `litellm/openai/gpt-4o` envia `openai/gpt-4o`.
+
+#### Balanceamento de Carga
+
+Configure múltiplos endpoints para o mesmo nome de modelo — o PicoClaw fará automaticamente round-robin entre eles:
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api1.example.com/v1",
+      "api_key": "sk-key1"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api2.example.com/v1",
+      "api_key": "sk-key2"
+    }
+  ]
+}
+```
+
+#### Migração da Configuração Legacy `providers`
+
+A configuração antiga `providers` está **descontinuada** mas ainda é suportada para compatibilidade retroativa.
+
+**Configuração Antiga (descontinuada):**
+
+```json
+{
+  "providers": {
+    "zhipu": {
+      "api_key": "your-key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  },
+  "agents": {
+    "defaults": {
+      "provider": "zhipu",
+      "model": "glm-4.7"
+    }
+  }
+}
+```
+
+**Configuração Nova (recomendada):**
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "glm-4.7"
+    }
+  }
+}
+```
+
+Para guia de migração detalhado, veja [migration/model-list-migration.md](../migration/model-list-migration.md).
+
+### Arquitetura de Provedores
+
+O PicoClaw roteia provedores por família de protocolo:
+
+- Protocolo compatível com OpenAI: OpenRouter, gateways compatíveis com OpenAI, Groq, Zhipu e endpoints estilo vLLM.
+- Protocolo Anthropic: Comportamento nativo da API Claude.
+- Caminho Codex/OAuth: Rota de autenticação OAuth/token da OpenAI.
+
+Isso mantém o runtime leve enquanto torna novos backends compatíveis com OpenAI basicamente uma operação de configuração (`api_base` + `api_key`).
+
+<details>
+<summary><b>Zhipu</b></summary>
+
+**1. Obter chave de API e URL base**
+
+* Obtenha a [chave de API](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
+
+**2. Configurar**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "providers": {
+    "zhipu": {
+      "api_key": "Your API Key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  }
+}
+```
+
+**3. Executar**
+
+```bash
+picoclaw agent -m "Hello"
+```
+
+</details>
+
+<details>
+<summary><b>Exemplo de configuração completa</b></summary>
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "anthropic/claude-opus-4-5"
+    }
+  },
+  "session": {
+    "dm_scope": "per-channel-peer"
+  },
+  "providers": {
+    "openrouter": {
+      "api_key": "sk-or-v1-xxx"
+    },
+    "groq": {
+      "api_key": "gsk_xxx"
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456:ABC...",
+      "allow_from": ["123456789"]
+    },
+    "discord": {
+      "enabled": true,
+      "token": "",
+      "allow_from": [""]
+    },
+    "whatsapp": {
+      "enabled": false,
+      "bridge_url": "ws://localhost:3001",
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": []
+    },
+    "feishu": {
+      "enabled": false,
+      "app_id": "cli_xxx",
+      "app_secret": "xxx",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    },
+    "qq": {
+      "enabled": false,
+      "app_id": "",
+      "app_secret": "",
+      "allow_from": []
+    }
+  },
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": false,
+        "api_key": "BSA...",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://localhost:8888",
+        "max_results": 5
+      }
+    },
+    "cron": {
+      "exec_timeout_minutes": 5
+    }
+  },
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+</details>
+
+---
+
+## 📝 Comparação de Chaves de API
+
+| Service          | Pricing                  | Use Case                              |
+| ---------------- | ------------------------ | ------------------------------------- |
+| **OpenRouter**   | Free: 200K tokens/month  | Multiple models (Claude, GPT-4, etc.) |
+| **Volcengine CodingPlan** | ¥9.9/first month | Best for Chinese users, multiple SOTA models (Doubao, DeepSeek, etc.) |
+| **Zhipu**        | Free: 200K tokens/month  | Suitable for Chinese users                |
+| **Brave Search** | $5/1000 queries          | Web search functionality              |
+| **SearXNG**      | Free (self-hosted)       | Privacy-focused metasearch (70+ engines) |
+| **Groq**         | Free tier available      | Fast inference (Llama, Mixtral)       |
+| **Cerebras**     | Free tier available      | Fast inference (Llama, Qwen, etc.)    |
+| **LongCat**      | Free: up to 5M tokens/day | Fast inference                       |
+| **ModelScope**   | Free: 2000 requests/day  | Inference (Qwen, GLM, DeepSeek, etc.) |
+
+---
+
+<div align="center">
+  <img src="assets/logo.jpg" alt="PicoClaw Meme" width="512">
+</div>
diff --git a/docs/pt-br/spawn-tasks.md b/docs/pt-br/spawn-tasks.md
new file mode 100644
index 000000000..d6b539cb1
--- /dev/null
+++ b/docs/pt-br/spawn-tasks.md
@@ -0,0 +1,61 @@
+# 🔄 Tarefas Assíncronas e Spawn
+
+> Voltar ao [README](../../README.pt-br.md)
+
+## Tarefas Rápidas (resposta direta)
+
+- Informar a hora atual
+
+## Tarefas Longas (usar spawn para assíncrono)
+
+- Pesquisar na web notícias sobre IA e resumir
+- Verificar e-mail e relatar mensagens importantes
+```
+
+**Comportamentos principais:**
+
+| Feature                 | Description                                               |
+| ----------------------- | --------------------------------------------------------- |
+| **spawn**               | Creates async subagent, doesn't block heartbeat           |
+| **Independent context** | Subagent has its own context, no session history          |
+| **message tool**        | Subagent communicates with user directly via message tool |
+| **Non-blocking**        | After spawning, heartbeat continues to next task          |
+
+#### Como Funciona a Comunicação do Subagente
+
+```
+Heartbeat é acionado
+    ↓
+Agente lê HEARTBEAT.md
+    ↓
+Para tarefa longa: spawn subagente
+    ↓                           ↓
+Continua para próxima tarefa  Subagente trabalha independentemente
+    ↓                           ↓
+Todas as tarefas concluídas   Subagente usa ferramenta "message"
+    ↓                           ↓
+Responde HEARTBEAT_OK         Usuário recebe resultado diretamente
+```
+
+O subagente tem acesso a ferramentas (message, web_search, etc.) e pode se comunicar com o usuário independentemente sem passar pelo agente principal.
+
+**Configuração:**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| Option     | Default | Description                        |
+| ---------- | ------- | ---------------------------------- |
+| `enabled`  | `true`  | Enable/disable heartbeat           |
+| `interval` | `30`    | Check interval in minutes (min: 5) |
+
+**Variáveis de ambiente:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` para desabilitar
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` para alterar o intervalo
diff --git a/docs/pt-br/tools_configuration.md b/docs/pt-br/tools_configuration.md
new file mode 100644
index 000000000..feec3c3d8
--- /dev/null
+++ b/docs/pt-br/tools_configuration.md
@@ -0,0 +1,412 @@
+# 🔧 Configuração de Ferramentas
+
+> Voltar ao [README](../../README.pt-br.md)
+
+A configuração de ferramentas do PicoClaw está localizada no campo `tools` do `config.json`.
+
+## Estrutura de diretórios
+
+```json
+{
+  "tools": {
+    "web": {
+      ...
+    },
+    "mcp": {
+      ...
+    },
+    "exec": {
+      ...
+    },
+    "cron": {
+      ...
+    },
+    "skills": {
+      ...
+    }
+  }
+}
+```
+
+## Ferramentas Web
+
+As ferramentas web são usadas para pesquisa e busca de páginas web.
+
+### Web Fetcher
+Configurações gerais para busca e processamento de conteúdo de páginas web.
+
+| Config              | Tipo   | Padrão        | Descrição                                                                                     |
+|---------------------|--------|---------------|-----------------------------------------------------------------------------------------------|
+| `enabled`           | bool   | true          | Habilitar a capacidade de busca de páginas web.                                               |
+| `fetch_limit_bytes` | int    | 10485760      | Tamanho máximo do payload da página web a ser buscado, em bytes (padrão é 10MB).              |
+| `format`            | string | "plaintext"   | Formato de saída do conteúdo buscado. Opções: `plaintext` ou `markdown` (recomendado).        |
+
+### DuckDuckGo
+
+| Config        | Tipo | Padrão | Descrição                      |
+|---------------|------|--------|--------------------------------|
+| `enabled`     | bool | true   | Habilitar pesquisa DuckDuckGo  |
+| `max_results` | int  | 5      | Número máximo de resultados    |
+
+### Baidu Search
+
+| Config        | Tipo   | Padrão                                                          | Descrição                          |
+|---------------|--------|-----------------------------------------------------------------|------------------------------------|
+| `enabled`     | bool   | false                                                           | Habilitar pesquisa Baidu           |
+| `api_key`     | string | -                                                               | Chave API Qianfan                  |
+| `base_url`    | string | `https://qianfan.baidubce.com/v2/ai_search/web_search`         | URL da API Baidu Search            |
+| `max_results` | int    | 10                                                              | Número máximo de resultados        |
+
+```json
+{
+  "tools": {
+    "web": {
+      "baidu_search": {
+        "enabled": true,
+        "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
+        "max_results": 10
+      }
+    }
+  }
+}
+```
+
+### Perplexity
+
+| Config        | Tipo   | Padrão | Descrição                      |
+|---------------|--------|--------|--------------------------------|
+| `enabled`     | bool     | false  | Habilitar pesquisa Perplexity                                    |
+| `api_key`     | string   | -      | Chave API do Perplexity                                          |
+| `api_keys`    | string[] | -      | Várias chaves API do Perplexity para rotação (prioridade sobre `api_key`) |
+| `max_results` | int      | 5      | Número máximo de resultados                                      |
+
+### Brave
+
+| Config        | Tipo   | Padrão | Descrição                  |
+|---------------|--------|--------|----------------------------|
+| `enabled`     | bool     | false  | Habilitar pesquisa Brave                                         |
+| `api_key`     | string   | -      | Chave API única do Brave Search                                  |
+| `api_keys`    | string[] | -      | Várias chaves API do Brave para rotação (prioridade sobre `api_key`) |
+| `max_results` | int      | 5      | Número máximo de resultados                                      |
+
+### Tavily
+
+| Config        | Tipo   | Padrão | Descrição                          |
+|---------------|--------|--------|------------------------------------|
+| `enabled`     | bool   | false  | Habilitar pesquisa Tavily          |
+| `api_key`     | string | -      | Chave API do Tavily                |
+| `base_url`    | string | -      | URL base personalizada do Tavily   |
+| `max_results` | int    | 0      | Número máximo de resultados (0 = padrão) |
+
+### SearXNG
+
+| Config        | Tipo   | Padrão                   | Descrição                      |
+|---------------|--------|--------------------------|--------------------------------|
+| `enabled`     | bool   | false                    | Habilitar pesquisa SearXNG     |
+| `base_url`    | string | `http://localhost:8888`  | URL da instância SearXNG       |
+| `max_results` | int    | 5                        | Número máximo de resultados    |
+
+### GLM Search
+
+| Config          | Tipo   | Padrão                                               | Descrição                  |
+|-----------------|--------|------------------------------------------------------|----------------------------|
+| `enabled`       | bool   | false                                                | Habilitar GLM Search       |
+| `api_key`       | string | -                                                    | Chave API GLM              |
+| `base_url`      | string | `https://open.bigmodel.cn/api/paas/v4/web_search`   | URL da API GLM Search      |
+| `search_engine` | string | `search_std`                                         | Tipo de motor de busca     |
+| `max_results`   | int    | 5                                                    | Número máximo de resultados |
+
+## Ferramenta Exec
+
+A ferramenta exec é usada para executar comandos shell.
+
+| Config                 | Tipo  | Padrão | Descrição                                      |
+|------------------------|-------|--------|-------------------------------------------------|
+| `enabled`              | bool  | true   | Habilitar a ferramenta exec                     |
+| `enable_deny_patterns` | bool  | true   | Habilitar bloqueio padrão de comandos perigosos |
+| `custom_deny_patterns` | array | []     | Padrões de negação personalizados (expressões regulares) |
+
+### Desabilitando a Ferramenta Exec
+
+Para desabilitar completamente a ferramenta `exec`, defina `enabled` como `false`:
+
+**Via arquivo de configuração:**
+```json
+{
+  "tools": {
+    "exec": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**Via variável de ambiente:**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **Nota:** Quando desabilitada, o agent não poderá executar comandos shell. Isso também afeta a capacidade da ferramenta Cron de executar comandos shell agendados.
+
+### Funcionalidade
+
+- **`enable_deny_patterns`**: Defina como `false` para desabilitar completamente os padrões de bloqueio de comandos perigosos padrão
+- **`custom_deny_patterns`**: Adicione padrões regex de negação personalizados; comandos correspondentes serão bloqueados
+
+### Padrões de comandos bloqueados por padrão
+
+Por padrão, o PicoClaw bloqueia os seguintes comandos perigosos:
+
+- Comandos de exclusão: `rm -rf`, `del /f/q`, `rmdir /s`
+- Operações de disco: `format`, `mkfs`, `diskpart`, `dd if=`, escrita em `/dev/sd*`
+- Operações do sistema: `shutdown`, `reboot`, `poweroff`
+- Substituição de comandos: `$()`, `${}`, crases
+- Pipe para shell: `| sh`, `| bash`
+- Escalação de privilégios: `sudo`, `chmod`, `chown`
+- Controle de processos: `pkill`, `killall`, `kill -9`
+- Operações remotas: `curl | sh`, `wget | sh`, `ssh`
+- Gerenciamento de pacotes: `apt`, `yum`, `dnf`, `npm install -g`, `pip install --user`
+- Contêineres: `docker run`, `docker exec`
+- Git: `git push`, `git force`
+- Outros: `eval`, `source *.sh`
+
+### Limitação arquitetural conhecida
+
+O guarda exec apenas valida o comando de nível superior enviado ao PicoClaw. Ele **não** inspeciona recursivamente processos filhos gerados por ferramentas de build ou scripts após o início desse comando.
+
+Exemplos de fluxos de trabalho que podem contornar o guarda de comando direto uma vez que o comando inicial é permitido:
+
+- `make run`
+- `go run ./cmd/...`
+- `cargo run`
+- `npm run build`
+
+Isso significa que o guarda é útil para bloquear comandos diretos obviamente perigosos, mas **não** é um sandbox completo para pipelines de build não revisados. Se seu modelo de ameaça inclui código não confiável no workspace, use isolamento mais forte, como contêineres, VMs ou um fluxo de aprovação em torno de comandos de build e execução.
+
+### Exemplo de configuração
+
+```json
+{
+  "tools": {
+    "exec": {
+      "enable_deny_patterns": true,
+      "custom_deny_patterns": [
+        "\\brm\\s+-r\\b",
+        "\\bkillall\\s+python"
+      ]
+    }
+  }
+}
+```
+
+## Ferramenta Cron
+
+A ferramenta cron é usada para agendar tarefas periódicas.
+
+| Config                 | Tipo | Padrão | Descrição                                          |
+|------------------------|------|--------|-----------------------------------------------------|
+| `exec_timeout_minutes` | int  | 5      | Tempo limite de execução em minutos, 0 significa sem limite |
+
+## Ferramenta MCP
+
+A ferramenta MCP permite a integração com servidores Model Context Protocol externos.
+
+### Descoberta de ferramentas (carregamento preguiçoso)
+
+Ao conectar a vários servidores MCP, expor centenas de ferramentas simultaneamente pode esgotar a janela de contexto do LLM e aumentar os custos de API. O recurso **Discovery** resolve isso mantendo as ferramentas MCP *ocultas* por padrão.
+
+Em vez de carregar todas as ferramentas, o LLM recebe uma ferramenta de pesquisa leve (usando correspondência de palavras-chave BM25 ou Regex). Quando o LLM precisa de uma capacidade específica, ele pesquisa a biblioteca oculta. As ferramentas correspondentes são então temporariamente "desbloqueadas" e injetadas no contexto por um número configurado de turnos (`ttl`).
+
+### Configuração global
+
+| Config      | Tipo   | Padrão | Descrição                                    |
+|-------------|--------|--------|----------------------------------------------|
+| `enabled`   | bool   | false  | Habilitar integração MCP globalmente         |
+| `discovery` | object | `{}`   | Configuração de descoberta de ferramentas (veja abaixo) |
+| `servers`   | object | `{}`   | Mapa de nome do servidor para configuração do servidor |
+
+### Configuração Discovery (`discovery`)
+
+| Config               | Tipo | Padrão | Descrição                                                                                                                         |
+|----------------------|------|--------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `enabled`            | bool | false  | Se true, as ferramentas MCP ficam ocultas e são carregadas sob demanda via pesquisa. Se false, todas as ferramentas são carregadas |
+| `ttl`                | int  | 5      | Número de turnos de conversa que uma ferramenta descoberta permanece desbloqueada                                                 |
+| `max_search_results` | int  | 5      | Número máximo de ferramentas retornadas por consulta de pesquisa                                                                  |
+| `use_bm25`           | bool | true   | Habilitar a ferramenta de pesquisa por linguagem natural/palavras-chave (`tool_search_tool_bm25`). **Aviso**: consome mais recursos que a pesquisa regex |
+| `use_regex`          | bool | false  | Habilitar a ferramenta de pesquisa por padrão regex (`tool_search_tool_regex`)                                                    |
+
+> **Nota:** Se `discovery.enabled` for `true`, você **deve** habilitar pelo menos um mecanismo de pesquisa (`use_bm25` ou `use_regex`),
+> caso contrário a aplicação falhará ao iniciar.
+
+### Configuração por servidor
+
+| Config     | Tipo   | Obrigatório | Descrição                                  |
+|------------|--------|-------------|--------------------------------------------|
+| `enabled`  | bool   | sim         | Habilitar este servidor MCP                |
+| `type`     | string | não         | Tipo de transporte: `stdio`, `sse`, `http` |
+| `command`  | string | stdio       | Comando executável para transporte stdio   |
+| `args`     | array  | não         | Argumentos do comando para transporte stdio |
+| `env`      | object | não         | Variáveis de ambiente para processo stdio  |
+| `env_file` | string | não         | Caminho para arquivo de ambiente para processo stdio |
+| `url`      | string | sse/http    | URL do endpoint para transporte `sse`/`http` |
+| `headers`  | object | não         | Cabeçalhos HTTP para transporte `sse`/`http` |
+
+### Comportamento do transporte
+
+- Se `type` for omitido, o transporte é detectado automaticamente:
+    - `url` está definido → `sse`
+    - `command` está definido → `stdio`
+- `http` e `sse` ambos usam `url` + `headers` opcionais.
+- `env` e `env_file` são aplicados apenas a servidores `stdio`.
+
+### Exemplos de configuração
+
+#### 1) Servidor MCP Stdio
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-filesystem",
+            "/tmp"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+#### 2) Servidor MCP remoto SSE/HTTP
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "remote-mcp": {
+          "enabled": true,
+          "type": "sse",
+          "url": "https://example.com/mcp",
+          "headers": {
+            "Authorization": "Bearer YOUR_TOKEN"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### 3) Configuração MCP massiva com descoberta de ferramentas habilitada
+
+*Neste exemplo, o LLM verá apenas o `tool_search_tool_bm25`. Ele pesquisará e desbloqueará ferramentas do Github ou Postgres dinamicamente apenas quando solicitado pelo usuário.*
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "discovery": {
+        "enabled": true,
+        "ttl": 5,
+        "max_search_results": 5,
+        "use_bm25": true,
+        "use_regex": false
+      },
+      "servers": {
+        "github": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-github"
+          ],
+          "env": {
+            "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
+          }
+        },
+        "postgres": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-postgres",
+            "postgresql://user:password@localhost/dbname"
+          ]
+        },
+        "slack": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-slack"
+          ],
+          "env": {
+            "SLACK_BOT_TOKEN": "YOUR_SLACK_BOT_TOKEN",
+            "SLACK_TEAM_ID": "YOUR_SLACK_TEAM_ID"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Ferramenta Skills
+
+A ferramenta skills configura a descoberta e instalação de habilidades via registros como o ClawHub.
+
+### Registros
+
+| Config                             | Tipo   | Padrão               | Descrição                                    |
+|------------------------------------|--------|-----------------------|----------------------------------------------|
+| `registries.clawhub.enabled`       | bool   | true                  | Habilitar registro ClawHub                   |
+| `registries.clawhub.base_url`      | string | `https://clawhub.ai`  | URL base do ClawHub                          |
+| `registries.clawhub.auth_token`    | string | `""`                  | Token Bearer opcional para limites de taxa mais altos |
+| `registries.clawhub.search_path`   | string | `/api/v1/search`      | Caminho da API de pesquisa                   |
+| `registries.clawhub.skills_path`   | string | `/api/v1/skills`      | Caminho da API de Skills                     |
+| `registries.clawhub.download_path` | string | `/api/v1/download`    | Caminho da API de download                   |
+
+### Exemplo de configuração
+
+```json
+{
+  "tools": {
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "enabled": true,
+          "base_url": "https://clawhub.ai",
+          "auth_token": "",
+          "search_path": "/api/v1/search",
+          "skills_path": "/api/v1/skills",
+          "download_path": "/api/v1/download"
+        }
+      }
+    }
+  }
+}
+```
+
+## Variáveis de ambiente
+
+Todas as opções de configuração podem ser substituídas via variáveis de ambiente com o formato `PICOCLAW_TOOLS_<SECTION>_<KEY>`:
+
+Por exemplo:
+
+- `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
+- `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
+- `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
+- `PICOCLAW_TOOLS_MCP_ENABLED=true`
+
+Nota: Configuração de tipo mapa aninhado (por exemplo `tools.mcp.servers.<name>.*`) é configurada no `config.json` em vez de variáveis de ambiente.
diff --git a/docs/pt-br/troubleshooting.md b/docs/pt-br/troubleshooting.md
new file mode 100644
index 000000000..286ad2ac8
--- /dev/null
+++ b/docs/pt-br/troubleshooting.md
@@ -0,0 +1,45 @@
+# 🐛 Solução de Problemas
+
+> Voltar ao [README](../../README.pt-br.md)
+
+## "model ... not found in model_list" ou OpenRouter "free is not a valid model ID"
+
+**Sintoma:** Você vê um dos seguintes erros:
+
+- `Error creating provider: model "openrouter/free" not found in model_list`
+- OpenRouter retorna 400: `"free is not a valid model ID"`
+
+**Causa:** O campo `model` na sua entrada `model_list` é o que é enviado para a API. Para o OpenRouter, você deve usar o ID de modelo **completo**, não uma abreviação.
+
+- **Errado:** `"model": "free"` → OpenRouter recebe `free` e rejeita.
+- **Correto:** `"model": "openrouter/free"` → OpenRouter recebe `openrouter/free` (roteamento automático do nível gratuito).
+
+**Correção:** Em `~/.picoclaw/config.json` (ou seu caminho de configuração):
+
+1. **agents.defaults.model_name** deve corresponder a um `model_name` em `model_list` (ex.: `"openrouter-free"`).
+2. O **model** dessa entrada deve ser um ID de modelo OpenRouter válido, por exemplo:
+   - `"openrouter/free"` – nível gratuito automático
+   - `"google/gemini-2.0-flash-exp:free"`
+   - `"meta-llama/llama-3.1-8b-instruct:free"`
+
+Exemplo:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "openrouter-free"
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "openrouter-free",
+      "model": "openrouter/free",
+      "api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
+      "api_base": "https://openrouter.ai/api/v1"
+    }
+  ]
+}
+```
+
+Obtenha sua chave em [OpenRouter Keys](https://openrouter.ai/keys).
diff --git a/docs/sensitive_data_filtering.md b/docs/sensitive_data_filtering.md
new file mode 100644
index 000000000..0c10ff01d
--- /dev/null
+++ b/docs/sensitive_data_filtering.md
@@ -0,0 +1,107 @@
+# Sensitive Data Filtering
+
+PicoClaw can filter sensitive values (API keys, tokens, secrets, passwords) from tool call results before they are sent to the LLM. This prevents the LLM from seeing its own credentials, which could otherwise leak through tool output or cause confusing behavior.
+
+---
+
+## Overview
+
+When the LLM uses a tool that returns its own credentials (e.g., a tool that echoes the API key being used), those values are automatically replaced with `[FILTERED]` in the message sent to the LLM.
+
+Sensitive values are collected from [`.security.yml`](./credential_encryption.md) — the centralized storage for all sensitive configuration (API keys, tokens, secrets stored alongside `config.json`). This includes:
+
+- Model API keys
+- Channel tokens (Telegram, Discord, Slack, Matrix, etc.)
+- Web tool API keys (Brave, Tavily, Perplexity, etc.)
+- Skills tokens (GitHub, ClawHub)
+
+---
+
+## Configuration
+
+Sensitive data filtering is configured in the `tools` section of `config.json`:
+
+| Config | Type | Default | Description |
+|--------|------|---------|-------------|
+| `filter_sensitive_data` | bool | `true` | Enable/disable filtering. When `false`, no filtering is performed. |
+| `filter_min_length` | int | `8` | Minimum content length to trigger filtering. Short content is skipped for performance. |
+
+```json
+{
+  "tools": {
+    "filter_sensitive_data": true,
+    "filter_min_length": 8
+  }
+}
+```
+
+### Environment Variable
+
+| Variable | Description |
+|----------|-------------|
+| `PICOCLAW_TOOLS_FILTER_SENSITIVE_DATA` | Set to `true` or `false` to override the config value |
+
+---
+
+## How It Works
+
+1. **On startup**: All sensitive values are collected from `.security.yml` using reflection and compiled into a `strings.Replacer` (O(n+m) performance, computed once).
+
+2. **Per tool result**: Before sending any tool result content to the LLM:
+   - If `filter_sensitive_data` is `false`, content is passed through unchanged
+   - If content length < `filter_min_length`, content is passed through unchanged (fast path)
+   - Otherwise, all sensitive values are replaced with `[FILTERED]`
+
+3. **Replacement**: Uses `strings.Replacer` for efficient O(n+m) string substitution, where n = content length and m = total sensitive value length.
+
+---
+
+## Example
+
+Given the following `.security.yml`:
+
+```yaml
+model_list:
+  my-model:
+    api_keys:
+      - sk-secret-key-12345
+
+channels:
+  telegram:
+    token: "123456:ABC-DEF"
+```
+
+And a tool result containing:
+
+```
+The model is using API key sk-secret-key-12345 and Telegram bot 123456:ABC-DEF
+```
+
+The LLM will receive:
+
+```
+The model is using API key [FILTERED] and Telegram bot [FILTERED]
+```
+
+---
+
+## Performance
+
+- **Fast path**: Content shorter than `filter_min_length` (default 8) is returned unchanged without any string scanning
+- **Efficient replacement**: Uses `strings.Replacer` with O(n+m) complexity instead of regex
+- **Lazy initialization**: The replacement map is built once on first access via `sync.Once`
+
+---
+
+## Security Considerations
+
+- **Credential exposure prevention**: Without filtering, tools that echo credentials could cause the LLM to see its own API keys, potentially leading to confusion or credential leakage in logs
+- **Defense in depth**: Filtering complements (but does not replace) credential encryption — both features should be used together
+- **No false positives**: Only values explicitly stored in `.security.yml` are filtered; the LLM's general knowledge is unaffected
+
+---
+
+## Related
+
+- [Credential Encryption](./credential_encryption.md) — encrypting API keys in config
+- [Tools Configuration](./tools_configuration.md)
diff --git a/docs/spawn-tasks.md b/docs/spawn-tasks.md
new file mode 100644
index 000000000..05a5215d2
--- /dev/null
+++ b/docs/spawn-tasks.md
@@ -0,0 +1,70 @@
+# 🔄 Spawn & Async Tasks
+
+> Back to [README](../README.md)
+
+PicoClaw supports **asynchronous task execution** via the `spawn` tool. This is primarily used by the **Heartbeat** system to run long-running tasks without blocking the main agent loop.
+
+## Heartbeat
+
+The heartbeat system periodically checks `workspace/HEARTBEAT.md` for scheduled tasks. On first run, a default template is auto-generated. You can customize it to define quick tasks (handled inline) and long tasks (delegated via `spawn`).
+
+**Example `HEARTBEAT.md`:**
+
+```markdown
+## Quick Tasks (respond directly)
+
+- Report current time
+
+## Long Tasks (use spawn for async)
+
+- Search the web for AI news and summarize
+- Check email and report important messages
+```
+
+**Key behaviors:**
+
+| Feature                 | Description                                               |
+| ----------------------- | --------------------------------------------------------- |
+| **spawn**               | Creates async subagent, doesn't block heartbeat           |
+| **Independent context** | Subagent has its own context, no session history          |
+| **message tool**        | Subagent communicates with user directly via message tool |
+| **Non-blocking**        | After spawning, heartbeat continues to next task          |
+
+#### How Subagent Communication Works
+
+```
+Heartbeat triggers
+    ↓
+Agent reads HEARTBEAT.md
+    ↓
+For long task: spawn subagent
+    ↓                           ↓
+Continue to next task      Subagent works independently
+    ↓                           ↓
+All tasks done            Subagent uses "message" tool
+    ↓                           ↓
+Respond HEARTBEAT_OK      User receives result directly
+```
+
+The subagent has access to tools (message, web_search, etc.) and can communicate with the user independently without going through the main agent.
+
+**Configuration:**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| Option     | Default | Description                        |
+| ---------- | ------- | ---------------------------------- |
+| `enabled`  | `true`  | Enable/disable heartbeat           |
+| `interval` | `30`    | Check interval in minutes (min: 5) |
+
+**Environment variables:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` to disable
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` to change interval
diff --git a/docs/steering.md b/docs/steering.md
new file mode 100644
index 000000000..63294ac5f
--- /dev/null
+++ b/docs/steering.md
@@ -0,0 +1,199 @@
+# Steering
+
+Steering allows injecting messages into an already-running agent loop, interrupting it between tool calls without waiting for the entire cycle to complete.
+
+## How it works
+
+When the agent is executing a sequence of tool calls (e.g. the model requested 3 tools in a single turn), steering checks the queue **after each tool** completes. If it finds queued messages:
+
+1. The remaining tools are **skipped** and receive `"Skipped due to queued user message."` as their result
+2. The steering messages are **injected into the conversation context**
+3. The model is called again with the updated context, including the user's steering message
+
+```
+User ──► Steer("change approach")
+                │
+Agent Loop      ▼
+  ├─ tool[0] ✔  (executed)
+  ├─ [polling] → steering found!
+  ├─ tool[1] ✘  (skipped)
+  ├─ tool[2] ✘  (skipped)
+  └─ new LLM turn with steering message
+```
+
+## Scoped queues
+
+Steering is now isolated per resolved session scope, not stored in a single
+global queue.
+
+- The active turn writes and reads from its own scope key (usually the routed session key such as `agent:<agent_id>:...`)
+- `Steer()` still works outside an active turn through a legacy fallback queue
+- `Continue()` first dequeues messages for the requested session scope, then falls back to the legacy queue for backwards compatibility
+
+This prevents a message arriving from another chat, DM peer, or routed agent
+session from being injected into the wrong conversation.
+
+## Configuration
+
+In `config.json`, under `agents.defaults`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "steering_mode": "one-at-a-time"
+    }
+  }
+}
+```
+
+### Modes
+
+| Value | Behavior |
+|-------|----------|
+| `"one-at-a-time"` | **(default)** Dequeues only one message per polling cycle. If there are 3 messages in the queue, they are processed one at a time across 3 successive iterations. |
+| `"all"` | Drains the entire queue in a single poll. All pending messages are injected into the context together. |
+
+The environment variable `PICOCLAW_AGENTS_DEFAULTS_STEERING_MODE` can be used as an alternative.
+
+## Go API
+
+### Steer — Send a steering message
+
+```go
+err := agentLoop.Steer(providers.Message{
+    Role:    "user",
+    Content: "change direction, focus on X instead",
+})
+if err != nil {
+    // Queue is full (MaxQueueSize=10) or not initialized
+}
+```
+
+The message is enqueued in a thread-safe manner. Returns an error if the queue is full or not initialized. It will be picked up at the next polling point (after the current tool finishes).
+
+### SteeringMode / SetSteeringMode
+
+```go
+// Read the current mode
+mode := agentLoop.SteeringMode() // SteeringOneAtATime | SteeringAll
+
+// Change it at runtime
+agentLoop.SetSteeringMode(agent.SteeringAll)
+```
+
+### Continue — Resume an idle agent
+
+When the agent is idle (it has finished processing and its last message was from the assistant), `Continue` checks if there are steering messages in the queue and uses them to start a new cycle:
+
+```go
+response, err := agentLoop.Continue(ctx, sessionKey, channel, chatID)
+if err != nil {
+    // Error (e.g. "no default agent available")
+}
+if response == "" {
+    // No steering messages in queue, the agent stays idle
+}
+```
+
+`Continue` internally uses `SkipInitialSteeringPoll: true` to avoid double-dequeuing the same messages (since it already extracted them and passes them directly as input).
+
+`Continue` also resolves the target agent from the provided session key, so
+agent-scoped sessions continue on the correct agent instead of always using
+the default one.
+
+## Polling points in the loop
+
+Steering is checked at the following points in the agent cycle:
+
+1. **At loop start** — before the first LLM call, to catch messages enqueued during setup
+2. **After every tool completes** — including the first and the last. If steering is found and there are remaining tools, they are all skipped immediately
+3. **After a direct LLM response** — if a new steering message arrived while the model was generating a non-tool response, the loop continues instead of returning a stale answer
+4. **Right before the turn is finalized** — if steering arrived at the very end of the turn, the agent immediately starts a continuation turn instead of leaving the message orphaned in the queue
+
+## Why remaining tools are skipped
+
+When a steering message is detected, all remaining tools in the batch are skipped rather than executed. The alternative — let all tools finish and inject the steering message afterwards — was considered and rejected. Here is why.
+
+### Preventing unwanted side effects
+
+Tools can have **irreversible side effects**. If the user says "no, wait" while the agent is mid-batch, executing the remaining tools means those side effects happen anyway:
+
+| Tool batch | Steering message | With skip | Without skip |
+|---|---|---|---|
+| `[web_search, send_email]` | "don't send it" | Email **not** sent | Email sent, damage done |
+| `[query_db, write_file, spawn_agent]` | "use another database" | Only the query runs | File written + subagent spawned, all wasted |
+| `[search₁, search₂, search₃, write_file]` | user changes topic entirely | 1 search | 3 searches + file write, all irrelevant |
+
+### Avoiding wasted time
+
+Tools that take seconds (web fetches, API calls, database queries) would all run to completion before the agent sees the user's correction. In a batch of 3 tools each taking 3-4 seconds, that's 10+ seconds of work that will be discarded.
+
+With skipping, the agent reacts as soon as the current tool finishes — typically within a few seconds instead of waiting for the entire batch.
+
+### The LLM gets full context
+
+Skipped tools receive an explicit error result (`"Skipped due to queued user message."`), so the model knows exactly which actions were not performed. It can then decide whether to re-execute them with the new context, or take a different path entirely.
+
+### Trade-off: sequential execution
+
+Skipping requires tools to run **sequentially** (the previous implementation ran them in parallel). This introduces latency when the LLM requests multiple independent tools in a single turn. In practice, most batches contain 1-2 tools, so the impact is minimal compared to the benefit of being able to stop unwanted actions.
+
+## Skipped tool result format
+
+When steering interrupts a batch, each tool that was not executed receives a `tool` result with:
+
+```
+Content: "Skipped due to queued user message."
+```
+
+This is saved to the session via `AddFullMessage` and sent to the model, so it is aware that some requested actions were not performed.
+
+## Full flow example
+
+```
+1. User: "search for info on X, write a file, and send me a message"
+
+2. LLM responds with 3 tool calls: [web_search, write_file, message]
+
+3. web_search is executed → result saved
+
+4. [polling] → User called Steer("no, search for Y instead")
+
+5. write_file is skipped → "Skipped due to queued user message."
+   message is skipped    → "Skipped due to queued user message."
+
+6. Message "search for Y instead" injected into context
+
+7. LLM receives the full updated context and responds accordingly
+```
+
+## Automatic bus drain
+
+When the agent loop (`Run()`) starts processing a message, it spawns a background goroutine that keeps consuming new inbound messages from the bus. These messages are automatically redirected into the steering queue via `Steer()`. This means:
+
+- Users on any channel (Telegram, Discord, etc.) don't need to do anything special — their messages are automatically captured as steering when the agent is busy
+- Audio messages are transcribed before being steered, so the agent receives text. If transcription fails, the original (non-transcribed) message is steered as-is
+- Only messages that resolve to the **same steering scope** as the active turn are redirected. Messages for other chats/sessions are requeued onto the inbound bus so they can be processed normally
+- `system` inbound messages are not treated as steering input
+- When `processMessage` finishes, the drain goroutine is canceled and normal message consumption resumes
+
+## Steering with media
+
+Steering messages can include `Media` refs, just like normal inbound user
+messages.
+
+- The original `media://` refs are preserved in session history via `AddFullMessage`
+- Before the next provider call, steering messages go through the normal media resolution pipeline
+- Image refs are converted to data URLs for multimodal providers; non-image refs are resolved the same way as standard inbound media
+
+This applies both to in-turn steering and to idle-session continuation through
+`Continue()`.
+
+## Notes
+
+- Steering **does not interrupt** a tool that is currently executing. It waits for the current tool to finish, then checks the queue.
+- With `one-at-a-time` mode, if multiple messages are enqueued rapidly, they will be processed one per iteration. This gives the model the opportunity to react to each message individually.
+- With `all` mode, all pending messages are combined into a single injection. Useful when you want the agent to receive all the context at once.
+- The steering queue has a maximum capacity of 10 messages (`MaxQueueSize`). `Steer()` returns an error when the queue is full. In the bus drain path, the error is logged as a warning and the message is effectively dropped.
+- Manual `Steer()` calls made outside an active turn still go to the legacy fallback queue, so older integrations keep working.
diff --git a/docs/subturn.md b/docs/subturn.md
new file mode 100644
index 000000000..b84c06627
--- /dev/null
+++ b/docs/subturn.md
@@ -0,0 +1,279 @@
+# 🔄 SubTurn Mechanism
+
+> Back to [README](../README.md)
+
+## Overview
+
+The `SubTurn` mechanism is a core feature in PicoClaw that allows tools to spawn isolated, nested agent loops to handle complex sub-tasks.
+
+By using a SubTurn, an agent can break down a problem and run a separate LLM invocation in an independent, ephemeral session. This ensures that intermediate reasoning, background tasks, or sub-agent outputs do not pollute the main conversation history.
+
+## Core Capabilities
+
+- **Context Isolation**: Each SubTurn uses an `ephemeralSessionStore`. Its message history does not leak into the parent task and is destroyed upon completion. The ephemeral session holds at most **50 messages**; older messages are automatically truncated when this limit is reached.
+- **Depth & Concurrency Limits**: Prevents infinite loops and resource exhaustion.
+  - **Maximum Depth**: Up to 3 nested levels.
+  - **Maximum Concurrency**: Up to 5 concurrent sub-turns per parent turn (managed via a semaphore with a 30-second timeout).
+- **Context Protection**: Supports soft context limits (`MaxContextRunes`). It proactively truncates old messages (while preserving system prompts and recent context) before hitting the provider's hard context window limit.
+- **Error Recovery**: Automatically detects and recovers from provider context length exceeded errors and truncation errors by compressing history and retrying.
+
+## Configuration (`SubTurnConfig`)
+
+When spawning a SubTurn, you must provide a `SubTurnConfig`:
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `Model` | `string` | The LLM model to use for the sub-turn (e.g., `gpt-4o-mini`). **Required.** |
+| `Tools` | `[]tools.Tool` | Tools granted to the sub-turn. If empty, it inherits the parent's tools. |
+| `SystemPrompt` | `string` | The task description for the sub-turn. Sent as the first user message to the LLM (not as a system prompt override). |
+| `ActualSystemPrompt` | `string` | Optional explicit system prompt to replace the agent's default. Leave empty to inherit the parent agent's system prompt. |
+| `MaxTokens` | `int` | Maximum tokens for the generated response. |
+| `Async` | `bool` | Controls the result delivery mode (Synchronous vs. Asynchronous). |
+| `Critical` | `bool` | If `true`, the sub-turn continues running even if the parent finishes gracefully. |
+| `Timeout` | `time.Duration` | Maximum execution time (default: 5 minutes). |
+| `MaxContextRunes`| `int` | Soft context limit. `0` = auto-calculate (75% of model's context window, recommended), `-1` = no limit (disable soft truncation, rely only on hard context error recovery), `>0` = use specified rune limit. |
+
+> **Note:** The `Async` flag does **not** make the call non-blocking. It only controls whether the result is also delivered to the parent's `pendingResults` channel. Both modes block the caller until the sub-turn completes. For true non-blocking execution, the caller must spawn the sub-turn in a separate goroutine.
+
+## Execution Modes
+
+### Synchronous (`Async: false`)
+
+This is the standard mode where the caller needs the result immediately to proceed.
+
+- The caller blocks until the sub-turn completes.
+- The result is **only** returned directly via the function return value.
+- It is **not** delivered to the parent's pending results channel.
+
+**Example:**
+```go
+cfg := agent.SubTurnConfig{
+    Model:        "gpt-4o-mini",
+    SystemPrompt: "Analyze the provided codebase...",
+    Async:        false,
+}
+result, err := agent.SpawnSubTurn(ctx, cfg)
+// Process result immediately
+```
+
+### Asynchronous (`Async: true`)
+
+Used for "fire-and-forget" operations or parallel processing where the parent turn collects results later.
+
+- The result is delivered to the parent turn's `pendingResults` channel.
+- The result is **also** returned via the function return value (for consistency).
+- The parent's Agent Loop will poll this channel in subsequent iterations and automatically inject the results into the ongoing conversation context as `[SubTurn Result]`.
+
+**Example:**
+```go
+cfg := agent.SubTurnConfig{
+    Model:        "gpt-4o-mini",
+    SystemPrompt: "Run a background security scan...",
+    Async:        true,
+}
+result, err := agent.SpawnSubTurn(ctx, cfg)
+// The result will also be injected into the parent loop later via channel
+```
+
+## Error Recovery and Retries
+
+SubTurns implement automatic retry mechanisms for transient errors:
+
+| Error Type | Max Retries | Recovery Action |
+|:-----------|:------------|:----------------|
+| Context Length Exceeded | 2 | Force compress history and retry |
+| Response Truncated (`finish_reason="truncated"`) | 2 | Inject recovery prompt and retry |
+
+### Truncation Recovery
+When the LLM response is truncated (`finish_reason="truncated"`), SubTurn automatically:
+1. Detects the truncation from `turnState.lastFinishReason`
+2. Injects a recovery prompt: "Your previous response was truncated due to length. Please provide a shorter, complete response..."
+3. Retries up to 2 times
+
+### Context Error Recovery
+When the provider returns a context length error (e.g., `context_length_exceeded`):
+1. Force compresses the message history (drops oldest 50% of conversation)
+2. Retries with the compressed context
+3. Up to 2 retries before failing
+
+## Lifecycle and Cancellation
+
+SubTurns operate within an independent context but maintain a structural link to their parent `turnState`.
+
+### Graceful Parent Finish
+When the parent task finishes naturally (`Finish(false)`):
+- **Non-critical** sub-turns receive a signal to exit gracefully without throwing an error.
+- **Critical** (`Critical: true`) sub-turns continue running in the background. Once finished, their results are emitted as **Orphan Results** so the data is not lost.
+
+### Hard Abort
+When the parent task is forcefully aborted (e.g., user interrupts with `/stop`):
+- A cascading cancellation is triggered, instantly terminating all child and grandchild sub-turns.
+- The root turn's session history rolls back to the snapshot taken at turn start (`initialHistoryLength`), preventing dirty context. SubTurns are not affected by this rollback as they use ephemeral sessions that are discarded anyway.
+
+## Agent Loop Integration
+
+### Bus Draining During Processing
+
+When a message enters the `Run()` loop, the agent starts a `drainBusToSteering` goroutine before calling `processMessage`. This goroutine runs concurrently with the entire processing lifecycle and continuously consumes any new inbound messages from the bus, redirecting them into the **steering queue** instead of dropping them.
+
+This ensures that if a user sends a follow-up message while the agent is processing (including during SubTurn execution), the message is not lost — it will be picked up between tool call iterations via `dequeueSteeringMessages`.
+
+The drain goroutine stops automatically when `processMessage` returns (via a cancellable context).
+
+### Pending Result Polling
+
+The agent loop polls for async SubTurn results at two points per iteration:
+1. **Before the LLM call**: injects any arrived results as `[SubTurn Result]` messages into the conversation context.
+2. **After all tool executions**: polls again during the tool loop to catch results that arrived during tool execution.
+3. **After the final iteration**: one last poll before the turn ends to avoid losing late-arriving results.
+
+### Turn State Tracking
+
+All active root turns are registered in `AgentLoop.activeTurnStates` (`sync.Map`, keyed by session key). This allows `HardAbort` and `/subagents` observability commands to find and operate on active turns.
+
+## Event Bus Integration
+
+SubTurns emit specific events to the PicoClaw `EventBus` for observability and debugging:
+
+| Event Kind | When Emitted | Payload |
+|:------|:-------------|:--------|
+| `subturn_spawn` | Sub-turn successfully initialized | `SubTurnSpawnPayload{AgentID, Label, ParentTurnID}` |
+| `subturn_end` | Sub-turn finishes (success or error) | `SubTurnEndPayload{AgentID, Status}` |
+| `subturn_result_delivered` | Async result successfully delivered to parent | `SubTurnResultDeliveredPayload{TargetChannel, TargetChatID, ContentLen}` |
+| `subturn_orphan` | Result cannot be delivered (parent finished or channel full) | `SubTurnOrphanPayload{ParentTurnID, ChildTurnID, Reason}` |
+
+## API Reference
+
+### SpawnSubTurn (Public Entry Point)
+
+```go
+func SpawnSubTurn(ctx context.Context, cfg SubTurnConfig) (*tools.ToolResult, error)
+```
+
+This is the exported package-level entry point for agent-internal code (e.g., tests, direct invocations). It retrieves `AgentLoop` and `turnState` from context and delegates to the internal `spawnSubTurn`.
+
+**Requirements:**
+- `AgentLoop` must be injected into context via `WithAgentLoop()`
+- Parent `turnState` must exist in context (automatically set when called from tools)
+
+**Returns:**
+- `*tools.ToolResult`: Contains `ForLLM` field with the sub-turn's output
+- `error`: One of the defined error types or context errors
+
+### AgentLoopSpawner (Interface Implementation)
+
+```go
+type AgentLoopSpawner struct { al *AgentLoop }
+
+func (s *AgentLoopSpawner) SpawnSubTurn(ctx context.Context, cfg tools.SubTurnConfig) (*tools.ToolResult, error)
+```
+
+This implements the `tools.SubTurnSpawner` interface for use by tools that need to spawn sub-turns without a direct import of the `agent` package (avoiding circular dependencies). It converts `tools.SubTurnConfig` → `agent.SubTurnConfig` before delegating to the internal `spawnSubTurn`.
+
+### NewSubTurnSpawner
+
+```go
+func NewSubTurnSpawner(al *AgentLoop) *AgentLoopSpawner
+```
+
+Creates a new spawner instance for the given AgentLoop. Pass the returned value to `SpawnTool.SetSpawner()` or `SubagentTool.SetSpawner()` during tool registration.
+
+### Continue
+
+```go
+func (al *AgentLoop) Continue(ctx context.Context, sessionKey string) error
+```
+
+Resumes an idle agent turn by injecting any queued steering messages as a new LLM iteration. Used when the agent is waiting and a deferred steering message needs to be processed without a new inbound message arriving.
+
+## Context Propagation
+
+SubTurn relies on context values for proper operation:
+
+| Context Key | Purpose |
+|:------------|:--------|
+| `agentLoopKey` | Stores `*AgentLoop` for tool access and SubTurn spawning |
+| `turnStateKey` | Stores `*turnState` for hierarchy tracking and result delivery |
+
+### Injecting Dependencies
+
+```go
+// Before calling tools that may spawn SubTurns
+ctx = WithAgentLoop(ctx, agentLoop)
+ctx = withTurnState(ctx, turnState)
+```
+
+### Independent Child Context
+
+**Important**: The child SubTurn uses an **independent context** derived from `context.Background()`, not from the parent context. This design choice:
+
+- Allows critical SubTurns to continue after parent cancellation
+- Prevents parent timeout from affecting child execution
+- Child has its own timeout for self-protection (`Timeout` config or 5 minutes default)
+
+## Error Types
+
+| Error | Condition |
+|:------|:----------|
+| `ErrDepthLimitExceeded` | SubTurn depth exceeds 3 levels |
+| `ErrInvalidSubTurnConfig` | Required field `Model` is empty |
+| `ErrConcurrencyTimeout` | All 5 concurrency slots occupied for 30+ seconds |
+| Context errors | Parent context cancelled during semaphore acquisition |
+
+## Thread Safety
+
+SubTurns are designed for concurrent execution:
+
+- **Parent-child relationships**: Managed under mutex (`parentTS.mu.Lock()`)
+- **Active turn tracking**: Uses `sync.Map` for concurrent access to `activeTurnStates`
+- **ID generation**: Uses `atomic.Int64` for unique SubTurn IDs (format: `subturn-N`, globally monotonic per `AgentLoop` instance)
+- **Result delivery**: Reads parent state under lock, releases before channel send (small race window acceptable)
+
+## Orphan Results
+
+An orphan result occurs when:
+1. Parent turn finishes before the SubTurn completes
+2. The `pendingResults` channel is full (buffer size: 16)
+
+When a result becomes orphan:
+- `SubTurnOrphanResultEvent` is emitted to EventBus
+- The result is **NOT** delivered to the LLM context
+- External systems can listen to this event for custom handling
+
+### Preventing Orphan Results
+- Use `Critical: true` for important SubTurns that must complete
+- Monitor `SubTurnOrphanResultEvent` for observability
+- Consider the 16-buffer limit when spawning many async SubTurns
+
+## Tool Inheritance
+
+### When `cfg.Tools` is empty:
+- SubTurn inherits **all** tools from the parent agent
+- Tools are registered in a new `ToolRegistry` instance
+- Tool TTL is managed independently from parent
+
+### When `cfg.Tools` is specified:
+- Only the specified tools are available to the SubTurn
+- Parent tools are **NOT** merged
+- Use this to restrict SubTurn capabilities for security or focus
+
+**Example - Restricted SubTurn:**
+```go
+cfg := agent.SubTurnConfig{
+    Model: "gpt-4o-mini",
+    Tools: []tools.Tool{readOnlyTool}, // Only read-only access
+    SystemPrompt: "Analyze the file structure...",
+}
+```
+
+## Reference
+
+| Constant | Value |
+|:---------|:------|
+| `maxSubTurnDepth` | 3 |
+| `maxConcurrentSubTurns` | 5 |
+| `concurrencyTimeout` | 30s |
+| `defaultSubTurnTimeout` | 5m |
+| `maxEphemeralHistorySize` | 50 messages |
+| `pendingResults` buffer | 16 |
+| `MaxContextRunes` default | 75% of model context window |
diff --git a/docs/tools_configuration.md b/docs/tools_configuration.md
index 8aba1aa91..b5907b991 100644
--- a/docs/tools_configuration.md
+++ b/docs/tools_configuration.md
@@ -7,49 +7,164 @@ PicoClaw's tools configuration is located in the `tools` field of `config.json`.
 ```json
 {
   "tools": {
-    "web": { ... },
-    "exec": { ... },
-    "cron": { ... },
-    "skills": { ... }
+    "web": {
+      ...
+    },
+    "mcp": {
+      ...
+    },
+    "exec": {
+      ...
+    },
+    "cron": {
+      ...
+    },
+    "skills": {
+      ...
+    }
   }
 }
 ```
 
+## Sensitive Data Filtering
+
+Before tool results are sent to the LLM, PicoClaw can filter sensitive values (API keys, tokens, secrets) from the output. This prevents the LLM from seeing its own credentials.
+
+See [Sensitive Data Filtering](../sensitive_data_filtering.md) for full documentation.
+
+| Config | Type | Default | Description |
+|--------|------|---------|-------------|
+| `filter_sensitive_data` | bool | `true` | Enable/disable filtering |
+| `filter_min_length` | int | `8` | Minimum content length to trigger filtering |
+
 ## Web Tools
 
 Web tools are used for web search and fetching.
 
+### Web Fetcher
+General settings for fetching and processing webpage content.
+
+| Config              | Type   | Default       | Description                                                                                   |
+|---------------------|--------|---------------|-----------------------------------------------------------------------------------------------|
+| `enabled`           | bool   | true          | Enable the webpage fetching capability.                                                       |
+| `fetch_limit_bytes` | int    | 10485760      | Maximum size of the webpage payload to fetch, in bytes (default is 10MB).                     |
+| `format`            | string | "plaintext"   | Output format of the fetched content. Options: `plaintext` or `markdown` (recommended).       |
+
 ### Brave
 
-| Config | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enabled` | bool | false | Enable Brave search |
-| `api_key` | string | - | Brave Search API key |
-| `max_results` | int | 5 | Maximum number of results |
+| Config        | Type     | Default | Description                                    |
+|---------------|----------|---------|------------------------------------------------|
+| `enabled`     | bool     | false   | Enable Brave search                            |
+| `api_key`     | string   | -       | Brave Search API key                           |
+| `api_keys`    | string[] | -       | Multiple API keys for rotation (takes priority over `api_key`) |
+| `max_results` | int      | 5       | Maximum number of results                      |
 
 ### DuckDuckGo
 
-| Config | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enabled` | bool | true | Enable DuckDuckGo search |
-| `max_results` | int | 5 | Maximum number of results |
+| Config        | Type | Default | Description               |
+|---------------|------|---------|---------------------------|
+| `enabled`     | bool | true    | Enable DuckDuckGo search  |
+| `max_results` | int  | 5       | Maximum number of results |
+
+### Baidu Search
+
+Baidu Search uses the [Qianfan AI Search API](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5), which is AI-powered and optimized for Chinese-language queries.
+
+| Config        | Type   | Default                                                          | Description               |
+|---------------|--------|------------------------------------------------------------------|---------------------------|
+| `enabled`     | bool   | false                                                            | Enable Baidu Search       |
+| `api_key`     | string | -                                                                | Qianfan API key           |
+| `base_url`    | string | `https://qianfan.baidubce.com/v2/ai_search/web_search`          | Baidu Search API URL      |
+| `max_results` | int    | 10                                                               | Maximum number of results |
+
+```json
+{
+  "tools": {
+    "web": {
+      "baidu_search": {
+        "enabled": true,
+        "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
+        "max_results": 10
+      }
+    }
+  }
+}
+```
 
 ### Perplexity
 
-| Config | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enabled` | bool | false | Enable Perplexity search |
-| `api_key` | string | - | Perplexity API key |
-| `max_results` | int | 5 | Maximum number of results |
+| Config        | Type     | Default | Description                                    |
+|---------------|----------|---------|------------------------------------------------|
+| `enabled`     | bool     | false   | Enable Perplexity search                       |
+| `api_key`     | string   | -       | Perplexity API key                             |
+| `api_keys`    | string[] | -       | Multiple API keys for rotation (takes priority over `api_key`) |
+| `max_results` | int      | 5       | Maximum number of results                      |
+
+### Tavily
+
+| Config        | Type   | Default | Description               |
+|---------------|--------|---------|---------------------------|
+| `enabled`     | bool   | false   | Enable Tavily search      |
+| `api_key`     | string | -       | Tavily API key            |
+| `base_url`    | string | -       | Custom Tavily API base URL |
+| `max_results` | int    | 0       | Maximum number of results (0 = default) |
+
+### SearXNG
+
+| Config        | Type   | Default                  | Description               |
+|---------------|--------|--------------------------|---------------------------|
+| `enabled`     | bool   | false                    | Enable SearXNG search     |
+| `base_url`    | string | `http://localhost:8888`  | SearXNG instance URL      |
+| `max_results` | int    | 5                        | Maximum number of results |
+
+### GLM Search
+
+| Config          | Type   | Default                                              | Description               |
+|-----------------|--------|------------------------------------------------------|---------------------------|
+| `enabled`       | bool   | false                                                | Enable GLM Search         |
+| `api_key`       | string | -                                                    | GLM API key               |
+| `base_url`      | string | `https://open.bigmodel.cn/api/paas/v4/web_search`   | GLM Search API URL        |
+| `search_engine` | string | `search_std`                                         | Search engine type        |
+| `max_results`   | int    | 5                                                    | Maximum number of results |
+
+### Additional Web Settings
+
+| Config                   | Type     | Default | Description                                                    |
+|--------------------------|----------|---------|----------------------------------------------------------------|
+| `prefer_native`          | bool     | true    | Prefer provider's native search over configured search engines |
+| `private_host_whitelist` | string[] | `[]`    | Private/internal hosts allowed for web fetching                |
 
 ## Exec Tool
 
 The exec tool is used to execute shell commands.
 
-| Config | Type | Default | Description |
-|--------|------|---------|-------------|
-| `enable_deny_patterns` | bool | true | Enable default dangerous command blocking |
-| `custom_deny_patterns` | array | [] | Custom deny patterns (regular expressions) |
+| Config                 | Type  | Default | Description                                |
+|------------------------|-------|---------|--------------------------------------------|
+| `enabled`              | bool  | true    | Enable the exec tool                        |
+| `enable_deny_patterns` | bool  | true    | Enable default dangerous command blocking  |
+| `custom_deny_patterns` | array | []      | Custom deny patterns (regular expressions) |
+
+### Disabling the Exec Tool
+
+To completely disable the `exec` tool, set `enabled` to `false`:
+
+**Via config file:**
+```json
+{
+  "tools": {
+    "exec": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**Via environment variable:**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **Note:** When disabled, the agent will not be able to execute shell commands. This also affects the Cron tool's ability to run scheduled shell commands.
 
 ### Functionality
 
@@ -73,6 +188,22 @@ By default, PicoClaw blocks the following dangerous commands:
 - Git: `git push`, `git force`
 - Other: `eval`, `source *.sh`
 
+### Known Architectural Limitation
+
+The exec guard only validates the top-level command sent to PicoClaw. It does **not** recursively inspect child
+processes spawned by build tools or scripts after that command starts running.
+
+Examples of workflows that can bypass the direct command guard once the initial command is allowed:
+
+- `make run`
+- `go run ./cmd/...`
+- `cargo run`
+- `npm run build`
+
+This means the guard is useful for blocking obviously dangerous direct commands, but it is **not** a full sandbox for
+unreviewed build pipelines. If your threat model includes untrusted code in the workspace, use stronger isolation such
+as containers, VMs, or an approval flow around build-and-run commands.
+
 ### Configuration Example
 
 ```json
@@ -93,9 +224,213 @@ By default, PicoClaw blocks the following dangerous commands:
 
 The cron tool is used for scheduling periodic tasks.
 
-| Config | Type | Default | Description |
-|--------|------|---------|-------------|
-| `exec_timeout_minutes` | int | 5 | Execution timeout in minutes, 0 means no limit |
+| Config                 | Type | Default | Description                                    |
+|------------------------|------|---------|------------------------------------------------|
+| `exec_timeout_minutes` | int  | 5       | Execution timeout in minutes, 0 means no limit |
+| `allow_command`        | bool | false   | Allow cron tasks to execute shell commands      |
+
+## MCP Tool
+
+The MCP tool enables integration with external Model Context Protocol servers.
+
+### Tool Discovery (Lazy Loading)
+
+When connecting to multiple MCP servers, exposing hundreds of tools simultaneously can exhaust the LLM's context window
+and increase API costs. The **Discovery** feature solves this by keeping MCP tools *hidden* by default.
+
+Instead of loading all tools, the LLM is provided with a lightweight search tool (using BM25 keyword matching or Regex).
+When the LLM needs a specific capability, it searches the hidden library. Matching tools are then temporarily "unlocked"
+and injected into the context for a configured number of turns (`ttl`).
+
+### Global Config
+
+| Config      | Type   | Default | Description                                  |
+|-------------|--------|---------|----------------------------------------------|
+| `enabled`   | bool   | false   | Enable MCP integration globally              |
+| `discovery` | object | `{}`    | Configuration for Tool Discovery (see below) |
+| `servers`   | object | `{}`    | Map of server name to server config          |
+
+### Discovery Config (`discovery`)
+
+| Config               | Type | Default | Description                                                                                                                       |
+|----------------------|------|---------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `enabled`            | bool | false   | Global default: if `true`, all MCP tools are hidden and loaded on-demand via search; if `false`, all tools are loaded into context. Individual servers can override this with the per-server `deferred` field. |
+| `ttl`                | int  | 5       | Number of conversational turns a discovered tool remains unlocked                                                                 |
+| `max_search_results` | int  | 5       | Maximum number of tools returned per search query                                                                                 |
+| `use_bm25`           | bool | true    | Enable the natural language/keyword search tool (`tool_search_tool_bm25`). **Warning**: consumes more resources than regex search |
+| `use_regex`          | bool | false   | Enable the regex pattern search tool (`tool_search_tool_regex`)                                                                   |
+
+> **Note:** If `discovery.enabled` is `true`, you MUST enable at least one search engine (`use_bm25` or `use_regex`),
+> otherwise the application will fail to start.
+
+### Per-Server Config
+
+| Config     | Type    | Required | Description                                                                                                                                                     |
+|------------|---------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `enabled`  | bool    | yes      | Enable this MCP server                                                                                                                                          |
+| `deferred` | bool    | no       | Override deferred mode for this server only. `true` = tools are hidden and discoverable via search; `false` = tools are always visible in context. When omitted, the global `discovery.enabled` value applies. |
+| `type`     | string  | no       | Transport type: `stdio`, `sse`, `http`                                                                                                                          |
+| `command`  | string  | stdio    | Executable command for stdio transport                                                                                                                          |
+| `args`     | array   | no       | Command arguments for stdio transport                                                                                                                           |
+| `env`      | object  | no       | Environment variables for stdio process                                                                                                                         |
+| `env_file` | string  | no       | Path to environment file for stdio process                                                                                                                      |
+| `url`      | string  | sse/http | Endpoint URL for `sse`/`http` transport                                                                                                                         |
+| `headers`  | object  | no       | HTTP headers for `sse`/`http` transport                                                                                                                         |
+
+### Transport Behavior
+
+- If `type` is omitted, transport is auto-detected:
+    - `url` is set → `sse`
+    - `command` is set → `stdio`
+- `http` and `sse` both use `url` + optional `headers`.
+- `env` and `env_file` are only applied to `stdio` servers.
+
+### Configuration Examples
+
+#### 1) Stdio MCP server
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-filesystem",
+            "/tmp"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+#### 2) Remote SSE/HTTP MCP server
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "remote-mcp": {
+          "enabled": true,
+          "type": "sse",
+          "url": "https://example.com/mcp",
+          "headers": {
+            "Authorization": "Bearer YOUR_TOKEN"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### 3) Massive MCP setup with Tool Discovery enabled
+
+*In this example, the LLM will only see the `tool_search_tool_bm25`. It will search and unlock Github or Postgres tools
+dynamically only when requested by the user.*
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "discovery": {
+        "enabled": true,
+        "ttl": 5,
+        "max_search_results": 5,
+        "use_bm25": true,
+        "use_regex": false
+      },
+      "servers": {
+        "github": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-github"
+          ],
+          "env": {
+            "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
+          }
+        },
+        "postgres": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-postgres",
+            "postgresql://user:password@localhost/dbname"
+          ]
+        },
+        "slack": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-slack"
+          ],
+          "env": {
+            "SLACK_BOT_TOKEN": "YOUR_SLACK_BOT_TOKEN",
+            "SLACK_TEAM_ID": "YOUR_SLACK_TEAM_ID"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### 4) Mixed setup: per-server deferred override
+
+*Discovery is enabled globally, but `filesystem` is pinned as always-visible while `context7` follows the global
+default (deferred). `aws` explicitly opts in to deferred mode even though it is the same as the global default.*
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "discovery": {
+        "enabled": true,
+        "ttl": 5,
+        "max_search_results": 5,
+        "use_bm25": true
+      },
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
+          "deferred": false
+        },
+        "context7": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "@upstash/context7-mcp"]
+        },
+        "aws": {
+          "enabled": true,
+          "command": "npx",
+          "args": ["-y", "aws-mcp-server"],
+          "deferred": true
+        }
+      }
+    }
+  }
+}
+```
+
+> **Tip:** `deferred` on a per-server basis is independent of `discovery.enabled`. You can keep
+> `discovery.enabled: false` globally (all tools visible by default) and still mark individual
+> high-volume servers as `"deferred": true` to avoid polluting the context with their tools.
 
 ## Skills Tool
 
@@ -103,13 +438,32 @@ The skills tool configures skill discovery and installation via registries like
 
 ### Registries
 
-| Config | Type | Default | Description |
-|--------|------|---------|-------------|
-| `registries.clawhub.enabled` | bool | true | Enable ClawHub registry |
-| `registries.clawhub.base_url` | string | `https://clawhub.ai` | ClawHub base URL |
-| `registries.clawhub.search_path` | string | `/api/v1/search` | Search API path |
-| `registries.clawhub.skills_path` | string | `/api/v1/skills` | Skills API path |
-| `registries.clawhub.download_path` | string | `/api/v1/download` | Download API path |
+| Config                             | Type   | Default              | Description                                  |
+|------------------------------------|--------|----------------------|----------------------------------------------|
+| `registries.clawhub.enabled`       | bool   | true                 | Enable ClawHub registry                      |
+| `registries.clawhub.base_url`      | string | `https://clawhub.ai` | ClawHub base URL                             |
+| `registries.clawhub.auth_token`    | string | `""`                 | Optional Bearer token for higher rate limits |
+| `registries.clawhub.search_path`   | string | `""`                 | Search API path                              |
+| `registries.clawhub.skills_path`   | string | `""`                 | Skills API path                              |
+| `registries.clawhub.download_path` | string | `""`                 | Download API path                            |
+| `registries.clawhub.timeout`       | int    | 0                    | Request timeout in seconds (0 = default)     |
+| `registries.clawhub.max_zip_size`  | int    | 0                    | Max skill zip size in bytes (0 = default)    |
+| `registries.clawhub.max_response_size` | int | 0                   | Max API response size in bytes (0 = default) |
+
+### GitHub Integration
+
+| Config           | Type   | Default | Description                          |
+|------------------|--------|---------|--------------------------------------|
+| `github.proxy`   | string | `""`    | HTTP proxy for GitHub API requests   |
+| `github.token`   | string | `""`    | GitHub personal access token         |
+
+### Search Settings
+
+| Config                    | Type | Default | Description                                |
+|---------------------------|------|---------|--------------------------------------------|
+| `max_concurrent_searches` | int  | 2       | Max concurrent skill search requests       |
+| `search_cache.max_size`   | int  | 50      | Max cached search results                  |
+| `search_cache.ttl_seconds`| int  | 300     | Cache TTL in seconds                       |
 
 ### Configuration Example
 
@@ -121,10 +475,17 @@ The skills tool configures skill discovery and installation via registries like
         "clawhub": {
           "enabled": true,
           "base_url": "https://clawhub.ai",
-          "search_path": "/api/v1/search",
-          "skills_path": "/api/v1/skills",
-          "download_path": "/api/v1/download"
+          "auth_token": ""
         }
+      },
+      "github": {
+        "proxy": "",
+        "token": ""
+      },
+      "max_concurrent_searches": 2,
+      "search_cache": {
+        "max_size": 50,
+        "ttl_seconds": 300
       }
     }
   }
@@ -136,8 +497,12 @@ The skills tool configures skill discovery and installation via registries like
 All configuration options can be overridden via environment variables with the format `PICOCLAW_TOOLS_<SECTION>_<KEY>`:
 
 For example:
+
 - `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
 - `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
 - `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
+- `PICOCLAW_TOOLS_MCP_ENABLED=true`
 
-Note: Array-type environment variables are not currently supported and must be set via the config file.
+Note: Nested map-style config (for example `tools.mcp.servers.<name>.*`) is configured in `config.json` rather than
+environment variables.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 219d2c6e3..096beec78 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -14,7 +14,7 @@
 
 **Fix:** In `~/.picoclaw/config.json` (or your config path):
 
-1. **agents.defaults.model** must match a `model_name` in `model_list` (e.g. `"openrouter-free"`).
+1. **agents.defaults.model_name** must match a `model_name` in `model_list` (e.g. `"openrouter-free"`).
 2. That entry’s **model** must be a valid OpenRouter model ID, for example:
    - `"openrouter/free"` – auto free-tier
    - `"google/gemini-2.0-flash-exp:free"`
@@ -26,7 +26,7 @@ Example snippet:
 {
   "agents": {
     "defaults": {
-      "model": "openrouter-free"
+      "model_name": "openrouter-free"
     }
   },
   "model_list": [
diff --git a/docs/vi/ANTIGRAVITY_AUTH.md b/docs/vi/ANTIGRAVITY_AUTH.md
new file mode 100644
index 000000000..783dc5181
--- /dev/null
+++ b/docs/vi/ANTIGRAVITY_AUTH.md
@@ -0,0 +1,807 @@
+> Quay lại [README](../../README.vi.md)
+
+# Hướng dẫn Xác thực và Tích hợp Antigravity
+
+## Tổng quan
+
+**Antigravity** (Google Cloud Code Assist) là nhà cung cấp mô hình AI được Google hỗ trợ, cung cấp quyền truy cập vào các mô hình như Claude Opus 4.6 và Gemini thông qua hạ tầng đám mây của Google. Tài liệu này cung cấp hướng dẫn đầy đủ về cách xác thực hoạt động, cách lấy danh sách mô hình và cách triển khai nhà cung cấp mới trong PicoClaw.
+
+---
+
+## Mục lục
+
+1. [Luồng xác thực](#luồng-xác-thực)
+2. [Chi tiết triển khai OAuth](#chi-tiết-triển-khai-oauth)
+3. [Quản lý token](#quản-lý-token)
+4. [Lấy danh sách mô hình](#lấy-danh-sách-mô-hình)
+5. [Theo dõi mức sử dụng](#theo-dõi-mức-sử-dụng)
+6. [Cấu trúc plugin nhà cung cấp](#cấu-trúc-plugin-nhà-cung-cấp)
+7. [Yêu cầu tích hợp](#yêu-cầu-tích-hợp)
+8. [Các endpoint API](#các-endpoint-api)
+9. [Cấu hình](#cấu-hình)
+10. [Tạo nhà cung cấp mới trong PicoClaw](#tạo-nhà-cung-cấp-mới-trong-picoclaw)
+
+---
+
+## Luồng xác thực
+
+### 1. OAuth 2.0 với PKCE
+
+Antigravity sử dụng **OAuth 2.0 với PKCE (Proof Key for Code Exchange)** để xác thực an toàn:
+
+```
+┌─────────────┐                                    ┌─────────────────┐
+│   Client    │ ───(1) Generate PKCE Pair────────> │                 │
+│             │ ───(2) Open Auth URL─────────────> │  Google OAuth   │
+│             │                                    │    Server       │
+│             │ <──(3) Redirect with Code───────── │                 │
+│             │                                    └─────────────────┘
+│             │ ───(4) Exchange Code for Tokens──> │   Token URL     │
+│             │                                    │                 │
+│             │ <──(5) Access + Refresh Tokens──── │                 │
+└─────────────┘                                    └─────────────────┘
+```
+
+### 2. Các bước chi tiết
+
+#### Bước 1: Tạo tham số PKCE
+```typescript
+function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = randomBytes(32).toString("hex");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+```
+
+#### Bước 2: Xây dựng URL ủy quyền
+```typescript
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const REDIRECT_URI = "http://localhost:51121/oauth-callback";
+
+function buildAuthUrl(params: { challenge: string; state: string }): string {
+  const url = new URL(AUTH_URL);
+  url.searchParams.set("client_id", CLIENT_ID);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("redirect_uri", REDIRECT_URI);
+  url.searchParams.set("scope", SCOPES.join(" "));
+  url.searchParams.set("code_challenge", params.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", params.state);
+  url.searchParams.set("access_type", "offline");
+  url.searchParams.set("prompt", "consent");
+  return url.toString();
+}
+```
+
+**Các phạm vi quyền cần thiết:**
+```typescript
+const SCOPES = [
+  "https://www.googleapis.com/auth/cloud-platform",
+  "https://www.googleapis.com/auth/userinfo.email",
+  "https://www.googleapis.com/auth/userinfo.profile",
+  "https://www.googleapis.com/auth/cclog",
+  "https://www.googleapis.com/auth/experimentsandconfigs",
+];
+```
+
+#### Bước 3: Xử lý callback OAuth
+
+**Chế độ tự động (Phát triển cục bộ):**
+- Khởi động máy chủ HTTP cục bộ trên cổng 51121
+- Chờ chuyển hướng từ Google
+- Trích xuất mã ủy quyền từ tham số truy vấn
+
+**Chế độ thủ công (Từ xa/Không có giao diện):**
+- Hiển thị URL ủy quyền cho người dùng
+- Người dùng hoàn tất xác thực trong trình duyệt
+- Người dùng dán URL chuyển hướng đầy đủ vào terminal
+- Phân tích mã từ URL đã dán
+
+#### Bước 4: Đổi mã lấy token
+```typescript
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+async function exchangeCode(params: {
+  code: string;
+  verifier: string;
+}): Promise<{ access: string; refresh: string; expires: number }> {
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      code: params.code,
+      grant_type: "authorization_code",
+      redirect_uri: REDIRECT_URI,
+      code_verifier: params.verifier,
+    }),
+  });
+
+  const data = await response.json();
+  
+  return {
+    access: data.access_token,
+    refresh: data.refresh_token,
+    expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, // 5 min buffer
+  };
+}
+```
+
+#### Bước 5: Lấy dữ liệu người dùng bổ sung
+
+**Email người dùng:**
+```typescript
+async function fetchUserEmail(accessToken: string): Promise<string | undefined> {
+  const response = await fetch(
+    "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+    { headers: { Authorization: `Bearer ${accessToken}` } }
+  );
+  const data = await response.json();
+  return data.email;
+}
+```
+
+**ID dự án (Bắt buộc cho các lệnh gọi API):**
+```typescript
+async function fetchProjectId(accessToken: string): Promise<string> {
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "google-api-nodejs-client/9.15.1",
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+    "Client-Metadata": JSON.stringify({
+      ideType: "IDE_UNSPECIFIED",
+      platform: "PLATFORM_UNSPECIFIED",
+      pluginType: "GEMINI",
+    }),
+  };
+
+  const response = await fetch(
+    "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        metadata: {
+          ideType: "IDE_UNSPECIFIED",
+          platform: "PLATFORM_UNSPECIFIED",
+          pluginType: "GEMINI",
+        },
+      }),
+    }
+  );
+
+  const data = await response.json();
+  return data.cloudaicompanionProject || "rising-fact-p41fc"; // Giá trị mặc định dự phòng
+}
+```
+
+---
+
+## Chi tiết triển khai OAuth
+
+### Thông tin xác thực client
+
+**Quan trọng:** Các giá trị này được mã hóa base64 trong mã nguồn để đồng bộ với pi-ai:
+
+```typescript
+const decode = (s: string) => Buffer.from(s, "base64").toString();
+
+const CLIENT_ID = decode(
+  "MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ=="
+);
+const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
+```
+
+### Các chế độ luồng OAuth
+
+1. **Luồng tự động** (Máy cục bộ có trình duyệt):
+   - Tự động mở trình duyệt
+   - Máy chủ callback cục bộ bắt chuyển hướng
+   - Không cần tương tác người dùng sau xác thực ban đầu
+
+2. **Luồng thủ công** (Từ xa/Không có giao diện/WSL2):
+   - Hiển thị URL để sao chép-dán thủ công
+   - Người dùng hoàn tất xác thực trong trình duyệt bên ngoài
+   - Người dùng dán lại URL chuyển hướng đầy đủ
+
+```typescript
+function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+  return isRemote || isWSL2Sync();
+}
+```
+
+---
+
+## Quản lý token
+
+### Cấu trúc hồ sơ xác thực
+
+```typescript
+type OAuthCredential = {
+  type: "oauth";
+  provider: "google-antigravity";
+  access: string;           // Token truy cập
+  refresh: string;          // Token làm mới
+  expires: number;          // Dấu thời gian hết hạn (ms kể từ epoch)
+  email?: string;           // Email người dùng
+  projectId?: string;       // ID dự án Google Cloud
+};
+```
+
+### Làm mới token
+
+Thông tin xác thực bao gồm token làm mới có thể được sử dụng để lấy token truy cập mới khi token hiện tại hết hạn. Thời gian hết hạn được đặt với bộ đệm 5 phút để tránh điều kiện tranh chấp.
+
+---
+
+## Lấy danh sách mô hình
+
+### Lấy các mô hình khả dụng
+
+```typescript
+const BASE_URL = "https://cloudcode-pa.googleapis.com";
+
+async function fetchAvailableModels(
+  accessToken: string,
+  projectId: string
+): Promise<Model[]> {
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "antigravity",
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+  };
+
+  const response = await fetch(
+    `${BASE_URL}/v1internal:fetchAvailableModels`,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ project: projectId }),
+    }
+  );
+
+  const data = await response.json();
+  
+  // Trả về các mô hình kèm thông tin hạn mức
+  return Object.entries(data.models).map(([modelId, modelInfo]) => ({
+    id: modelId,
+    displayName: modelInfo.displayName,
+    quotaInfo: {
+      remainingFraction: modelInfo.quotaInfo?.remainingFraction,
+      resetTime: modelInfo.quotaInfo?.resetTime,
+      isExhausted: modelInfo.quotaInfo?.isExhausted,
+    },
+  }));
+}
+```
+
+### Định dạng phản hồi
+
+```typescript
+type FetchAvailableModelsResponse = {
+  models?: Record<string, {
+    displayName?: string;
+    quotaInfo?: {
+      remainingFraction?: number | string;
+      resetTime?: string;      // Dấu thời gian ISO 8601
+      isExhausted?: boolean;
+    };
+  }>;
+};
+```
+
+---
+
+## Theo dõi mức sử dụng
+
+### Lấy dữ liệu sử dụng
+
+```typescript
+export async function fetchAntigravityUsage(
+  token: string,
+  timeoutMs: number
+): Promise<ProviderUsageSnapshot> {
+  // 1. Lấy thông tin tín dụng và gói dịch vụ
+  const loadCodeAssistRes = await fetch(
+    `${BASE_URL}/v1internal:loadCodeAssist`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        metadata: {
+          ideType: "ANTIGRAVITY",
+          platform: "PLATFORM_UNSPECIFIED",
+          pluginType: "GEMINI",
+        },
+      }),
+    }
+  );
+
+  // Trích xuất thông tin tín dụng
+  const { availablePromptCredits, planInfo, currentTier } = data;
+  
+  // 2. Lấy hạn mức mô hình
+  const modelsRes = await fetch(
+    `${BASE_URL}/v1internal:fetchAvailableModels`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ project: projectId }),
+    }
+  );
+
+  // Xây dựng cửa sổ sử dụng
+  return {
+    provider: "google-antigravity",
+    displayName: "Google Antigravity",
+    windows: [
+      { label: "Credits", usedPercent: calculateUsedPercent(available, monthly) },
+      // Hạn mức từng mô hình...
+    ],
+    plan: currentTier?.name || planType,
+  };
+}
+```
+
+### Cấu trúc phản hồi sử dụng
+
+```typescript
+type ProviderUsageSnapshot = {
+  provider: "google-antigravity";
+  displayName: string;
+  windows: UsageWindow[];
+  plan?: string;
+  error?: string;
+};
+
+type UsageWindow = {
+  label: string;           // "Credits" hoặc ID mô hình
+  usedPercent: number;     // 0-100
+  resetAt?: number;        // Dấu thời gian khi hạn mức được đặt lại
+};
+```
+
+---
+
+## Cấu trúc plugin nhà cung cấp
+
+### Định nghĩa plugin
+
+```typescript
+const antigravityPlugin = {
+  id: "google-antigravity-auth",
+  name: "Google Antigravity Auth",
+  description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
+  configSchema: emptyPluginConfigSchema(),
+  
+  register(api: PicoClawPluginApi) {
+    api.registerProvider({
+      id: "google-antigravity",
+      label: "Google Antigravity",
+      docsPath: "/providers/models",
+      aliases: ["antigravity"],
+      
+      auth: [
+        {
+          id: "oauth",
+          label: "Google OAuth",
+          hint: "PKCE + localhost callback",
+          kind: "oauth",
+          run: async (ctx: ProviderAuthContext) => {
+            // Triển khai OAuth tại đây
+          },
+        },
+      ],
+    });
+  },
+};
+```
+
+### ProviderAuthContext
+
+```typescript
+type ProviderAuthContext = {
+  config: PicoClawConfig;
+  agentDir?: string;
+  workspaceDir?: string;
+  prompter: WizardPrompter;      // Lời nhắc/thông báo UI
+  runtime: RuntimeEnv;           // Ghi log, v.v.
+  isRemote: boolean;             // Có đang chạy từ xa không
+  openUrl: (url: string) => Promise<void>;  // Mở trình duyệt
+  oauth: {
+    createVpsAwareHandlers: Function;
+  };
+};
+```
+
+### ProviderAuthResult
+
+```typescript
+type ProviderAuthResult = {
+  profiles: Array<{
+    profileId: string;
+    credential: AuthProfileCredential;
+  }>;
+  configPatch?: Partial<PicoClawConfig>;
+  defaultModel?: string;
+  notes?: string[];
+};
+```
+
+---
+
+## Yêu cầu tích hợp
+
+### 1. Môi trường/Phụ thuộc cần thiết
+
+- Go ≥ 1.25
+- Mã nguồn PicoClaw (`pkg/providers/` và `pkg/auth/`)
+- Các gói thư viện chuẩn `crypto` và `net/http`
+
+### 2. Các header bắt buộc cho lệnh gọi API
+
+```typescript
+const REQUIRED_HEADERS = {
+  "Authorization": `Bearer ${accessToken}`,
+  "Content-Type": "application/json",
+  "User-Agent": "antigravity",  // hoặc "google-api-nodejs-client/9.15.1"
+  "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+};
+
+// Đối với các lệnh gọi loadCodeAssist, cũng bao gồm:
+const CLIENT_METADATA = {
+  ideType: "ANTIGRAVITY",  // hoặc "IDE_UNSPECIFIED"
+  platform: "PLATFORM_UNSPECIFIED",
+  pluginType: "GEMINI",
+};
+```
+
+### 3. Làm sạch schema mô hình
+
+Antigravity sử dụng các mô hình tương thích Gemini, vì vậy schema công cụ phải được làm sạch:
+
+```typescript
+const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
+  "patternProperties",
+  "additionalProperties",
+  "$schema",
+  "$id",
+  "$ref",
+  "$defs",
+  "definitions",
+  "examples",
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+  "multipleOf",
+  "pattern",
+  "format",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minProperties",
+  "maxProperties",
+]);
+
+// Làm sạch schema trước khi gửi
+function cleanToolSchemaForGemini(schema: Record<string, unknown>): unknown {
+  // Xóa các từ khóa không được hỗ trợ
+  // Đảm bảo cấp cao nhất có type: "object"
+  // Làm phẳng các union anyOf/oneOf
+}
+```
+
+### 4. Xử lý khối suy nghĩ (Mô hình Claude)
+
+Đối với các mô hình Claude qua Antigravity, khối suy nghĩ cần xử lý đặc biệt:
+
+```typescript
+const ANTIGRAVITY_SIGNATURE_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+export function sanitizeAntigravityThinkingBlocks(
+  messages: AgentMessage[]
+): AgentMessage[] {
+  // Xác thực chữ ký suy nghĩ
+  // Chuẩn hóa các trường chữ ký
+  // Loại bỏ các khối suy nghĩ chưa ký
+}
+```
+
+---
+
+## Các endpoint API
+
+### Endpoint xác thực
+
+| Endpoint | Phương thức | Mục đích |
+|----------|------------|----------|
+| `https://accounts.google.com/o/oauth2/v2/auth` | GET | Ủy quyền OAuth |
+| `https://oauth2.googleapis.com/token` | POST | Trao đổi token |
+| `https://www.googleapis.com/oauth2/v1/userinfo` | GET | Thông tin người dùng (email) |
+
+### Endpoint Cloud Code Assist
+
+| Endpoint | Phương thức | Mục đích |
+|----------|------------|----------|
+| `https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` | POST | Tải thông tin dự án, tín dụng, gói dịch vụ |
+| `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` | POST | Liệt kê các mô hình khả dụng kèm hạn mức |
+| `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse` | POST | Endpoint streaming chat |
+
+**Định dạng yêu cầu API (Chat):**
+Endpoint `v1internal:streamGenerateContent` yêu cầu một envelope bao bọc yêu cầu Gemini tiêu chuẩn:
+
+```json
+{
+  "project": "your-project-id",
+  "model": "model-id",
+  "request": {
+    "contents": [...],
+    "systemInstruction": {...},
+    "generationConfig": {...},
+    "tools": [...]
+  },
+  "requestType": "agent",
+  "userAgent": "antigravity",
+  "requestId": "agent-timestamp-random"
+}
+```
+
+**Định dạng phản hồi API (SSE):**
+Mỗi thông điệp SSE (`data: {...}`) được bao bọc trong trường `response`:
+
+```json
+{
+  "response": {
+    "candidates": [...],
+    "usageMetadata": {...},
+    "modelVersion": "...",
+    "responseId": "..."
+  },
+  "traceId": "...",
+  "metadata": {}
+}
+```
+
+---
+
+## Cấu hình
+
+### Cấu hình config.json
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gemini-flash",
+      "model": "antigravity/gemini-3-flash",
+      "auth_method": "oauth"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "gemini-flash"
+    }
+  }
+}
+```
+
+### Lưu trữ hồ sơ xác thực
+
+Hồ sơ xác thực được lưu trữ trong `~/.picoclaw/auth.json`:
+
+```json
+{
+  "credentials": {
+    "google-antigravity": {
+      "access_token": "ya29...",
+      "refresh_token": "1//...",
+      "expires_at": "2026-01-01T00:00:00Z",
+      "provider": "google-antigravity",
+      "auth_method": "oauth",
+      "email": "user@example.com",
+      "project_id": "my-project-id"
+    }
+  }
+}
+```
+
+---
+
+## Tạo nhà cung cấp mới trong PicoClaw
+
+Các nhà cung cấp PicoClaw được triển khai dưới dạng gói Go trong `pkg/providers/`. Để thêm nhà cung cấp mới:
+
+### Triển khai từng bước
+
+#### 1. Tạo file nhà cung cấp
+
+Tạo file Go mới trong `pkg/providers/`:
+
+```
+pkg/providers/
+└── your_provider.go
+```
+
+#### 2. Triển khai interface Provider
+
+Nhà cung cấp của bạn phải triển khai interface `Provider` được định nghĩa trong `pkg/providers/types.go`:
+
+```go
+package providers
+
+type YourProvider struct {
+    apiKey  string
+    apiBase string
+}
+
+func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
+    if apiBase == "" {
+        apiBase = "https://api.your-provider.com/v1"
+    }
+    return &YourProvider{apiKey: apiKey, apiBase: apiBase}
+}
+
+func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
+    // Triển khai hoàn thành chat với streaming
+}
+```
+
+#### 3. Đăng ký trong factory
+
+Thêm nhà cung cấp của bạn vào switch giao thức trong `pkg/providers/factory.go`:
+
+```go
+case "your-provider":
+    return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
+```
+
+#### 4. Thêm cấu hình mặc định (Tùy chọn)
+
+Thêm mục mặc định trong `pkg/config/defaults.go`:
+
+```go
+{
+    ModelName: "your-model",
+    Model:     "your-provider/model-name",
+    APIKey:    "",
+},
+```
+
+#### 5. Thêm hỗ trợ xác thực (Tùy chọn)
+
+Nếu nhà cung cấp của bạn yêu cầu OAuth hoặc xác thực đặc biệt, thêm case vào `cmd/picoclaw/internal/auth/helpers.go`:
+
+```go
+case "your-provider":
+    authLoginYourProvider()
+```
+
+#### 6. Cấu hình qua `config.json`
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "your-model",
+      "model": "your-provider/model-name",
+      "api_key": "your-api-key",
+      "api_base": "https://api.your-provider.com/v1"
+    }
+  ]
+}
+```
+
+---
+
+## Kiểm thử triển khai của bạn
+
+### Lệnh CLI
+
+```bash
+# Xác thực với nhà cung cấp
+picoclaw auth login --provider your-provider
+
+# Liệt kê mô hình (cho Antigravity)
+picoclaw auth models
+
+# Khởi động gateway
+picoclaw gateway
+
+# Chạy agent với mô hình cụ thể
+picoclaw agent -m "Hello" --model your-model
+```
+
+### Biến môi trường cho kiểm thử
+
+```bash
+# Ghi đè mô hình mặc định
+export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
+
+# Ghi đè cài đặt nhà cung cấp
+export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
+```
+
+---
+
+## Tài liệu tham khảo
+
+- **File nguồn:**
+  - `pkg/providers/antigravity_provider.go` - Triển khai nhà cung cấp Antigravity
+  - `pkg/auth/oauth.go` - Triển khai luồng OAuth
+  - `pkg/auth/store.go` - Lưu trữ thông tin xác thực (`~/.picoclaw/auth.json`)
+  - `pkg/providers/factory.go` - Factory nhà cung cấp và định tuyến giao thức
+  - `pkg/providers/types.go` - Định nghĩa interface nhà cung cấp
+  - `cmd/picoclaw/internal/auth/helpers.go` - Lệnh CLI xác thực
+
+- **Tài liệu:**
+  - `docs/ANTIGRAVITY_USAGE.md` - Hướng dẫn sử dụng Antigravity
+  - `docs/migration/model-list-migration.md` - Hướng dẫn di chuyển
+
+---
+
+## Lưu ý
+
+1. **Dự án Google Cloud:** Antigravity yêu cầu Gemini for Google Cloud được bật trên dự án Google Cloud của bạn
+2. **Hạn mức:** Sử dụng hạn mức dự án Google Cloud (không tính phí riêng)
+3. **Truy cập mô hình:** Các mô hình khả dụng phụ thuộc vào cấu hình dự án Google Cloud của bạn
+4. **Khối suy nghĩ:** Mô hình Claude qua Antigravity yêu cầu xử lý đặc biệt khối suy nghĩ có chữ ký
+5. **Làm sạch schema:** Schema công cụ phải được làm sạch để loại bỏ các từ khóa JSON Schema không được hỗ trợ
+
+---
+
+## Xử lý lỗi thường gặp
+
+### 1. Giới hạn tốc độ (HTTP 429)
+
+Antigravity trả về lỗi 429 khi hạn mức dự án/mô hình đã cạn kiệt. Phản hồi lỗi thường chứa `quotaResetDelay` trong trường `details`.
+
+**Ví dụ lỗi 429:**
+```json
+{
+  "error": {
+    "code": 429,
+    "message": "You have exhausted your capacity on this model. Your quota will reset after 4h30m28s.",
+    "status": "RESOURCE_EXHAUSTED",
+    "details": [
+      {
+        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+        "metadata": {
+          "quotaResetDelay": "4h30m28.060903746s"
+        }
+      }
+    ]
+  }
+}
+```
+
+### 2. Phản hồi trống (Mô hình bị hạn chế)
+
+Một số mô hình có thể xuất hiện trong danh sách mô hình khả dụng nhưng trả về phản hồi trống (200 OK nhưng luồng SSE trống). Điều này thường xảy ra với các mô hình xem trước hoặc bị hạn chế mà dự án hiện tại không có quyền sử dụng.
+
+**Cách xử lý:** Coi phản hồi trống là lỗi, thông báo cho người dùng rằng mô hình có thể bị hạn chế hoặc không hợp lệ cho dự án của họ.
+
+---
+
+## Khắc phục sự cố
+
+### "Token expired" (Token đã hết hạn)
+- Làm mới token OAuth: `picoclaw auth login --provider antigravity`
+
+### "Gemini for Google Cloud is not enabled" (Gemini for Google Cloud chưa được bật)
+- Bật API trong Google Cloud Console của bạn
+
+### "Project not found" (Không tìm thấy dự án)
+- Đảm bảo dự án Google Cloud của bạn đã bật các API cần thiết
+- Kiểm tra xem ID dự án có được lấy chính xác trong quá trình xác thực không
+
+### Mô hình không xuất hiện trong danh sách
+- Xác minh xác thực OAuth đã hoàn tất thành công
+- Kiểm tra lưu trữ hồ sơ xác thực: `~/.picoclaw/auth.json`
+- Chạy lại `picoclaw auth login --provider antigravity`
diff --git a/docs/vi/ANTIGRAVITY_USAGE.md b/docs/vi/ANTIGRAVITY_USAGE.md
new file mode 100644
index 000000000..4a696f770
--- /dev/null
+++ b/docs/vi/ANTIGRAVITY_USAGE.md
@@ -0,0 +1,72 @@
+> Quay lại [README](../../README.vi.md)
+
+# Sử dụng nhà cung cấp Antigravity trong PicoClaw
+
+Hướng dẫn này giải thích cách thiết lập và sử dụng nhà cung cấp **Antigravity** (Google Cloud Code Assist) trong PicoClaw.
+
+## Điều kiện tiên quyết
+
+1.  Một tài khoản Google.
+2.  Đã kích hoạt Google Cloud Code Assist (thường có sẵn thông qua quy trình giới thiệu "Gemini for Google Cloud").
+
+## 1. Xác thực
+
+Để xác thực với Antigravity, chạy lệnh sau:
+
+```bash
+picoclaw auth login --provider antigravity
+```
+
+### Xác thực thủ công (Headless/VPS)
+Nếu bạn đang chạy trên máy chủ (Coolify/Docker) và không thể truy cập `localhost`, hãy làm theo các bước sau:
+1.  Chạy lệnh ở trên.
+2.  Sao chép URL được cung cấp và mở nó trong trình duyệt cục bộ của bạn.
+3.  Hoàn tất đăng nhập.
+4.  Trình duyệt của bạn sẽ chuyển hướng đến URL `localhost:51121` (trang sẽ không tải được).
+5.  **Sao chép URL cuối cùng đó** từ thanh địa chỉ trình duyệt.
+6.  **Dán nó vào terminal** nơi PicoClaw đang chờ.
+
+PicoClaw sẽ tự động trích xuất mã ủy quyền và hoàn tất quy trình.
+
+## 2. Quản lý mô hình
+
+### Liệt kê các mô hình khả dụng
+Để xem dự án của bạn có quyền truy cập vào những mô hình nào và kiểm tra hạn mức của chúng:
+
+```bash
+picoclaw auth models
+```
+
+### Chuyển đổi mô hình
+Bạn có thể thay đổi mô hình mặc định trong `~/.picoclaw/config.json` hoặc ghi đè qua CLI:
+
+```bash
+# Ghi đè cho một lệnh duy nhất
+picoclaw agent -m "Hello" --model claude-opus-4-6-thinking
+```
+
+## 3. Sử dụng thực tế (Coolify/Docker)
+
+Nếu bạn đang triển khai qua Coolify hoặc Docker, hãy làm theo các bước sau để kiểm tra:
+
+1.  **Biến môi trường**:
+    *   `PICOCLAW_AGENTS_DEFAULTS_MODEL=gemini-flash`
+2.  **Lưu trữ xác thực**:
+    Nếu bạn đã đăng nhập cục bộ, bạn có thể sao chép thông tin xác thực lên máy chủ:
+    ```bash
+    scp ~/.picoclaw/auth.json user@your-server:~/.picoclaw/
+    ```
+    *Hoặc*, chạy lệnh `auth login` một lần trên máy chủ nếu bạn có quyền truy cập terminal.
+
+## 4. Khắc phục sự cố
+
+*   **Phản hồi trống**: Nếu một mô hình trả về phản hồi trống, nó có thể bị hạn chế cho dự án của bạn. Hãy thử `gemini-3-flash` hoặc `claude-opus-4-6-thinking`.
+*   **429 Giới hạn tốc độ**: Antigravity có hạn mức nghiêm ngặt. PicoClaw sẽ hiển thị "thời gian đặt lại" trong thông báo lỗi nếu bạn đạt đến giới hạn.
+*   **404 Không tìm thấy**: Đảm bảo bạn đang sử dụng ID mô hình từ danh sách `picoclaw auth models`. Sử dụng ID ngắn (ví dụ: `gemini-3-flash`) thay vì đường dẫn đầy đủ.
+
+## 5. Tóm tắt các mô hình hoạt động tốt
+
+Dựa trên kiểm tra, các mô hình sau đáng tin cậy nhất:
+*   `gemini-3-flash` (Nhanh, khả dụng cao)
+*   `gemini-2.5-flash-lite` (Nhẹ)
+*   `claude-opus-4-6-thinking` (Mạnh mẽ, bao gồm khả năng suy luận)
diff --git a/docs/vi/chat-apps.md b/docs/vi/chat-apps.md
new file mode 100644
index 000000000..5e2a81ccf
--- /dev/null
+++ b/docs/vi/chat-apps.md
@@ -0,0 +1,675 @@
+# 💬 Cấu Hình Ứng Dụng Chat
+
+> Quay lại [README](../../README.vi.md)
+
+## 💬 Ứng Dụng Chat
+
+Trò chuyện với picoclaw của bạn qua Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, WeCom, Feishu, Slack, IRC, OneBot hoặc MaixCam
+
+> **Lưu ý**: Tất cả các kênh dựa trên webhook (LINE, WeCom, v.v.) được phục vụ trên một máy chủ HTTP Gateway chung (`gateway.host`:`gateway.port`, mặc định `127.0.0.1:18790`). Không có port riêng cho từng kênh. Lưu ý: Feishu sử dụng chế độ WebSocket/SDK và không sử dụng máy chủ HTTP webhook chung.
+
+| Kênh                 | Độ khó             | Mô tả                                                 | Tài liệu                                                                                                         |
+| -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **Telegram**         | ⭐ Dễ              | Khuyến nghị, chuyển giọng nói thành văn bản, long polling (không cần IP công khai) | [Tài liệu](../channels/telegram/README.vi.md)                                              |
+| **Discord**          | ⭐ Dễ              | Socket Mode, hỗ trợ nhóm/DM, hệ sinh thái bot phong phú | [Tài liệu](../channels/discord/README.vi.md)                                                                  |
+| **WhatsApp**         | ⭐ Dễ              | Bản địa (quét QR) hoặc Bridge URL                     | [Tài liệu](#whatsapp)                                                                                            |
+| **Weixin**           | ⭐ Dễ              | Quét QR gốc (API Tencent iLink)                       | [Tài liệu](#weixin)                                                                                              |
+| **Slack**            | ⭐ Dễ              | **Socket Mode** (không cần IP công khai), doanh nghiệp | [Tài liệu](../channels/slack/README.vi.md)                                                                      |
+| **Matrix**           | ⭐⭐ Trung bình    | Giao thức liên kết, hỗ trợ tự lưu trữ                | [Tài liệu](../channels/matrix/README.vi.md)                                                                     |
+| **QQ**               | ⭐⭐ Trung bình    | API bot chính thức, cộng đồng Trung Quốc              | [Tài liệu](../channels/qq/README.vi.md)                                                                         |
+| **DingTalk**         | ⭐⭐ Trung bình    | Chế độ Stream (không cần IP công khai), doanh nghiệp  | [Tài liệu](../channels/dingtalk/README.vi.md)                                                                   |
+| **LINE**             | ⭐⭐⭐ Nâng cao    | Yêu cầu HTTPS Webhook                                 | [Tài liệu](../channels/line/README.vi.md)                                                                       |
+| **WeCom (企业微信)** | ⭐⭐⭐ Nâng cao    | Bot nhóm (Webhook), ứng dụng tùy chỉnh (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.vi.md) / [App](../channels/wecom/wecom_app/README.vi.md) / [AI Bot](../channels/wecom/wecom_aibot/README.vi.md) |
+| **Feishu (飞书)**    | ⭐⭐⭐ Nâng cao    | Cộng tác doanh nghiệp, nhiều tính năng                | [Tài liệu](../channels/feishu/README.vi.md)                                                                     |
+| **IRC**              | ⭐⭐ Trung bình    | Máy chủ + cấu hình TLS                                | [Tài liệu](#irc) |
+| **OneBot**           | ⭐⭐ Trung bình    | Tương thích NapCat/Go-CQHTTP, hệ sinh thái cộng đồng  | [Tài liệu](../channels/onebot/README.vi.md)                                                                     |
+| **MaixCam**          | ⭐ Dễ              | Kênh tích hợp phần cứng cho camera AI Sipeed          | [Tài liệu](../channels/maixcam/README.vi.md)                                                                    |
+| **Pico**             | ⭐ Dễ              | Kênh giao thức bản địa PicoClaw                       |                                                                                                                  |
+
+<a id="telegram"></a>
+<details>
+<summary><b>Telegram</b> (Khuyến nghị)</summary>
+
+**1. Tạo bot**
+
+* Mở Telegram, tìm `@BotFather`
+* Gửi `/newbot`, làm theo hướng dẫn
+* Sao chép token
+
+**2. Cấu hình**
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+> Lấy user ID của bạn từ `@userinfobot` trên Telegram.
+
+**3. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+**4. Menu lệnh Telegram (tự động đăng ký khi khởi động)**
+
+PicoClaw hiện lưu trữ định nghĩa lệnh trong một registry chung. Khi khởi động, Telegram sẽ tự động đăng ký các lệnh bot được hỗ trợ (ví dụ `/start`, `/help`, `/show`, `/list`) để menu lệnh và hành vi runtime luôn đồng bộ.
+Đăng ký menu lệnh Telegram vẫn là UX khám phá cục bộ của kênh; thực thi lệnh chung được xử lý tập trung trong vòng lặp agent qua commands executor.
+
+Nếu đăng ký lệnh thất bại (lỗi tạm thời mạng/API), kênh vẫn khởi động và PicoClaw thử lại đăng ký trong nền.
+
+</details>
+
+<a id="discord"></a>
+<details>
+<summary><b>Discord</b></summary>
+
+**1. Tạo bot**
+
+* Truy cập <https://discord.com/developers/applications>
+* Tạo ứng dụng → Bot → Add Bot
+* Sao chép bot token
+
+**2. Bật intents**
+
+* Trong cài đặt Bot, bật **MESSAGE CONTENT INTENT**
+* (Tùy chọn) Bật **SERVER MEMBERS INTENT** nếu bạn muốn sử dụng danh sách cho phép dựa trên dữ liệu thành viên
+
+**3. Lấy User ID**
+* Cài đặt Discord → Nâng cao → bật **Developer Mode**
+* Nhấp chuột phải vào avatar → **Copy User ID**
+
+**4. Cấu hình**
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**5. Mời bot**
+
+* OAuth2 → URL Generator
+* Scopes: `bot`
+* Bot Permissions: `Send Messages`, `Read Message History`
+* Mở URL mời được tạo và thêm bot vào server của bạn
+
+**Tùy chọn: Chế độ kích hoạt nhóm**
+
+Mặc định bot phản hồi tất cả tin nhắn trong kênh server. Để giới hạn phản hồi chỉ khi @mention, thêm:
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "mention_only": true }
+    }
+  }
+}
+```
+
+Bạn cũng có thể kích hoạt bằng tiền tố từ khóa (ví dụ: `!bot`):
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "prefixes": ["!bot"] }
+    }
+  }
+}
+```
+
+**6. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="whatsapp"></a>
+<details>
+<summary><b>WhatsApp</b> (native qua whatsmeow)</summary>
+
+PicoClaw có thể kết nối WhatsApp theo hai cách:
+
+- **Native (khuyến nghị):** In-process sử dụng [whatsmeow](https://github.com/tulir/whatsmeow). Không cần bridge riêng. Đặt `"use_native": true` và để trống `bridge_url`. Lần chạy đầu tiên, quét mã QR bằng WhatsApp (Thiết bị liên kết). Phiên được lưu trong workspace (ví dụ: `workspace/whatsapp/`). Kênh native là **tùy chọn** để giữ binary mặc định nhỏ; build với `-tags whatsapp_native` (ví dụ: `make build-whatsapp-native` hoặc `go build -tags whatsapp_native ./cmd/...`).
+- **Bridge:** Kết nối đến bridge WebSocket bên ngoài. Đặt `bridge_url` (ví dụ: `ws://localhost:3001`) và giữ `use_native` là false.
+
+**Cấu hình (native)**
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "use_native": true,
+      "session_store_path": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+Nếu `session_store_path` trống, phiên được lưu tại `<workspace>/whatsapp/`. Chạy `picoclaw gateway`; lần chạy đầu tiên, quét mã QR hiển thị trong terminal bằng WhatsApp → Thiết bị liên kết.
+
+</details>
+
+<a id="weixin"></a>
+<details>
+<summary><b>Weixin</b> (WeChat Cá nhân)</summary>
+
+PicoClaw hỗ trợ kết nối với tài khoản WeChat cá nhân của bạn thông qua API chính thức Tencent iLink.
+
+**1. Đăng nhập**
+
+Chạy luồng đăng nhập QR tương tác:
+```bash
+picoclaw auth weixin
+```
+Quét mã QR được in ra bằng ứng dụng WeChat trên điện thoại. Sau khi đăng nhập thành công, token sẽ được lưu vào cấu hình.
+
+**2. Cấu hình**
+
+(Tùy chọn) Thêm ID người dùng WeChat vào `allow_from` để giới hạn ai có thể nhắn tin với bot:
+```json
+{
+  "channels": {
+    "weixin": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**3. Chạy**
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="qq"></a>
+<details>
+<summary><b>QQ</b></summary>
+
+**Thiết lập nhanh (khuyến nghị)**
+
+QQ Open Platform cung cấp trang thiết lập một chạm cho bot tương thích OpenClaw:
+
+1. Mở [QQ Bot Quick Start](https://q.qq.com/qqbot/openclaw/index.html) và quét mã QR để đăng nhập
+2. Bot được tạo tự động — sao chép **App ID** và **App Secret**
+3. Cấu hình PicoClaw:
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+4. Chạy `picoclaw gateway` và mở QQ để trò chuyện với bot của bạn
+
+> App Secret chỉ hiển thị một lần. Lưu ngay lập tức — xem lại sẽ buộc phải đặt lại.
+>
+> Bot được tạo qua trang thiết lập nhanh ban đầu chỉ dành cho người tạo và không hỗ trợ chat nhóm. Để bật quyền truy cập nhóm, cấu hình chế độ sandbox trên [QQ Open Platform](https://q.qq.com/).
+
+**Thiết lập thủ công**
+
+Nếu bạn muốn tạo bot thủ công:
+
+* Đăng nhập tại [QQ Open Platform](https://q.qq.com/) để đăng ký làm nhà phát triển
+* Tạo bot QQ — tùy chỉnh avatar và tên
+* Sao chép **App ID** và **App Secret** từ cài đặt bot
+* Cấu hình như trên và chạy `picoclaw gateway`
+
+</details>
+
+<a id="dingtalk"></a>
+<details>
+<summary><b>DingTalk</b></summary>
+
+**1. Tạo bot**
+
+* Truy cập [Open Platform](https://open.dingtalk.com/)
+* Tạo ứng dụng nội bộ
+* Sao chép Client ID và Client Secret
+
+**2. Cấu hình**
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Đặt `allow_from` trống để cho phép tất cả người dùng, hoặc chỉ định DingTalk user ID để giới hạn truy cập.
+
+**3. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="maixcam"></a>
+<details>
+<summary><b>MaixCam</b></summary>
+
+Kênh tích hợp được thiết kế đặc biệt cho phần cứng camera AI Sipeed.
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true
+    }
+  }
+}
+```
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+
+<a id="matrix"></a>
+<details>
+<summary><b>Matrix</b></summary>
+
+**1. Chuẩn bị tài khoản bot**
+
+* Sử dụng homeserver ưa thích (ví dụ: `https://matrix.org` hoặc tự host)
+* Tạo user bot và lấy access token
+
+**2. Cấu hình**
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+Để xem đầy đủ các tùy chọn (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), xem [Hướng Dẫn Cấu Hình Kênh Matrix](../channels/matrix/README.md).
+
+</details>
+
+<a id="line"></a>
+<details>
+<summary><b>LINE</b></summary>
+
+**1. Tạo Tài Khoản LINE Official**
+
+- Truy cập [LINE Developers Console](https://developers.line.biz/)
+- Tạo provider → Tạo kênh Messaging API
+- Sao chép **Channel Secret** và **Channel Access Token**
+
+**2. Cấu hình**
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Webhook LINE được phục vụ trên máy chủ Gateway chung (`gateway.host`:`gateway.port`, mặc định `127.0.0.1:18790`).
+
+**3. Thiết lập Webhook URL**
+
+LINE yêu cầu HTTPS cho webhook. Sử dụng reverse proxy hoặc tunnel:
+
+```bash
+# Ví dụ với ngrok (port mặc định gateway là 18790)
+ngrok http 18790
+```
+
+Sau đó đặt Webhook URL trong LINE Developers Console thành `https://your-domain/webhook/line` và bật **Use webhook**.
+
+**4. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+> Trong chat nhóm, bot chỉ phản hồi khi được @mention. Phản hồi trích dẫn tin nhắn gốc.
+
+</details>
+
+<a id="wecom"></a>
+<details>
+<summary><b>WeCom (企业微信)</b></summary>
+
+PicoClaw hỗ trợ ba loại tích hợp WeCom:
+
+**Tùy chọn 1: WeCom Bot (Bot)** - Thiết lập dễ hơn, hỗ trợ chat nhóm
+**Tùy chọn 2: WeCom App (App Tùy chỉnh)** - Nhiều tính năng hơn, nhắn tin chủ động, chỉ chat riêng
+**Tùy chọn 3: WeCom AI Bot (AI Bot)** - AI Bot chính thức, phản hồi streaming, hỗ trợ chat nhóm & riêng
+
+Xem [Hướng Dẫn Cấu Hình WeCom AI Bot](../channels/wecom/wecom_aibot/README.vi.md) để biết hướng dẫn thiết lập chi tiết.
+
+**Thiết Lập Nhanh - WeCom Bot:**
+
+**1. Tạo bot**
+
+* Truy cập Console Quản Trị WeCom → Chat Nhóm → Thêm Bot Nhóm
+* Sao chép URL webhook (định dạng: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
+
+**2. Cấu hình**
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+      "webhook_path": "/webhook/wecom",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Webhook WeCom được phục vụ trên máy chủ Gateway chung (`gateway.host`:`gateway.port`, mặc định `127.0.0.1:18790`).
+
+**Thiết Lập Nhanh - WeCom App:**
+
+**1. Tạo ứng dụng**
+
+* Truy cập Console Quản Trị WeCom → Quản Lý App → Tạo App
+* Sao chép **AgentId** và **Secret**
+* Truy cập trang "Công Ty Của Tôi", sao chép **CorpID**
+
+**2. Cấu hình nhận tin nhắn**
+
+* Trong chi tiết App, nhấp "Nhận Tin Nhắn" → "Cấu Hình API"
+* Đặt URL thành `http://your-server:18790/webhook/wecom-app`
+* Tạo **Token** và **EncodingAESKey**
+
+**3. Cấu hình**
+
+```json
+{
+  "channels": {
+    "wecom_app": {
+      "enabled": true,
+      "corp_id": "wwxxxxxxxxxxxxxxxx",
+      "corp_secret": "YOUR_CORP_SECRET",
+      "agent_id": 1000002,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**4. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+> **Lưu ý**: Callback webhook WeCom được phục vụ trên port Gateway (mặc định 18790). Sử dụng reverse proxy cho HTTPS.
+
+**Thiết Lập Nhanh - WeCom AI Bot:**
+
+**1. Tạo AI Bot**
+
+* Truy cập Console Quản Trị WeCom → Quản Lý App → AI Bot
+* Trong cài đặt AI Bot, cấu hình callback URL: `http://your-server:18790/webhook/wecom-aibot`
+* Sao chép **Token** và nhấp "Tạo Ngẫu Nhiên" cho **EncodingAESKey**
+
+**2. Cấu hình**
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-aibot",
+      "allow_from": [],
+      "welcome_message": "Hello! How can I help you?",
+      "processing_message": "⏳ Processing, please wait. The results will be sent shortly."
+    }
+  }
+}
+```
+
+**3. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+> **Lưu ý**: WeCom AI Bot sử dụng giao thức streaming pull — không lo timeout phản hồi. Tác vụ dài (>30 giây) tự động chuyển sang gửi qua `response_url` push.
+
+</details>
+
+<a id="feishu"></a>
+<details>
+<summary><b>Feishu (Lark)</b></summary>
+
+PicoClaw kết nối với Feishu qua chế độ WebSocket/SDK — không cần URL webhook công khai hay máy chủ callback.
+
+**1. Tạo ứng dụng**
+
+* Truy cập [Feishu Open Platform](https://open.feishu.cn/) và tạo ứng dụng
+* Trong cài đặt ứng dụng, bật khả năng **Bot**
+* Tạo phiên bản và xuất bản ứng dụng (ứng dụng phải được xuất bản mới có hiệu lực)
+* Sao chép **App ID** (bắt đầu bằng `cli_`) và **App Secret**
+
+**2. Cấu hình**
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "app_id": "cli_xxx",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+Tùy chọn: `encrypt_key` và `verification_token` để mã hóa sự kiện (khuyến nghị cho môi trường production).
+
+**3. Chạy và trò chuyện**
+
+```bash
+picoclaw gateway
+```
+
+Mở Feishu, tìm tên bot của bạn và bắt đầu trò chuyện. Bạn cũng có thể thêm bot vào nhóm — sử dụng `group_trigger.mention_only: true` để chỉ phản hồi khi được @mention.
+
+Để xem đầy đủ các tùy chọn, xem [Hướng Dẫn Cấu Hình Kênh Feishu](../channels/feishu/README.vi.md).
+
+</details>
+
+<a id="slack"></a>
+<details>
+<summary><b>Slack</b></summary>
+
+**1. Tạo ứng dụng Slack**
+
+* Truy cập [Slack API](https://api.slack.com/apps) và tạo ứng dụng mới
+* Trong **OAuth & Permissions**, thêm các scope bot: `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write`
+* Cài đặt ứng dụng vào workspace của bạn
+* Sao chép **Bot Token** (`xoxb-...`) và **App-Level Token** (`xapp-...`, bật Socket Mode để lấy token này)
+
+**2. Cấu hình**
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "bot_token": "xoxb-YOUR-BOT-TOKEN",
+      "app_token": "xapp-YOUR-APP-TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="irc"></a>
+<details>
+<summary><b>IRC</b></summary>
+
+**1. Cấu hình**
+
+```json
+{
+  "channels": {
+    "irc": {
+      "enabled": true,
+      "server": "irc.libera.chat:6697",
+      "tls": true,
+      "nick": "picoclaw-bot",
+      "channels": ["#your-channel"],
+      "password": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+Tùy chọn: `nickserv_password` để xác thực NickServ, `sasl_user`/`sasl_password` để xác thực SASL.
+
+**2. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+Bot sẽ kết nối đến máy chủ IRC và tham gia các kênh đã chỉ định.
+
+</details>
+
+<a id="onebot"></a>
+<details>
+<summary><b>OneBot (QQ qua giao thức OneBot)</b></summary>
+
+OneBot là giao thức mở cho bot QQ. PicoClaw kết nối với bất kỳ triển khai tương thích OneBot v11 nào (ví dụ: [Lagrange](https://github.com/LagrangeDev/Lagrange.Core), [NapCat](https://github.com/NapNeko/NapCatQQ)) qua WebSocket.
+
+**1. Thiết lập triển khai OneBot**
+
+Cài đặt và chạy framework bot QQ tương thích OneBot v11. Bật máy chủ WebSocket của nó.
+
+**2. Cấu hình**
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://127.0.0.1:8080",
+      "access_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| Trường | Mô tả |
+|--------|-------|
+| `ws_url` | URL WebSocket của triển khai OneBot |
+| `access_token` | Token truy cập để xác thực (nếu đã cấu hình trong OneBot) |
+| `reconnect_interval` | Khoảng thời gian kết nối lại tính bằng giây (mặc định: 5) |
+
+**3. Chạy**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<details>
+<summary><b>MaixCam</b></summary>
+
+Kênh tích hợp được thiết kế đặc biệt cho phần cứng camera AI Sipeed.
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true
+    }
+  }
+}
+```
+
+```bash
+picoclaw gateway
+```
+
+</details>
diff --git a/docs/vi/configuration.md b/docs/vi/configuration.md
new file mode 100644
index 000000000..fecadc6ff
--- /dev/null
+++ b/docs/vi/configuration.md
@@ -0,0 +1,364 @@
+# ⚙️ Hướng Dẫn Cấu Hình
+
+> Quay lại [README](../../README.vi.md)
+
+## ⚙️ Cấu Hình
+
+File cấu hình: `~/.picoclaw/config.json`
+
+### Biến Môi Trường
+
+Bạn có thể ghi đè các đường dẫn mặc định bằng biến môi trường. Điều này hữu ích cho cài đặt portable, triển khai container, hoặc chạy picoclaw như dịch vụ hệ thống. Các biến này độc lập và kiểm soát các đường dẫn khác nhau.
+
+| Biến              | Mô tả                                                                                                                             | Đường Dẫn Mặc Định       |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | Ghi đè đường dẫn đến file cấu hình. Chỉ định trực tiếp cho picoclaw file `config.json` nào cần tải, bỏ qua tất cả vị trí khác. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | Ghi đè thư mục gốc cho dữ liệu picoclaw. Thay đổi vị trí mặc định của `workspace` và các thư mục dữ liệu khác.          | `~/.picoclaw`             |
+
+**Ví dụ:**
+
+```bash
+# Chạy picoclaw với file cấu hình cụ thể
+# Đường dẫn workspace sẽ được đọc từ trong file cấu hình đó
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Chạy picoclaw với tất cả dữ liệu lưu tại /opt/picoclaw
+# Cấu hình sẽ được tải từ mặc định ~/.picoclaw/config.json
+# Workspace sẽ được tạo tại /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Sử dụng cả hai cho thiết lập tùy chỉnh hoàn toàn
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
+### Bố Cục Workspace
+
+PicoClaw lưu trữ dữ liệu trong workspace đã cấu hình (mặc định: `~/.picoclaw/workspace`):
+
+```
+~/.picoclaw/workspace/
+├── sessions/          # Phiên hội thoại và lịch sử
+├── memory/           # Bộ nhớ dài hạn (MEMORY.md)
+├── state/            # Trạng thái bền vững (kênh cuối, v.v.)
+├── cron/             # Cơ sở dữ liệu tác vụ lên lịch
+├── skills/           # Skill tùy chỉnh
+├── AGENT.md          # Hướng dẫn hành vi agent
+├── HEARTBEAT.md      # Prompt tác vụ định kỳ (kiểm tra mỗi 30 phút)
+├── IDENTITY.md       # Danh tính agent
+├── SOUL.md           # Linh hồn agent
+└── USER.md           # Tùy chọn người dùng
+```
+
+> **Lưu ý:** Các thay đổi đối với `AGENT.md`, `SOUL.md`, `USER.md` và `memory/MEMORY.md` được tự động phát hiện trong thời gian chạy thông qua theo dõi thời gian sửa đổi file (mtime). **Không cần khởi động lại gateway** sau khi chỉnh sửa các file này — agent sẽ tải nội dung mới vào yêu cầu tiếp theo.
+
+### Nguồn Skill
+
+Mặc định, skill được tải từ:
+
+1. `~/.picoclaw/workspace/skills` (workspace)
+2. `~/.picoclaw/skills` (global)
+3. `<đường-dẫn-nhúng-khi-build>/skills` (tích hợp)
+
+Cho thiết lập nâng cao/test, bạn có thể ghi đè thư mục gốc skill builtin với:
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
+### Chính Sách Thực Thi Lệnh Thống Nhất
+
+- Lệnh slash chung được thực thi qua một đường dẫn duy nhất trong `pkg/agent/loop.go` qua `commands.Executor`.
+- Adapter kênh không còn xử lý lệnh chung cục bộ; chúng chuyển tiếp văn bản đầu vào đến đường dẫn bus/agent. Telegram vẫn tự động đăng ký lệnh được hỗ trợ khi khởi động.
+- Lệnh slash không xác định (ví dụ `/foo`) được chuyển sang xử lý LLM bình thường.
+- Lệnh đã đăng ký nhưng không được hỗ trợ trên kênh hiện tại (ví dụ `/show` trên WhatsApp) trả về lỗi rõ ràng cho người dùng và dừng xử lý tiếp.
+
+### 🔒 Sandbox Bảo Mật
+
+PicoClaw chạy trong môi trường sandbox mặc định. Agent chỉ có thể truy cập file và thực thi lệnh trong workspace đã cấu hình.
+
+#### Cấu Hình Mặc Định
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "restrict_to_workspace": true
+    }
+  }
+}
+```
+
+| Tùy chọn                | Mặc định                | Mô tả                                    |
+| ----------------------- | ----------------------- | ----------------------------------------- |
+| `workspace`             | `~/.picoclaw/workspace` | Thư mục làm việc của agent               |
+| `restrict_to_workspace` | `true`                  | Giới hạn truy cập file/lệnh trong workspace |
+
+#### Công Cụ Được Bảo Vệ
+
+Khi `restrict_to_workspace: true`, các công cụ sau được sandbox:
+
+| Công cụ       | Chức năng        | Giới hạn                               |
+| ------------- | ---------------- | -------------------------------------- |
+| `read_file`   | Đọc file         | Chỉ file trong workspace              |
+| `write_file`  | Ghi file         | Chỉ file trong workspace              |
+| `list_dir`    | Liệt kê thư mục | Chỉ thư mục trong workspace           |
+| `edit_file`   | Sửa file         | Chỉ file trong workspace              |
+| `append_file` | Nối vào file     | Chỉ file trong workspace              |
+| `exec`        | Thực thi lệnh   | Đường dẫn lệnh phải trong workspace   |
+
+#### Bảo Vệ Exec Bổ Sung
+
+Ngay cả khi `restrict_to_workspace: false`, công cụ `exec` chặn các lệnh nguy hiểm sau:
+
+* `rm -rf`, `del /f`, `rmdir /s` — Xóa hàng loạt
+* `format`, `mkfs`, `diskpart` — Định dạng đĩa
+* `dd if=` — Tạo ảnh đĩa
+* Ghi vào `/dev/sd[a-z]` — Ghi trực tiếp đĩa
+* `shutdown`, `reboot`, `poweroff` — Tắt hệ thống
+* Fork bomb `:(){ :|:& };:`
+
+### Kiểm Soát Truy Cập File
+
+| Config Key | Type | Default | Description |
+|------------|------|---------|-------------|
+| `tools.allow_read_paths` | string[] | `[]` | Additional paths allowed for reading outside workspace |
+| `tools.allow_write_paths` | string[] | `[]` | Additional paths allowed for writing outside workspace |
+
+### Bảo Mật Exec
+
+| Config Key | Type | Default | Description |
+|------------|------|---------|-------------|
+| `tools.exec.allow_remote` | bool | `false` | Allow exec tool from remote channels (Telegram/Discord etc.) |
+| `tools.exec.enable_deny_patterns` | bool | `true` | Enable dangerous command interception |
+| `tools.exec.custom_deny_patterns` | string[] | `[]` | Custom regex patterns to block |
+| `tools.exec.custom_allow_patterns` | string[] | `[]` | Custom regex patterns to allow |
+
+> **Lưu ý Bảo Mật:** Bảo vệ symlink được bật mặc định — tất cả đường dẫn file được giải quyết qua `filepath.EvalSymlinks` trước khi so khớp whitelist, ngăn chặn tấn công thoát qua symlink.
+
+#### Hạn Chế Đã Biết: Tiến Trình Con Từ Công Cụ Build
+
+Guard bảo mật exec chỉ kiểm tra dòng lệnh mà PicoClaw khởi chạy trực tiếp. Nó không kiểm tra đệ quy các tiến trình con được tạo bởi công cụ phát triển được phép như `make`, `go run`, `cargo`, `npm run`, hoặc script build tùy chỉnh.
+
+Điều này có nghĩa là lệnh cấp cao nhất vẫn có thể biên dịch hoặc khởi chạy binary khác sau khi vượt qua kiểm tra guard ban đầu. Trong thực tế, hãy coi script build, Makefile, script package, và binary được tạo như mã thực thi cần cùng mức độ review như lệnh shell trực tiếp.
+
+Cho môi trường rủi ro cao hơn:
+
+* Review script build trước khi thực thi.
+* Ưu tiên phê duyệt/review thủ công cho quy trình biên dịch và chạy.
+* Chạy PicoClaw trong container hoặc VM nếu bạn cần cách ly mạnh hơn guard tích hợp.
+
+#### Ví Dụ Lỗi
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (path outside working dir)}
+```
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
+```
+
+#### Tắt Giới Hạn (Rủi Ro Bảo Mật)
+
+Nếu bạn cần agent truy cập đường dẫn ngoài workspace:
+
+**Phương pháp 1: File cấu hình**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "restrict_to_workspace": false
+    }
+  }
+}
+```
+
+**Phương pháp 2: Biến môi trường**
+
+```bash
+export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
+```
+
+> ⚠️ **Cảnh báo**: Tắt giới hạn này cho phép agent truy cập bất kỳ đường dẫn nào trên hệ thống. Chỉ sử dụng cẩn thận trong môi trường được kiểm soát.
+
+#### Tính Nhất Quán Ranh Giới Bảo Mật
+
+Cài đặt `restrict_to_workspace` áp dụng nhất quán trên tất cả đường dẫn thực thi:
+
+| Đường Dẫn Thực Thi | Ranh Giới Bảo Mật          |
+| -------------------- | ---------------------------- |
+| Main Agent           | `restrict_to_workspace` ✅   |
+| Subagent / Spawn     | Kế thừa cùng giới hạn ✅    |
+| Heartbeat tasks      | Kế thừa cùng giới hạn ✅    |
+
+Tất cả đường dẫn chia sẻ cùng giới hạn workspace — không có cách nào vượt qua ranh giới bảo mật qua subagent hoặc tác vụ lên lịch.
+
+### Heartbeat (Tác Vụ Định Kỳ)
+
+PicoClaw có thể thực hiện tác vụ định kỳ tự động. Tạo file `HEARTBEAT.md` trong workspace:
+
+```markdown
+# Tác Vụ Định Kỳ
+
+- Kiểm tra email cho tin nhắn quan trọng
+- Xem lịch cho sự kiện sắp tới
+- Kiểm tra dự báo thời tiết
+```
+
+Agent sẽ đọc file này mỗi 30 phút (có thể cấu hình) và thực thi các tác vụ sử dụng công cụ có sẵn.
+
+#### Tác Vụ Bất Đồng Bộ Với Spawn
+
+Cho tác vụ chạy lâu (tìm kiếm web, gọi API), sử dụng công cụ `spawn` để tạo **subagent**:
+
+```markdown
+# Tác Vụ Định Kỳ
+
+## Tác Vụ Nhanh (trả lời trực tiếp)
+
+- Báo giờ hiện tại
+
+## Tác Vụ Dài (dùng spawn cho bất đồng bộ)
+
+- Tìm kiếm tin tức AI trên web và tóm tắt
+- Kiểm tra email và báo cáo tin nhắn quan trọng
+```
+
+**Hành vi chính:**
+
+| Tính năng        | Mô tả                                                              |
+| ---------------- | ------------------------------------------------------------------ |
+| **spawn**        | Tạo subagent bất đồng bộ, không chặn heartbeat                    |
+| **Ngữ cảnh độc lập** | Subagent có ngữ cảnh riêng, không có lịch sử phiên             |
+| **message tool** | Subagent giao tiếp trực tiếp với người dùng qua message tool      |
+| **Không chặn**   | Sau khi spawn, heartbeat tiếp tục tác vụ tiếp theo                |
+
+#### Luồng Giao Tiếp Của Subagent
+
+```
+Heartbeat kích hoạt
+    ↓
+Agent đọc HEARTBEAT.md
+    ↓
+Tác vụ dài: spawn subagent
+    ↓                           ↓
+Tiếp tục tác vụ tiếp theo  Subagent hoạt động độc lập
+    ↓                           ↓
+Hoàn thành tất cả tác vụ   Subagent dùng công cụ "message"
+    ↓                           ↓
+Trả lời HEARTBEAT_OK        Người dùng nhận kết quả trực tiếp
+```
+
+**Cấu hình:**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| Tùy chọn   | Mặc định | Mô tả                                  |
+| ---------- | -------- | -------------------------------------- |
+| `enabled`  | `true`   | Bật/tắt heartbeat                      |
+| `interval` | `30`     | Khoảng thời gian kiểm tra tính bằng phút (tối thiểu: 5) |
+
+**Biến môi trường:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` để tắt
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` để thay đổi khoảng thời gian
+
+### Providers
+
+> [!NOTE]
+> Groq cung cấp chuyển đổi giọng nói thành văn bản miễn phí qua Whisper. Nếu được cấu hình, tin nhắn âm thanh từ bất kỳ kênh nào sẽ được tự động chuyển đổi ở cấp độ agent.
+
+| Provider     | Mục đích                                | Lấy API Key                                                  |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini`     | LLM (Gemini trực tiếp)                  | [aistudio.google.com](https://aistudio.google.com)           |
+| `zhipu`      | LLM (Zhipu trực tiếp)                   | [bigmodel.cn](https://bigmodel.cn)                           |
+| `volcengine` | LLM (Volcengine trực tiếp)              | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter` | LLM (khuyến nghị, truy cập tất cả mô hình) | [openrouter.ai](https://openrouter.ai)                   |
+| `anthropic`  | LLM (Claude trực tiếp)                  | [console.anthropic.com](https://console.anthropic.com)       |
+| `openai`     | LLM (GPT trực tiếp)                     | [platform.openai.com](https://platform.openai.com)           |
+| `deepseek`   | LLM (DeepSeek trực tiếp)                | [platform.deepseek.com](https://platform.deepseek.com)       |
+| `qwen`       | LLM (Qwen trực tiếp)                    | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq`       | LLM + **Chuyển đổi giọng nói** (Whisper)| [console.groq.com](https://console.groq.com)                 |
+| `cerebras`   | LLM (Cerebras trực tiếp)                | [cerebras.ai](https://cerebras.ai)                           |
+| `vivgrid`    | LLM (Vivgrid trực tiếp)                 | [vivgrid.com](https://vivgrid.com)                           |
+
+### Cấu Hình Mô Hình (model_list)
+
+> **Tính năng mới:** PicoClaw hiện sử dụng cách tiếp cận **lấy mô hình làm trung tâm**. Chỉ cần chỉ định định dạng `vendor/model` (ví dụ: `zhipu/glm-4.7`) để thêm provider mới — **không cần thay đổi code!**
+
+#### Tất Cả Vendor Được Hỗ Trợ
+
+| Vendor                  | Tiền tố `model` | API Base mặc định                                   | Giao thức | API Key                                                          |
+| ----------------------- | --------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
+| **OpenAI**              | `openai/`       | `https://api.openai.com/v1`                         | OpenAI    | [Lấy](https://platform.openai.com)                               |
+| **Anthropic**           | `anthropic/`    | `https://api.anthropic.com/v1`                      | Anthropic | [Lấy](https://console.anthropic.com)                             |
+| **智谱 AI (GLM)**       | `zhipu/`        | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Lấy](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys)     |
+| **DeepSeek**            | `deepseek/`     | `https://api.deepseek.com/v1`                       | OpenAI    | [Lấy](https://platform.deepseek.com)                             |
+| **Google Gemini**       | `gemini/`       | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI    | [Lấy](https://aistudio.google.com/api-keys)                      |
+| **Groq**                | `groq/`         | `https://api.groq.com/openai/v1`                    | OpenAI    | [Lấy](https://console.groq.com)                                  |
+| **通义千问 (Qwen)**     | `qwen/`         | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Lấy](https://dashscope.console.aliyun.com)                      |
+| **Ollama**              | `ollama/`       | `http://localhost:11434/v1`                         | OpenAI    | Cục bộ (không cần key)                                           |
+| **OpenRouter**          | `openrouter/`   | `https://openrouter.ai/api/v1`                      | OpenAI    | [Lấy](https://openrouter.ai/keys)                                |
+| **VolcEngine (Doubao)** | `volcengine/`   | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Lấy](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **Antigravity**         | `antigravity/`  | Google Cloud                                        | Custom    | Chỉ OAuth                                                        |
+
+#### Cân Bằng Tải
+
+Cấu hình nhiều endpoint cho cùng tên mô hình — PicoClaw sẽ tự động round-robin:
+
+```json
+{
+  "model_list": [
+    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api1.example.com/v1", "api_key": "sk-key1" },
+    { "model_name": "gpt-5.4", "model": "openai/gpt-5.4", "api_base": "https://api2.example.com/v1", "api_key": "sk-key2" }
+  ]
+}
+```
+
+#### Di Chuyển Từ Cấu Hình `providers` Cũ
+
+Cấu hình `providers` cũ đã **bị deprecated** nhưng vẫn được hỗ trợ. Xem [docs/migration/model-list-migration.md](../migration/model-list-migration.md).
+
+### Kiến Trúc Provider
+
+PicoClaw định tuyến provider theo họ giao thức:
+
+- **Tương thích OpenAI**: OpenRouter, Groq, Zhipu, endpoint kiểu vLLM và hầu hết các provider khác.
+- **Anthropic**: Hành vi API Claude gốc.
+- **Codex/OAuth**: Tuyến xác thực OAuth/token OpenAI.
+
+### Tác Vụ Đã Lên Lịch / Nhắc Nhở
+
+PicoClaw hỗ trợ tác vụ theo lịch qua công cụ `cron`.
+
+```json
+{
+  "tools": {
+    "cron": {
+      "enabled": true,
+      "exec_timeout_minutes": 5
+    }
+  }
+}
+```
+
+Tác vụ đã lên lịch được lưu trữ bền vững sau khi khởi động lại tại `~/.picoclaw/workspace/cron/`.
+
+### Chủ Đề Nâng Cao
+
+| Chủ đề | Mô tả |
+| ------ | ----- |
+| [Hệ Thống Hook](../hooks/README.md) | Hook hướng sự kiện: observer, interceptor, approval hook |
+| [Steering](../steering.md) | Chèn tin nhắn vào vòng lặp agent đang chạy |
+| [SubTurn](../subturn.md) | Điều phối subagent, kiểm soát đồng thời, vòng đời |
+| [Quản Lý Ngữ Cảnh](../agent-refactor/context.md) | Phát hiện ranh giới ngữ cảnh, nén |
diff --git a/docs/vi/credential_encryption.md b/docs/vi/credential_encryption.md
new file mode 100644
index 000000000..9ba24588b
--- /dev/null
+++ b/docs/vi/credential_encryption.md
@@ -0,0 +1,159 @@
+> Quay lại [README](../../README.vi.md)
+
+# Mã hóa Thông tin Xác thực
+
+PicoClaw hỗ trợ mã hóa các giá trị `api_key` trong các mục cấu hình `model_list`.
+Các khóa đã mã hóa được lưu trữ dưới dạng chuỗi `enc://<base64>` và được giải mã tự động khi khởi động.
+
+---
+
+## Bắt đầu Nhanh
+
+**1. Đặt cụm mật khẩu**
+
+```bash
+export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
+```
+
+**2. Mã hóa khóa API**
+
+Chạy `picoclaw onboard` — nó yêu cầu nhập cụm mật khẩu và tạo khóa SSH,
+sau đó tự động mã hóa lại tất cả các mục `api_key` dạng văn bản thuần trong cấu hình
+ở lần gọi `SaveConfig` tiếp theo. Giá trị `enc://` kết quả sẽ có dạng:
+
+```
+enc://AAAA...base64...
+```
+
+**3. Dán kết quả vào cấu hình**
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-4o",
+      "model": "openai/gpt-4o",
+      "api_key": "enc://AAAA...base64...",
+      "api_base": "https://api.openai.com/v1"
+    }
+  ]
+}
+```
+
+---
+
+## Các Định dạng `api_key` được Hỗ trợ
+
+| Định dạng | Ví dụ | Hành vi |
+|-----------|-------|---------|
+| Văn bản thuần | `sk-abc123` | Sử dụng nguyên trạng |
+| Tham chiếu tệp | `file://openai.key` | Nội dung được đọc từ cùng thư mục với tệp cấu hình |
+| Đã mã hóa | `enc://<base64>` | Giải mã khi khởi động bằng `PICOCLAW_KEY_PASSPHRASE` |
+| Trống | `""` | Truyền qua không thay đổi (dùng với `auth_method: oauth`) |
+
+---
+
+## Thiết kế Mật mã
+
+### Dẫn xuất Khóa
+
+Mã hóa sử dụng **HKDF-SHA256** với khóa riêng SSH làm yếu tố thứ hai.
+
+```
+sshHash = SHA256(ssh_private_key_file_bytes)
+ikm     = HMAC-SHA256(key=sshHash, message=passphrase)
+aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+```
+
+### Mã hóa
+
+```
+AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
+```
+
+### Định dạng Truyền tải
+
+```
+enc://<base64( salt[16] + nonce[12] + ciphertext )>
+```
+
+| Trường | Kích thước | Mô tả |
+|--------|-----------|-------|
+| `salt` | 16 byte | Ngẫu nhiên mỗi lần mã hóa; đưa vào HKDF |
+| `nonce` | 12 byte | Ngẫu nhiên mỗi lần mã hóa; IV của AES-GCM |
+| `ciphertext` | thay đổi | Bản mã AES-256-GCM + thẻ xác thực 16 byte |
+
+Thẻ xác thực GCM được tự động nối vào bản mã. Bất kỳ sự giả mạo nào đều khiến giải mã thất bại với lỗi thay vì trả về văn bản thuần bị hỏng.
+
+### Hiệu suất
+
+| Thao tác | Thời gian (ARM Cortex-A) |
+|----------|--------------------------|
+| Dẫn xuất khóa (HKDF) | < 1 ms |
+| Giải mã AES-256-GCM | < 1 ms |
+| **Tổng chi phí khởi động** | **< 2 ms mỗi khóa** |
+
+---
+
+## Bảo mật Hai Yếu tố với Khóa SSH
+
+Khi khóa riêng SSH được cung cấp, việc phá vỡ mã hóa yêu cầu **cả hai**:
+
+1. **Cụm mật khẩu** (`PICOCLAW_KEY_PASSPHRASE`)
+2. **Tệp khóa riêng SSH**
+
+Điều này có nghĩa là chỉ rò rỉ tệp cấu hình không đủ để khôi phục khóa API, ngay cả khi cụm mật khẩu yếu. Khóa SSH đóng góp 256 bit entropy (Ed25519) bất kể độ mạnh của cụm mật khẩu.
+
+### Mô hình Mối đe dọa
+
+| Kẻ tấn công có | Có thể giải mã? |
+|----------------|-----------------|
+| Chỉ tệp cấu hình | Không — cần cụm mật khẩu + khóa SSH |
+| Chỉ khóa SSH | Không — cần cụm mật khẩu |
+| Chỉ cụm mật khẩu | Không — cần khóa SSH |
+| Tệp cấu hình + khóa SSH + cụm mật khẩu | Có — xâm phạm hoàn toàn |
+
+---
+
+## Biến Môi trường
+
+| Biến | Bắt buộc | Mô tả |
+|------|----------|-------|
+| `PICOCLAW_KEY_PASSPHRASE` | Có (cho `enc://`) | Cụm mật khẩu dùng để dẫn xuất khóa |
+| `PICOCLAW_SSH_KEY_PATH` | Không | Đường dẫn đến khóa riêng SSH. Nếu không đặt, tự động phát hiện từ `~/.ssh/picoclaw_ed25519.key` |
+
+### Tự động Phát hiện Khóa SSH
+
+Nếu `PICOCLAW_SSH_KEY_PATH` không được đặt, PicoClaw tìm khóa chuyên dụng:
+
+```
+~/.ssh/picoclaw_ed25519.key
+```
+
+Tệp chuyên dụng này tránh xung đột với các khóa SSH hiện có của người dùng.
+Chạy `picoclaw onboard` để tạo tự động.
+
+`os.UserHomeDir()` được sử dụng để phân giải thư mục home đa nền tảng (đọc `USERPROFILE` trên Windows, `HOME` trên Unix/macOS).
+
+> **Lưu ý:** Tệp khóa SSH là bắt buộc cho mã hóa thông tin xác thực. Nếu không tìm thấy khóa và `PICOCLAW_SSH_KEY_PATH` không được đặt, mã hóa/giải mã sẽ thất bại. Chạy `picoclaw onboard` để tạo khóa tự động.
+
+---
+
+## Di chuyển
+
+Vì tài liệu bí mật duy nhất là `PICOCLAW_KEY_PASSPHRASE` và tệp khóa riêng SSH, việc di chuyển rất đơn giản:
+
+1. Sao chép tệp cấu hình sang máy mới.
+2. Đặt `PICOCLAW_KEY_PASSPHRASE` với cùng giá trị.
+3. Sao chép tệp khóa riêng SSH đến cùng đường dẫn (hoặc đặt `PICOCLAW_SSH_KEY_PATH` đến vị trí mới).
+
+Không cần mã hóa lại.
+
+---
+
+## Lưu ý về Bảo mật
+
+- **Cả cụm mật khẩu và khóa SSH đều bắt buộc.** Khóa SSH đóng vai trò yếu tố thứ hai — không có nó, mã hóa/giải mã sẽ thất bại. Chạy `picoclaw onboard` để tạo khóa nếu chưa tồn tại.
+- **Khóa SSH chỉ đọc khi chạy.** PicoClaw không bao giờ ghi hoặc sửa đổi tệp khóa SSH.
+- **Khóa văn bản thuần vẫn được hỗ trợ.** Các cấu hình hiện có không dùng `enc://` không bị ảnh hưởng.
+- **Định dạng `enc://` được quản lý phiên bản** thông qua trường `info` của HKDF (`picoclaw-credential-v1`), cho phép nâng cấp thuật toán trong tương lai mà không làm hỏng các giá trị đã mã hóa hiện có.
diff --git a/docs/vi/debug.md b/docs/vi/debug.md
new file mode 100644
index 000000000..69583d486
--- /dev/null
+++ b/docs/vi/debug.md
@@ -0,0 +1,36 @@
+# Gỡ lỗi PicoClaw
+
+> Quay lại [README](../../README.vi.md)
+
+PicoClaw thực hiện nhiều tương tác phức tạp ở hậu trường cho mỗi yêu cầu nhận được — từ định tuyến tin nhắn và đánh giá độ phức tạp, đến thực thi công cụ và thích ứng với lỗi mô hình. Khả năng xem chính xác những gì đang xảy ra là rất quan trọng, không chỉ để khắc phục các sự cố tiềm ẩn, mà còn để thực sự hiểu cách agent hoạt động.
+
+## Khởi động PicoClaw ở chế độ gỡ lỗi
+
+Để nhận thông tin chi tiết về những gì agent đang thực hiện (yêu cầu LLM, lệnh gọi công cụ, định tuyến tin nhắn), bạn có thể khởi động gateway PicoClaw với cờ gỡ lỗi:
+
+```bash
+picoclaw gateway --debug
+# or
+picoclaw gateway -d
+```
+
+Ở chế độ này, hệ thống sẽ định dạng log chi tiết và hiển thị bản xem trước của prompt hệ thống và kết quả thực thi công cụ.
+
+## Tắt cắt ngắn log (log đầy đủ)
+
+Theo mặc định, PicoClaw cắt ngắn các chuỗi rất dài (như *Prompt Hệ thống* hoặc kết quả JSON lớn) trong log gỡ lỗi để giữ cho console dễ đọc.
+
+Nếu bạn cần kiểm tra đầu ra đầy đủ của một lệnh hoặc payload chính xác được gửi đến mô hình LLM, bạn có thể sử dụng cờ `--no-truncate`.
+
+**Lưu ý:** Cờ này *chỉ* hoạt động khi kết hợp với chế độ `--debug`.
+
+```bash
+picoclaw gateway --debug --no-truncate
+
+```
+
+Khi cờ này được kích hoạt, chức năng cắt ngắn toàn cục sẽ bị vô hiệu hóa. Điều này cực kỳ hữu ích để:
+
+* Xác minh cú pháp chính xác của các tin nhắn được gửi đến nhà cung cấp.
+* Đọc đầu ra đầy đủ của các công cụ như `exec`, `web_fetch` hoặc `read_file`.
+* Gỡ lỗi lịch sử phiên được lưu trong bộ nhớ.
diff --git a/docs/vi/docker.md b/docs/vi/docker.md
new file mode 100644
index 000000000..eddc20a75
--- /dev/null
+++ b/docs/vi/docker.md
@@ -0,0 +1,167 @@
+# 🐳 Docker và Bắt Đầu Nhanh
+
+> Quay lại [README](../../README.vi.md)
+
+## 🐳 Docker Compose
+
+Bạn cũng có thể chạy PicoClaw bằng Docker Compose mà không cần cài đặt gì trên máy.
+
+```bash
+# 1. Clone repo này
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. Lần chạy đầu tiên — tự động tạo docker/data/config.json rồi thoát
+#    (chỉ kích hoạt khi cả config.json và workspace/ đều không tồn tại)
+docker compose -f docker/docker-compose.yml --profile gateway up
+# Container hiển thị "First-run setup complete." và dừng lại.
+
+# 3. Cấu hình API key của bạn
+vim docker/data/config.json   # Set provider API keys, bot tokens, etc.
+
+# 4. Khởi động
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+> [!TIP]
+> **Người dùng Docker**: Mặc định, Gateway lắng nghe trên `127.0.0.1`, không thể truy cập từ host. Nếu bạn cần truy cập các health endpoint hoặc mở port, hãy đặt `PICOCLAW_GATEWAY_HOST=0.0.0.0` trong môi trường hoặc cập nhật `config.json`.
+
+```bash
+# 5. Kiểm tra log
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. Dừng
+docker compose -f docker/docker-compose.yml --profile gateway down
+```
+
+### Chế Độ Launcher (Web Console)
+
+Image `launcher` bao gồm cả ba binary (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) và khởi động web console mặc định, cung cấp giao diện trình duyệt để cấu hình và chat.
+
+```bash
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+```
+
+Mở http://localhost:18800 trong trình duyệt. Launcher tự động quản lý tiến trình gateway.
+
+> [!WARNING]
+> Web console chưa hỗ trợ xác thực. Tránh để lộ ra internet công cộng.
+
+### Chế Độ Agent (One-shot)
+
+```bash
+# Đặt câu hỏi
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
+
+# Chế độ tương tác
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+```
+
+### Cập Nhật
+
+```bash
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+### 🚀 Bắt Đầu Nhanh
+
+> [!TIP]
+> Cấu hình API Key trong `~/.picoclaw/config.json`. Lấy API Key: [Volcengine (CodingPlan)](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM). Tìm kiếm web là tùy chọn — lấy miễn phí [Tavily API](https://tavily.com) (1000 truy vấn miễn phí/tháng) hoặc [Brave Search API](https://brave.com/search/api) (2000 truy vấn miễn phí/tháng).
+
+**1. Khởi tạo**
+
+```bash
+picoclaw onboard
+```
+
+**2. Cấu hình** (`~/.picoclaw/config.json`)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "gpt-5.4",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key",
+      "api_base":"https://ark.cn-beijing.volces.com/api/coding/v3"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "your-api-key",
+      "request_timeout": 300
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "your-anthropic-key"
+    }
+  ],
+  "tools": {
+    "web": {
+      "enabled": true,
+      "fetch_limit_bytes": 10485760,
+      "format": "plaintext",
+      "brave": {
+        "enabled": false,
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      },
+      "tavily": {
+        "enabled": false,
+        "api_key": "YOUR_TAVILY_API_KEY",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "YOUR_PERPLEXITY_API_KEY",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://your-searxng-instance:8888",
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+> **Mới**: Định dạng cấu hình `model_list` cho phép thêm provider mà không cần thay đổi code. Xem [Cấu Hình Mô Hình](#cấu-hình-mô-hình-model_list) để biết chi tiết.
+> `request_timeout` là tùy chọn và tính bằng giây. Nếu bỏ qua hoặc đặt `<= 0`, PicoClaw sử dụng timeout mặc định (120s).
+
+**3. Lấy API Key**
+
+* **Nhà cung cấp LLM**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
+* **Tìm kiếm Web** (tùy chọn):
+  * [Brave Search](https://brave.com/search/api) - Trả phí ($5/1000 truy vấn, ~$5-6/tháng)
+  * [Perplexity](https://www.perplexity.ai) - Tìm kiếm bằng AI với giao diện chat
+  * [SearXNG](https://github.com/searxng/searxng) - Công cụ tìm kiếm tổng hợp tự host (miễn phí, không cần API key)
+  * [Tavily](https://tavily.com) - Tối ưu cho AI Agent (1000 yêu cầu/tháng)
+  * DuckDuckGo - Fallback tích hợp (không cần API key)
+
+> **Lưu ý**: Xem `config.example.json` để có mẫu cấu hình đầy đủ.
+
+**4. Chat**
+
+```bash
+picoclaw agent -m "What is 2+2?"
+```
+
+Vậy là xong! Bạn có một trợ lý AI hoạt động trong 2 phút.
+
+---
diff --git a/docs/vi/hardware-compatibility.md b/docs/vi/hardware-compatibility.md
new file mode 100644
index 000000000..8315c049e
--- /dev/null
+++ b/docs/vi/hardware-compatibility.md
@@ -0,0 +1,152 @@
+> Quay lại [README](../../README.vi.md)
+
+# 🖥️ PicoClaw Danh sách tương thích phần cứng
+
+PicoClaw chạy được trên hầu hết mọi thiết bị Linux. Trang này ghi nhận các chip, sản phẩm và bo mạch phát triển đã được xác minh.
+
+**Phần cứng của bạn chưa có trong danh sách?** Gửi PR để thêm vào! Các nhà sản xuất phần cứng được hoan nghênh đóng góp và đồng quảng bá.
+
+---
+
+## 1. Hỗ trợ chip đã xác minh
+
+### x86
+
+| Nhà sản xuất | Chip | Ghi chú |
+|--------------|------|---------|
+| Intel | Any x86 CPU (i386+) | Tất cả bộ xử lý desktop/server/laptop |
+| AMD | Any x86 CPU | Tất cả bộ xử lý desktop/server/laptop |
+
+### ARM
+
+| Kiến trúc phụ | Chip tiêu biểu | Ghi chú |
+|----------------|----------------|---------|
+| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | Đơn nhân ARM1176JZF-S |
+| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | Đơn nhân Cortex-A7, dùng trong LicheePi Zero |
+| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | Bốn nhân Cortex-A53, dùng trong Orange Pi Zero 3 |
+| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | Bốn nhân Cortex-A72 |
+| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | Bốn nhân Cortex-A76 |
+| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | Hai nhân Cortex-A53 + NPU, dùng trong NanoKVM-Pro / MaixCAM2 |
+
+### RISC-V (riscv64)
+
+| Nhà sản xuất | Chip | Lõi | Ghi chú |
+|--------------|------|-----|---------|
+| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 tích hợp, dùng trong LicheeRV-Nano / NanoKVM / MaixCAM |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L tích hợp, 1 TOPS NPU, camera AI 4K SiP |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | Dòng camera AI RISC-V |
+| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | Dùng trong HaaS506-LD1 RTU công nghiệp |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | Dùng trong Milk-V Jupiter, BananaPi BPI-F3 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | Tuân thủ RVA23, RVV 1024-bit, suy luận AI FP8 |
+| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8 lõi, 16MB cache L3, cấp desktop |
+| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU, dùng trong CanMV-K230 |
+
+### MIPS
+
+| Nhà sản xuất | Chip | Ghi chú |
+|--------------|------|---------|
+| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz, dùng trong nhiều router OpenWrt (vd. Xiaomi Router 3G) |
+
+### LoongArch (loong64)
+
+| Nhà sản xuất | Chip | Ghi chú |
+|--------------|------|---------|
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | Bốn nhân LA464 @ 2.5GHz, desktop/máy trạm |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | Bốn nhân 4C/8T @ 2.5GHz, IPC tương đương Intel thế hệ 10 |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | Hai nhân @ 1GHz, ứng dụng công nghiệp/IoT |
+
+---
+
+## 2. Sản phẩm đã xác minh (theo ngày phát hành)
+
+Sản phẩm tiêu dùng, router và thiết bị công nghiệp đã được kiểm thử với PicoClaw.
+
+| Năm | Sản phẩm | Kiến trúc | SoC | RAM | Danh mục |
+|-----|----------|-----------|-----|-----|----------|
+| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | Điện thoại thông minh |
+| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | Máy tính bảng |
+| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | Router (OpenWrt) |
+| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | TV Box / Máy chủ gia đình |
+| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | Loa thông minh |
+| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
+| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | RTU công nghiệp |
+| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | IP-KVM Pro |
+| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | Camera AI 4K |
+
+---
+
+## 3. Bo mạch phát triển đã xác minh (theo ngày phát hành)
+
+| Năm | Bo mạch | Kiến trúc | SoC | RAM | Liên kết mua |
+|-----|---------|-----------|-----|-----|--------------|
+| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
+| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
+| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
+| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
+| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
+| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
+| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
+| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
+| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
+
+---
+
+## 4. Cũng hoạt động trên
+
+### Điện thoại Android (qua Termux)
+
+Bất kỳ điện thoại Android ARM64 nào (2015+) với 1GB+ RAM. Cài đặt [Termux](https://github.com/termux/termux-app), sử dụng `proot` để chạy PicoClaw.
+
+> Xem [README: Chạy trên điện thoại Android cũ](../../README.vi.md#-run-on-old-android-phones) để biết hướng dẫn cài đặt.
+
+### Desktop / Máy chủ / Đám mây
+
+| Nền tảng | Ghi chú |
+|----------|---------|
+| x86_64 Linux | Binary gốc, không phụ thuộc |
+| x86_64 Windows | Binary gốc |
+| macOS (Intel / Apple Silicon) | Binary gốc |
+| Docker (any platform) | `docker compose` một dòng lệnh, xem [Hướng dẫn Docker](docker.md) |
+| OpenWrt routers | Bản dựng MIPS/ARM, yêu cầu >32MB RAM trống |
+| FreeBSD / NetBSD | Có bản dựng x86_64 và arm64 |
+
+---
+
+## 5. Yêu cầu tối thiểu
+
+| Tài nguyên | Tối thiểu | Khuyến nghị |
+|------------|-----------|-------------|
+| RAM | 10MB trống | 32MB+ trống |
+| Lưu trữ | 20MB (binary) | 50MB+ (với workspace) |
+| CPU | Bất kỳ (đơn nhân 0.6GHz+) | — |
+| OS | Linux (kernel 3.x+) | Linux 5.x+ |
+| Mạng | Bắt buộc (cho các lệnh gọi API LLM) | Ethernet hoặc WiFi |
+
+---
+
+## 6. Cách kiểm thử và đóng góp
+
+```bash
+# 1. Tải xuống cho kiến trúc của bạn
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+
+# 2. Khởi tạo
+./picoclaw onboard
+
+# 3. Kiểm thử
+./picoclaw agent -m "Hello, what board am I running on?"
+```
+
+Các bản dựng có sẵn: `linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
+
+### Thêm phần cứng của bạn
+
+1. Fork kho lưu trữ này
+2. Thêm chip / sản phẩm / bo mạch của bạn vào bảng tương ứng
+3. Bao gồm: tên, kiến trúc, SoC, RAM, năm và liên kết nếu có
+4. Gửi PR
+
+Nhà sản xuất phần cứng: muốn thêm hỗ trợ chính thức hoặc đồng quảng bá? Mở issue hoặc liên hệ qua [Discord](https://discord.gg/V4sAZ9XWpN).
diff --git a/docs/vi/providers.md b/docs/vi/providers.md
new file mode 100644
index 000000000..09b51c56b
--- /dev/null
+++ b/docs/vi/providers.md
@@ -0,0 +1,433 @@
+# 🔌 Nhà Cung Cấp và Cấu Hình Mô Hình
+
+> Quay lại [README](../../README.vi.md)
+
+### Nhà Cung Cấp
+
+> [!NOTE]
+> Groq cung cấp chuyển đổi giọng nói miễn phí qua Whisper. Nếu được cấu hình, tin nhắn âm thanh từ bất kỳ kênh nào sẽ được tự động chuyển đổi ở cấp agent.
+
+| Provider     | Purpose                                 | Get API Key                                                  |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini`     | LLM (Gemini direct)                     | [aistudio.google.com](https://aistudio.google.com)           |
+| `zhipu`      | LLM (Zhipu direct)                      | [bigmodel.cn](https://bigmodel.cn)                           |
+| `volcengine` | LLM(Volcengine direct)                  | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw)                 |
+| `openrouter` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai)                       |
+| `anthropic`  | LLM (Claude direct)                     | [console.anthropic.com](https://console.anthropic.com)       |
+| `openai`     | LLM (GPT direct)                        | [platform.openai.com](https://platform.openai.com)           |
+| `deepseek`   | LLM (DeepSeek direct)                   | [platform.deepseek.com](https://platform.deepseek.com)       |
+| `qwen`       | LLM (Qwen direct)                       | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq`       | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com)                 |
+| `cerebras`   | LLM (Cerebras direct)                   | [cerebras.ai](https://cerebras.ai)                           |
+| `vivgrid`    | LLM (Vivgrid direct)                    | [vivgrid.com](https://vivgrid.com)                           |
+| `moonshot`   | LLM (Kimi/Moonshot direct)              | [platform.moonshot.cn](https://platform.moonshot.cn)         |
+| `minimax`    | LLM (Minimax direct)                    | [platform.minimaxi.com](https://platform.minimaxi.com)      |
+| `avian`      | LLM (Avian direct)                      | [avian.io](https://avian.io)                                 |
+| `mistral`    | LLM (Mistral direct)                    | [console.mistral.ai](https://console.mistral.ai)            |
+| `longcat`    | LLM (Longcat direct)                    | [longcat.ai](https://longcat.ai)                             |
+| `modelscope` | LLM (ModelScope direct)                 | [modelscope.cn](https://modelscope.cn)                       |
+
+### Cấu Hình Mô Hình (model_list)
+
+> **Có gì mới?** PicoClaw hiện sử dụng cách tiếp cận cấu hình **tập trung vào mô hình**. Chỉ cần chỉ định định dạng `vendor/model` (ví dụ: `zhipu/glm-4.7`) để thêm provider mới — **không cần thay đổi code!**
+
+Thiết kế này cũng cho phép **hỗ trợ đa agent** với lựa chọn provider linh hoạt:
+
+- **Agent khác nhau, provider khác nhau**: Mỗi agent có thể sử dụng provider LLM riêng
+- **Fallback mô hình**: Cấu hình mô hình chính và dự phòng cho khả năng phục hồi
+- **Cân bằng tải**: Phân phối yêu cầu qua nhiều endpoint
+- **Cấu hình tập trung**: Quản lý tất cả provider tại một nơi
+
+#### 📋 Tất Cả Vendor Được Hỗ Trợ
+
+| Vendor              | `model` Prefix    | Default API Base                                    | Protocol  | API Key                                                          |
+| ------------------- | ----------------- |-----------------------------------------------------| --------- | ---------------------------------------------------------------- |
+| **OpenAI**          | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [Get Key](https://platform.openai.com)                           |
+| **Anthropic**       | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [Get Key](https://console.anthropic.com)                         |
+| **智谱 AI (GLM)**   | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [Get Key](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek**        | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [Get Key](https://platform.deepseek.com)                         |
+| **Google Gemini**   | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI    | [Get Key](https://aistudio.google.com/api-keys)                  |
+| **Groq**            | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [Get Key](https://console.groq.com)                              |
+| **Moonshot**        | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [Get Key](https://platform.moonshot.cn)                          |
+| **通义千问 (Qwen)** | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [Get Key](https://dashscope.console.aliyun.com)                  |
+| **NVIDIA**          | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [Get Key](https://build.nvidia.com)                              |
+| **Ollama**          | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | Local (no key needed)                                            |
+| **OpenRouter**      | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [Get Key](https://openrouter.ai/keys)                            |
+| **LiteLLM Proxy**   | `litellm/`        | `http://localhost:4000/v1`                          | OpenAI    | Your LiteLLM proxy key                                            |
+| **VLLM**            | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | Local                                                            |
+| **Cerebras**        | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [Get Key](https://cerebras.ai)                                   |
+| **VolcEngine (Doubao)** | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [Get Key](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw)                        |
+| **神算云**          | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                |
+| **BytePlus**        | `byteplus/`       | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [Get Key](https://www.byteplus.com)                        |
+| **Vivgrid**         | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [Get Key](https://vivgrid.com)                                   |
+| **LongCat**         | `longcat/`        | `https://api.longcat.chat/openai`                   | OpenAI    | [Get Key](https://longcat.chat/platform)                         |
+| **ModelScope (魔搭)**| `modelscope/`    | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [Get Token](https://modelscope.cn/my/tokens)                     |
+| **Antigravity**     | `antigravity/`    | Google Cloud                                        | Custom    | OAuth only                                                       |
+| **GitHub Copilot**  | `github-copilot/` | `localhost:4321`                                    | gRPC      | -                                                                |
+
+#### Cấu Hình Cơ Bản
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-openai-key"
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "sk-ant-your-key"
+    },
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-zhipu-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "gpt-5.4"
+    }
+  }
+}
+```
+
+#### Ví Dụ Theo Vendor
+
+**OpenAI**
+
+```json
+{
+  "model_name": "gpt-5.4",
+  "model": "openai/gpt-5.4",
+  "api_key": "sk-..."
+}
+```
+
+**VolcEngine (Doubao)**
+
+```json
+{
+  "model_name": "ark-code-latest",
+  "model": "volcengine/ark-code-latest",
+  "api_key": "sk-..."
+}
+```
+
+**智谱 AI (GLM)**
+
+```json
+{
+  "model_name": "glm-4.7",
+  "model": "zhipu/glm-4.7",
+  "api_key": "your-key"
+}
+```
+
+**DeepSeek**
+
+```json
+{
+  "model_name": "deepseek-chat",
+  "model": "deepseek/deepseek-chat",
+  "api_key": "sk-..."
+}
+```
+
+**Anthropic (với API key)**
+
+```json
+{
+  "model_name": "claude-sonnet-4.6",
+  "model": "anthropic/claude-sonnet-4.6",
+  "api_key": "sk-ant-your-key"
+}
+```
+
+> Chạy `picoclaw auth login --provider anthropic` để dán API token.
+
+**Anthropic Messages API (định dạng native)**
+
+Để truy cập trực tiếp API Anthropic hoặc endpoint tùy chỉnh chỉ hỗ trợ định dạng message native của Anthropic:
+
+```json
+{
+  "model_name": "claude-opus-4-6",
+  "model": "anthropic-messages/claude-opus-4-6",
+  "api_key": "sk-ant-your-key",
+  "api_base": "https://api.anthropic.com"
+}
+```
+
+> Sử dụng giao thức `anthropic-messages` khi:
+> - Sử dụng proxy bên thứ ba chỉ hỗ trợ endpoint native `/v1/messages` của Anthropic (không tương thích OpenAI `/v1/chat/completions`)
+> - Kết nối đến dịch vụ như MiniMax, Synthetic yêu cầu định dạng message native của Anthropic
+> - Giao thức `anthropic` hiện tại trả về lỗi 404 (cho thấy endpoint không hỗ trợ định dạng tương thích OpenAI)
+>
+> **Lưu ý:** Giao thức `anthropic` sử dụng định dạng tương thích OpenAI (`/v1/chat/completions`), trong khi `anthropic-messages` sử dụng định dạng native của Anthropic (`/v1/messages`). Chọn dựa trên định dạng endpoint hỗ trợ.
+
+**Ollama (local)**
+
+```json
+{
+  "model_name": "llama3",
+  "model": "ollama/llama3"
+}
+```
+
+**Proxy/API Tùy Chỉnh**
+
+```json
+{
+  "model_name": "my-custom-model",
+  "model": "openai/custom-model",
+  "api_base": "https://my-proxy.com/v1",
+  "api_key": "sk-...",
+  "request_timeout": 300
+}
+```
+
+**LiteLLM Proxy**
+
+```json
+{
+  "model_name": "lite-gpt4",
+  "model": "litellm/lite-gpt4",
+  "api_base": "http://localhost:4000/v1",
+  "api_key": "sk-..."
+}
+```
+
+PicoClaw chỉ loại bỏ tiền tố ngoài `litellm/` trước khi gửi yêu cầu, nên alias proxy như `litellm/lite-gpt4` gửi `lite-gpt4`, trong khi `litellm/openai/gpt-4o` gửi `openai/gpt-4o`.
+
+#### Cân Bằng Tải
+
+Cấu hình nhiều endpoint cho cùng tên mô hình — PicoClaw sẽ tự động round-robin giữa chúng:
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api1.example.com/v1",
+      "api_key": "sk-key1"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api2.example.com/v1",
+      "api_key": "sk-key2"
+    }
+  ]
+}
+```
+
+#### Di Chuyển Từ Cấu Hình Legacy `providers`
+
+Cấu hình `providers` cũ đã **ngừng hỗ trợ** nhưng vẫn được hỗ trợ để tương thích ngược.
+
+**Cấu hình cũ (ngừng hỗ trợ):**
+
+```json
+{
+  "providers": {
+    "zhipu": {
+      "api_key": "your-key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  },
+  "agents": {
+    "defaults": {
+      "provider": "zhipu",
+      "model": "glm-4.7"
+    }
+  }
+}
+```
+
+**Cấu hình mới (khuyến nghị):**
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "glm-4.7"
+    }
+  }
+}
+```
+
+Để xem hướng dẫn di chuyển chi tiết, xem [migration/model-list-migration.md](../migration/model-list-migration.md).
+
+### Kiến Trúc Provider
+
+PicoClaw định tuyến provider theo họ giao thức:
+
+- Giao thức tương thích OpenAI: OpenRouter, gateway tương thích OpenAI, Groq, Zhipu, và endpoint kiểu vLLM.
+- Giao thức Anthropic: Hành vi API native của Claude.
+- Đường dẫn Codex/OAuth: Tuyến xác thực OAuth/token của OpenAI.
+
+Điều này giữ runtime nhẹ trong khi làm cho backend tương thích OpenAI mới chủ yếu là thao tác cấu hình (`api_base` + `api_key`).
+
+<details>
+<summary><b>Zhipu</b></summary>
+
+**1. Lấy API key và URL base**
+
+* Lấy [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
+
+**2. Cấu hình**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "providers": {
+    "zhipu": {
+      "api_key": "Your API Key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  }
+}
+```
+
+**3. Chạy**
+
+```bash
+picoclaw agent -m "Hello"
+```
+
+</details>
+
+<details>
+<summary><b>Ví dụ cấu hình đầy đủ</b></summary>
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "anthropic/claude-opus-4-5"
+    }
+  },
+  "session": {
+    "dm_scope": "per-channel-peer"
+  },
+  "providers": {
+    "openrouter": {
+      "api_key": "sk-or-v1-xxx"
+    },
+    "groq": {
+      "api_key": "gsk_xxx"
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456:ABC...",
+      "allow_from": ["123456789"]
+    },
+    "discord": {
+      "enabled": true,
+      "token": "",
+      "allow_from": [""]
+    },
+    "whatsapp": {
+      "enabled": false,
+      "bridge_url": "ws://localhost:3001",
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": []
+    },
+    "feishu": {
+      "enabled": false,
+      "app_id": "cli_xxx",
+      "app_secret": "xxx",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    },
+    "qq": {
+      "enabled": false,
+      "app_id": "",
+      "app_secret": "",
+      "allow_from": []
+    }
+  },
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": false,
+        "api_key": "BSA...",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://localhost:8888",
+        "max_results": 5
+      }
+    },
+    "cron": {
+      "exec_timeout_minutes": 5
+    }
+  },
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+</details>
+
+---
+
+## 📝 So Sánh API Key
+
+| Service          | Pricing                  | Use Case                              |
+| ---------------- | ------------------------ | ------------------------------------- |
+| **OpenRouter**   | Free: 200K tokens/month  | Multiple models (Claude, GPT-4, etc.) |
+| **Volcengine CodingPlan** | ¥9.9/first month | Best for Chinese users, multiple SOTA models (Doubao, DeepSeek, etc.) |
+| **Zhipu**        | Free: 200K tokens/month  | Suitable for Chinese users                |
+| **Brave Search** | $5/1000 queries          | Web search functionality              |
+| **SearXNG**      | Free (self-hosted)       | Privacy-focused metasearch (70+ engines) |
+| **Groq**         | Free tier available      | Fast inference (Llama, Mixtral)       |
+| **Cerebras**     | Free tier available      | Fast inference (Llama, Qwen, etc.)    |
+| **LongCat**      | Free: up to 5M tokens/day | Fast inference                       |
+| **ModelScope**   | Free: 2000 requests/day  | Inference (Qwen, GLM, DeepSeek, etc.) |
+
+---
+
+<div align="center">
+  <img src="assets/logo.jpg" alt="PicoClaw Meme" width="512">
+</div>
diff --git a/docs/vi/spawn-tasks.md b/docs/vi/spawn-tasks.md
new file mode 100644
index 000000000..78f728040
--- /dev/null
+++ b/docs/vi/spawn-tasks.md
@@ -0,0 +1,61 @@
+# 🔄 Tác Vụ Bất Đồng Bộ và Spawn
+
+> Quay lại [README](../../README.vi.md)
+
+## Tác Vụ Nhanh (phản hồi trực tiếp)
+
+- Báo cáo thời gian hiện tại
+
+## Tác Vụ Dài (sử dụng spawn cho bất đồng bộ)
+
+- Tìm kiếm web tin tức AI và tóm tắt
+- Kiểm tra email và báo cáo tin nhắn quan trọng
+```
+
+**Hành vi chính:**
+
+| Feature                 | Description                                               |
+| ----------------------- | --------------------------------------------------------- |
+| **spawn**               | Creates async subagent, doesn't block heartbeat           |
+| **Independent context** | Subagent has its own context, no session history          |
+| **message tool**        | Subagent communicates with user directly via message tool |
+| **Non-blocking**        | After spawning, heartbeat continues to next task          |
+
+#### Cách Giao Tiếp Subagent Hoạt Động
+
+```
+Heartbeat được kích hoạt
+    ↓
+Agent đọc HEARTBEAT.md
+    ↓
+Cho tác vụ dài: spawn subagent
+    ↓                           ↓
+Tiếp tục tác vụ tiếp theo    Subagent làm việc độc lập
+    ↓                           ↓
+Tất cả tác vụ hoàn thành     Subagent sử dụng công cụ "message"
+    ↓                           ↓
+Phản hồi HEARTBEAT_OK        Người dùng nhận kết quả trực tiếp
+```
+
+Subagent có quyền truy cập công cụ (message, web_search, v.v.) và có thể giao tiếp với người dùng độc lập mà không cần qua agent chính.
+
+**Cấu hình:**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| Option     | Default | Description                        |
+| ---------- | ------- | ---------------------------------- |
+| `enabled`  | `true`  | Enable/disable heartbeat           |
+| `interval` | `30`    | Check interval in minutes (min: 5) |
+
+**Biến môi trường:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` để tắt
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` để thay đổi khoảng thời gian
diff --git a/docs/vi/tools_configuration.md b/docs/vi/tools_configuration.md
new file mode 100644
index 000000000..55e7699eb
--- /dev/null
+++ b/docs/vi/tools_configuration.md
@@ -0,0 +1,412 @@
+# 🔧 Cấu Hình Công Cụ
+
+> Quay lại [README](../../README.vi.md)
+
+Cấu hình công cụ của PicoClaw nằm trong trường `tools` của `config.json`.
+
+## Cấu trúc thư mục
+
+```json
+{
+  "tools": {
+    "web": {
+      ...
+    },
+    "mcp": {
+      ...
+    },
+    "exec": {
+      ...
+    },
+    "cron": {
+      ...
+    },
+    "skills": {
+      ...
+    }
+  }
+}
+```
+
+## Công cụ Web
+
+Các công cụ web được sử dụng để tìm kiếm và tải nội dung web.
+
+### Web Fetcher
+Cài đặt chung để tải và xử lý nội dung trang web.
+
+| Cấu hình            | Kiểu   | Mặc định      | Mô tả                                                                                        |
+|----------------------|--------|---------------|-----------------------------------------------------------------------------------------------|
+| `enabled`            | bool   | true          | Bật khả năng tải trang web.                                                                   |
+| `fetch_limit_bytes`  | int    | 10485760      | Kích thước tối đa của payload trang web cần tải, tính bằng byte (mặc định là 10MB).          |
+| `format`             | string | "plaintext"   | Định dạng đầu ra của nội dung đã tải. Tùy chọn: `plaintext` hoặc `markdown` (khuyến nghị).   |
+
+### DuckDuckGo
+
+| Cấu hình      | Kiểu | Mặc định | Mô tả                        |
+|----------------|------|----------|-------------------------------|
+| `enabled`      | bool | true     | Bật tìm kiếm DuckDuckGo      |
+| `max_results`  | int  | 5        | Số kết quả tối đa            |
+
+### Baidu Search
+
+| Cấu hình      | Kiểu   | Mặc định                                                        | Mô tả                              |
+|----------------|--------|-----------------------------------------------------------------|------------------------------------|
+| `enabled`      | bool   | false                                                           | Bật tìm kiếm Baidu                |
+| `api_key`      | string | -                                                               | Khóa API Qianfan                   |
+| `base_url`     | string | `https://qianfan.baidubce.com/v2/ai_search/web_search`         | URL API Baidu Search               |
+| `max_results`  | int    | 10                                                              | Số kết quả tối đa                 |
+
+```json
+{
+  "tools": {
+    "web": {
+      "baidu_search": {
+        "enabled": true,
+        "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
+        "max_results": 10
+      }
+    }
+  }
+}
+```
+
+### Perplexity
+
+| Cấu hình      | Kiểu   | Mặc định | Mô tả                        |
+|----------------|--------|----------|-------------------------------|
+| `enabled`      | bool     | false    | Bật tìm kiếm Perplexity                                          |
+| `api_key`      | string   | -        | Khóa API Perplexity                                              |
+| `api_keys`     | string[] | -        | Nhiều khóa API Perplexity để xoay vòng (ưu tiên hơn `api_key`)  |
+| `max_results`  | int      | 5        | Số kết quả tối đa                                                |
+
+### Brave
+
+| Cấu hình      | Kiểu   | Mặc định | Mô tả                     |
+|----------------|--------|----------|----------------------------|
+| `enabled`      | bool     | false    | Bật tìm kiếm Brave                                               |
+| `api_key`      | string   | -        | Khóa API Brave Search                                            |
+| `api_keys`     | string[] | -        | Nhiều khóa API Brave Search để xoay vòng (ưu tiên hơn `api_key`) |
+| `max_results`  | int      | 5        | Số kết quả tối đa                                                |
+
+### Tavily
+
+| Cấu hình      | Kiểu   | Mặc định | Mô tả                              |
+|----------------|--------|----------|------------------------------------|
+| `enabled`      | bool   | false    | Bật tìm kiếm Tavily               |
+| `api_key`      | string | -        | Khóa API Tavily                    |
+| `base_url`     | string | -        | URL cơ sở Tavily tùy chỉnh        |
+| `max_results`  | int    | 0        | Số kết quả tối đa (0 = mặc định)  |
+
+### SearXNG
+
+| Cấu hình      | Kiểu   | Mặc định                 | Mô tả                      |
+|----------------|--------|--------------------------|----------------------------|
+| `enabled`      | bool   | false                    | Bật tìm kiếm SearXNG       |
+| `base_url`     | string | `http://localhost:8888`  | URL phiên bản SearXNG      |
+| `max_results`  | int    | 5                        | Số kết quả tối đa          |
+
+### GLM Search
+
+| Cấu hình        | Kiểu   | Mặc định                                             | Mô tả                      |
+|------------------|--------|------------------------------------------------------|----------------------------|
+| `enabled`        | bool   | false                                                | Bật GLM Search             |
+| `api_key`        | string | -                                                    | Khóa API GLM               |
+| `base_url`       | string | `https://open.bigmodel.cn/api/paas/v4/web_search`   | URL API GLM Search         |
+| `search_engine`  | string | `search_std`                                         | Loại công cụ tìm kiếm      |
+| `max_results`    | int    | 5                                                    | Số kết quả tối đa          |
+
+## Công cụ Exec
+
+Công cụ exec được sử dụng để thực thi các lệnh shell.
+
+| Cấu hình               | Kiểu  | Mặc định | Mô tả                                         |
+|--------------------------|-------|----------|------------------------------------------------|
+| `enabled`                | bool  | true     | Bật công cụ exec                             |
+| `enable_deny_patterns`   | bool  | true     | Bật chặn lệnh nguy hiểm mặc định             |
+| `custom_deny_patterns`   | array | []       | Mẫu từ chối tùy chỉnh (biểu thức chính quy)  |
+
+### Vô hiệu hóa Công cụ Exec
+
+Để hoàn toàn vô hiệu hóa công cụ `exec`, đặt `enabled` thành `false`:
+
+**Qua tệp cấu hình:**
+```json
+{
+  "tools": {
+    "exec": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**Qua biến môi trường:**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **Lưu ý:** Khi bị vô hiệu hóa, agent sẽ không thể thực thi lệnh shell. Điều này cũng ảnh hưởng đến khả năng chạy lệnh shell theo lịch của công cụ Cron.
+
+### Chức năng
+
+- **`enable_deny_patterns`**: Đặt thành `false` để tắt hoàn toàn các mẫu chặn lệnh nguy hiểm mặc định
+- **`custom_deny_patterns`**: Thêm các mẫu regex từ chối tùy chỉnh; các lệnh khớp sẽ bị chặn
+
+### Các mẫu lệnh bị chặn mặc định
+
+Theo mặc định, PicoClaw chặn các lệnh nguy hiểm sau:
+
+- Lệnh xóa: `rm -rf`, `del /f/q`, `rmdir /s`
+- Thao tác đĩa: `format`, `mkfs`, `diskpart`, `dd if=`, ghi vào `/dev/sd*`
+- Thao tác hệ thống: `shutdown`, `reboot`, `poweroff`
+- Thay thế lệnh: `$()`, `${}`, dấu backtick
+- Pipe đến shell: `| sh`, `| bash`
+- Leo thang đặc quyền: `sudo`, `chmod`, `chown`
+- Điều khiển tiến trình: `pkill`, `killall`, `kill -9`
+- Thao tác từ xa: `curl | sh`, `wget | sh`, `ssh`
+- Quản lý gói: `apt`, `yum`, `dnf`, `npm install -g`, `pip install --user`
+- Container: `docker run`, `docker exec`
+- Git: `git push`, `git force`
+- Khác: `eval`, `source *.sh`
+
+### Hạn chế kiến trúc đã biết
+
+Bộ bảo vệ exec chỉ xác thực lệnh cấp cao nhất được gửi đến PicoClaw. Nó **không** kiểm tra đệ quy các tiến trình con được tạo bởi các công cụ build hoặc script sau khi lệnh đó bắt đầu chạy.
+
+Ví dụ về các quy trình có thể bỏ qua bộ bảo vệ lệnh trực tiếp sau khi lệnh ban đầu được cho phép:
+
+- `make run`
+- `go run ./cmd/...`
+- `cargo run`
+- `npm run build`
+
+Điều này có nghĩa là bộ bảo vệ hữu ích để chặn các lệnh trực tiếp rõ ràng nguy hiểm, nhưng nó **không phải** là sandbox đầy đủ cho các pipeline build chưa được xem xét. Nếu mô hình mối đe dọa của bạn bao gồm mã không đáng tin cậy trong workspace, hãy sử dụng cách ly mạnh hơn như container, VM hoặc quy trình phê duyệt xung quanh các lệnh build và chạy.
+
+### Ví dụ cấu hình
+
+```json
+{
+  "tools": {
+    "exec": {
+      "enable_deny_patterns": true,
+      "custom_deny_patterns": [
+        "\\brm\\s+-r\\b",
+        "\\bkillall\\s+python"
+      ]
+    }
+  }
+}
+```
+
+## Công cụ Cron
+
+Công cụ cron được sử dụng để lên lịch các tác vụ định kỳ.
+
+| Cấu hình               | Kiểu | Mặc định | Mô tả                                              |
+|--------------------------|------|----------|-----------------------------------------------------|
+| `exec_timeout_minutes`   | int  | 5        | Thời gian chờ thực thi tính bằng phút, 0 nghĩa là không giới hạn |
+
+## Công cụ MCP
+
+Công cụ MCP cho phép tích hợp với các máy chủ Model Context Protocol bên ngoài.
+
+### Khám phá công cụ (tải chậm)
+
+Khi kết nối với nhiều máy chủ MCP, việc hiển thị hàng trăm công cụ cùng lúc có thể làm cạn kiệt cửa sổ ngữ cảnh của LLM và tăng chi phí API. Tính năng **Discovery** giải quyết vấn đề này bằng cách giữ các công cụ MCP *ẩn* theo mặc định.
+
+Thay vì tải tất cả các công cụ, LLM được cung cấp một công cụ tìm kiếm nhẹ (sử dụng khớp từ khóa BM25 hoặc Regex). Khi LLM cần một khả năng cụ thể, nó tìm kiếm trong thư viện ẩn. Các công cụ khớp sau đó được tạm thời "mở khóa" và đưa vào ngữ cảnh trong số lượt được cấu hình (`ttl`).
+
+### Cấu hình toàn cục
+
+| Cấu hình    | Kiểu   | Mặc định | Mô tả                                        |
+|-------------|--------|----------|-----------------------------------------------|
+| `enabled`   | bool   | false    | Bật tích hợp MCP toàn cục                    |
+| `discovery` | object | `{}`     | Cấu hình khám phá công cụ (xem bên dưới)    |
+| `servers`   | object | `{}`     | Ánh xạ tên máy chủ đến cấu hình máy chủ     |
+
+### Cấu hình Discovery (`discovery`)
+
+| Cấu hình             | Kiểu | Mặc định | Mô tả                                                                                                                            |
+|----------------------|------|----------|-----------------------------------------------------------------------------------------------------------------------------------|
+| `enabled`            | bool | false    | Nếu true, các công cụ MCP bị ẩn và được tải theo yêu cầu qua tìm kiếm. Nếu false, tất cả công cụ được tải                      |
+| `ttl`                | int  | 5        | Số lượt hội thoại mà một công cụ đã khám phá vẫn được mở khóa                                                                   |
+| `max_search_results` | int  | 5        | Số công cụ tối đa được trả về cho mỗi truy vấn tìm kiếm                                                                         |
+| `use_bm25`           | bool | true     | Bật công cụ tìm kiếm ngôn ngữ tự nhiên/từ khóa (`tool_search_tool_bm25`). **Cảnh báo**: tiêu tốn nhiều tài nguyên hơn tìm kiếm regex |
+| `use_regex`          | bool | false    | Bật công cụ tìm kiếm mẫu regex (`tool_search_tool_regex`)                                                                        |
+
+> **Lưu ý:** Nếu `discovery.enabled` là `true`, bạn **phải** bật ít nhất một công cụ tìm kiếm (`use_bm25` hoặc `use_regex`),
+> nếu không ứng dụng sẽ không khởi động được.
+
+### Cấu hình từng máy chủ
+
+| Cấu hình   | Kiểu   | Bắt buộc | Mô tả                                     |
+|------------|--------|----------|--------------------------------------------|
+| `enabled`  | bool   | có       | Bật máy chủ MCP này                       |
+| `type`     | string | không    | Loại truyền tải: `stdio`, `sse`, `http`   |
+| `command`  | string | stdio    | Lệnh thực thi cho truyền tải stdio        |
+| `args`     | array  | không    | Đối số lệnh cho truyền tải stdio          |
+| `env`      | object | không    | Biến môi trường cho tiến trình stdio      |
+| `env_file` | string | không    | Đường dẫn đến tệp môi trường cho tiến trình stdio |
+| `url`      | string | sse/http | URL endpoint cho truyền tải `sse`/`http`  |
+| `headers`  | object | không    | Header HTTP cho truyền tải `sse`/`http`   |
+
+### Hành vi truyền tải
+
+- Nếu bỏ qua `type`, truyền tải được tự động phát hiện:
+    - `url` được đặt → `sse`
+    - `command` được đặt → `stdio`
+- `http` và `sse` đều sử dụng `url` + `headers` tùy chọn.
+- `env` và `env_file` chỉ được áp dụng cho máy chủ `stdio`.
+
+### Ví dụ cấu hình
+
+#### 1) Máy chủ MCP Stdio
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-filesystem",
+            "/tmp"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+#### 2) Máy chủ MCP từ xa SSE/HTTP
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "remote-mcp": {
+          "enabled": true,
+          "type": "sse",
+          "url": "https://example.com/mcp",
+          "headers": {
+            "Authorization": "Bearer YOUR_TOKEN"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### 3) Thiết lập MCP quy mô lớn với khám phá công cụ được bật
+
+*Trong ví dụ này, LLM chỉ thấy `tool_search_tool_bm25`. Nó sẽ tìm kiếm và mở khóa động các công cụ Github hoặc Postgres chỉ khi được người dùng yêu cầu.*
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "discovery": {
+        "enabled": true,
+        "ttl": 5,
+        "max_search_results": 5,
+        "use_bm25": true,
+        "use_regex": false
+      },
+      "servers": {
+        "github": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-github"
+          ],
+          "env": {
+            "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
+          }
+        },
+        "postgres": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-postgres",
+            "postgresql://user:password@localhost/dbname"
+          ]
+        },
+        "slack": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-slack"
+          ],
+          "env": {
+            "SLACK_BOT_TOKEN": "YOUR_SLACK_BOT_TOKEN",
+            "SLACK_TEAM_ID": "YOUR_SLACK_TEAM_ID"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Công cụ Skills
+
+Công cụ skills cấu hình khám phá và cài đặt kỹ năng thông qua các registry như ClawHub.
+
+### Registry
+
+| Cấu hình                          | Kiểu   | Mặc định             | Mô tả                                       |
+|------------------------------------|--------|-----------------------|----------------------------------------------|
+| `registries.clawhub.enabled`       | bool   | true                  | Bật registry ClawHub                         |
+| `registries.clawhub.base_url`      | string | `https://clawhub.ai`  | URL cơ sở ClawHub                            |
+| `registries.clawhub.auth_token`    | string | `""`                  | Token Bearer tùy chọn để có giới hạn tốc độ cao hơn |
+| `registries.clawhub.search_path`   | string | `/api/v1/search`      | Đường dẫn API tìm kiếm                      |
+| `registries.clawhub.skills_path`   | string | `/api/v1/skills`      | Đường dẫn API Skills                         |
+| `registries.clawhub.download_path` | string | `/api/v1/download`    | Đường dẫn API tải xuống                      |
+
+### Ví dụ cấu hình
+
+```json
+{
+  "tools": {
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "enabled": true,
+          "base_url": "https://clawhub.ai",
+          "auth_token": "",
+          "search_path": "/api/v1/search",
+          "skills_path": "/api/v1/skills",
+          "download_path": "/api/v1/download"
+        }
+      }
+    }
+  }
+}
+```
+
+## Biến môi trường
+
+Tất cả các tùy chọn cấu hình có thể được ghi đè qua biến môi trường với định dạng `PICOCLAW_TOOLS_<SECTION>_<KEY>`:
+
+Ví dụ:
+
+- `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
+- `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
+- `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
+- `PICOCLAW_TOOLS_MCP_ENABLED=true`
+
+Lưu ý: Cấu hình kiểu map lồng nhau (ví dụ `tools.mcp.servers.<name>.*`) được cấu hình trong `config.json` thay vì qua biến môi trường.
diff --git a/docs/vi/troubleshooting.md b/docs/vi/troubleshooting.md
new file mode 100644
index 000000000..961c932aa
--- /dev/null
+++ b/docs/vi/troubleshooting.md
@@ -0,0 +1,45 @@
+# 🐛 Khắc Phục Sự Cố
+
+> Quay lại [README](../../README.vi.md)
+
+## "model ... not found in model_list" hoặc OpenRouter "free is not a valid model ID"
+
+**Triệu chứng:** Bạn thấy một trong các lỗi sau:
+
+- `Error creating provider: model "openrouter/free" not found in model_list`
+- OpenRouter trả về 400: `"free is not a valid model ID"`
+
+**Nguyên nhân:** Trường `model` trong mục `model_list` của bạn là giá trị được gửi đến API. Đối với OpenRouter, bạn phải sử dụng ID mô hình **đầy đủ**, không phải dạng viết tắt.
+
+- **Sai:** `"model": "free"` → OpenRouter nhận được `free` và từ chối.
+- **Đúng:** `"model": "openrouter/free"` → OpenRouter nhận được `openrouter/free` (định tuyến tự động tầng miễn phí).
+
+**Cách sửa:** Trong `~/.picoclaw/config.json` (hoặc đường dẫn cấu hình của bạn):
+
+1. **agents.defaults.model_name** phải khớp với một `model_name` trong `model_list` (ví dụ: `"openrouter-free"`).
+2. **model** của mục đó phải là ID mô hình OpenRouter hợp lệ, ví dụ:
+   - `"openrouter/free"` – tầng miễn phí tự động
+   - `"google/gemini-2.0-flash-exp:free"`
+   - `"meta-llama/llama-3.1-8b-instruct:free"`
+
+Ví dụ:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "openrouter-free"
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "openrouter-free",
+      "model": "openrouter/free",
+      "api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
+      "api_base": "https://openrouter.ai/api/v1"
+    }
+  ]
+}
+```
+
+Lấy khóa của bạn tại [OpenRouter Keys](https://openrouter.ai/keys).
diff --git a/docs/wecom-app-configuration.md b/docs/wecom-app-configuration.md
deleted file mode 100644
index 3c720ecd1..000000000
--- a/docs/wecom-app-configuration.md
+++ /dev/null
@@ -1,115 +0,0 @@
-# 企业微信自建应用 (WeCom App) 配置指南
-
-本文档介绍如何在 PicoClaw 中配置企业微信自建应用 (wecom-app) 通道。
-
-## 功能特性
-
-| 功能 | 支持状态 |
-|------|---------|
-| 被动接收消息 | ✅ |
-| 主动发送消息 | ✅ |
-| 私聊 | ✅ |
-| 群聊 | ❌ |
-
-## 配置步骤
-
-### 1. 企业微信后台配置
-
-1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin)
-2. 进入"应用管理" → 选择自建应用
-3. 记录以下信息：
-   - **AgentId**: 应用详情页显示
-   - **Secret**: 点击"查看"获取
-4. 进入"我的企业"页面，记录 **企业ID** (CorpID)
-
-### 2. 接收消息配置
-
-1. 在应用详情页，点击"接收消息"的"设置API接收"
-2. 填写以下信息：
-   - **URL**: `http://your-server:18790/webhook/wecom-app`
-   - **Token**: 随机生成或自定义（用于签名验证）
-   - **EncodingAESKey**: 点击"随机生成"生成43字符的密钥
-3. 点击"保存"时，企业微信会发送验证请求
-
-### 3. PicoClaw 配置
-
-在 `config.json` 中添加以下配置：
-
-```json
-{
-  "channels": {
-    "wecom_app": {
-      "enabled": true,
-      "corp_id": "wwxxxxxxxxxxxxxxxx",           // 企业ID
-      "corp_secret": "xxxxxxxxxxxxxxxxxxxxxxxx", // 应用Secret
-      "agent_id": 1000002,                        // 应用AgentId
-      "token": "your_token",                      // 接收消息配置的Token
-      "encoding_aes_key": "your_encoding_aes_key", // 接收消息配置的EncodingAESKey
-      "webhook_path": "/webhook/wecom-app",
-      "allow_from": [],
-      "reply_timeout": 5
-    }
-  }
-}
-```
-
-## 常见问题
-
-### 1. 回调URL验证失败
-
-**症状**: 企业微信保存API接收消息时提示验证失败
-
-**检查项**:
-- 确认服务器防火墙已开放 Gateway 端口（默认 18790）
-- 确认 `corp_id`、`token`、`encoding_aes_key` 配置正确
-- 查看 PicoClaw 日志是否有请求到达
-
-### 2. 中文消息解密失败
-
-**症状**: 发送中文消息时出现 `invalid padding size` 错误
-
-**原因**: 企业微信使用非标准的 PKCS7 填充（32字节块大小）
-
-**解决**: 确保使用最新版本的 PicoClaw，已修复此问题。
-
-### 3. 端口冲突
-
-**症状**: 启动时提示端口已被占用
-
-**解决**: 修改 `gateway.port` 为其他端口（所有 Webhook 渠道共享同一个 Gateway HTTP 服务器）
-
-## 技术细节
-
-### 加密算法
-
-- **算法**: AES-256-CBC
-- **密钥**: EncodingAESKey Base64解码后的32字节
-- **IV**: AESKey的前16字节
-- **填充**: PKCS7（块大小为32字节，非标准16字节）
-- **消息格式**: XML
-
-### 消息结构
-
-解密后的消息格式：
-```
-random(16B) + msg_len(4B) + msg + receiveid
-```
-
-其中 `receiveid` 对于自建应用是 `corp_id`。
-
-## 调试
-
-启用调试模式查看详细日志：
-
-```bash
-picoclaw gateway --debug
-```
-
-关键日志标识：
-- `wecom_app`: WeCom App 通道相关日志
-- `wecom_common`: 加密解密相关日志
-
-## 参考文档
-
-- [企业微信官方文档 - 接收消息](https://developer.work.weixin.qq.com/document/path/96211)
-- [企业微信官方加解密库](https://github.com/sbzhu/weworkapi_golang)
diff --git a/docs/zh/ANTIGRAVITY_AUTH.md b/docs/zh/ANTIGRAVITY_AUTH.md
new file mode 100644
index 000000000..db7c81dea
--- /dev/null
+++ b/docs/zh/ANTIGRAVITY_AUTH.md
@@ -0,0 +1,809 @@
+> 返回 [README](../../README.zh.md)
+
+# Antigravity 认证与集成指南
+
+## 概述
+
+**Antigravity**（Google Cloud Code Assist）是由 Google 支持的 AI 模型提供商，通过 Google 的云基础设施提供对 Claude Opus 4.6 和 Gemini 等模型的访问。本文档提供了关于认证工作原理、如何获取模型以及如何在 PicoClaw 中实现新提供商的完整指南。
+
+---
+
+## 目录
+
+1. [认证流程](#认证流程)
+2. [OAuth 实现细节](#oauth-实现细节)
+3. [令牌管理](#令牌管理)
+4. [模型列表获取](#模型列表获取)
+5. [用量追踪](#用量追踪)
+6. [提供商插件结构](#提供商插件结构)
+7. [集成要求](#集成要求)
+8. [API 端点](#api-端点)
+9. [配置](#配置)
+10. [在 PicoClaw 中创建新提供商](#在-picoclaw-中创建新提供商)
+
+---
+
+## 认证流程
+
+### 1. 带 PKCE 的 OAuth 2.0
+
+Antigravity 使用 **OAuth 2.0 with PKCE（Proof Key for Code Exchange）** 进行安全认证：
+
+```
+┌─────────────┐                                    ┌─────────────────┐
+│   Client    │ ───(1) Generate PKCE Pair────────> │                 │
+│             │ ───(2) Open Auth URL─────────────> │  Google OAuth   │
+│             │                                    │    Server       │
+│             │ <──(3) Redirect with Code───────── │                 │
+│             │                                    └─────────────────┘
+│             │ ───(4) Exchange Code for Tokens──> │   Token URL     │
+│             │                                    │                 │
+│             │ <──(5) Access + Refresh Tokens──── │                 │
+└─────────────┘                                    └─────────────────┘
+```
+
+### 2. 详细步骤
+
+#### 步骤 1：生成 PKCE 参数
+```typescript
+function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = randomBytes(32).toString("hex");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+}
+```
+
+#### 步骤 2：构建授权 URL
+```typescript
+const AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+const REDIRECT_URI = "http://localhost:51121/oauth-callback";
+
+function buildAuthUrl(params: { challenge: string; state: string }): string {
+  const url = new URL(AUTH_URL);
+  url.searchParams.set("client_id", CLIENT_ID);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("redirect_uri", REDIRECT_URI);
+  url.searchParams.set("scope", SCOPES.join(" "));
+  url.searchParams.set("code_challenge", params.challenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  url.searchParams.set("state", params.state);
+  url.searchParams.set("access_type", "offline");
+  url.searchParams.set("prompt", "consent");
+  return url.toString();
+}
+```
+
+**所需权限范围：**
+```typescript
+const SCOPES = [
+  "https://www.googleapis.com/auth/cloud-platform",
+  "https://www.googleapis.com/auth/userinfo.email",
+  "https://www.googleapis.com/auth/userinfo.profile",
+  "https://www.googleapis.com/auth/cclog",
+  "https://www.googleapis.com/auth/experimentsandconfigs",
+];
+```
+
+#### 步骤 3：处理 OAuth 回调
+
+**自动模式（本地开发）：**
+- 在端口 51121 上启动本地 HTTP 服务器
+- 等待来自 Google 的重定向
+- 从查询参数中提取授权码
+
+**手动模式（远程/无头环境）：**
+- 向用户显示授权 URL
+- 用户在浏览器中完成认证
+- 用户将完整的重定向 URL 粘贴回终端
+- 从粘贴的 URL 中解析授权码
+
+#### 步骤 4：用授权码交换令牌
+```typescript
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+
+async function exchangeCode(params: {
+  code: string;
+  verifier: string;
+}): Promise<{ access: string; refresh: string; expires: number }> {
+  const response = await fetch(TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      client_id: CLIENT_ID,
+      client_secret: CLIENT_SECRET,
+      code: params.code,
+      grant_type: "authorization_code",
+      redirect_uri: REDIRECT_URI,
+      code_verifier: params.verifier,
+    }),
+  });
+
+  const data = await response.json();
+  
+  return {
+    access: data.access_token,
+    refresh: data.refresh_token,
+    expires: Date.now() + data.expires_in * 1000 - 5 * 60 * 1000, // 5 min buffer
+  };
+}
+```
+
+#### 步骤 5：获取额外的用户数据
+
+**用户邮箱：**
+```typescript
+async function fetchUserEmail(accessToken: string): Promise<string | undefined> {
+  const response = await fetch(
+    "https://www.googleapis.com/oauth2/v1/userinfo?alt=json",
+    { headers: { Authorization: `Bearer ${accessToken}` } }
+  );
+  const data = await response.json();
+  return data.email;
+}
+```
+
+**项目 ID（API 调用必需）：**
+```typescript
+async function fetchProjectId(accessToken: string): Promise<string> {
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "google-api-nodejs-client/9.15.1",
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+    "Client-Metadata": JSON.stringify({
+      ideType: "IDE_UNSPECIFIED",
+      platform: "PLATFORM_UNSPECIFIED",
+      pluginType: "GEMINI",
+    }),
+  };
+
+  const response = await fetch(
+    "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        metadata: {
+          ideType: "IDE_UNSPECIFIED",
+          platform: "PLATFORM_UNSPECIFIED",
+          pluginType: "GEMINI",
+        },
+      }),
+    }
+  );
+
+  const data = await response.json();
+  return data.cloudaicompanionProject || "rising-fact-p41fc"; // 默认回退值
+}
+```
+
+---
+
+## OAuth 实现细节
+
+### 客户端凭据
+
+**重要：** 这些凭据在源代码中以 base64 编码存储，用于与 pi-ai 同步：
+
+```typescript
+const decode = (s: string) => Buffer.from(s, "base64").toString();
+
+const CLIENT_ID = decode(
+  "MTA3MTAwNjA2MDU5MS10bWhzc2luMmgyMWxjcmUyMzV2dG9sb2poNGc0MDNlcC5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbQ=="
+);
+const CLIENT_SECRET = decode("R09DU1BYLUs1OEZXUjQ4NkxkTEoxbUxCOHNYQzR6NnFEQWY=");
+```
+
+### OAuth 流程模式
+
+1. **自动流程**（有浏览器的本地机器）：
+   - 自动打开浏览器
+   - 本地回调服务器捕获重定向
+   - 初始认证后无需用户交互
+
+2. **手动流程**（远程/无头/WSL2 环境）：
+   - 显示 URL 供手动复制粘贴
+   - 用户在外部浏览器中完成认证
+   - 用户将完整的重定向 URL 粘贴回来
+
+```typescript
+function shouldUseManualOAuthFlow(isRemote: boolean): boolean {
+  return isRemote || isWSL2Sync();
+}
+```
+
+---
+
+## 令牌管理
+
+### 认证配置文件结构
+
+```typescript
+type OAuthCredential = {
+  type: "oauth";
+  provider: "google-antigravity";
+  access: string;           // 访问令牌
+  refresh: string;          // 刷新令牌
+  expires: number;          // 过期时间戳（毫秒，自 epoch 起）
+  email?: string;           // 用户邮箱
+  projectId?: string;       // Google Cloud 项目 ID
+};
+```
+
+### 令牌刷新
+
+凭据包含一个刷新令牌，可在当前访问令牌过期时用于获取新的访问令牌。过期时间设置了 5 分钟的缓冲区以防止竞态条件。
+
+---
+
+## 模型列表获取
+
+### 获取可用模型
+
+```typescript
+const BASE_URL = "https://cloudcode-pa.googleapis.com";
+
+async function fetchAvailableModels(
+  accessToken: string,
+  projectId: string
+): Promise<Model[]> {
+  const headers = {
+    Authorization: `Bearer ${accessToken}`,
+    "Content-Type": "application/json",
+    "User-Agent": "antigravity",
+    "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+  };
+
+  const response = await fetch(
+    `${BASE_URL}/v1internal:fetchAvailableModels`,
+    {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ project: projectId }),
+    }
+  );
+
+  const data = await response.json();
+  
+  // 返回带有配额信息的模型
+  return Object.entries(data.models).map(([modelId, modelInfo]) => ({
+    id: modelId,
+    displayName: modelInfo.displayName,
+    quotaInfo: {
+      remainingFraction: modelInfo.quotaInfo?.remainingFraction,
+      resetTime: modelInfo.quotaInfo?.resetTime,
+      isExhausted: modelInfo.quotaInfo?.isExhausted,
+    },
+  }));
+}
+```
+
+### 响应格式
+
+```typescript
+type FetchAvailableModelsResponse = {
+  models?: Record<string, {
+    displayName?: string;
+    quotaInfo?: {
+      remainingFraction?: number | string;
+      resetTime?: string;      // ISO 8601 时间戳
+      isExhausted?: boolean;
+    };
+  }>;
+};
+```
+
+---
+
+## 用量追踪
+
+### 获取用量数据
+
+```typescript
+export async function fetchAntigravityUsage(
+  token: string,
+  timeoutMs: number
+): Promise<ProviderUsageSnapshot> {
+  // 1. 获取额度和计划信息
+  const loadCodeAssistRes = await fetch(
+    `${BASE_URL}/v1internal:loadCodeAssist`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        metadata: {
+          ideType: "ANTIGRAVITY",
+          platform: "PLATFORM_UNSPECIFIED",
+          pluginType: "GEMINI",
+        },
+      }),
+    }
+  );
+
+  // 提取额度信息
+  const { availablePromptCredits, planInfo, currentTier } = data;
+  
+  // 2. 获取模型配额
+  const modelsRes = await fetch(
+    `${BASE_URL}/v1internal:fetchAvailableModels`,
+    {
+      method: "POST",
+      headers: { Authorization: `Bearer ${token}` },
+      body: JSON.stringify({ project: projectId }),
+    }
+  );
+
+  // 构建用量窗口
+  return {
+    provider: "google-antigravity",
+    displayName: "Google Antigravity",
+    windows: [
+      { label: "Credits", usedPercent: calculateUsedPercent(available, monthly) },
+      // 各模型配额...
+    ],
+    plan: currentTier?.name || planType,
+  };
+}
+```
+
+### 用量响应结构
+
+```typescript
+type ProviderUsageSnapshot = {
+  provider: "google-antigravity";
+  displayName: string;
+  windows: UsageWindow[];
+  plan?: string;
+  error?: string;
+};
+
+type UsageWindow = {
+  label: string;           // "Credits" 或模型 ID
+  usedPercent: number;     // 0-100
+  resetAt?: number;        // 配额重置的时间戳
+};
+```
+
+---
+
+## 提供商插件结构
+
+### 插件定义
+
+```typescript
+const antigravityPlugin = {
+  id: "google-antigravity-auth",
+  name: "Google Antigravity Auth",
+  description: "OAuth flow for Google Antigravity (Cloud Code Assist)",
+  configSchema: emptyPluginConfigSchema(),
+  
+  register(api: PicoClawPluginApi) {
+    api.registerProvider({
+      id: "google-antigravity",
+      label: "Google Antigravity",
+      docsPath: "/providers/models",
+      aliases: ["antigravity"],
+      
+      auth: [
+        {
+          id: "oauth",
+          label: "Google OAuth",
+          hint: "PKCE + localhost callback",
+          kind: "oauth",
+          run: async (ctx: ProviderAuthContext) => {
+            // OAuth 实现在此处
+          },
+        },
+      ],
+    });
+  },
+};
+```
+
+### ProviderAuthContext
+
+```typescript
+type ProviderAuthContext = {
+  config: PicoClawConfig;
+  agentDir?: string;
+  workspaceDir?: string;
+  prompter: WizardPrompter;      // UI 提示/通知
+  runtime: RuntimeEnv;           // 日志等
+  isRemote: boolean;             // 是否在远程运行
+  openUrl: (url: string) => Promise<void>;  // 浏览器打开器
+  oauth: {
+    createVpsAwareHandlers: Function;
+  };
+};
+```
+
+### ProviderAuthResult
+
+```typescript
+type ProviderAuthResult = {
+  profiles: Array<{
+    profileId: string;
+    credential: AuthProfileCredential;
+  }>;
+  configPatch?: Partial<PicoClawConfig>;
+  defaultModel?: string;
+  notes?: string[];
+};
+```
+
+---
+
+## 集成要求
+
+### 1. 所需环境/依赖
+
+- Go ≥ 1.25
+- PicoClaw 代码库（`pkg/providers/` 和 `pkg/auth/`）
+- `crypto` 和 `net/http` 标准库包
+
+### 2. API 调用所需的请求头
+
+```typescript
+const REQUIRED_HEADERS = {
+  "Authorization": `Bearer ${accessToken}`,
+  "Content-Type": "application/json",
+  "User-Agent": "antigravity",  // 或 "google-api-nodejs-client/9.15.1"
+  "X-Goog-Api-Client": "google-cloud-sdk vscode_cloudshelleditor/0.1",
+};
+
+// 对于 loadCodeAssist 调用，还需包含：
+const CLIENT_METADATA = {
+  ideType: "ANTIGRAVITY",  // 或 "IDE_UNSPECIFIED"
+  platform: "PLATFORM_UNSPECIFIED",
+  pluginType: "GEMINI",
+};
+```
+
+### 3. 模型 Schema 清理
+
+Antigravity 使用兼容 Gemini 的模型，因此工具 schema 必须进行清理：
+
+```typescript
+const GOOGLE_SCHEMA_UNSUPPORTED_KEYWORDS = new Set([
+  "patternProperties",
+  "additionalProperties",
+  "$schema",
+  "$id",
+  "$ref",
+  "$defs",
+  "definitions",
+  "examples",
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+  "multipleOf",
+  "pattern",
+  "format",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minProperties",
+  "maxProperties",
+]);
+
+// 发送前清理 schema
+function cleanToolSchemaForGemini(schema: Record<string, unknown>): unknown {
+  // 移除不支持的关键字
+  // 确保顶层有 type: "object"
+  // 展平 anyOf/oneOf 联合类型
+}
+```
+
+### 4. 思维块处理（Claude 模型）
+
+对于 Antigravity 的 Claude 模型，思维块需要特殊处理：
+
+```typescript
+const ANTIGRAVITY_SIGNATURE_RE = /^[A-Za-z0-9+/]+={0,2}$/;
+
+export function sanitizeAntigravityThinkingBlocks(
+  messages: AgentMessage[]
+): AgentMessage[] {
+  // 验证思维签名
+  // 规范化签名字段
+  // 丢弃未签名的思维块
+}
+```
+
+---
+
+## API 端点
+
+### 认证端点
+
+| 端点 | 方法 | 用途 |
+|------|------|------|
+| `https://accounts.google.com/o/oauth2/v2/auth` | GET | OAuth 授权 |
+| `https://oauth2.googleapis.com/token` | POST | 令牌交换 |
+| `https://www.googleapis.com/oauth2/v1/userinfo` | GET | 用户信息（邮箱） |
+
+### Cloud Code Assist 端点
+
+| 端点 | 方法 | 用途 |
+|------|------|------|
+| `https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist` | POST | 加载项目信息、额度、计划 |
+| `https://cloudcode-pa.googleapis.com/v1internal:fetchAvailableModels` | POST | 列出可用模型及配额 |
+| `https://cloudcode-pa.googleapis.com/v1internal:streamGenerateContent?alt=sse` | POST | 聊天流式端点 |
+
+**API 请求格式（聊天）：**
+`v1internal:streamGenerateContent` 端点期望一个包装标准 Gemini 请求的信封格式：
+
+```json
+{
+  "project": "your-project-id",
+  "model": "model-id",
+  "request": {
+    "contents": [...],
+    "systemInstruction": {...},
+    "generationConfig": {...},
+    "tools": [...]
+  },
+  "requestType": "agent",
+  "userAgent": "antigravity",
+  "requestId": "agent-timestamp-random"
+}
+```
+
+**API 响应格式（SSE）：**
+每条 SSE 消息（`data: {...}`）被包装在 `response` 字段中：
+
+```json
+{
+  "response": {
+    "candidates": [...],
+    "usageMetadata": {...},
+    "modelVersion": "...",
+    "responseId": "..."
+  },
+  "traceId": "...",
+  "metadata": {}
+}
+```
+
+---
+
+## 配置
+
+### config.json 配置
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gemini-flash",
+      "model": "antigravity/gemini-3-flash",
+      "auth_method": "oauth"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "gemini-flash"
+    }
+  }
+}
+```
+
+### 认证配置文件存储
+
+认证配置文件存储在 `~/.picoclaw/auth.json` 中：
+
+```json
+{
+  "credentials": {
+    "google-antigravity": {
+      "access_token": "ya29...",
+      "refresh_token": "1//...",
+      "expires_at": "2026-01-01T00:00:00Z",
+      "provider": "google-antigravity",
+      "auth_method": "oauth",
+      "email": "user@example.com",
+      "project_id": "my-project-id"
+    }
+  }
+}
+```
+
+---
+
+## 在 PicoClaw 中创建新提供商
+
+PicoClaw 提供商以 Go 包的形式实现，位于 `pkg/providers/` 下。要添加新提供商：
+
+### 分步实现
+
+#### 1. 创建提供商文件
+
+在 `pkg/providers/` 中创建新的 Go 文件：
+
+```
+pkg/providers/
+└── your_provider.go
+```
+
+#### 2. 实现 Provider 接口
+
+你的提供商必须实现 `pkg/providers/types.go` 中定义的 `Provider` 接口：
+
+```go
+package providers
+
+type YourProvider struct {
+    apiKey  string
+    apiBase string
+}
+
+func NewYourProvider(apiKey, apiBase, proxy string) *YourProvider {
+    if apiBase == "" {
+        apiBase = "https://api.your-provider.com/v1"
+    }
+    return &YourProvider{apiKey: apiKey, apiBase: apiBase}
+}
+
+func (p *YourProvider) Chat(ctx context.Context, messages []Message, tools []Tool, cb StreamCallback) error {
+    // 实现带流式传输的聊天补全
+}
+```
+
+#### 3. 在工厂中注册
+
+将你的提供商添加到 `pkg/providers/factory.go` 中的协议分支：
+
+```go
+case "your-provider":
+    return NewYourProvider(sel.apiKey, sel.apiBase, sel.proxy), nil
+```
+
+#### 4. 添加默认配置（可选）
+
+在 `pkg/config/defaults.go` 中添加默认条目：
+
+```go
+{
+    ModelName: "your-model",
+    Model:     "your-provider/model-name",
+    APIKey:    "",
+},
+```
+
+#### 5. 添加认证支持（可选）
+
+如果你的提供商需要 OAuth 或特殊认证，在 `cmd/picoclaw/internal/auth/helpers.go` 中添加分支：
+
+```go
+case "your-provider":
+    authLoginYourProvider()
+```
+
+#### 6. 通过 `config.json` 配置
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "your-model",
+      "model": "your-provider/model-name",
+      "api_key": "your-api-key",
+      "api_base": "https://api.your-provider.com/v1"
+    }
+  ]
+}
+```
+
+---
+
+## 测试你的实现
+
+### CLI 命令
+
+```bash
+# 使用提供商进行认证
+picoclaw auth login --provider your-provider
+
+# 列出模型（用于 Antigravity）
+picoclaw auth models
+
+# 启动网关
+picoclaw gateway
+
+# 使用指定模型运行代理
+picoclaw agent -m "Hello" --model your-model
+```
+
+### 测试用环境变量
+
+```bash
+# 覆盖默认模型
+export PICOCLAW_AGENTS_DEFAULTS_MODEL=your-model
+
+# 覆盖提供商设置
+export PICOCLAW_MODEL_LIST='[{"model_name":"your-model","model":"your-provider/model-name","api_key":"..."}]'
+```
+
+---
+
+## 参考资料
+
+- **源文件：**
+  - `pkg/providers/antigravity_provider.go` - Antigravity 提供商实现
+  - `pkg/auth/oauth.go` - OAuth 流程实现
+  - `pkg/auth/store.go` - 认证凭据存储（`~/.picoclaw/auth.json`）
+  - `pkg/providers/factory.go` - 提供商工厂和协议路由
+  - `pkg/providers/types.go` - 提供商接口定义
+  - `cmd/picoclaw/internal/auth/helpers.go` - 认证 CLI 命令
+
+- **文档：**
+  - `docs/ANTIGRAVITY_USAGE.md` - Antigravity 使用指南
+  - `docs/migration/model-list-migration.md` - 迁移指南
+
+---
+
+## 注意事项
+
+1. **Google Cloud 项目：** Antigravity 要求在你的 Google Cloud 项目上启用 Gemini for Google Cloud
+2. **配额：** 使用 Google Cloud 项目配额（非独立计费）
+3. **模型访问：** 可用模型取决于你的 Google Cloud 项目配置
+4. **思维块：** 通过 Antigravity 使用的 Claude 模型需要对带签名的思维块进行特殊处理
+5. **Schema 清理：** 工具 schema 必须清理以移除不支持的 JSON Schema 关键字
+
+---
+
+---
+
+## 常见错误处理
+
+### 1. 速率限制（HTTP 429）
+
+当项目/模型配额耗尽时，Antigravity 会返回 429 错误。错误响应通常在 `details` 字段中包含 `quotaResetDelay`。
+
+**429 错误示例：**
+```json
+{
+  "error": {
+    "code": 429,
+    "message": "You have exhausted your capacity on this model. Your quota will reset after 4h30m28s.",
+    "status": "RESOURCE_EXHAUSTED",
+    "details": [
+      {
+        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
+        "metadata": {
+          "quotaResetDelay": "4h30m28.060903746s"
+        }
+      }
+    ]
+  }
+}
+```
+
+### 2. 空响应（受限模型）
+
+某些模型可能出现在可用模型列表中，但返回空响应（200 OK 但 SSE 流为空）。这通常发生在当前项目没有权限使用的预览版或受限模型上。
+
+**处理方式：** 将空响应视为错误，通知用户该模型可能对其项目受限或无效。
+
+---
+
+## 故障排除
+
+### "Token expired"（令牌已过期）
+- 刷新 OAuth 令牌：`picoclaw auth login --provider antigravity`
+
+### "Gemini for Google Cloud is not enabled"（Gemini for Google Cloud 未启用）
+- 在 Google Cloud Console 中启用该 API
+
+### "Project not found"（项目未找到）
+- 确保你的 Google Cloud 项目已启用必要的 API
+- 检查认证过程中项目 ID 是否正确获取
+
+### 模型未出现在列表中
+- 验证 OAuth 认证是否成功完成
+- 检查认证配置文件存储：`~/.picoclaw/auth.json`
+- 重新运行 `picoclaw auth login --provider antigravity`
diff --git a/docs/zh/ANTIGRAVITY_USAGE.md b/docs/zh/ANTIGRAVITY_USAGE.md
new file mode 100644
index 000000000..2218618a9
--- /dev/null
+++ b/docs/zh/ANTIGRAVITY_USAGE.md
@@ -0,0 +1,72 @@
+> 返回 [README](../../README.zh.md)
+
+# 在 PicoClaw 中使用 Antigravity 提供商
+
+本指南介绍如何在 PicoClaw 中设置和使用 **Antigravity**（Google Cloud Code Assist）提供商。
+
+## 前提条件
+
+1.  一个 Google 账户。
+2.  已启用 Google Cloud Code Assist（通常通过"Gemini for Google Cloud"引导流程获取）。
+
+## 1. 身份验证
+
+要使用 Antigravity 进行身份验证，请运行以下命令：
+
+```bash
+picoclaw auth login --provider antigravity
+```
+
+### 手动验证（无界面/VPS 环境）
+如果你在服务器（Coolify/Docker）上运行且无法访问 `localhost`，请按照以下步骤操作：
+1.  运行上述命令。
+2.  复制提供的 URL 并在本地浏览器中打开。
+3.  完成登录。
+4.  浏览器将重定向到 `localhost:51121` URL（页面将无法加载）。
+5.  **从浏览器地址栏复制该最终 URL**。
+6.  **将其粘贴回 PicoClaw 正在等待的终端中**。
+
+PicoClaw 将自动提取授权码并完成流程。
+
+## 2. 管理模型
+
+### 列出可用模型
+查看你的项目可以访问哪些模型并检查其配额：
+
+```bash
+picoclaw auth models
+```
+
+### 切换模型
+你可以在 `~/.picoclaw/config.json` 中更改默认模型，或通过 CLI 覆盖：
+
+```bash
+# 为单个命令覆盖
+picoclaw agent -m "Hello" --model claude-opus-4-6-thinking
+```
+
+## 3. 实际使用（Coolify/Docker）
+
+如果你通过 Coolify 或 Docker 部署，请按照以下步骤进行测试：
+
+1.  **环境变量**：
+    *   `PICOCLAW_AGENTS_DEFAULTS_MODEL=gemini-flash`
+2.  **身份验证持久化**：
+    如果你已在本地登录，可以将凭据复制到服务器：
+    ```bash
+    scp ~/.picoclaw/auth.json user@your-server:~/.picoclaw/
+    ```
+    *或者*，如果你有终端访问权限，可以在服务器上运行一次 `auth login` 命令。
+
+## 4. 故障排除
+
+*   **空响应**：如果模型返回空回复，可能是该模型在你的项目中受到限制。请尝试 `gemini-3-flash` 或 `claude-opus-4-6-thinking`。
+*   **429 速率限制**：Antigravity 有严格的配额限制。如果触发限制，PicoClaw 将在错误消息中显示"重置时间"。
+*   **404 未找到**：确保你使用的是 `picoclaw auth models` 列表中的模型 ID。请使用短 ID（例如 `gemini-3-flash`），而非完整路径。
+
+## 5. 可用模型总结
+
+根据测试，以下模型最为可靠：
+*   `gemini-3-flash`（快速，高可用性）
+*   `gemini-2.5-flash-lite`（轻量级）
+*   `claude-opus-4-6-thinking`（强大，包含推理能力）
diff --git a/docs/zh/chat-apps.md b/docs/zh/chat-apps.md
new file mode 100644
index 000000000..47add38ac
--- /dev/null
+++ b/docs/zh/chat-apps.md
@@ -0,0 +1,597 @@
+# 💬 聊天应用配置
+
+> 返回 [README](../../README.zh.md)
+
+## 💬 聊天应用集成 (Chat Apps)
+
+PicoClaw 支持多种聊天平台，使您的 Agent 能够连接到任何地方。
+
+> **注意**: 依赖 HTTP 回调的渠道共用同一个 Gateway HTTP 服务器（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`），无需为每个渠道单独配置端口。飞书、钉钉、企业微信这类 Socket/Stream 模式渠道不依赖共享 webhook 服务器来接收入站消息。
+
+### 核心渠道
+
+| 渠道                 | 设置难度    | 特性说明                                  | 文档链接                                                                                                        |
+| -------------------- | ----------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **Telegram**         | ⭐ 简单     | 推荐，支持语音转文字，长轮询无需公网      | [查看文档](../channels/telegram/README.zh.md)                                                                 |
+| **Discord**          | ⭐ 简单     | Socket Mode，支持群组/私信，Bot 生态成熟  | [查看文档](../channels/discord/README.zh.md)                                                                  |
+| **WhatsApp**         | ⭐ 简单     | 原生 (QR 扫码) 或 Bridge URL              | [查看文档](#whatsapp)                                                                 |
+| **微信 (Weixin)**    | ⭐ 简单     | 原生扫码（腾讯 iLink API）                | [查看文档](#weixin)                                                                   |
+| **Slack**            | ⭐ 简单     | **Socket Mode** (无需公网 IP)，企业级支持 | [查看文档](../channels/slack/README.zh.md)                                                                    |
+| **Matrix**           | ⭐⭐ 中等   | 联邦协议，支持自建 homeserver 与公开服务器 | [查看文档](../channels/matrix/README.zh.md)                                                                  |
+| **QQ**               | ⭐⭐ 中等   | 官方机器人 API，适合国内社群              | [查看文档](../channels/qq/README.zh.md)                                                                       |
+| **钉钉 (DingTalk)**  | ⭐⭐ 中等   | Stream 模式无需公网，企业办公首选         | [查看文档](../channels/dingtalk/README.zh.md)                                                                 |
+| **LINE**             | ⭐⭐⭐ 较难 | 需要 HTTPS Webhook                        | [查看文档](../channels/line/README.zh.md)                                                                     |
+| **企业微信 (WeCom)** | ⭐⭐⭐ 较难 | 官方 AI Bot WebSocket 接入，支持流式回复和媒体消息 | [查看文档](../channels/wecom/README.zh.md) |
+| **飞书 (Feishu)**    | ⭐⭐⭐ 较难 | 企业级协作，功能丰富                      | [查看文档](../channels/feishu/README.zh.md)                                                                   |
+| **IRC**              | ⭐⭐ 中等   | 服务器 + TLS 配置                         | [查看文档](#irc) |
+| **OneBot**           | ⭐⭐ 中等   | 兼容 NapCat/Go-CQHTTP，社区生态丰富       | [查看文档](../channels/onebot/README.zh.md)                                                                   |
+| **MaixCam**          | ⭐ 简单     | 专为 AI 摄像头设计的硬件集成通道          | [查看文档](../channels/maixcam/README.zh.md)                                                                  |
+| **Pico**             | ⭐ 简单     | PicoClaw 原生协议通道                     |                                                                                                               |
+
+---
+
+<a id="telegram"></a>
+<details>
+<summary><b>Telegram</b>（推荐）</summary>
+
+**1. 创建 Bot**
+
+* 打开 Telegram，搜索 `@BotFather`
+* 发送 `/newbot`，按提示操作
+* 复制 Token
+
+**2. 配置**
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+> 通过 Telegram 上的 `@userinfobot` 获取你的 User ID。
+
+**3. 运行**
+
+```bash
+picoclaw gateway
+```
+
+**4. Telegram 命令菜单（启动时自动注册）**
+
+PicoClaw 使用统一的命令定义来源。启动时会自动将 Telegram 支持的命令（例如 `/start`、`/help`、`/show`、`/list`、`/use`）注册到 Bot 命令菜单，确保菜单展示与实际行为一致。
+Telegram 侧保留的是命令菜单注册能力；通用命令的实际执行统一走 Agent Loop 中的 commands executor。
+
+如果注册因网络或 API 短暂异常失败，不会阻塞 channel 启动；系统会在后台自动重试。
+
+你也可以直接在 Telegram 中管理已安装技能：
+
+- `/list skills`
+- `/use <skill> <message>`
+- `/use <skill>`，然后在下一条消息里发送真正的请求
+- `/use clear`
+
+</details>
+
+<a id="discord"></a>
+<details>
+<summary><b>Discord</b></summary>
+
+**1. 创建 Bot**
+
+* 前往 <https://discord.com/developers/applications>
+* 创建应用 → Bot → 添加 Bot
+* 复制 Bot Token
+
+**2. 启用 Intents**
+
+* 在 Bot 设置中启用 **MESSAGE CONTENT INTENT**
+* （可选）启用 **SERVER MEMBERS INTENT**（如需基于成员数据的白名单）
+
+**3. 获取 User ID**
+
+* Discord 设置 → 高级 → 启用 **开发者模式**
+* 右键点击头像 → **复制用户 ID**
+
+**4. 配置**
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**5. 邀请 Bot**
+
+* OAuth2 → URL Generator
+* Scopes: `bot`
+* Bot Permissions: `Send Messages`, `Read Message History`
+* 打开生成的邀请链接，将 Bot 添加到服务器
+
+**可选：群组触发模式**
+
+默认情况下 Bot 会回复服务器频道中的所有消息。如需仅在 @提及时回复：
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "mention_only": true }
+    }
+  }
+}
+```
+
+也可通过关键词前缀触发（如 `!bot`）：
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "prefixes": ["!bot"] }
+    }
+  }
+}
+```
+
+**6. 运行**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="whatsapp"></a>
+<details>
+<summary><b>WhatsApp</b>（原生 whatsmeow）</summary>
+
+PicoClaw 支持两种 WhatsApp 连接方式：
+
+- **原生（推荐）：** 进程内使用 [whatsmeow](https://github.com/tulir/whatsmeow)，无需独立 Bridge。设置 `"use_native": true` 并留空 `bridge_url`。首次运行时用 WhatsApp 扫描 QR 码（关联设备）。会话存储在工作区下（如 `workspace/whatsapp/`）。原生渠道为**可选**构建，使用 `-tags whatsapp_native` 编译（如 `make build-whatsapp-native` 或 `go build -tags whatsapp_native ./cmd/...`）。
+- **Bridge：** 连接外部 WebSocket Bridge。设置 `bridge_url`（如 `ws://localhost:3001`），保持 `use_native` 为 false。
+
+**配置（原生）**
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "use_native": true,
+      "session_store_path": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+如果 `session_store_path` 为空，会话存储在 `<workspace>/whatsapp/`。运行 `picoclaw gateway`；首次运行时在终端扫描 QR 码（WhatsApp → 关联设备）。
+
+</details>
+
+<a id="weixin"></a>
+<details>
+<summary><b>微信 (Weixin)</b></summary>
+
+PicoClaw 通过腾讯 iLink 官方 API 支持连接微信个人号。
+
+**1. 登录**
+
+运行交互式扫码登录流程：
+```bash
+picoclaw auth weixin
+```
+用微信手机端扫描打印出的二维码。登录成功后，token 会自动保存到配置文件。
+
+**2. 配置**
+
+（可选）在 `allow_from` 中填入你的微信用户 ID，限制可以与机器人对话的用户：
+```json
+{
+  "channels": {
+    "weixin": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**3. 运行**
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="matrix"></a>
+<details>
+<summary><b>Matrix</b></summary>
+
+**1. 准备 Bot 账号**
+
+* 使用你的 homeserver（如 `https://matrix.org` 或自建）
+* 创建 Bot 用户并获取 access token
+
+**2. 配置**
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. 运行**
+
+```bash
+picoclaw gateway
+```
+
+完整选项（`device_id`、`join_on_invite`、`group_trigger`、`placeholder`、`reasoning_channel_id`）请参考 [Matrix 渠道配置指南](../channels/matrix/README.md)。
+
+</details>
+
+<a id="qq"></a>
+<details>
+<summary><b>QQ</b></summary>
+
+**快速设置（推荐）**
+
+QQ 开放平台提供了一键创建 OpenClaw 兼容机器人的页面：
+
+1. 打开 [QQ 机器人快速创建](https://q.qq.com/qqbot/openclaw/index.html)，扫码登录
+2. 机器人自动创建 — 复制 **App ID** 和 **App Secret**
+3. 配置 PicoClaw：
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+4. 运行 `picoclaw gateway`，打开 QQ 与机器人聊天
+
+> App Secret 仅显示一次，请立即保存 — 再次查看将强制重置。
+>
+> 通过快速创建页面创建的机器人初始仅限创建者使用，不支持群聊。如需启用群聊访问，请在 [QQ 开放平台](https://q.qq.com/) 配置沙箱模式。
+
+**手动设置**
+
+如果你更喜欢手动创建机器人：
+
+* 登录 [QQ 开放平台](https://q.qq.com/) 注册成为开发者
+* 创建 QQ 机器人 — 自定义头像和名称
+* 从机器人设置中复制 **App ID** 和 **App Secret**
+* 按上述方式配置并运行 `picoclaw gateway`
+
+</details>
+
+<a id="slack"></a>
+<details>
+<summary><b>Slack</b></summary>
+
+**1. 创建 Slack App**
+
+* 前往 [Slack API](https://api.slack.com/apps) 创建新应用
+* 在 **OAuth & Permissions** 中添加 Bot 权限范围：`chat:write`、`app_mentions:read`、`im:history`、`im:read`、`im:write`
+* 将应用安装到你的工作区
+* 复制 **Bot Token**（`xoxb-...`）和 **App-Level Token**（`xapp-...`，启用 Socket Mode 后获取）
+
+**2. 配置**
+
+```json
+{
+  "channels": {
+    "slack": {
+      "enabled": true,
+      "bot_token": "xoxb-YOUR-BOT-TOKEN",
+      "app_token": "xapp-YOUR-APP-TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. 运行**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="irc"></a>
+<details>
+<summary><b>IRC</b></summary>
+
+**1. 配置**
+
+```json
+{
+  "channels": {
+    "irc": {
+      "enabled": true,
+      "server": "irc.libera.chat:6697",
+      "tls": true,
+      "nick": "picoclaw-bot",
+      "channels": ["#your-channel"],
+      "password": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+可选：`nickserv_password` 用于 NickServ 认证，`sasl_user`/`sasl_password` 用于 SASL 认证。
+
+**2. 运行**
+
+```bash
+picoclaw gateway
+```
+
+Bot 将连接到 IRC 服务器并加入指定的频道。
+
+</details>
+
+<a id="dingtalk"></a>
+<details>
+<summary><b>钉钉 (DingTalk)</b></summary>
+
+**1. 创建 Bot**
+
+* 前往 [开放平台](https://open.dingtalk.com/)
+* 创建内部应用
+* 复制 Client ID 和 Client Secret
+
+**2. 配置**
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> `allow_from` 留空表示允许所有用户，或指定钉钉用户 ID 限制访问。
+
+**3. 运行**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="line"></a>
+<details>
+<summary><b>LINE</b></summary>
+
+**1. 创建 LINE Official Account**
+
+- 前往 [LINE Developers Console](https://developers.line.biz/)
+- 创建 Provider → 创建 Messaging API Channel
+- 复制 **Channel Secret** 和 **Channel Access Token**
+
+**2. 配置**
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> LINE Webhook 挂载在共享 Gateway 服务器上（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`）。
+
+**3. 设置 Webhook URL**
+
+LINE 要求 HTTPS Webhook。使用反向代理或隧道：
+
+```bash
+# 示例：使用 ngrok（Gateway 默认端口 18790）
+ngrok http 18790
+```
+
+然后在 LINE Developers Console 中将 Webhook URL 设置为 `https://your-domain/webhook/line` 并启用 **Use webhook**。
+
+**4. 运行**
+
+```bash
+picoclaw gateway
+```
+
+> 在群聊中，Bot 仅在被 @提及时回复。回复会引用原始消息。
+
+</details>
+
+<a id="feishu"></a>
+<details>
+<summary><b>飞书 (Feishu)</b></summary>
+
+PicoClaw 通过 WebSocket/SDK 模式连接飞书 — 无需公网 Webhook URL 或回调服务器。
+
+**1. 创建应用**
+
+* 前往 [飞书开放平台](https://open.feishu.cn/) 创建应用
+* 在应用设置中启用 **机器人** 能力
+* 创建版本并发布应用（应用必须发布后才能生效）
+* 复制 **App ID**（以 `cli_` 开头）和 **App Secret**
+
+**2. 配置**
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "app_id": "cli_xxx",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+可选：`encrypt_key` 和 `verification_token` 用于事件加密（生产环境推荐）。
+
+**3. 运行并聊天**
+
+```bash
+picoclaw gateway
+```
+
+打开飞书，搜索你的机器人名称即可开始聊天。也可以将机器人添加到群组 — 使用 `group_trigger.mention_only: true` 设置为仅在 @提及时回复。
+
+完整选项请参考 [飞书渠道配置指南](../channels/feishu/README.zh.md)。
+
+</details>
+
+<a id="wecom"></a>
+<details>
+<summary><b>企业微信 (WeCom)</b></summary>
+
+PicoClaw 现在将企业微信统一为一个基于 WebSocket 的 AI Bot 渠道。
+它不再需要公网 webhook 回调地址。
+
+完整配置说明和迁移说明请参考 [企业微信配置指南](../channels/wecom/README.zh.md)。
+
+**推荐快速接入**
+
+**1. 认证**
+
+```bash
+picoclaw auth wecom
+```
+
+该命令会显示二维码，等待你在企业微信里确认，然后把 `bot_id` 和 `secret` 写入 `channels.wecom`。
+
+**2. 如需手动配置**
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "bot_id": "YOUR_BOT_ID",
+      "secret": "YOUR_SECRET",
+      "websocket_url": "wss://openws.work.weixin.qq.com",
+      "send_thinking_message": true,
+      "allow_from": [],
+      "reasoning_channel_id": ""
+    }
+  }
+}
+```
+
+**3. 运行**
+
+```bash
+picoclaw gateway
+```
+
+> 这个分支中旧的 `wecom_app` 和 `wecom_aibot` 配置已经被统一的 `channels.wecom` 替代。
+
+</details>
+
+<a id="onebot"></a>
+<details>
+<summary><b>OneBot（通过 OneBot 协议连接 QQ）</b></summary>
+
+OneBot 是 QQ 机器人的开放协议。PicoClaw 通过 WebSocket 连接任何 OneBot v11 兼容实现（如 [Lagrange](https://github.com/LagrangeDev/Lagrange.Core)、[NapCat](https://github.com/NapNeko/NapCatQQ)）。
+
+**1. 设置 OneBot 实现**
+
+安装并运行 OneBot v11 兼容的 QQ 机器人框架，启用其 WebSocket 服务器。
+
+**2. 配置**
+
+```json
+{
+  "channels": {
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://127.0.0.1:8080",
+      "access_token": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `ws_url` | OneBot 实现的 WebSocket URL |
+| `access_token` | 认证用的访问令牌（如果在 OneBot 中配置了的话） |
+| `reconnect_interval` | 重连间隔（秒）（默认：5） |
+
+**3. 运行**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<a id="maixcam"></a>
+<details>
+<summary><b>MaixCam</b></summary>
+
+专为 Sipeed AI 摄像头硬件设计的集成通道。
+
+```json
+{
+  "channels": {
+    "maixcam": {
+      "enabled": true
+    }
+  }
+}
+```
+
+```bash
+picoclaw gateway
+```
+
+</details>
diff --git a/docs/zh/configuration.md b/docs/zh/configuration.md
new file mode 100644
index 000000000..335566d36
--- /dev/null
+++ b/docs/zh/configuration.md
@@ -0,0 +1,630 @@
+# ⚙️ 配置指南
+
+> 返回 [README](../../README.zh.md)
+
+## ⚙️ 配置详解
+
+配置文件路径: `~/.picoclaw/config.json`
+
+### 环境变量
+
+你可以使用环境变量覆盖默认路径。这对于便携安装、容器化部署或将 picoclaw 作为系统服务运行非常有用。这些变量是独立的，控制不同的路径。
+
+| 变量              | 描述                                                                                                                             | 默认路径                  |
+|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
+| `PICOCLAW_CONFIG` | 覆盖配置文件的路径。这直接告诉 picoclaw 加载哪个 `config.json`，忽略所有其他位置。 | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | 覆盖 picoclaw 数据根目录。这会更改 `workspace` 和其他数据目录的默认位置。          | `~/.picoclaw`             |
+
+**示例：**
+
+```bash
+# 使用特定的配置文件运行 picoclaw
+# 工作区路径将从该配置文件中读取
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# 在 /opt/picoclaw 中存储所有数据运行 picoclaw
+# 配置将从默认的 ~/.picoclaw/config.json 加载
+# 工作区将在 /opt/picoclaw/workspace 创建
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# 同时使用两者进行完全自定义设置
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
+### 工作区布局 (Workspace Layout)
+
+PicoClaw 将数据存储在您配置的工作区中（默认：`~/.picoclaw/workspace`）：
+
+```
+~/.picoclaw/workspace/
+├── sessions/          # 对话会话和历史
+├── memory/           # 长期记忆 (MEMORY.md)
+├── state/            # 持久化状态 (最后一次频道等)
+├── cron/             # 定时任务数据库
+├── skills/           # 自定义技能
+├── AGENT.md          # Agent 行为指南
+├── HEARTBEAT.md      # 周期性任务提示词 (每 30 分钟检查一次)
+├── IDENTITY.md       # Agent 身份设定
+├── SOUL.md           # Agent 灵魂/性格
+└── USER.md           # 用户偏好
+```
+
+> **提示：** 对 `AGENT.md`、`SOUL.md`、`USER.md` 和 `memory/MEMORY.md` 的修改会通过文件修改时间（mtime）在运行时自动检测。**无需重启 gateway**，Agent 将在下一次请求时自动加载最新内容。
+
+### 技能来源 (Skill Sources)
+
+默认情况下，技能会按以下顺序加载：
+
+1. `~/.picoclaw/workspace/skills`（工作区）
+2. `~/.picoclaw/skills`（全局）
+3. `<构建时嵌入路径>/skills`（内置）
+
+在高级/测试场景下，可通过以下环境变量覆盖内置技能目录：
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
+### 在聊天频道中使用技能
+
+技能安装完成后，可以直接在聊天频道里查看并显式启用它们：
+
+- `/list skills`：显示当前 Agent 可用的已安装技能名称。
+- `/use <skill> <message>`：只对当前这一条请求强制使用指定技能。
+- `/use <skill>`：为同一会话中的下一条消息预先启用该技能。
+- `/use clear`：取消通过 `/use <skill>` 设置的待应用技能。
+
+示例：
+
+```text
+/list skills
+/use git explain how to squash the last 3 commits
+/use italiapersonalfinance
+dammi le ultime news
+```
+
+### 统一命令执行策略
+
+- 通用斜杠命令通过 `pkg/agent/loop.go` 中的 `commands.Executor` 统一执行。
+- Channel 适配器不再在本地消费通用命令；它们只负责把入站文本转发到 bus/agent 路径。Telegram 仍会在启动时自动注册其支持的命令菜单。
+- 未注册的斜杠命令（例如 `/foo`）会透传给 LLM 按普通输入处理。
+- 已注册但当前 channel 不支持的命令（例如 WhatsApp 上的 `/show`）会返回明确的用户可见错误，并停止后续处理。
+
+### 🔒 安全沙箱 (Security Sandbox)
+
+PicoClaw 默认在沙箱环境中运行。Agent 只能访问配置的工作区内的文件和执行命令。
+
+#### 默认配置
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "restrict_to_workspace": true
+    }
+  }
+}
+```
+
+| 选项                    | 默认值                  | 描述                          |
+| ----------------------- | ----------------------- | ----------------------------- |
+| `workspace`             | `~/.picoclaw/workspace` | Agent 的工作目录              |
+| `restrict_to_workspace` | `true`                  | 限制文件/命令访问在工作区内   |
+
+#### 受保护的工具
+
+当 `restrict_to_workspace: true` 时，以下工具会被沙箱化：
+
+| 工具          | 功能         | 限制                           |
+| ------------- | ------------ | ------------------------------ |
+| `read_file`   | 读取文件     | 仅限工作区内的文件             |
+| `write_file`  | 写入文件     | 仅限工作区内的文件             |
+| `list_dir`    | 列出目录     | 仅限工作区内的目录             |
+| `edit_file`   | 编辑文件     | 仅限工作区内的文件             |
+| `append_file` | 追加文件     | 仅限工作区内的文件             |
+| `exec`        | 执行命令     | 命令路径必须在工作区内         |
+
+#### 额外的 Exec 保护
+
+即使 `restrict_to_workspace: false`，`exec` 工具也会阻止以下危险命令：
+
+* `rm -rf`、`del /f`、`rmdir /s` — 批量删除
+* `format`、`mkfs`、`diskpart` — 磁盘格式化
+* `dd if=` — 磁盘镜像
+* 写入 `/dev/sd[a-z]` — 直接磁盘写入
+* `shutdown`、`reboot`、`poweroff` — 系统关机
+* Fork bomb `:(){ :|:& };:`
+
+### 文件访问控制
+
+| 配置键 | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| `tools.allow_read_paths` | string[] | `[]` | 允许在工作区外读取的额外路径 |
+| `tools.allow_write_paths` | string[] | `[]` | 允许在工作区外写入的额外路径 |
+
+### Exec 安全配置
+
+| 配置键 | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| `tools.exec.allow_remote` | bool | `false` | 允许从远程渠道（Telegram/Discord 等）执行 exec 工具 |
+| `tools.exec.enable_deny_patterns` | bool | `true` | 启用危险命令拦截 |
+| `tools.exec.custom_deny_patterns` | string[] | `[]` | 自定义阻止的正则表达式模式 |
+| `tools.exec.custom_allow_patterns` | string[] | `[]` | 自定义允许的正则表达式模式 |
+
+> **安全提示：** Symlink 保护默认启用——所有文件路径在白名单匹配前都会通过 `filepath.EvalSymlinks` 解析，防止符号链接逃逸攻击。
+
+#### 已知限制：构建工具的子进程
+
+exec 安全守卫仅检查 PicoClaw 直接启动的命令行。它不会递归检查由 `make`、`go run`、`cargo`、`npm run` 或自定义构建脚本等开发工具产生的子进程。
+
+这意味着顶层命令通过初始守卫检查后，仍可以编译或启动其他二进制文件。实际上，应将构建脚本、Makefile、包脚本和生成的二进制文件视为与直接 shell 命令同等级别的可执行代码进行审查。
+
+对于高风险环境：
+
+* 执行前审查构建脚本。
+* 对编译并运行的工作流优先使用审批/手动审查。
+* 如果需要比内置守卫更强的隔离，请在容器或虚拟机中运行 PicoClaw。
+
+#### 错误示例
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (path outside working dir)}
+```
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
+```
+
+#### 禁用限制（安全风险）
+
+如果需要 Agent 访问工作区外的路径：
+
+**方法 1: 配置文件**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "restrict_to_workspace": false
+    }
+  }
+}
+```
+
+**方法 2: 环境变量**
+
+```bash
+export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
+```
+
+> ⚠️ **警告**: 禁用此限制将允许 Agent 访问系统上的任何路径。仅在受控环境中谨慎使用。
+
+#### 安全边界一致性
+
+`restrict_to_workspace` 设置在所有执行路径中一致应用：
+
+| 执行路径         | 安全边界                     |
+| ---------------- | ---------------------------- |
+| 主 Agent         | `restrict_to_workspace` ✅   |
+| 子 Agent / Spawn | 继承相同限制 ✅              |
+| 心跳任务         | 继承相同限制 ✅              |
+
+所有路径共享相同的工作区限制——无法通过子 Agent 或定时任务绕过安全边界。
+
+### 心跳 / 周期性任务 (Heartbeat)
+
+PicoClaw 可以自动执行周期性任务。在工作区创建 `HEARTBEAT.md` 文件：
+
+```markdown
+# Periodic Tasks
+
+- Check my email for important messages
+- Review my calendar for upcoming events
+- Check the weather forecast
+```
+
+Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具执行任务。
+
+#### 使用 Spawn 的异步任务
+
+对于耗时较长的任务（网络搜索、API 调用），使用 `spawn` 工具创建一个 **子 Agent (subagent)**：
+
+```markdown
+# Periodic Tasks
+
+## Quick Tasks (respond directly)
+
+- Report current time
+
+## Long Tasks (use spawn for async)
+
+- Search the web for AI news and summarize
+- Check email and report important messages
+```
+
+**关键行为：**
+
+| 特性             | 描述                                     |
+| ---------------- | ---------------------------------------- |
+| **spawn**        | 创建异步子 Agent，不阻塞主心跳进程       |
+| **独立上下文**   | 子 Agent 拥有独立上下文，无会话历史      |
+| **message tool** | 子 Agent 通过 message 工具直接与用户通信 |
+| **非阻塞**       | spawn 后，心跳继续处理下一个任务         |
+
+**配置：**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| 选项       | 默认值 | 描述                         |
+| ---------- | ------ | ---------------------------- |
+| `enabled`  | `true` | 启用/禁用心跳                |
+| `interval` | `30`   | 检查间隔，单位分钟 (最小: 5) |
+
+**环境变量:**
+
+- `PICOCLAW_HEARTBEAT_ENABLED=false` 禁用
+- `PICOCLAW_HEARTBEAT_INTERVAL=60` 更改间隔
+
+#### 子 Agent 通信流程
+
+```
+心跳触发
+    ↓
+Agent 读取 HEARTBEAT.md
+    ↓
+遇到耗时任务：spawn 子 Agent
+    ↓                           ↓
+继续处理下一个任务         子 Agent 独立运行
+    ↓                           ↓
+所有任务完成               子 Agent 使用 "message" 工具
+    ↓                           ↓
+回复 HEARTBEAT_OK          用户直接收到结果
+```
+
+子 Agent 拥有工具访问权限（message、web_search 等），可以独立与用户通信，无需经过主 Agent。
+
+### Providers（模型提供商）
+
+> [!NOTE]
+> Groq 通过 Whisper 提供免费语音转录。配置后，任意渠道的语音消息都会在 Agent 层自动转录为文字。
+
+| 提供商       | 用途                                    | 获取 API Key                                                 |
+| ------------ | --------------------------------------- | ------------------------------------------------------------ |
+| `gemini`     | LLM（Gemini 直连）                      | [aistudio.google.com](https://aistudio.google.com)           |
+| `zhipu`      | LLM（智谱直连）                         | [bigmodel.cn](https://bigmodel.cn)                           |
+| `volcengine` | LLM（火山引擎直连）                     | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter` | LLM（推荐，可访问所有模型）             | [openrouter.ai](https://openrouter.ai)                       |
+| `anthropic`  | LLM（Claude 直连）                      | [console.anthropic.com](https://console.anthropic.com)       |
+| `openai`     | LLM（GPT 直连）                         | [platform.openai.com](https://platform.openai.com)           |
+| `deepseek`   | LLM（DeepSeek 直连）                    | [platform.deepseek.com](https://platform.deepseek.com)       |
+| `qwen`       | LLM（通义千问直连）                     | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq`       | LLM + **语音转录**（Whisper）           | [console.groq.com](https://console.groq.com)                 |
+| `cerebras`   | LLM（Cerebras 直连）                    | [cerebras.ai](https://cerebras.ai)                           |
+| `vivgrid`    | LLM（Vivgrid 直连）                     | [vivgrid.com](https://vivgrid.com)                           |
+
+### 模型配置 (model_list)
+
+> **新特性：** PicoClaw 现在采用**以模型为中心**的配置方式。只需指定 `vendor/model` 格式（例如 `zhipu/glm-4.7`）即可接入新提供商——**无需修改任何代码！**
+
+这一设计同时支持**多 Agent**场景，灵活选择提供商：
+
+- **不同 Agent 使用不同提供商**：每个 Agent 可以使用独立的 LLM 提供商
+- **模型降级**：配置主模型和备用模型，提升可用性
+- **负载均衡**：将请求分发到多个端点
+- **集中管理**：在一处管理所有提供商配置
+
+#### 所有支持的厂商
+
+| 厂商                    | `model` 前缀      | 默认 API Base                                       | 协议      | API Key                                                          |
+| ----------------------- | ----------------- | --------------------------------------------------- | --------- | ---------------------------------------------------------------- |
+| **OpenAI**              | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [获取](https://platform.openai.com)                              |
+| **Anthropic**           | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [获取](https://console.anthropic.com)                            |
+| **智谱 AI (GLM)**       | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [获取](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys)    |
+| **DeepSeek**            | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [获取](https://platform.deepseek.com)                            |
+| **Google Gemini**       | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI    | [获取](https://aistudio.google.com/api-keys)                     |
+| **Groq**                | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [获取](https://console.groq.com)                                 |
+| **Moonshot**            | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [获取](https://platform.moonshot.cn)                             |
+| **通义千问 (Qwen)**     | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [获取](https://dashscope.console.aliyun.com)                     |
+| **NVIDIA**              | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [获取](https://build.nvidia.com)                                 |
+| **Ollama**              | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | 本地（无需 Key）                                                 |
+| **OpenRouter**          | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [获取](https://openrouter.ai/keys)                               |
+| **LiteLLM Proxy**       | `litellm/`        | `http://localhost:4000/v1`                          | OpenAI    | 你的 LiteLLM 代理 Key                                            |
+| **VLLM**                | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | 本地                                                             |
+| **Cerebras**            | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [获取](https://cerebras.ai)                                      |
+| **火山引擎 (豆包)**     | `volcengine/`     | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [获取](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **神算云**              | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | —                                                                |
+| **BytePlus**            | `byteplus/`       | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [获取](https://www.byteplus.com)                                 |
+| **Vivgrid**             | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [获取](https://vivgrid.com)                                      |
+| **LongCat**             | `longcat/`        | `https://api.longcat.chat/openai`                   | OpenAI    | [获取](https://longcat.chat/platform)                            |
+| **ModelScope (魔搭)**   | `modelscope/`     | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [获取](https://modelscope.cn/my/tokens)                          |
+| **Antigravity**         | `antigravity/`    | Google Cloud                                        | Custom    | 仅 OAuth                                                         |
+| **GitHub Copilot**      | `github-copilot/` | `localhost:4321`                                    | gRPC      | —                                                                |
+
+#### 基础配置
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-openai-key"
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "sk-ant-your-key"
+    },
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-zhipu-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model": "gpt-5.4"
+    }
+  }
+}
+```
+
+#### 各厂商配置示例
+
+<details>
+<summary><b>OpenAI</b></summary>
+
+```json
+{
+  "model_name": "gpt-5.4",
+  "model": "openai/gpt-5.4",
+  "api_key": "sk-..."
+}
+```
+
+</details>
+
+<details>
+<summary><b>火山引擎（豆包）</b></summary>
+
+```json
+{
+  "model_name": "ark-code-latest",
+  "model": "volcengine/ark-code-latest",
+  "api_key": "sk-..."
+}
+```
+
+</details>
+
+<details>
+<summary><b>智谱 AI (GLM)</b></summary>
+
+```json
+{
+  "model_name": "glm-4.7",
+  "model": "zhipu/glm-4.7",
+  "api_key": "your-key"
+}
+```
+
+</details>
+
+<details>
+<summary><b>DeepSeek</b></summary>
+
+```json
+{
+  "model_name": "deepseek-chat",
+  "model": "deepseek/deepseek-chat",
+  "api_key": "sk-..."
+}
+```
+
+</details>
+
+<details>
+<summary><b>Anthropic</b></summary>
+
+```json
+{
+  "model_name": "claude-sonnet-4.6",
+  "model": "anthropic/claude-sonnet-4.6",
+  "api_key": "sk-ant-your-key"
+}
+```
+
+> 运行 `picoclaw auth login --provider anthropic` 粘贴 API Token。
+
+如需直连 Anthropic 原生接口（不兼容 OpenAI 格式的端点）：
+
+```json
+{
+  "model_name": "claude-opus-4-6",
+  "model": "anthropic-messages/claude-opus-4-6",
+  "api_key": "sk-ant-your-key",
+  "api_base": "https://api.anthropic.com"
+}
+```
+
+> 当端点不支持 OpenAI 兼容格式（`/v1/chat/completions`），需要 Anthropic 原生 `/v1/messages` 时使用 `anthropic-messages`。
+
+</details>
+
+<details>
+<summary><b>Ollama（本地）</b></summary>
+
+```json
+{
+  "model_name": "llama3",
+  "model": "ollama/llama3"
+}
+```
+
+</details>
+
+<details>
+<summary><b>自定义代理 / LiteLLM</b></summary>
+
+```json
+{
+  "model_name": "my-custom-model",
+  "model": "openai/custom-model",
+  "api_base": "https://my-proxy.com/v1",
+  "api_key": "sk-..."
+}
+```
+
+PicoClaw 只剥离最外层的 `litellm/` 前缀再发送请求，因此 `litellm/lite-gpt4` 发送 `lite-gpt4`，而 `litellm/openai/gpt-4o` 发送 `openai/gpt-4o`。
+
+</details>
+
+#### 负载均衡
+
+为同一模型名称配置多个端点，PicoClaw 会自动轮询：
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api1.example.com/v1",
+      "api_key": "sk-key1"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api2.example.com/v1",
+      "api_key": "sk-key2"
+    }
+  ]
+}
+```
+
+#### 从旧版 `providers` 配置迁移
+
+旧版 `providers` 配置**已废弃**，但仍向后兼容。完整迁移指南见 [docs/migration/model-list-migration.md](../migration/model-list-migration.md)。
+
+### Provider 架构
+
+PicoClaw 按协议族路由提供商：
+
+- **OpenAI 兼容**：OpenRouter、Groq、智谱、vLLM 风格端点及大多数其他提供商。
+- **Anthropic**：Claude 原生 API 行为。
+- **Codex/OAuth**：OpenAI OAuth/Token 认证路由。
+
+这使运行时保持轻量，同时让接入新的 OpenAI 兼容后端基本只需配置 `api_base` + `api_key`。
+
+<details>
+<summary><b>智谱（旧版 providers 格式）</b></summary>
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "providers": {
+    "zhipu": {
+      "api_key": "Your API Key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><b>完整配置示例</b></summary>
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": "anthropic/claude-opus-4-5"
+    }
+  },
+  "session": {
+    "dm_scope": "per-channel-peer",
+    "backlog_limit": 20
+  },
+  "providers": {
+    "openrouter": {
+      "api_key": "sk-or-v1-xxx"
+    },
+    "groq": {
+      "api_key": "gsk_xxx"
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456:ABC...",
+      "allow_from": ["123456789"]
+    }
+  },
+  "tools": {
+    "web": {
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      }
+    }
+  },
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+</details>
+
+### 定时任务 / 提醒
+
+PicoClaw 通过 `cron` 工具支持 cron 风格的定时任务。Agent 可以设置、列出和取消在指定时间触发的提醒或周期性任务。
+
+```json
+{
+  "tools": {
+    "cron": {
+      "enabled": true,
+      "exec_timeout_minutes": 5
+    }
+  }
+}
+```
+
+定时任务在重启后持久保存，存储于 `~/.picoclaw/workspace/cron/`。
+
+### 进阶主题
+
+| 主题 | 说明 |
+| ---- | ---- |
+| [敏感数据过滤](../sensitive_data_filtering.md) | 在发送给 LLM 前，从工具结果中过滤 API 密钥和令牌 |
+| [Hook 系统](../hooks/README.zh.md) | 事件驱动 Hook：观察者、拦截器、审批 Hook |
+| [Steering](../steering.md) | 在工具调用间向运行中的 Agent 注入消息 |
+| [SubTurn](../subturn.md) | 子 Agent 协调、并发控制、生命周期管理 |
+| [上下文管理](../agent-refactor/context.md) | 上下文边界检测、主动预算检查、压缩策略 |
diff --git a/docs/zh/credential_encryption.md b/docs/zh/credential_encryption.md
new file mode 100644
index 000000000..2105e4307
--- /dev/null
+++ b/docs/zh/credential_encryption.md
@@ -0,0 +1,158 @@
+> 返回 [README](../../README.zh.md)
+
+# 凭据加密
+
+PicoClaw 支持对 `model_list` 配置条目中的 `api_key` 值进行加密。
+加密后的密钥以 `enc://<base64>` 字符串形式存储，并在启动时自动解密。
+
+---
+
+## 快速开始
+
+**1. 设置密码短语**
+
+```bash
+export PICOCLAW_KEY_PASSPHRASE="your-passphrase"
+```
+
+**2. 加密 API 密钥**
+
+运行 `picoclaw onboard` — 它会提示你输入密码短语并生成 SSH 密钥，
+然后在下一次 `SaveConfig` 调用时自动重新加密配置中所有明文 `api_key` 条目。生成的 `enc://` 值如下所示：
+
+```
+enc://AAAA...base64...
+```
+
+**3. 将输出粘贴到你的配置中**
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-4o",
+      "model": "openai/gpt-4o",
+      "api_key": "enc://AAAA...base64...",
+      "api_base": "https://api.openai.com/v1"
+    }
+  ]
+}
+```
+
+---
+
+## 支持的 `api_key` 格式
+
+| 格式 | 示例 | 行为 |
+|------|------|------|
+| 明文 | `sk-abc123` | 直接使用 |
+| 文件引用 | `file://openai.key` | 从配置文件所在目录读取内容 |
+| 加密 | `enc://<base64>` | 启动时使用 `PICOCLAW_KEY_PASSPHRASE` 解密 |
+| 空值 | `""` | 原样传递（用于 `auth_method: oauth`） |
+
+---
+
+## 加密设计
+
+### 密钥派生
+
+加密使用 **HKDF-SHA256**，并以 SSH 私钥作为第二因子。
+
+```
+sshHash = SHA256(ssh_private_key_file_bytes)
+ikm     = HMAC-SHA256(key=sshHash, message=passphrase)
+aes_key = HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+```
+
+### 加密
+
+```
+AES-256-GCM(key=aes_key, nonce=random[12], plaintext=api_key)
+```
+
+### 传输格式
+
+```
+enc://<base64( salt[16] + nonce[12] + ciphertext )>
+```
+
+| 字段 | 大小 | 描述 |
+|------|------|------|
+| `salt` | 16 字节 | 每次加密随机生成；输入 HKDF |
+| `nonce` | 12 字节 | 每次加密随机生成；AES-GCM IV |
+| `ciphertext` | 可变 | AES-256-GCM 密文 + 16 字节认证标签 |
+
+GCM 认证标签会自动附加到密文之后。任何篡改都会导致解密失败并报错，而不是返回损坏的明文。
+
+### 性能
+
+| 操作 | 耗时 (ARM Cortex-A) |
+|------|---------------------|
+| 密钥派生 (HKDF) | < 1 ms |
+| AES-256-GCM 解密 | < 1 ms |
+| **启动总开销** | **每个密钥 < 2 ms** |
+
+---
+
+## 使用 SSH 密钥的双因子安全
+
+当提供 SSH 私钥时，破解加密需要**同时具备**：
+
+1. **密码短语** (`PICOCLAW_KEY_PASSPHRASE`)
+2. **SSH 私钥文件**
+
+这意味着仅泄露配置文件不足以恢复 API 密钥，即使密码短语较弱也是如此。SSH 密钥贡献 256 位熵（Ed25519），与密码短语强度无关。
+
+### 威胁模型
+
+| 攻击者拥有 | 能否解密？ |
+|------------|-----------|
+| 仅配置文件 | 否 — 需要密码短语 + SSH 密钥 |
+| 仅 SSH 密钥 | 否 — 需要密码短语 |
+| 仅密码短语 | 否 — 需要 SSH 密钥 |
+| 配置文件 + SSH 密钥 + 密码短语 | 是 — 完全泄露 |
+
+---
+
+## 环境变量
+
+| 变量 | 是否必需 | 描述 |
+|------|----------|------|
+| `PICOCLAW_KEY_PASSPHRASE` | 是（用于 `enc://`） | 用于密钥派生的密码短语 |
+| `PICOCLAW_SSH_KEY_PATH` | 否 | SSH 私钥路径。如未设置，自动从 `~/.ssh/picoclaw_ed25519.key` 检测 |
+
+### SSH 密钥自动检测
+
+如果未设置 `PICOCLAW_SSH_KEY_PATH`，PicoClaw 会查找专用密钥：
+
+```
+~/.ssh/picoclaw_ed25519.key
+```
+
+此专用文件避免与用户现有的 SSH 密钥冲突。
+运行 `picoclaw onboard` 可自动生成该密钥。
+
+`os.UserHomeDir()` 用于跨平台主目录解析（在 Windows 上读取 `USERPROFILE`，在 Unix/macOS 上读取 `HOME`）。
+
+> **注意：** SSH 密钥文件是凭据加密的必要条件。如果未找到密钥且未设置 `PICOCLAW_SSH_KEY_PATH`，加密/解密将失败。运行 `picoclaw onboard` 可自动生成密钥。
+
+---
+
+## 迁移
+
+由于唯一的密钥材料是 `PICOCLAW_KEY_PASSPHRASE` 和 SSH 私钥文件，迁移非常简单：
+
+1. 将配置文件复制到新机器。
+2. 将 `PICOCLAW_KEY_PASSPHRASE` 设置为相同的值。
+3. 将 SSH 私钥文件复制到相同路径（或将 `PICOCLAW_SSH_KEY_PATH` 设置为新位置）。
+
+无需重新加密。
+
+---
+
+## 安全注意事项
+
+- **密码短语和 SSH 密钥都是必需的。** SSH 密钥作为第二因子 — 没有它，加密/解密将失败。如果密钥不存在，运行 `picoclaw onboard` 生成。
+- **SSH 密钥在运行时为只读。** PicoClaw 不会写入或修改 SSH 密钥文件。
+- **仍然支持明文密钥。** 不使用 `enc://` 的现有配置不受影响。
+- **`enc://` 格式通过版本控制**，通过 HKDF `info` 字段（`picoclaw-credential-v1`）实现，允许未来升级算法而不破坏现有加密值。
diff --git a/docs/zh/debug.md b/docs/zh/debug.md
new file mode 100644
index 000000000..e7f20d777
--- /dev/null
+++ b/docs/zh/debug.md
@@ -0,0 +1,36 @@
+# 调试 PicoClaw
+
+> 返回 [README](../../README.zh.md)
+
+PicoClaw 在处理每一个请求时，都会在后台执行多个复杂的交互操作——从消息路由和复杂度评估，到工具执行和模型故障适配。能够准确地看到正在发生什么至关重要，这不仅有助于排查潜在问题，也有助于真正理解代理的运作方式。
+
+## 以调试模式启动 PicoClaw
+
+要获取代理运行的详细信息（LLM 请求、工具调用、消息路由），可以使用调试标志启动 PicoClaw 网关：
+
+```bash
+picoclaw gateway --debug
+# or
+picoclaw gateway -d
+```
+
+在此模式下，系统会对日志进行详细格式化，并显示系统提示词和工具执行结果的预览。
+
+## 禁用日志截断（完整日志）
+
+默认情况下，PicoClaw 会在调试日志中截断过长的字符串（例如*系统提示词*或大型 JSON 输出结果），以保持控制台的可读性。
+
+如果你需要检查某个命令的完整输出，或发送给 LLM 模型的确切载荷，可以使用 `--no-truncate` 标志。
+
+**注意：** 此标志*仅*在与 `--debug` 模式组合使用时有效。
+
+```bash
+picoclaw gateway --debug --no-truncate
+
+```
+
+当此标志激活时，全局截断功能将被禁用。这在以下场景中非常有用：
+
+* 验证发送给提供商的消息的确切语法。
+* 读取 `exec`、`web_fetch` 或 `read_file` 等工具的完整输出。
+* 调试保存在内存中的会话历史。
diff --git a/docs/zh/docker.md b/docs/zh/docker.md
new file mode 100644
index 000000000..10bc46544
--- /dev/null
+++ b/docs/zh/docker.md
@@ -0,0 +1,169 @@
+# 🐳 Docker 与快速开始
+
+> 返回 [README](../../README.zh.md)
+
+## 🐳 Docker Compose
+
+您也可以使用 Docker Compose 运行 PicoClaw，无需在本地安装任何环境。
+
+```bash
+# 1. 克隆仓库
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. 首次运行 — 自动生成 docker/data/config.json 后退出
+#    （仅在 config.json 和 workspace/ 都不存在时触发）
+docker compose -f docker/docker-compose.yml --profile gateway up
+# 容器打印 "First-run setup complete." 后自动停止
+
+# 3. 填写 API Key 等配置
+vim docker/data/config.json   # 设置 provider API key、Bot Token 等
+
+# 4. 正式启动
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+> [!TIP]
+> **Docker 用户**: 默认情况下, Gateway 监听 `127.0.0.1`，该端口不会暴露到容器外。如果需要通过端口映射访问健康检查接口，请在环境变量中设置 `PICOCLAW_GATEWAY_HOST=0.0.0.0` 或修改 `config.json`。
+
+```bash
+# 5. 查看日志
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. 停止
+docker compose -f docker/docker-compose.yml --profile gateway down
+```
+
+### Launcher 模式 (Web 控制台)
+
+`launcher` 镜像包含所有三个二进制文件（`picoclaw`、`picoclaw-launcher`、`picoclaw-launcher-tui`），默认启动 Web 控制台，提供基于浏览器的配置和聊天界面。
+
+```bash
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+```
+
+在浏览器中打开 http://localhost:18800。Launcher 会自动管理 Gateway 进程。
+
+> [!WARNING]
+> Web 控制台尚不支持身份验证。请勿将其暴露到公网。
+
+### Agent 模式 (一次性运行)
+
+```bash
+# 提问
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "2+2 等于几？"
+
+# 交互模式
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+```
+
+### 更新镜像
+
+```bash
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+---
+
+## 🚀 快速开始
+
+> [!TIP]
+> 在 `~/.picoclaw/config.json` 中设置您的 API Key。获取 API Key: [火山引擎 (CodingPlan)](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu (智谱)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)。网络搜索是 **可选的** — 获取免费的 [Tavily API](https://tavily.com) (每月 1000 次免费查询) 或 [Brave Search API](https://brave.com/search/api) (每月 2000 次免费查询)。
+
+**1. 初始化 (Initialize)**
+
+```bash
+picoclaw onboard
+```
+
+**2. 配置 (Configure)** (`~/.picoclaw/config.json`)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "gpt-5.4",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key",
+      "api_base":"https://ark.cn-beijing.volces.com/api/coding/v3"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "your-api-key",
+      "request_timeout": 300
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "your-anthropic-key"
+    }
+  ],
+  "tools": {
+    "web": {
+      "enabled": true,
+      "fetch_limit_bytes": 10485760,
+      "format": "plaintext",
+      "brave": {
+        "enabled": false,
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      },
+      "tavily": {
+        "enabled": false,
+        "api_key": "YOUR_TAVILY_API_KEY",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "YOUR_PERPLEXITY_API_KEY",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://your-searxng-instance:8888",
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+> **新功能**: `model_list` 配置格式支持零代码添加 provider。详见[模型配置](providers.md#模型配置-model_list)章节。
+> `request_timeout` 为可选项，单位为秒。若省略或设置为 `<= 0`，PicoClaw 使用默认超时（120 秒）。
+
+**3. 获取 API Key**
+
+* **LLM 提供商**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
+* **网络搜索** (可选):
+  * [Brave Search](https://brave.com/search/api) - 付费 ($5/1000 次查询，约 $5-6/月)
+  * [Perplexity](https://www.perplexity.ai) - AI 驱动的搜索与聊天界面
+  * [SearXNG](https://github.com/searxng/searxng) - 自建元搜索引擎（免费，无需 API Key）
+  * [Tavily](https://tavily.com) - 专为 AI Agent 优化 (1000 请求/月)
+  * DuckDuckGo - 内置回退（无需 API Key）
+
+> **注意**: 完整的配置模板请参考 `config.example.json`。
+
+**4. 对话 (Chat)**
+
+```bash
+picoclaw agent -m "2+2 等于几？"
+```
+
+就是这样！您在 2 分钟内就拥有了一个可工作的 AI 助手。
+
+---
diff --git a/docs/zh/hardware-compatibility.md b/docs/zh/hardware-compatibility.md
new file mode 100644
index 000000000..66bd08072
--- /dev/null
+++ b/docs/zh/hardware-compatibility.md
@@ -0,0 +1,152 @@
+> 返回 [README](../../README.zh.md)
+
+# 🖥️ PicoClaw 硬件兼容性列表
+
+PicoClaw 几乎可以在任何 Linux 设备上运行。本页面记录了已验证的芯片、产品和开发板。
+
+**你的硬件不在列表中？** 提交 PR 来添加它！欢迎硬件厂商贡献和联合推广。
+
+---
+
+## 1. 已验证的芯片支持
+
+### x86
+
+| 厂商 | 芯片 | 备注 |
+|------|------|------|
+| Intel | Any x86 CPU (i386+) | 所有桌面/服务器/笔记本处理器 |
+| AMD | Any x86 CPU | 所有桌面/服务器/笔记本处理器 |
+
+### ARM
+
+| 子架构 | 典型芯片 | 备注 |
+|--------|----------|------|
+| ARMv6 | [BCM2835](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2835) (Raspberry Pi 1/Zero) | 单核 ARM1176JZF-S |
+| ARMv7 | [Allwinner V3s](https://linux-sunxi.org/V3s) | 单核 Cortex-A7，用于 LicheePi Zero |
+| ARM64 | [Allwinner H618](https://linux-sunxi.org/H618) | 四核 Cortex-A53，用于 Orange Pi Zero 3 |
+| ARM64 | [BCM2711](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2711) (Raspberry Pi 4) | 四核 Cortex-A72 |
+| ARM64 | [BCM2712](https://www.raspberrypi.com/documentation/computers/processors.html#bcm2712) (Raspberry Pi 5) | 四核 Cortex-A76 |
+| ARM64 | [AX630C](https://www.axera-tech.com/) (爱芯元智) | 双核 Cortex-A53 + NPU，用于 NanoKVM-Pro / MaixCAM2 |
+
+### RISC-V (riscv64)
+
+| 厂商 | 芯片 | 核心 | 备注 |
+|------|------|------|------|
+| [SOPHGO (算能)](https://www.sophgo.com/) | SG2002 | C906 @ 1GHz | 256MB DDR3 片上内存，用于 LicheeRV-Nano / NanoKVM / MaixCAM |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V861 | Dual C907 | 128MB DDR3L 片上内存，1 TOPS NPU，4K AI 摄像头 SiP |
+| [Allwinner (全志)](https://www.allwinnertech.com/) | V881 | C907 | RISC-V AI 摄像头系列 |
+| [Arterytek (匠芯创)](https://www.arterytek.com/) | D213 | RISC-V | 用于 HaaS506-LD1 工业 RTU |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K1 | 8x X60 @ 1.8GHz | 用于 Milk-V Jupiter, BananaPi BPI-F3 |
+| [SpacemiT (进迭)](https://www.spacemit.com/) | K3 | 8x X100 @ 2.5GHz | 符合 RVA23 规范，1024 位 RVV，FP8 AI 推理 |
+| [Zhihe (知合)](https://www.zhihe-tech.com/) | A210 | High-perf RISC-V | 8 核，16MB L3 缓存，桌面级 |
+| [Canaan (嘉楠)](https://www.canaan-creative.com/) | K230 | Dual C908 @ 1.6GHz | 6 TOPS KPU，用于 CanMV-K230 |
+
+### MIPS
+
+| 厂商 | 芯片 | 备注 |
+|------|------|------|
+| MediaTek | [MT7620](https://www.mediatek.com/products/home-networking/mt7620) | MIPS24KEc @ 580MHz，用于许多 OpenWrt 路由器（如小米路由器 3G） |
+
+### LoongArch (loong64)
+
+| 厂商 | 芯片 | 备注 |
+|------|------|------|
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A5000 | 四核 LA464 @ 2.5GHz，桌面/工作站 |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 3A6000 | 四核 4C/8T @ 2.5GHz，IPC 可与 Intel 第十代相媲美 |
+| [Loongson (龙芯)](https://www.loongson.cn/) | 2K1000LA | 双核 @ 1GHz，工业/物联网应用 |
+
+---
+
+## 2. 已验证的产品（按发布日期排列）
+
+已通过 PicoClaw 测试的消费产品、路由器和工业设备。
+
+| 年份 | 产品 | 架构 | SoC | 内存 | 类别 |
+|------|------|------|-----|------|------|
+| 2009 | Nokia N900 | ARM (A8) | OMAP3430 | 256MB | 智能手机 |
+| 2012 | Samsung Galaxy Note 10.1 (N8000) | ARM (A9) | Exynos 4412 | 2GB | 平板电脑 |
+| 2016 | Xiaomi Router 3G (小米路由器3G) | MIPS | MT7620 | 256MB | 路由器 (OpenWrt) |
+| 2018 | Phicomm N1 (斐讯N1) | ARM64 (A53) | S905D | 2GB | 电视盒子 / 家庭服务器 |
+| 2019 | Xiaomi AI Speaker (小爱音箱) | ARM64 (A53) | — | 256MB | 智能音箱 |
+| 2024 | [NanoKVM](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM/introduction.html) | RISC-V | SG2002 | 256MB | IP-KVM |
+| 2025 | HaaS506-LD1 | RISC-V | D213 | 128MB | 工业 RTU |
+| 2025 | [NanoKVM-Pro](https://wiki.sipeed.com/hardware/en/kvm/NanoKVM_Pro/introduction.html) | ARM64 (A53) | AX630C | 1GB | 专业 IP-KVM |
+| 2026 | [MaixCAM2](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | ARM64 (A53) | AX630C | 1/4GB | 4K AI 摄像头 |
+
+---
+
+## 3. 已验证的开发板（按发布日期排列）
+
+| 年份 | 开发板 | 架构 | SoC | 内存 | 购买链接 |
+|------|--------|------|-----|------|----------|
+| 2012 | [Raspberry Pi 1 Model B](https://www.raspberrypi.com/products/) | ARMv6 | BCM2835 | 512MB | — |
+| 2015 | [Raspberry Pi 2 Model B](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) | ARMv7 (A7) | BCM2836 | 1GB | — |
+| 2015 | [Raspberry Pi Zero](https://www.raspberrypi.com/products/raspberry-pi-zero/) | ARMv6 | BCM2835 | 512MB | — |
+| 2016 | [Raspberry Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) | ARM64 (A53) | BCM2837 | 1GB | — |
+| 2017 | [LicheePi Zero](https://wiki.sipeed.com/hardware/en/lichee/Zero/Zero.html) | ARMv7 (A7) | Allwinner V3s | 64MB | [Sipeed](https://sipeed.com/) |
+| 2019 | [Raspberry Pi 4 Model B](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/) | ARM64 (A72) | BCM2711 | 1~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2023 | [Raspberry Pi 5](https://www.raspberrypi.com/products/raspberry-pi-5/) | ARM64 (A76) | BCM2712 | 2~8GB | [RPi](https://www.raspberrypi.com/) |
+| 2024 | [LicheeRV-Nano](https://wiki.sipeed.com/hardware/en/lichee/RV_Nano/1_intro.html) | RISC-V | SG2002 | 256MB | [AliExpress](https://www.aliexpress.com/item/1005006519668532.html) |
+| 2024 | [MaixCAM-Pro](https://wiki.sipeed.com/hardware/en/maixcam/index.html) | RISC-V | SG2002 | 256MB | [Sipeed](https://sipeed.com/) |
+| 2024 | [Milk-V Duo 64M](https://milkv.io/docs/duo/getting-started/duo) | RISC-V | CV1800B | 64MB | [Milk-V](https://milkv.io/) |
+| 2024 | [CanMV-K230](https://developer.canaan-creative.com/k230_canmv/en/main/) | RISC-V | K230 | 512MB | [Canaan](https://www.canaan-creative.com/) |
+
+---
+
+## 4. 同样适用于
+
+### Android 手机（通过 Termux）
+
+任何 ARM64 Android 手机（2015 年以后），1GB 以上内存。安装 [Termux](https://github.com/termux/termux-app)，使用 `proot` 运行 PicoClaw。
+
+> 参见 [README：在旧 Android 手机上运行](../../README.zh.md#-run-on-old-android-phones) 获取设置说明。
+
+### 桌面 / 服务器 / 云
+
+| 平台 | 备注 |
+|------|------|
+| x86_64 Linux | 原生二进制文件，无依赖 |
+| x86_64 Windows | 原生二进制文件 |
+| macOS (Intel / Apple Silicon) | 原生二进制文件 |
+| Docker (any platform) | `docker compose` 一行命令，参见 [Docker 指南](docker.md) |
+| OpenWrt routers | MIPS/ARM 构建，需要 >32MB 可用内存 |
+| FreeBSD / NetBSD | 提供 x86_64 和 arm64 构建 |
+
+---
+
+## 5. 最低要求
+
+| 资源 | 最低要求 | 推荐配置 |
+|------|----------|----------|
+| 内存 | 10MB 可用 | 32MB 以上可用 |
+| 存储 | 20MB（二进制文件） | 50MB 以上（含工作区） |
+| CPU | 任意（单核 0.6GHz 以上） | — |
+| 操作系统 | Linux (kernel 3.x+) | Linux 5.x+ |
+| 网络 | 必需（用于 LLM API 调用） | 以太网或 WiFi |
+
+---
+
+## 6. 如何测试与贡献
+
+```bash
+# 1. 下载适合你架构的版本
+wget https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw_Linux_arm64.tar.gz
+tar xzf picoclaw_Linux_arm64.tar.gz
+
+# 2. 初始化
+./picoclaw onboard
+
+# 3. 测试
+./picoclaw agent -m "Hello, what board am I running on?"
+```
+
+可用构建版本：`linux-amd64`, `linux-arm64`, `linux-arm`, `linux-riscv64`, `linux-loong64`, `linux-mipsle`
+
+### 添加你的硬件
+
+1. Fork 本仓库
+2. 将你的芯片/产品/开发板添加到相应的表格中
+3. 包含：名称、架构、SoC、内存、年份，以及可用的链接
+4. 提交 PR
+
+硬件厂商：想要添加官方支持或联合推广？请提交 issue 或通过 [Discord](https://discord.gg/V4sAZ9XWpN) 联系我们。
diff --git a/docs/zh/providers.md b/docs/zh/providers.md
new file mode 100644
index 000000000..e7b323ebf
--- /dev/null
+++ b/docs/zh/providers.md
@@ -0,0 +1,458 @@
+# 🔌 提供商与模型配置
+
+> 返回 [README](../../README.zh.md)
+
+### 提供商 (Providers)
+
+> [!NOTE]
+> 语音转录现在可以通过 `voice.model_name` 指定的多模态模型完成；如果未配置语音模型，Groq Whisper 仍可作为回退方案。
+
+| 提供商               | 用途                         | 获取 API Key                                                         |
+| -------------------- | ---------------------------- | -------------------------------------------------------------------- |
+| `gemini`             | LLM (Gemini 直连)            | [aistudio.google.com](https://aistudio.google.com)                   |
+| `zhipu`              | LLM (智谱直连)               | [bigmodel.cn](https://bigmodel.cn)                                   |
+| `volcengine`         | LLM (火山引擎直连)           | [volcengine.com](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| `openrouter`         | LLM (推荐，可访问所有模型)   | [openrouter.ai](https://openrouter.ai)                               |
+| `anthropic`          | LLM (Claude 直连)            | [console.anthropic.com](https://console.anthropic.com)               |
+| `openai`             | LLM (GPT 直连)               | [platform.openai.com](https://platform.openai.com)                   |
+| `deepseek`           | LLM (DeepSeek 直连)          | [platform.deepseek.com](https://platform.deepseek.com)               |
+| `qwen`               | LLM (通义千问)               | [dashscope.console.aliyun.com](https://dashscope.console.aliyun.com) |
+| `groq`               | LLM + **语音转录** (Whisper) | [console.groq.com](https://console.groq.com)                         |
+| `cerebras`           | LLM (Cerebras 直连)          | [cerebras.ai](https://cerebras.ai)                                   |
+| `vivgrid`            | LLM (Vivgrid 直连)           | [vivgrid.com](https://vivgrid.com)                                   |
+| `moonshot`           | LLM (Kimi/Moonshot 直连)     | [platform.moonshot.cn](https://platform.moonshot.cn)                 |
+| `minimax`            | LLM (Minimax 直连)           | [platform.minimaxi.com](https://platform.minimaxi.com)              |
+| `avian`              | LLM (Avian 直连)             | [avian.io](https://avian.io)                                         |
+| `mistral`            | LLM (Mistral 直连)           | [console.mistral.ai](https://console.mistral.ai)                    |
+| `longcat`            | LLM (Longcat 直连)           | [longcat.ai](https://longcat.ai)                                     |
+| `modelscope`         | LLM (ModelScope 直连)        | [modelscope.cn](https://modelscope.cn)                               |
+
+### 模型配置 (model_list)
+
+> **新功能！** PicoClaw 现在采用**以模型为中心**的配置方式。只需使用 `厂商/模型` 格式（如 `zhipu/glm-4.7`）即可添加新的 provider——**无需修改任何代码！**
+
+该设计同时支持**多 Agent 场景**，提供灵活的 Provider 选择：
+
+- **不同 Agent 使用不同 Provider**：每个 Agent 可以使用自己的 LLM provider
+- **模型回退（Fallback）**：配置主模型和备用模型，提高可靠性
+- **负载均衡**：在多个 API 端点之间分配请求
+- **集中化配置**：在一个地方管理所有 provider
+
+#### 📋 所有支持的厂商
+
+| 厂商                | `model` 前缀      | 默认 API Base                                       | 协议      | 获取 API Key                                                      |
+| ------------------- | ----------------- | --------------------------------------------------- | --------- | ----------------------------------------------------------------- |
+| **OpenAI**          | `openai/`         | `https://api.openai.com/v1`                         | OpenAI    | [获取密钥](https://platform.openai.com)                           |
+| **Anthropic**       | `anthropic/`      | `https://api.anthropic.com/v1`                      | Anthropic | [获取密钥](https://console.anthropic.com)                         |
+| **智谱 AI (GLM)**   | `zhipu/`          | `https://open.bigmodel.cn/api/paas/v4`              | OpenAI    | [获取密钥](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) |
+| **DeepSeek**        | `deepseek/`       | `https://api.deepseek.com/v1`                       | OpenAI    | [获取密钥](https://platform.deepseek.com)                         |
+| **Google Gemini**   | `gemini/`         | `https://generativelanguage.googleapis.com/v1beta`  | OpenAI    | [获取密钥](https://aistudio.google.com/api-keys)                  |
+| **Groq**            | `groq/`           | `https://api.groq.com/openai/v1`                    | OpenAI    | [获取密钥](https://console.groq.com)                              |
+| **Moonshot**        | `moonshot/`       | `https://api.moonshot.cn/v1`                        | OpenAI    | [获取密钥](https://platform.moonshot.cn)                          |
+| **通义千问 (Qwen)** | `qwen/`           | `https://dashscope.aliyuncs.com/compatible-mode/v1` | OpenAI    | [获取密钥](https://dashscope.console.aliyun.com)                  |
+| **NVIDIA**          | `nvidia/`         | `https://integrate.api.nvidia.com/v1`               | OpenAI    | [获取密钥](https://build.nvidia.com)                              |
+| **Ollama**          | `ollama/`         | `http://localhost:11434/v1`                         | OpenAI    | 本地（无需密钥）                                                  |
+| **OpenRouter**      | `openrouter/`     | `https://openrouter.ai/api/v1`                      | OpenAI    | [获取密钥](https://openrouter.ai/keys)                            |
+| **LiteLLM Proxy**   | `litellm/`        | `http://localhost:4000/v1`                          | OpenAI    | 你的 LiteLLM 代理密钥                                             |
+| **VLLM**            | `vllm/`           | `http://localhost:8000/v1`                          | OpenAI    | 本地                                                              |
+| **Cerebras**        | `cerebras/`       | `https://api.cerebras.ai/v1`                        | OpenAI    | [获取密钥](https://cerebras.ai)                                   |
+| **火山引擎（Doubao）** | `volcengine/`  | `https://ark.cn-beijing.volces.com/api/v3`          | OpenAI    | [获取密钥](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) |
+| **神算云**          | `shengsuanyun/`   | `https://router.shengsuanyun.com/api/v1`            | OpenAI    | -                                                                 |
+| **BytePlus**        | `byteplus/`       | `https://ark.ap-southeast.bytepluses.com/api/v3`    | OpenAI    | [获取密钥](https://www.byteplus.com)                              |
+| **Vivgrid**         | `vivgrid/`        | `https://api.vivgrid.com/v1`                        | OpenAI    | [获取密钥](https://vivgrid.com)                                   |
+| **LongCat**         | `longcat/`        | `https://api.longcat.chat/openai`                   | OpenAI    | [获取密钥](https://longcat.chat/platform)                         |
+| **ModelScope (魔搭)**| `modelscope/`    | `https://api-inference.modelscope.cn/v1`            | OpenAI    | [获取 Token](https://modelscope.cn/my/tokens)                    |
+| **Antigravity**     | `antigravity/`    | Google Cloud                                        | 自定义    | 仅 OAuth                                                          |
+| **GitHub Copilot**  | `github-copilot/` | `localhost:4321`                                    | gRPC      | -                                                                 |
+
+#### 基础配置示例
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-openai-key"
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "sk-ant-your-key"
+    },
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-zhipu-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "gpt-5.4"
+    }
+  }
+}
+```
+
+#### 语音转录
+
+你可以通过 `voice.model_name` 为语音转录指定一个专用模型。这样可以直接复用已经配置好的、支持音频输入的多模态 provider，而不必只依赖 Groq。
+
+如果没有配置 `voice.model_name`，且存在 Groq API Key，PicoClaw 会继续回退到 Groq 转录。
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "voice-gemini",
+      "model": "gemini/gemini-2.5-flash",
+      "api_key": "your-gemini-key"
+    }
+  ],
+  "voice": {
+    "model_name": "voice-gemini",
+    "echo_transcription": false
+  },
+  "providers": {
+    "groq": {
+      "api_key": "gsk_xxx"
+    }
+  }
+}
+```
+
+#### 各厂商配置示例
+
+**OpenAI**
+
+```json
+{
+  "model_name": "gpt-5.4",
+  "model": "openai/gpt-5.4",
+  "api_key": "sk-..."
+}
+```
+
+**火山引擎（Doubao）**
+
+```json
+{
+  "model_name": "ark-code-latest",
+  "model": "volcengine/ark-code-latest",
+  "api_key": "sk-..."
+}
+```
+
+**智谱 AI (GLM)**
+
+```json
+{
+  "model_name": "glm-4.7",
+  "model": "zhipu/glm-4.7",
+  "api_key": "your-key"
+}
+```
+
+**DeepSeek**
+
+```json
+{
+  "model_name": "deepseek-chat",
+  "model": "deepseek/deepseek-chat",
+  "api_key": "sk-..."
+}
+```
+
+**Anthropic (使用 OAuth)**
+
+```json
+{
+  "model_name": "claude-sonnet-4.6",
+  "model": "anthropic/claude-sonnet-4.6",
+  "auth_method": "oauth"
+}
+```
+
+> 运行 `picoclaw auth login --provider anthropic` 来设置 OAuth 凭证。
+
+**Anthropic Messages API（原生格式）**
+
+用于直接访问 Anthropic API 或仅支持 Anthropic 原生消息格式的自定义端点：
+
+```json
+{
+  "model_name": "claude-opus-4-6",
+  "model": "anthropic-messages/claude-opus-4-6",
+  "api_key": "sk-ant-your-key",
+  "api_base": "https://api.anthropic.com"
+}
+```
+
+> 使用 `anthropic-messages` 协议的场景：
+> - 使用仅支持 Anthropic 原生 `/v1/messages` 端点的第三方代理（不支持 OpenAI 兼容的 `/v1/chat/completions`）
+> - 连接到 MiniMax、Synthetic 等需要 Anthropic 原生消息格式的服务
+> - 现有的 `anthropic` 协议返回 404 错误（说明端点不支持 OpenAI 兼容格式）
+>
+> **注意：** `anthropic` 协议使用 OpenAI 兼容格式（`/v1/chat/completions`），而 `anthropic-messages` 使用 Anthropic 原生格式（`/v1/messages`）。请根据端点支持的格式选择。
+
+**Ollama (本地)**
+
+```json
+{
+  "model_name": "llama3",
+  "model": "ollama/llama3"
+}
+```
+
+**自定义代理/API**
+
+```json
+{
+  "model_name": "my-custom-model",
+  "model": "openai/custom-model",
+  "api_base": "https://my-proxy.com/v1",
+  "api_key": "sk-...",
+  "request_timeout": 300
+}
+```
+
+**LiteLLM Proxy**
+
+```json
+{
+  "model_name": "lite-gpt4",
+  "model": "litellm/lite-gpt4",
+  "api_base": "http://localhost:4000/v1",
+  "api_key": "sk-..."
+}
+```
+
+PicoClaw 在发送请求前仅去除外层 `litellm/` 前缀，因此 `litellm/lite-gpt4` 会发送 `lite-gpt4`，而 `litellm/openai/gpt-4o` 会发送 `openai/gpt-4o`。
+
+#### 负载均衡
+
+为同一个模型名称配置多个端点——PicoClaw 会自动在它们之间轮询：
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api1.example.com/v1",
+      "api_key": "sk-key1"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api2.example.com/v1",
+      "api_key": "sk-key2"
+    }
+  ]
+}
+```
+
+#### 从旧的 `providers` 配置迁移
+
+旧的 `providers` 配置格式**已弃用**，但为向后兼容仍支持。
+
+**旧配置（已弃用）：**
+
+```json
+{
+  "providers": {
+    "zhipu": {
+      "api_key": "your-key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  },
+  "agents": {
+    "defaults": {
+      "provider": "zhipu",
+      "model": "glm-4.7"
+    }
+  }
+}
+```
+
+**新配置（推荐）：**
+
+```json
+{
+  "model_list": [
+    {
+      "model_name": "glm-4.7",
+      "model": "zhipu/glm-4.7",
+      "api_key": "your-key"
+    }
+  ],
+  "agents": {
+    "defaults": {
+      "model_name": "glm-4.7"
+    }
+  }
+}
+```
+
+详细的迁移指南请参考 [docs/migration/model-list-migration.md](../migration/model-list-migration.md)。
+
+### Provider 架构
+
+PicoClaw 按协议族路由 Provider：
+
+- OpenAI 兼容协议：OpenRouter、OpenAI 兼容网关、Groq、智谱、vLLM 风格端点。
+- Anthropic 协议：Claude 原生 API 行为。
+- Codex/OAuth 路径：OpenAI OAuth/Token 认证路由。
+
+这使得运行时保持轻量，同时让新的 OpenAI 兼容后端基本只需配置操作（`api_base` + `api_key`）。
+
+<details>
+<summary><b>智谱 (Zhipu) 配置示例</b></summary>
+
+**1. 获取 API key 和 base URL**
+
+- 获取 [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
+
+**2. 配置**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "providers": {
+    "zhipu": {
+      "api_key": "Your API Key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  }
+}
+```
+
+**3. 运行**
+
+```bash
+picoclaw agent -m "你好"
+```
+
+</details>
+
+<details>
+<summary><b>完整配置示例</b></summary>
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "anthropic/claude-opus-4-5"
+    }
+  },
+  "session": {
+    "dm_scope": "per-channel-peer"
+  },
+  "providers": {
+    "openrouter": {
+      "api_key": "sk-or-v1-xxx"
+    },
+    "groq": {
+      "api_key": "gsk_xxx"
+    }
+  },
+  "voice": {
+    "model_name": "voice-gemini",
+    "echo_transcription": false
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456:ABC...",
+      "allow_from": ["123456789"]
+    },
+    "discord": {
+      "enabled": true,
+      "token": "",
+      "allow_from": [""]
+    },
+    "whatsapp": {
+      "enabled": false,
+      "bridge_url": "ws://localhost:3001",
+      "use_native": false,
+      "session_store_path": "",
+      "allow_from": []
+    },
+    "feishu": {
+      "enabled": false,
+      "app_id": "cli_xxx",
+      "app_secret": "xxx",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    },
+    "qq": {
+      "enabled": false,
+      "app_id": "",
+      "app_secret": "",
+      "allow_from": []
+    }
+  },
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": false,
+        "api_key": "BSA...",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://localhost:8888",
+        "max_results": 5
+      }
+    },
+    "cron": {
+      "exec_timeout_minutes": 5
+    }
+  },
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+</details>
+
+---
+
+## 📝 API Key 对比
+
+| 服务 | 价格 | 适用场景 |
+| --- | --- | --- |
+| **OpenRouter** | 免费: 200K tokens/月 | 多模型聚合 (Claude, GPT-4 等) |
+| **火山引擎 CodingPlan** | ¥9.9/首月 | 最适合国内用户，多种 SOTA 模型（豆包、DeepSeek 等） |
+| **智谱 (Zhipu)** | 免费: 200K tokens/月 | 适合中国用户 |
+| **Brave Search** | $5/1000 次查询 | 网络搜索功能 |
+| **SearXNG** | 免费（自建） | 隐私优先的元搜索引擎（70+ 搜索引擎） |
+| **Groq** | 免费额度可用 | 极速推理 (Llama, Mixtral) |
+| **Cerebras** | 免费额度可用 | 极速推理 (Llama, Qwen 等) |
+| **LongCat** | 免费: 最多 5M tokens/天 | 极速推理 |
+| **ModelScope (魔搭)** | 免费: 2000 次请求/天 | 推理 (Qwen, GLM, DeepSeek 等) |
diff --git a/docs/zh/sensitive_data_filtering.md b/docs/zh/sensitive_data_filtering.md
new file mode 100644
index 000000000..4382706ed
--- /dev/null
+++ b/docs/zh/sensitive_data_filtering.md
@@ -0,0 +1,107 @@
+# 敏感数据过滤
+
+PicoClaw 可以从工具调用结果中过滤敏感值（API 密钥、令牌、密码等），然后再发送给 LLM。这可以防止 LLM 看到自己的凭据，避免通过工具输出泄露或产生混淆行为。
+
+---
+
+## 概述
+
+当 LLM 使用的工具返回其自身的凭据时（例如，一个回显正在使用的 API 密钥的工具），这些值会自动替换为 `[FILTERED]` 再发送给 LLM。
+
+敏感值从 `.security.yml` 中收集 —— 这是所有敏感配置的集中存储，包括：
+
+- 模型 API 密钥
+- 频道令牌（Telegram、Discord、Slack、Matrix 等）
+- Web 工具 API 密钥（Brave、Tavily、Perplexity 等）
+- 技能令牌（GitHub、ClawHub）
+
+---
+
+## 配置
+
+敏感数据过滤在 `config.json` 的 `tools` 部分配置：
+
+| 配置 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `filter_sensitive_data` | bool | `true` | 启用/禁用过滤。为 `false` 时，不进行任何过滤。 |
+| `filter_min_length` | int | `8` | 触发过滤的最小内容长度。短内容会被跳过以提高性能。 |
+
+```json
+{
+  "tools": {
+    "filter_sensitive_data": true,
+    "filter_min_length": 8
+  }
+}
+```
+
+### 环境变量
+
+| 变量 | 说明 |
+|------|------|
+| `PICOCLAW_TOOLS_FILTER_SENSITIVE_DATA` | 设置为 `true` 或 `false` 以覆盖配置值 |
+
+---
+
+## 工作原理
+
+1. **启动时**：使用反射从 `.security.yml` 中收集所有敏感值，并编译成 `strings.Replacer`（O(n+m) 性能，仅计算一次）。
+
+2. **每个工具结果**：在将任何工具结果发送给 LLM 之前：
+   - 如果 `filter_sensitive_data` 为 `false`，内容原样传递
+   - 如果内容长度 < `filter_min_length`，内容原样传递（快速路径）
+   - 否则，所有敏感值都会被替换为 `[FILTERED]`
+
+3. **替换**：使用 `strings.Replacer` 进行高效的 O(n+m) 字符串替换，其中 n = 内容长度，m = 敏感值总长度。
+
+---
+
+## 示例
+
+给定以下 `.security.yml`：
+
+```yaml
+model_list:
+  my-model:
+    api_keys:
+      - sk-secret-key-12345
+
+channels:
+  telegram:
+    token: "123456:ABC-DEF"
+```
+
+以及包含以下内容的工具结果：
+
+```
+The model is using API key sk-secret-key-12345 and Telegram bot 123456:ABC-DEF
+```
+
+LLM 将收到：
+
+```
+The model is using API key [FILTERED] and Telegram bot [FILTERED]
+```
+
+---
+
+## 性能
+
+- **快速路径**：短于 `filter_min_length`（默认 8）的内容会直接返回，不进行任何字符串扫描
+- **高效替换**：使用 `strings.Replacer`，复杂度为 O(n+m)，而非正则表达式
+- **延迟初始化**：替换映射通过 `sync.Once` 在首次访问时构建一次
+
+---
+
+## 安全注意事项
+
+- **凭据泄露防护**：如果没有过滤，返回凭据的工具可能导致 LLM 看到自己的 API 密钥，可能导致日志中泄露凭据或产生混淆
+- **纵深防御**：过滤是对凭据加密的补充（而非替代）—— 应同时使用这两个功能
+- **无误报**：只有明确存储在 `.security.yml` 中的值才会被过滤；LLM 的通用知识不受影响
+
+---
+
+## 相关文档
+
+- [凭据加密](../credential_encryption.md) — 配置中 API 密钥的加密
+- [工具配置](../tools_configuration.md)
diff --git a/docs/zh/spawn-tasks.md b/docs/zh/spawn-tasks.md
new file mode 100644
index 000000000..781462af2
--- /dev/null
+++ b/docs/zh/spawn-tasks.md
@@ -0,0 +1,70 @@
+# 🔄 异步任务与 Spawn
+
+> 返回 [README](../../README.zh.md)
+
+PicoClaw 通过 `spawn` 工具支持**异步任务执行**。主要由 **Heartbeat（心跳）** 系统使用，在不阻塞主 Agent 循环的情况下运行耗时任务。
+
+## Heartbeat
+
+心跳系统会定期检查 `workspace/HEARTBEAT.md` 中的计划任务。首次运行时会自动生成默认模板，你可以自定义它来定义快速任务（内联处理）和长任务（通过 `spawn` 委派）。
+
+**`HEARTBEAT.md` 示例：**
+
+```markdown
+## Quick Tasks (respond directly)
+
+- Report current time
+
+## Long Tasks (use spawn for async)
+
+- Search the web for AI news and summarize
+- Check email and report important messages
+```
+
+**关键行为：**
+
+| 特性             | 描述                                     |
+| ---------------- | ---------------------------------------- |
+| **spawn**        | 创建异步子 Agent，不阻塞主心跳进程       |
+| **独立上下文**   | 子 Agent 拥有独立上下文，无会话历史      |
+| **message tool** | 子 Agent 通过 message 工具直接与用户通信 |
+| **非阻塞**       | spawn 后，心跳继续处理下一个任务         |
+
+#### 子 Agent 通信原理
+
+```
+心跳触发 (Heartbeat triggers)
+    ↓
+Agent 读取 HEARTBEAT.md
+    ↓
+对于长任务: spawn 子 Agent
+    ↓                           ↓
+继续下一个任务               子 Agent 独立工作
+    ↓                           ↓
+所有任务完成                 子 Agent 使用 "message" 工具
+    ↓                           ↓
+响应 HEARTBEAT_OK            用户直接收到结果
+```
+
+子 Agent 可以访问工具（message, web_search 等），并且无需通过主 Agent 即可独立与用户通信。
+
+**配置：**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| 选项       | 默认值 | 描述                         |
+| ---------- | ------ | ---------------------------- |
+| `enabled`  | `true` | 启用/禁用心跳                |
+| `interval` | `30`   | 检查间隔，单位分钟 (最小: 5) |
+
+**环境变量:**
+
+- `PICOCLAW_HEARTBEAT_ENABLED=false` 禁用
+- `PICOCLAW_HEARTBEAT_INTERVAL=60` 更改间隔
diff --git a/docs/zh/tools_configuration.md b/docs/zh/tools_configuration.md
new file mode 100644
index 000000000..63ac5000b
--- /dev/null
+++ b/docs/zh/tools_configuration.md
@@ -0,0 +1,463 @@
+# 🔧 工具配置
+
+> 返回 [README](../../README.zh.md)
+
+PicoClaw 的工具配置位于 `config.json` 的 `tools` 字段中。
+
+## 目录结构
+
+```json
+{
+  "tools": {
+    "web": {
+      ...
+    },
+    "mcp": {
+      ...
+    },
+    "exec": {
+      ...
+    },
+    "cron": {
+      ...
+    },
+    "skills": {
+      ...
+    }
+  }
+}
+```
+
+## 敏感数据过滤
+
+在将工具结果发送给 LLM 之前，PicoClaw 可以从输出中过滤敏感值（API 密钥、令牌、密码）。这可以防止 LLM 看到自己的凭据。
+
+详细说明请参阅[敏感数据过滤](../sensitive_data_filtering.md)。
+
+| 配置项 | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| `filter_sensitive_data` | bool | `true` | 启用/禁用过滤 |
+| `filter_min_length` | int | `8` | 触发过滤的最小内容长度 |
+
+## Web 工具
+
+Web 工具用于网页搜索和抓取。
+
+### Web Fetcher
+用于抓取和处理网页内容的通用设置。
+
+| 配置项              | 类型   | 默认值        | 描述                                                                                   |
+|---------------------|--------|---------------|----------------------------------------------------------------------------------------|
+| `enabled`           | bool   | true          | 启用网页抓取功能。                                                                     |
+| `fetch_limit_bytes` | int    | 10485760      | 抓取网页负载的最大大小，单位为字节（默认 10MB）。                                      |
+| `format`            | string | "plaintext"   | 抓取内容的输出格式。选项：`plaintext` 或 `markdown`（推荐）。                          |
+
+### 百度搜索
+
+使用[千帆 AI 搜索 API](https://cloud.baidu.com/doc/qianfan-api/s/Wmbq4z7e5)，国内访问稳定，中文搜索效果好。
+
+| 配置项        | 类型   | 默认值                                                          | 描述                  |
+|---------------|--------|----------------------------------------------------------------|-----------------------|
+| `enabled`     | bool   | false                                                          | 启用百度搜索          |
+| `api_key`     | string | -                                                              | 千帆 API 密钥         |
+| `base_url`    | string | `https://qianfan.baidubce.com/v2/ai_search/web_search`        | 百度搜索 API URL      |
+| `max_results` | int    | 10                                                             | 最大结果数            |
+
+```json
+{
+  "tools": {
+    "web": {
+      "baidu_search": {
+        "enabled": true,
+        "api_key": "YOUR_BAIDU_QIANFAN_API_KEY",
+        "max_results": 10
+      }
+    }
+  }
+}
+```
+
+### Tavily
+
+| 配置项        | 类型   | 默认值 | 描述                              |
+|---------------|--------|--------|-----------------------------------|
+| `enabled`     | bool   | false  | 启用 Tavily 搜索                  |
+| `api_key`     | string | -      | Tavily API 密钥                   |
+| `base_url`    | string | -      | 自定义 Tavily API 基础 URL        |
+| `max_results` | int    | 0      | 最大结果数（0 = 默认）            |
+
+### GLM Search
+
+| 配置项          | 类型   | 默认值                                               | 描述                  |
+|-----------------|--------|------------------------------------------------------|-----------------------|
+| `enabled`       | bool   | false                                                | 启用 GLM 搜索        |
+| `api_key`       | string | -                                                    | GLM API 密钥          |
+| `base_url`      | string | `https://open.bigmodel.cn/api/paas/v4/web_search`   | GLM Search API URL    |
+| `search_engine` | string | `search_std`                                         | 搜索引擎类型          |
+| `max_results`   | int    | 5                                                    | 最大结果数            |
+
+### DuckDuckGo
+
+> ⚠️ 国内访问困难，建议搭配代理使用。
+
+| 配置项        | 类型 | 默认值 | 描述                  |
+|---------------|------|--------|-----------------------|
+| `enabled`     | bool | true   | 启用 DuckDuckGo 搜索  |
+| `max_results` | int  | 5      | 最大结果数            |
+
+### Perplexity
+
+> ⚠️ 国内访问困难，建议搭配代理使用。
+
+| 配置项        | 类型     | 默认值 | 描述                                           |
+|---------------|----------|--------|------------------------------------------------|
+| `enabled`     | bool     | false  | 启用 Perplexity 搜索                           |
+| `api_key`     | string   | -      | Perplexity API 密钥                            |
+| `api_keys`    | string[] | -      | 多个 API 密钥轮换（优先于 `api_key`）          |
+| `max_results` | int      | 5      | 最大结果数                                     |
+
+### Brave
+
+> ⚠️ 国内访问困难，建议搭配代理使用。
+
+| 配置项        | 类型     | 默认值 | 描述                                           |
+|---------------|----------|--------|------------------------------------------------|
+| `enabled`     | bool     | false  | 启用 Brave 搜索                                |
+| `api_key`     | string   | -      | Brave Search API 密钥                          |
+| `api_keys`    | string[] | -      | 多个 API 密钥轮换（优先于 `api_key`）          |
+| `max_results` | int      | 5      | 最大结果数                                     |
+
+### SearXNG
+
+| 配置项        | 类型   | 默认值                   | 描述                  |
+|---------------|--------|--------------------------|-----------------------|
+| `enabled`     | bool   | false                    | 启用 SearXNG 搜索     |
+| `base_url`    | string | `http://localhost:8888`  | SearXNG 实例 URL      |
+| `max_results` | int    | 5                        | 最大结果数            |
+
+### 其他 Web 设置
+
+| 配置项                   | 类型     | 默认值 | 描述                                           |
+|--------------------------|----------|--------|-------------------------------------------------|
+| `prefer_native`          | bool     | true   | 优先使用 provider 原生搜索而非配置的搜索引擎    |
+| `private_host_whitelist` | string[] | `[]`   | 允许 Web 抓取的私有/内部主机白名单              |
+
+## Exec 工具
+
+Exec 工具用于执行 shell 命令。
+
+| 配置项                 | 类型  | 默认值 | 描述                           |
+|------------------------|-------|--------|--------------------------------|
+| `enabled`              | bool  | true   | 启用 exec 工具                 |
+| `enable_deny_patterns` | bool  | true   | 启用默认的危险命令拦截         |
+| `custom_deny_patterns` | array | []     | 自定义拒绝模式（正则表达式）   |
+
+### 禁用 Exec 工具
+
+要完全禁用 `exec` 工具，请将 `enabled` 设置为 `false`：
+
+**通过配置文件：**
+```json
+{
+  "tools": {
+    "exec": {
+      "enabled": false
+    }
+  }
+}
+```
+
+**通过环境变量：**
+```bash
+PICOCLAW_TOOLS_EXEC_ENABLED=false
+```
+
+> **注意：** 禁用后，代理将无法执行 shell 命令。这也会影响 Cron 工具运行计划 shell 命令的能力。
+
+### 功能说明
+
+- **`enable_deny_patterns`**：设为 `false` 可完全禁用默认的危险命令拦截模式
+- **`custom_deny_patterns`**：添加自定义拒绝正则模式；匹配的命令将被拦截
+
+### 默认拦截的命令模式
+
+默认情况下，PicoClaw 会拦截以下危险命令：
+
+- 删除命令：`rm -rf`、`del /f/q`、`rmdir /s`
+- 磁盘操作：`format`、`mkfs`、`diskpart`、`dd if=`、写入 `/dev/sd*`
+- 系统操作：`shutdown`、`reboot`、`poweroff`
+- 命令替换：`$()`、`${}`、反引号
+- 管道到 shell：`| sh`、`| bash`
+- 权限提升：`sudo`、`chmod`、`chown`
+- 进程控制：`pkill`、`killall`、`kill -9`
+- 远程操作：`curl | sh`、`wget | sh`、`ssh`
+- 包管理：`apt`、`yum`、`dnf`、`npm install -g`、`pip install --user`
+- 容器：`docker run`、`docker exec`
+- Git：`git push`、`git force`
+- 其他：`eval`、`source *.sh`
+
+### 已知架构限制
+
+exec 守卫仅验证发送给 PicoClaw 的顶层命令。它**不会**递归检查该命令启动后由构建工具或脚本生成的子进程。
+
+以下工作流在初始命令被允许后可以绕过直接命令守卫：
+
+- `make run`
+- `go run ./cmd/...`
+- `cargo run`
+- `npm run build`
+
+这意味着守卫对于拦截明显危险的直接命令很有用，但它**不是**未审查构建管道的完整沙箱。如果你的威胁模型包括工作区中的不受信任代码，请使用更强的隔离措施，如容器、虚拟机或围绕构建和运行命令的审批流程。
+
+### 配置示例
+
+```json
+{
+  "tools": {
+    "exec": {
+      "enable_deny_patterns": true,
+      "custom_deny_patterns": [
+        "\\brm\\s+-r\\b",
+        "\\bkillall\\s+python"
+      ]
+    }
+  }
+}
+```
+
+## Cron 工具
+
+Cron 工具用于调度周期性任务。
+
+| 配置项                 | 类型 | 默认值 | 描述                                |
+|------------------------|------|--------|-------------------------------------|
+| `exec_timeout_minutes` | int  | 5      | 执行超时时间（分钟），0 表示无限制  |
+| `allow_command`        | bool | false  | 允许 cron 任务执行 shell 命令       |
+
+## MCP 工具
+
+MCP 工具支持与外部 Model Context Protocol 服务器集成。
+
+### 工具发现（延迟加载）
+
+当连接多个 MCP 服务器时，同时暴露数百个工具可能会耗尽 LLM 的上下文窗口并增加 API 成本。**Discovery** 功能通过默认*隐藏* MCP 工具来解决此问题。
+
+LLM 不会加载所有工具，而是获得一个轻量级搜索工具（使用 BM25 关键词匹配或正则表达式）。当 LLM 需要特定功能时，它会搜索隐藏的工具库。匹配的工具随后被临时"解锁"并注入上下文中，持续配置的轮数（`ttl`）。
+
+### 全局配置
+
+| 配置项      | 类型   | 默认值 | 描述                                 |
+|-------------|--------|--------|--------------------------------------|
+| `enabled`   | bool   | false  | 全局启用 MCP 集成                    |
+| `discovery` | object | `{}`   | 工具发现配置（见下文）               |
+| `servers`   | object | `{}`   | 服务器名称到服务器配置的映射         |
+
+### Discovery 配置（`discovery`）
+
+| 配置项               | 类型 | 默认值 | 描述                                                                                                          |
+|----------------------|------|--------|---------------------------------------------------------------------------------------------------------------|
+| `enabled`            | bool | false  | 如果为 true，MCP 工具将被隐藏并按需通过搜索加载。如果为 false，所有工具都会被加载                             |
+| `ttl`                | int  | 5      | 已发现工具保持解锁状态的对话轮数                                                                              |
+| `max_search_results` | int  | 5      | 每次搜索查询返回的最大工具数                                                                                  |
+| `use_bm25`           | bool | true   | 启用自然语言/关键词搜索工具（`tool_search_tool_bm25`）。**警告**：比正则搜索消耗更多资源                       |
+| `use_regex`          | bool | false  | 启用正则模式搜索工具（`tool_search_tool_regex`）                                                              |
+
+> **注意：** 如果 `discovery.enabled` 为 `true`，你**必须**启用至少一个搜索引擎（`use_bm25` 或 `use_regex`），
+> 否则应用程序将无法启动。
+
+### 单服务器配置
+
+| 配置项     | 类型   | 必需     | 描述                               |
+|------------|--------|----------|------------------------------------|
+| `enabled`  | bool   | 是       | 启用此 MCP 服务器                  |
+| `type`     | string | 否       | 传输类型：`stdio`、`sse`、`http`   |
+| `command`  | string | stdio    | stdio 传输的可执行命令             |
+| `args`     | array  | 否       | stdio 传输的命令参数               |
+| `env`      | object | 否       | stdio 进程的环境变量               |
+| `env_file` | string | 否       | stdio 进程的环境文件路径           |
+| `url`      | string | sse/http | `sse`/`http` 传输的端点 URL        |
+| `headers`  | object | 否       | `sse`/`http` 传输的 HTTP 头        |
+
+### 传输行为
+
+- 如果省略 `type`，传输方式将自动检测：
+    - 设置了 `url` → `sse`
+    - 设置了 `command` → `stdio`
+- `http` 和 `sse` 都使用 `url` + 可选的 `headers`。
+- `env` 和 `env_file` 仅应用于 `stdio` 服务器。
+
+### 配置示例
+
+#### 1) Stdio MCP 服务器
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "filesystem": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-filesystem",
+            "/tmp"
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+#### 2) 远程 SSE/HTTP MCP 服务器
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "servers": {
+        "remote-mcp": {
+          "enabled": true,
+          "type": "sse",
+          "url": "https://example.com/mcp",
+          "headers": {
+            "Authorization": "Bearer YOUR_TOKEN"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+#### 3) 启用工具发现的大规模 MCP 设置
+
+*在此示例中，LLM 只会看到 `tool_search_tool_bm25`。它将仅在用户请求时动态搜索并解锁 Github 或 Postgres 工具。*
+
+```json
+{
+  "tools": {
+    "mcp": {
+      "enabled": true,
+      "discovery": {
+        "enabled": true,
+        "ttl": 5,
+        "max_search_results": 5,
+        "use_bm25": true,
+        "use_regex": false
+      },
+      "servers": {
+        "github": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-github"
+          ],
+          "env": {
+            "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
+          }
+        },
+        "postgres": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-postgres",
+            "postgresql://user:password@localhost/dbname"
+          ]
+        },
+        "slack": {
+          "enabled": true,
+          "command": "npx",
+          "args": [
+            "-y",
+            "@modelcontextprotocol/server-slack"
+          ],
+          "env": {
+            "SLACK_BOT_TOKEN": "YOUR_SLACK_BOT_TOKEN",
+            "SLACK_TEAM_ID": "YOUR_SLACK_TEAM_ID"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Skills 工具
+
+Skills 工具配置通过 ClawHub 等注册表进行技能发现和安装。
+
+### 注册表
+
+| 配置项                             | 类型   | 默认值               | 描述                                 |
+|------------------------------------|--------|----------------------|--------------------------------------|
+| `registries.clawhub.enabled`       | bool   | true                 | 启用 ClawHub 注册表                  |
+| `registries.clawhub.base_url`      | string | `https://clawhub.ai` | ClawHub 基础 URL                     |
+| `registries.clawhub.auth_token`    | string | `""`                 | 可选的 Bearer 令牌，用于更高速率限制 |
+| `registries.clawhub.search_path`   | string | `""`                 | 搜索 API 路径                        |
+| `registries.clawhub.skills_path`   | string | `""`                 | Skills API 路径                      |
+| `registries.clawhub.download_path` | string | `""`                 | 下载 API 路径                        |
+| `registries.clawhub.timeout`       | int    | 0                    | 请求超时时间（秒），0 = 默认         |
+| `registries.clawhub.max_zip_size`  | int    | 0                    | 技能 zip 最大大小（字节），0 = 默认  |
+| `registries.clawhub.max_response_size` | int | 0                   | API 响应最大大小（字节），0 = 默认   |
+
+### GitHub 集成
+
+| 配置项           | 类型   | 默认值 | 描述                          |
+|------------------|--------|--------|-------------------------------|
+| `github.proxy`   | string | `""`   | GitHub API 请求的 HTTP 代理   |
+| `github.token`   | string | `""`   | GitHub 个人访问令牌           |
+
+### 搜索设置
+
+| 配置项                     | 类型 | 默认值 | 描述                     |
+|----------------------------|------|--------|--------------------------|
+| `max_concurrent_searches`  | int  | 2      | 最大并发技能搜索请求数   |
+| `search_cache.max_size`    | int  | 50     | 最大缓存搜索结果数       |
+| `search_cache.ttl_seconds` | int  | 300    | 缓存 TTL（秒）           |
+
+### 配置示例
+
+```json
+{
+  "tools": {
+    "skills": {
+      "registries": {
+        "clawhub": {
+          "enabled": true,
+          "base_url": "https://clawhub.ai",
+          "auth_token": ""
+        }
+      },
+      "github": {
+        "proxy": "",
+        "token": ""
+      },
+      "max_concurrent_searches": 2,
+      "search_cache": {
+        "max_size": 50,
+        "ttl_seconds": 300
+      }
+    }
+  }
+}
+```
+
+## 环境变量
+
+所有配置选项都可以通过格式为 `PICOCLAW_TOOLS_<SECTION>_<KEY>` 的环境变量覆盖：
+
+例如：
+
+- `PICOCLAW_TOOLS_WEB_BRAVE_ENABLED=true`
+- `PICOCLAW_TOOLS_EXEC_ENABLED=false`
+- `PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS=false`
+- `PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES=10`
+- `PICOCLAW_TOOLS_MCP_ENABLED=true`
+
+注意：嵌套的映射式配置（例如 `tools.mcp.servers.<name>.*`）在 `config.json` 中配置，而非通过环境变量。
diff --git a/docs/zh/troubleshooting.md b/docs/zh/troubleshooting.md
new file mode 100644
index 000000000..be4d4f5d7
--- /dev/null
+++ b/docs/zh/troubleshooting.md
@@ -0,0 +1,45 @@
+# 🐛 疑难解答
+
+> 返回 [README](../../README.zh.md)
+
+## "model ... not found in model_list" 或 OpenRouter "free is not a valid model ID"
+
+**症状：** 你看到以下任一错误：
+
+- `Error creating provider: model "openrouter/free" not found in model_list`
+- OpenRouter 返回 400：`"free is not a valid model ID"`
+
+**原因：** `model_list` 条目中的 `model` 字段是发送给 API 的内容。对于 OpenRouter，你必须使用**完整的**模型 ID，而不是简写。
+
+- **错误：** `"model": "free"` → OpenRouter 收到 `free` 并拒绝。
+- **正确：** `"model": "openrouter/free"` → OpenRouter 收到 `openrouter/free`（自动免费层路由）。
+
+**修复方法：** 在 `~/.picoclaw/config.json`（或你的配置路径）中：
+
+1. **agents.defaults.model_name** 必须匹配 `model_list` 中的某个 `model_name`（例如 `"openrouter-free"`）。
+2. 该条目的 **model** 必须是有效的 OpenRouter 模型 ID，例如：
+   - `"openrouter/free"` – 自动免费层
+   - `"google/gemini-2.0-flash-exp:free"`
+   - `"meta-llama/llama-3.1-8b-instruct:free"`
+
+示例片段：
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model_name": "openrouter-free"
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "openrouter-free",
+      "model": "openrouter/free",
+      "api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
+      "api_base": "https://openrouter.ai/api/v1"
+    }
+  ]
+}
+```
+
+在 [OpenRouter Keys](https://openrouter.ai/keys) 获取你的密钥。
diff --git a/examples/pico-echo-server/README.md b/examples/pico-echo-server/README.md
new file mode 100644
index 000000000..f6b5d8020
--- /dev/null
+++ b/examples/pico-echo-server/README.md
@@ -0,0 +1,47 @@
+# pico-echo-server
+
+Minimal Pico Protocol WebSocket server for testing the `pico_client` channel.
+
+## Usage
+
+```bash
+go run ./examples/pico-echo-server -addr :9090 -token secret
+```
+
+### Flags
+
+| Flag     | Default | Description                        |
+|----------|---------|------------------------------------|
+| `-addr`  | `:9090` | Listen address                     |
+| `-token` | (none)  | Auth token; empty disables auth    |
+
+## How it works
+
+- Listens for WebSocket connections at `/ws`
+- Authenticates via `Authorization: Bearer <token>` header or `?token=<token>` query param
+- Prints received `message.send` content to stdout
+- Responds to `ping` with `pong`
+- Lines typed into stdin are broadcast as `message.create` to all connected clients
+
+## Testing with pico_client
+
+1. Start the server:
+   ```bash
+   go run ./examples/pico-echo-server -token mytoken
+   ```
+
+2. Configure `pico_client` in your `config.json`:
+   ```json
+   {
+     "channels": {
+       "pico_client": {
+         "enabled": true,
+         "url": "ws://localhost:9090/ws",
+         "token": "mytoken",
+         "session_id": "test-session"
+       }
+     }
+   }
+   ```
+
+3. Start picoclaw — the client connects and you can exchange messages interactively via stdin/stdout.
diff --git a/examples/pico-echo-server/main.go b/examples/pico-echo-server/main.go
new file mode 100644
index 000000000..46970fb34
--- /dev/null
+++ b/examples/pico-echo-server/main.go
@@ -0,0 +1,160 @@
+// pico-echo-server is a minimal Pico Protocol WebSocket server for testing
+// the pico_client channel. It accepts connections, prints received messages
+// to stdout, and forwards stdin lines as message.create to all connected clients.
+//
+// Usage:
+//
+//	go run ./examples/pico-echo-server -addr :9090 -token secret
+//
+// Then configure pico_client with url=ws://localhost:9090/ws&token=secret.
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"log"
+	"net/http"
+	"os"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+type picoMessage struct {
+	Type      string         `json:"type"`
+	ID        string         `json:"id,omitempty"`
+	SessionID string         `json:"session_id,omitempty"`
+	Timestamp int64          `json:"timestamp,omitempty"`
+	Payload   map[string]any `json:"payload,omitempty"`
+}
+
+var upgrader = websocket.Upgrader{CheckOrigin: func(*http.Request) bool { return true }}
+
+type server struct {
+	token string
+	mu    sync.Mutex
+	conns map[*websocket.Conn]string // conn → sessionID
+}
+
+func (s *server) handleWS(w http.ResponseWriter, r *http.Request) {
+	if s.token != "" {
+		auth := r.Header.Get("Authorization")
+		if auth != "Bearer "+s.token {
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+	}
+
+	conn, err := upgrader.Upgrade(w, r, nil)
+	if err != nil {
+		log.Printf("upgrade: %v", err)
+		return
+	}
+
+	sessionID := r.URL.Query().Get("session_id")
+	if sessionID == "" {
+		sessionID = fmt.Sprintf("sess-%d", time.Now().UnixMilli())
+	}
+
+	s.mu.Lock()
+	s.conns[conn] = sessionID
+	s.mu.Unlock()
+
+	log.Printf("[+] client connected (session=%s)", sessionID)
+
+	defer func() {
+		s.mu.Lock()
+		delete(s.conns, conn)
+		s.mu.Unlock()
+		conn.Close()
+		log.Printf("[-] client disconnected (session=%s)", sessionID)
+	}()
+
+	for {
+		_, raw, err := conn.ReadMessage()
+		if err != nil {
+			if websocket.IsUnexpectedCloseError(err, websocket.CloseGoingAway, websocket.CloseNormalClosure) {
+				log.Printf("read error: %v", err)
+			}
+			return
+		}
+
+		var msg picoMessage
+		if err := json.Unmarshal(raw, &msg); err != nil {
+			log.Printf("bad json: %v", err)
+			continue
+		}
+
+		switch msg.Type {
+		case "ping":
+			pong := picoMessage{Type: "pong", ID: msg.ID, Timestamp: time.Now().UnixMilli()}
+			conn.WriteJSON(pong)
+
+		case "message.send":
+			content, _ := msg.Payload["content"].(string)
+			fmt.Printf("[%s] %s\n", sessionID, content)
+
+		case "typing.start":
+			log.Printf("[%s] typing...", sessionID)
+
+		case "typing.stop":
+			log.Printf("[%s] stopped typing", sessionID)
+
+		default:
+			log.Printf("[%s] unknown type: %s", sessionID, msg.Type)
+		}
+	}
+}
+
+func (s *server) broadcast(content string) {
+	msg := picoMessage{
+		Type:      "message.create",
+		Timestamp: time.Now().UnixMilli(),
+		Payload:   map[string]any{"content": content},
+	}
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	for conn, sid := range s.conns {
+		msg.SessionID = sid
+		if err := conn.WriteJSON(msg); err != nil {
+			log.Printf("write to %s failed: %v", sid, err)
+		}
+	}
+}
+
+func main() {
+	addr := flag.String("addr", ":9090", "listen address")
+	token := flag.String("token", "", "auth token (empty = no auth)")
+	flag.Parse()
+
+	s := &server{
+		token: *token,
+		conns: make(map[*websocket.Conn]string),
+	}
+
+	http.HandleFunc("/ws", s.handleWS)
+
+	log.Printf("listening on %s", *addr)
+	log.Printf("connect with: ws://localhost%s/ws", *addr)
+	fmt.Println("Type messages to send to connected clients (Ctrl+C to quit):")
+
+	go func() {
+		scanner := bufio.NewScanner(os.Stdin)
+		for scanner.Scan() {
+			line := strings.TrimSpace(scanner.Text())
+			if line == "" {
+				continue
+			}
+			s.broadcast(line)
+			log.Printf("[server] sent: %s", line)
+		}
+	}()
+
+	log.Fatal(http.ListenAndServe(*addr, nil))
+}
diff --git a/go.mod b/go.mod
index 7892cade6..e9ef37e98 100644
--- a/go.mod
+++ b/go.mod
@@ -1,59 +1,86 @@
 module github.com/sipeed/picoclaw
 
-go 1.25.7
+go 1.25.8
 
 require (
+	fyne.io/systray v1.12.0
+	github.com/BurntSushi/toml v1.6.0
 	github.com/adhocore/gronx v1.19.6
-	github.com/anthropics/anthropic-sdk-go v1.22.1
+	github.com/anthropics/anthropic-sdk-go v1.26.0
+	github.com/aws/aws-sdk-go-v2 v1.41.4
+	github.com/aws/aws-sdk-go-v2/config v1.32.12
+	github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.2
 	github.com/bwmarrin/discordgo v0.29.0
-	github.com/caarlos0/env/v11 v11.3.1
-	github.com/chzyer/readline v1.5.1
+	github.com/caarlos0/env/v11 v11.4.0
+	github.com/ergochat/irc-go v0.6.0
+	github.com/ergochat/readline v0.1.3
+	github.com/gdamore/tcell/v2 v2.13.8
+	github.com/gomarkdown/markdown v0.0.0-20260217112301-37c66b85d6ab
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.3
+	github.com/h2non/filetype v1.1.3
 	github.com/larksuite/oapi-sdk-go/v3 v3.5.3
+	github.com/mattn/go-sqlite3 v1.14.34
 	github.com/mdp/qrterminal/v3 v3.2.1
-	github.com/mymmrac/telego v1.6.0
+	github.com/modelcontextprotocol/go-sdk v1.4.1
+	github.com/mymmrac/telego v1.7.0
 	github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1
 	github.com/openai/openai-go/v3 v3.22.0
+	github.com/rivo/tview v0.42.0
+	github.com/rs/zerolog v1.34.0
 	github.com/slack-go/slack v0.17.3
 	github.com/spf13/cobra v1.10.2
 	github.com/stretchr/testify v1.11.1
 	github.com/tencent-connect/botgo v0.2.1
+	go.mau.fi/util v0.9.7
 	go.mau.fi/whatsmeow v0.0.0-20260219150138-7ae702b1eed4
-	golang.org/x/oauth2 v0.35.0
+	golang.org/x/oauth2 v0.36.0
+	golang.org/x/term v0.41.0
 	golang.org/x/time v0.14.0
 	google.golang.org/protobuf v1.36.11
+	gopkg.in/yaml.v3 v3.0.1
+	maunium.net/go/mautrix v0.26.4
 	modernc.org/sqlite v1.46.1
 )
 
 require (
-	filippo.io/edwards25519 v1.1.0 // indirect
+	filippo.io/edwards25519 v1.2.0 // indirect
+	github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.7 // indirect
+	github.com/aws/aws-sdk-go-v2/credentials v1.19.12 // indirect
+	github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.20 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.20 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.20 // indirect
+	github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 // indirect
+	github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.20 // indirect
+	github.com/aws/aws-sdk-go-v2/service/signin v1.0.8 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sso v1.30.13 // indirect
+	github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.17 // indirect
+	github.com/aws/aws-sdk-go-v2/service/sts v1.41.9 // indirect
+	github.com/aws/smithy-go v1.24.2 // indirect
 	github.com/beeper/argo-go v1.1.2 // indirect
 	github.com/coder/websocket v1.8.14 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/elliotchance/orderedmap/v3 v3.1.0 // indirect
 	github.com/gdamore/encoding v1.0.1 // indirect
-	github.com/gdamore/tcell/v2 v2.13.8 // indirect
+	github.com/godbus/dbus/v5 v5.1.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/lucasb-eyer/go-colorful v1.3.0 // indirect
 	github.com/mattn/go-colorable v0.1.14 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/ncruces/go-strftime v1.0.0 // indirect
-	github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741 // indirect
+	github.com/petermattis/goid v0.0.0-20260226131333-17d1149c6ac6 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
-	github.com/rivo/tview v0.42.0 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
-	github.com/rs/zerolog v1.34.0 // indirect
+	github.com/segmentio/asm v1.1.3 // indirect
+	github.com/segmentio/encoding v0.5.4 // indirect
 	github.com/spf13/pflag v1.0.10 // indirect
 	github.com/vektah/gqlparser/v2 v2.5.27 // indirect
 	go.mau.fi/libsignal v0.2.1 // indirect
-	go.mau.fi/util v0.9.6 // indirect
-	golang.org/x/exp v0.0.0-20260212183809-81e46e3db34a // indirect
-	golang.org/x/term v0.40.0 // indirect
-	golang.org/x/text v0.34.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
+	golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 // indirect
+	golang.org/x/text v0.35.0 // indirect
 	modernc.org/libc v1.67.6 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.11.0 // indirect
@@ -66,7 +93,7 @@ require (
 	github.com/bytedance/sonic v1.15.0 // indirect
 	github.com/bytedance/sonic/loader v0.5.0 // indirect
 	github.com/cloudwego/base64x v0.1.6 // indirect
-	github.com/github/copilot-sdk/go v0.1.23
+	github.com/github/copilot-sdk/go v0.1.32
 	github.com/go-resty/resty/v2 v2.17.1 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
 	github.com/google/jsonschema-go v0.4.2 // indirect
@@ -80,10 +107,11 @@ require (
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/valyala/bytebufferpool v1.0.0 // indirect
 	github.com/valyala/fasthttp v1.69.0 // indirect
-	github.com/valyala/fastjson v1.6.7 // indirect
+	github.com/valyala/fastjson v1.6.10 // indirect
+	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	golang.org/x/arch v0.24.0 // indirect
-	golang.org/x/crypto v0.48.0 // indirect
-	golang.org/x/net v0.50.0 // indirect
-	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/crypto v0.49.0
+	golang.org/x/net v0.52.0
+	golang.org/x/sync v0.20.0 // indirect
+	golang.org/x/sys v0.42.0
 )
diff --git a/go.sum b/go.sum
index d1ee1d629..87117bc98 100644
--- a/go.sum
+++ b/go.sum
@@ -1,6 +1,10 @@
 cloud.google.com/go/compute/metadata v0.3.0/go.mod h1:zFmK7XCadkQkj6TtorcaGlCW1hT1fIilQDwofLpJ20k=
-filippo.io/edwards25519 v1.1.0 h1:FNf4tywRC1HmFuKW5xopWpigGjJKiJSV0Cqo0cJWDaA=
-filippo.io/edwards25519 v1.1.0/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4=
+filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo=
+filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc=
+fyne.io/systray v1.12.0 h1:CA1Kk0e2zwFlxtc02L3QFSiIbxJ/P0n582YrZHT7aTM=
+fyne.io/systray v1.12.0/go.mod h1:RVwqP9nYMo7h5zViCBHri2FgjXF7H2cub7MAq4NSoLs=
+github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
+github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
 github.com/DATA-DOG/go-sqlmock v1.5.2 h1:OcvFkGmslmlZibjAjaHm3L//6LiuBgolP7OputlJIzU=
 github.com/DATA-DOG/go-sqlmock v1.5.2/go.mod h1:88MAG/4G7SMwSE3CeA0ZKzrT5CiOU3OJ+JlNzwDqpNU=
 github.com/adhocore/gronx v1.19.6 h1:5KNVcoR9ACgL9HhEqCm5QXsab/gI4QDIybTAWcXDKDc=
@@ -11,8 +15,40 @@ github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883 h1:bvNMNQO63//z+xNg
 github.com/andreyvit/diff v0.0.0-20170406064948-c7f18ee00883/go.mod h1:rCTlJbsFo29Kk6CurOXKm700vrz8f0KW0JNfpkRJY/8=
 github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
 github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
-github.com/anthropics/anthropic-sdk-go v1.22.1 h1:xbsc3vJKCX/ELDZSpTNfz9wCgrFsamwFewPb1iI0Xh0=
-github.com/anthropics/anthropic-sdk-go v1.22.1/go.mod h1:WTz31rIUHUHqai2UslPpw5CwXrQP3geYBioRV4WOLvE=
+github.com/anthropics/anthropic-sdk-go v1.26.0 h1:oUTzFaUpAevfuELAP1sjL6CQJ9HHAfT7CoSYSac11PY=
+github.com/anthropics/anthropic-sdk-go v1.26.0/go.mod h1:qUKmaW+uuPB64iy1l+4kOSvaLqPXnHTTBKH6RVZ7q5Q=
+github.com/aws/aws-sdk-go-v2 v1.41.4 h1:10f50G7WyU02T56ox1wWXq+zTX9I1zxG46HYuG1hH/k=
+github.com/aws/aws-sdk-go-v2 v1.41.4/go.mod h1:mwsPRE8ceUUpiTgF7QmQIJ7lgsKUPQOUl3o72QBrE1o=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.7 h1:3kGOqnh1pPeddVa/E37XNTaWJ8W6vrbYV9lJEkCnhuY=
+github.com/aws/aws-sdk-go-v2/aws/protocol/eventstream v1.7.7/go.mod h1:lyw7GFp3qENLh7kwzf7iMzAxDn+NzjXEAGjKS2UOKqI=
+github.com/aws/aws-sdk-go-v2/config v1.32.12 h1:O3csC7HUGn2895eNrLytOJQdoL2xyJy0iYXhoZ1OmP0=
+github.com/aws/aws-sdk-go-v2/config v1.32.12/go.mod h1:96zTvoOFR4FURjI+/5wY1vc1ABceROO4lWgWJuxgy0g=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.12 h1:oqtA6v+y5fZg//tcTWahyN9PEn5eDU/Wpvc2+kJ4aY8=
+github.com/aws/aws-sdk-go-v2/credentials v1.19.12/go.mod h1:U3R1RtSHx6NB0DvEQFGyf/0sbrpJrluENHdPy1j/3TE=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.20 h1:zOgq3uezl5nznfoK3ODuqbhVg1JzAGDUhXOsU0IDCAo=
+github.com/aws/aws-sdk-go-v2/feature/ec2/imds v1.18.20/go.mod h1:z/MVwUARehy6GAg/yQ1GO2IMl0k++cu1ohP9zo887wE=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.20 h1:CNXO7mvgThFGqOFgbNAP2nol2qAWBOGfqR/7tQlvLmc=
+github.com/aws/aws-sdk-go-v2/internal/configsources v1.4.20/go.mod h1:oydPDJKcfMhgfcgBUZaG+toBbwy8yPWubJXBVERtI4o=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.20 h1:tN6W/hg+pkM+tf9XDkWUbDEjGLb+raoBMFsTodcoYKw=
+github.com/aws/aws-sdk-go-v2/internal/endpoints/v2 v2.7.20/go.mod h1:YJ898MhD067hSHA6xYCx5ts/jEd8BSOLtQDL3iZsvbc=
+github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6 h1:qYQ4pzQ2Oz6WpQ8T3HvGHnZydA72MnLuFK9tJwmrbHw=
+github.com/aws/aws-sdk-go-v2/internal/ini v1.8.6/go.mod h1:O3h0IK87yXci+kg6flUKzJnWeziQUKciKrLjcatSNcY=
+github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.2 h1:x0eGAWpd1B5I/vMtrB4Q4Zuc3CXWI8wjHfPPqBSrKmM=
+github.com/aws/aws-sdk-go-v2/service/bedrockruntime v1.50.2/go.mod h1:V9oTWSDC2MtS1DR71hbNET/bZ8psQp022amEBe1grJc=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7 h1:5EniKhLZe4xzL7a+fU3C2tfUN4nWIqlLesfrjkuPFTY=
+github.com/aws/aws-sdk-go-v2/service/internal/accept-encoding v1.13.7/go.mod h1:x0nZssQ3qZSnIcePWLvcoFisRXJzcTVvYpAAdYX8+GI=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.20 h1:2HvVAIq+YqgGotK6EkMf+KIEqTISmTYh5zLpYyeTo1Y=
+github.com/aws/aws-sdk-go-v2/service/internal/presigned-url v1.13.20/go.mod h1:V4X406Y666khGa8ghKmphma/7C0DAtEQYhkq9z4vpbk=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.8 h1:0GFOLzEbOyZABS3PhYfBIx2rNBACYcKty+XGkTgw1ow=
+github.com/aws/aws-sdk-go-v2/service/signin v1.0.8/go.mod h1:LXypKvk85AROkKhOG6/YEcHFPoX+prKTowKnVdcaIxE=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.13 h1:kiIDLZ005EcKomYYITtfsjn7dtOwHDOFy7IbPXKek2o=
+github.com/aws/aws-sdk-go-v2/service/sso v1.30.13/go.mod h1:2h/xGEowcW/g38g06g3KpRWDlT+OTfxxI0o1KqayAB8=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.17 h1:jzKAXIlhZhJbnYwHbvUQZEB8KfgAEuG0dc08Bkda7NU=
+github.com/aws/aws-sdk-go-v2/service/ssooidc v1.35.17/go.mod h1:Al9fFsXjv4KfbzQHGe6V4NZSZQXecFcvaIF4e70FoRA=
+github.com/aws/aws-sdk-go-v2/service/sts v1.41.9 h1:Cng+OOwCHmFljXIxpEVXAGMnBia8MSU6Ch5i9PgBkcU=
+github.com/aws/aws-sdk-go-v2/service/sts v1.41.9/go.mod h1:LrlIndBDdjA/EeXeyNBle+gyCwTlizzW5ycgWnvIxkk=
+github.com/aws/smithy-go v1.24.2 h1:FzA3bu/nt/vDvmnkg+R8Xl46gmzEDam6mZ1hzmwXFng=
+github.com/aws/smithy-go v1.24.2/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=
 github.com/beeper/argo-go v1.1.2 h1:UQI2G8F+NLfGTOmTUI0254pGKx/HUU/etbUGTJv91Fs=
 github.com/beeper/argo-go v1.1.2/go.mod h1:M+LJAnyowKVQ6Rdj6XYGEn+qcVFkb3R/MUpqkGR0hM4=
 github.com/bwmarrin/discordgo v0.29.0 h1:FmWeXFaKUwrcL3Cx65c20bTRW+vOb6k8AnaP+EgjDno=
@@ -23,16 +59,10 @@ github.com/bytedance/sonic v1.15.0 h1:/PXeWFaR5ElNcVE84U0dOHjiMHQOwNIx3K4ymzh/uS
 github.com/bytedance/sonic v1.15.0/go.mod h1:tFkWrPz0/CUCLEF4ri4UkHekCIcdnkqXw9VduqpJh0k=
 github.com/bytedance/sonic/loader v0.5.0 h1:gXH3KVnatgY7loH5/TkeVyXPfESoqSBSBEiDd5VjlgE=
 github.com/bytedance/sonic/loader v0.5.0/go.mod h1:AR4NYCk5DdzZizZ5djGqQ92eEhCCcdf5x77udYiSJRo=
-github.com/caarlos0/env/v11 v11.3.1 h1:cArPWC15hWmEt+gWk7YBi7lEXTXCvpaSdCiZE2X5mCA=
-github.com/caarlos0/env/v11 v11.3.1/go.mod h1:qupehSf/Y0TUTsxKywqRt/vJjN5nz6vauiYEUUr8P4U=
+github.com/caarlos0/env/v11 v11.4.0 h1:Kcb6t5kIIr4XkoQC9AF2j+8E1Jsrl3Wz/hhm1LtoGAc=
+github.com/caarlos0/env/v11 v11.4.0/go.mod h1:qupehSf/Y0TUTsxKywqRt/vJjN5nz6vauiYEUUr8P4U=
 github.com/cespare/xxhash/v2 v2.1.2/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
-github.com/chzyer/logex v1.2.1 h1:XHDu3E6q+gdHgsdTPH6ImJMIp436vR6MPtH8gP05QzM=
-github.com/chzyer/logex v1.2.1/go.mod h1:JLbx6lG2kDbNRFnfkgvh4eRJRPX1QCoOIWomwysCBrQ=
-github.com/chzyer/readline v1.5.1 h1:upd/6fQk4src78LMRzh5vItIt361/o4uq553V8B5sGI=
-github.com/chzyer/readline v1.5.1/go.mod h1:Eh+b79XXUwfKfcPLepksvw2tcLE/Ct21YObkaSkeBlk=
-github.com/chzyer/test v1.0.0 h1:p3BQDXSxOhOG0P9z6/hGnII4LGiEPOYBhs8asl/fC04=
-github.com/chzyer/test v1.0.0/go.mod h1:2JlltgoNkt4TW/z9V/IzDdFaMTM2JPIi26O1pF38GC8=
 github.com/cloudwego/base64x v0.1.6 h1:t11wG9AECkCDk5fMSoxmufanudBtJ+/HemLstXDLI2M=
 github.com/cloudwego/base64x v0.1.6/go.mod h1:OFcloc187FXDaYHvrNIjxSe8ncn0OOM8gEHfghB2IPU=
 github.com/coder/websocket v1.8.14 h1:9L0p0iKiNOibykf283eHkKUHHrpG7f65OE3BhhO7v9g=
@@ -44,18 +74,24 @@ github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSs
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f/go.mod h1:cuUVRXasLTGF7a8hSLbxyZXjz+1KgoB3wDUb6vlszIc=
+github.com/dnaeon/go-vcr v1.2.0 h1:zHCHvJYTMh1N7xnV7zf1m1GPBF9Ad0Jk/whtQ1663qI=
+github.com/dnaeon/go-vcr v1.2.0/go.mod h1:R4UdLID7HZT3taECzJs4YgbbH6PIGXB6W/sc5OLb6RQ=
 github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/elliotchance/orderedmap/v3 v3.1.0 h1:j4DJ5ObEmMBt/lcwIecKcoRxIQUEnw0L804lXYDt/pg=
 github.com/elliotchance/orderedmap/v3 v3.1.0/go.mod h1:G+Hc2RwaZvJMcS4JpGCOyViCnGeKf0bTYCGTO4uhjSo=
+github.com/ergochat/irc-go v0.6.0 h1:Y0AGV76aeihJfCtLaQh+OyJKFiKGrYC0VTkeMZ6XW28=
+github.com/ergochat/irc-go v0.6.0/go.mod h1:2vi7KNpIPWnReB5hmLpl92eMywQvuIeIIGdt/FQCph0=
+github.com/ergochat/readline v0.1.3 h1:/DytGTmwdUJcLAe3k3VJgowh5vNnsdifYT6uVaf4pSo=
+github.com/ergochat/readline v0.1.3/go.mod h1:o3ux9QLHLm77bq7hDB21UTm6HlV2++IPDMfIfKDuOgY=
 github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMoQvtojpjFo=
 github.com/fsnotify/fsnotify v1.4.9/go.mod h1:znqG4EE+3YCdAaPaxE2ZRY/06pZUdp0tY4IgpuI1SZQ=
 github.com/gdamore/encoding v1.0.1 h1:YzKZckdBL6jVt2Gc+5p82qhrGiqMdG/eNs6Wy0u3Uhw=
 github.com/gdamore/encoding v1.0.1/go.mod h1:0Z0cMFinngz9kS1QfMjCP8TY7em3bZYeeklsSDPivEo=
 github.com/gdamore/tcell/v2 v2.13.8 h1:Mys/Kl5wfC/GcC5Cx4C2BIQH9dbnhnkPgS9/wF3RlfU=
 github.com/gdamore/tcell/v2 v2.13.8/go.mod h1:+Wfe208WDdB7INEtCsNrAN6O2m+wsTPk1RAovjaILlo=
-github.com/github/copilot-sdk/go v0.1.23 h1:uExtO/inZQndCZMiSAA1hvXINiz9tqo/MZgQzFzurxw=
-github.com/github/copilot-sdk/go v0.1.23/go.mod h1:GdwwBfMbm9AABLEM3x5IZKw4ZfwCYxZ1BgyytmZenQ0=
+github.com/github/copilot-sdk/go v0.1.32 h1:wc9SFWwxXhJts6vyzzboPLJqcEJGnHE8rMCAY1RrUgo=
+github.com/github/copilot-sdk/go v0.1.32/go.mod h1:qc2iEF7hdO8kzSvbyGvrcGhuk2fzdW4xTtT0+1EH2ts=
 github.com/go-redis/redis/v8 v8.11.4/go.mod h1:2Z2wHZXdQpCDXEGzqMockDpNyYvi2l4Pxt6RJr792+w=
 github.com/go-resty/resty/v2 v2.6.0/go.mod h1:PwvJS6hvaPkjtjNg9ph+VrSD92bi5Zq73w/BIH7cC3Q=
 github.com/go-resty/resty/v2 v2.17.1 h1:x3aMpHK1YM9e4va/TMDRlusDDoZiQ+ViDu/WpA6xTM4=
@@ -64,8 +100,12 @@ github.com/go-task/slim-sprig v0.0.0-20210107165309-348f09dbbbc0/go.mod h1:fyg78
 github.com/go-test/deep v1.1.1 h1:0r/53hagsehfO4bzD2Pgr/+RgHqhmf+k1Bpse2cTu1U=
 github.com/go-test/deep v1.1.1/go.mod h1:5C2ZWiW0ErCdrYzpqxLbTX7MG14M9iiw8DgHncVwcsE=
 github.com/godbus/dbus/v5 v5.0.4/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
+github.com/godbus/dbus/v5 v5.1.0 h1:4KLkAxT3aOY8Li4FRJe/KvhoNFFxo0m6fNuFUO8QJUk=
+github.com/godbus/dbus/v5 v5.1.0/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
 github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
 github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
+github.com/golang-jwt/jwt/v5 v5.3.0 h1:pv4AsKCKKZuqlgs5sUmn4x8UlGa0kEVt/puTpKx9vvo=
+github.com/golang-jwt/jwt/v5 v5.3.0/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
 github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
 github.com/golang/protobuf v1.4.0-rc.1/go.mod h1:ceaxUfeHdC40wWswd/P6IGgMaK3YpKi5j83Wpe3EHw8=
 github.com/golang/protobuf v1.4.0-rc.1.0.20200221234624-67d41d38c208/go.mod h1:xKAWHe0F5eneWXFV3EuXVDTCmh+JuBKY0li0aMyXATA=
@@ -75,6 +115,8 @@ github.com/golang/protobuf v1.4.0/go.mod h1:jodUvKwWbYaEsadDk5Fwe5c77LiNKVO9IDvq
 github.com/golang/protobuf v1.4.2/go.mod h1:oDoupMAO8OvCJWAcko0GGGIgR6R6ocIYbsSw735rRwI=
 github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
 github.com/golang/protobuf v1.5.2/go.mod h1:XVQd3VNwM+JqD3oG2Ue2ip4fOMUkwXdXDdiuN0vRsmY=
+github.com/gomarkdown/markdown v0.0.0-20260217112301-37c66b85d6ab h1:VYNivV7P8IRHUam2swVUNkhIdp0LRRFKe4hXNnoZKTc=
+github.com/gomarkdown/markdown v0.0.0-20260217112301-37c66b85d6ab/go.mod h1:JDGcbDT52eL4fju3sZ4TeHGsQwhG9nbDV21aMyhwPoA=
 github.com/google/go-cmp v0.3.0/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
 github.com/google/go-cmp v0.3.1/go.mod h1:8QqcDgzrUqlUb/G2PQTWiueGozuR1884gddMywk6iLU=
 github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
@@ -96,6 +138,8 @@ github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aN
 github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
 github.com/grbit/go-json v0.11.0 h1:bAbyMdYrYl/OjYsSqLH99N2DyQ291mHy726Mx+sYrnc=
 github.com/grbit/go-json v0.11.0/go.mod h1:IYpHsdybQ386+6g3VE6AXQ3uTGa5mquBme5/ZWmtzek=
+github.com/h2non/filetype v1.1.3 h1:FKkx9QbD7HR/zjK1Ia5XiBsq9zdLi5Kf3zGyFTAFkGg=
+github.com/h2non/filetype v1.1.3/go.mod h1:319b3zT68BvV+WRj7cwy856M2ehB3HqNOt6sy1HndBY=
 github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
 github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
 github.com/hpcloud/tail v1.0.0/go.mod h1:ab1qPbhIpdTxEkNHXyeSf5vhxWSCs/tWer42PpOxQnU=
@@ -130,8 +174,10 @@ github.com/mattn/go-sqlite3 v1.14.34 h1:3NtcvcUnFBPsuRcno8pUtupspG/GM+9nZ88zgJcp
 github.com/mattn/go-sqlite3 v1.14.34/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
 github.com/mdp/qrterminal/v3 v3.2.1 h1:6+yQjiiOsSuXT5n9/m60E54vdgFsw0zhADHhHLrFet4=
 github.com/mdp/qrterminal/v3 v3.2.1/go.mod h1:jOTmXvnBsMy5xqLniO0R++Jmjs2sTm9dFSuQ5kpz/SU=
-github.com/mymmrac/telego v1.6.0 h1:Zc8rgyHozvd/7ZgyrigyHdAF9koHYMfilYfyB6wlFC0=
-github.com/mymmrac/telego v1.6.0/go.mod h1:xt6ZWA8zi8KmuzryE1ImEdl9JSwjHNpM4yhC7D8hU4Y=
+github.com/modelcontextprotocol/go-sdk v1.4.1 h1:M4x9GyIPj+HoIlHNGpK2hq5o3BFhC+78PkEaldQRphc=
+github.com/modelcontextprotocol/go-sdk v1.4.1/go.mod h1:Bo/mS87hPQqHSRkMv4dQq1XCu6zv4INdXnFZabkNU6s=
+github.com/mymmrac/telego v1.7.0 h1:yRO/l00tFGG4nY66ufUKb4ARqv7qx9+LsjQv/b0NEyo=
+github.com/mymmrac/telego v1.7.0/go.mod h1:pdLV346EgVuq7Xrh3kMggeBiazeHhsdEoK0RTEOPXRM=
 github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w=
 github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
 github.com/nxadm/tail v1.4.4/go.mod h1:kenIhsEOeOJmVchQTgglprH7qJGnHDVpk1VPCcaMI8A=
@@ -146,8 +192,8 @@ github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1 h1:Lb/Uzkiw2Ugt2Xf03J5wmv
 github.com/open-dingtalk/dingtalk-stream-sdk-go v0.9.1/go.mod h1:ln3IqPYYocZbYvl9TAOrG/cxGR9xcn4pnZRLdCTEGEU=
 github.com/openai/openai-go/v3 v3.22.0 h1:6MEoNoV8sbjOVmXdvhmuX3BjVbVdcExbVyGixiyJ8ys=
 github.com/openai/openai-go/v3 v3.22.0/go.mod h1:cdufnVK14cWcT9qA1rRtrXx4FTRsgbDPW7Ia7SS5cZo=
-github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741 h1:KPpdlQLZcHfTMQRi6bFQ7ogNO0ltFT4PmtwTLW4W+14=
-github.com/petermattis/goid v0.0.0-20260113132338-7c7de50cc741/go.mod h1:pxMtw7cyUw6B2bRH0ZBANSPg+AoSud1I1iyJHI69jH4=
+github.com/petermattis/goid v0.0.0-20260226131333-17d1149c6ac6 h1:rh2lKw/P/EqHa724vYH2+VVQ1YnW4u6EOXl0PMAovZE=
+github.com/petermattis/goid v0.0.0-20260226131333-17d1149c6ac6/go.mod h1:pxMtw7cyUw6B2bRH0ZBANSPg+AoSud1I1iyJHI69jH4=
 github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
@@ -165,6 +211,10 @@ github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=
 github.com/rs/zerolog v1.34.0 h1:k43nTLIwcTVQAncfCw4KZ2VY6ukYoZaBPNOE8txlOeY=
 github.com/rs/zerolog v1.34.0/go.mod h1:bJsvje4Z08ROH4Nhs5iH600c3IkWhwp44iRc54W6wYQ=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
+github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
+github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
+github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
 github.com/sergi/go-diff v1.3.1 h1:xkr+Oxo4BOQKmkn/B9eMK0g5Kg/983T9DqqPHwYqD+8=
 github.com/sergi/go-diff v1.3.1/go.mod h1:aMJSSKb2lpPvRNec0+w3fl7LP9IOFzdc9Pa4NFbPK1I=
 github.com/slack-go/slack v0.17.3 h1:zV5qO3Q+WJAQ/XwbGfNFrRMaJ5T/naqaonyPV/1TP4g=
@@ -206,19 +256,21 @@ github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6Kllzaw
 github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
 github.com/valyala/fasthttp v1.69.0 h1:fNLLESD2SooWeh2cidsuFtOcrEi4uB4m1mPrkJMZyVI=
 github.com/valyala/fasthttp v1.69.0/go.mod h1:4wA4PfAraPlAsJ5jMSqCE2ug5tqUPwKXxVj8oNECGcw=
-github.com/valyala/fastjson v1.6.7 h1:ZE4tRy0CIkh+qDc5McjatheGX2czdn8slQjomexVpBM=
-github.com/valyala/fastjson v1.6.7/go.mod h1:CLCAqky6SMuOcxStkYQvblddUtoRxhYMGLrsQns1aXY=
+github.com/valyala/fastjson v1.6.10 h1:/yjJg8jaVQdYR3arGxPE2X5z89xrlhS0eGXdv+ADTh4=
+github.com/valyala/fastjson v1.6.10/go.mod h1:e6FubmQouUNP73jtMLmcbxS6ydWIpOfhz34TSfO3JaE=
 github.com/vektah/gqlparser/v2 v2.5.27 h1:RHPD3JOplpk5mP5JGX8RKZkt2/Vwj/PZv0HxTdwFp0s=
 github.com/vektah/gqlparser/v2 v2.5.27/go.mod h1:D1/VCZtV3LPnQrcPBeR/q5jkSQIPti0uYCP/RI0gIeo=
 github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
 github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
+github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
+github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
 go.mau.fi/libsignal v0.2.1 h1:vRZG4EzTn70XY6Oh/pVKrQGuMHBkAWlGRC22/85m9L0=
 go.mau.fi/libsignal v0.2.1/go.mod h1:iVvjrHyfQqWajOUaMEsIfo3IqgVMrhWcPiiEzk7NgoU=
-go.mau.fi/util v0.9.6 h1:2nsvxm49KhI3wrFltr0+wSUBlnQ4CMtykuELjpIU+ts=
-go.mau.fi/util v0.9.6/go.mod h1:sIJpRH7Iy5Ad1SBuxQoatxtIeErgzxCtjd/2hCMkYMI=
+go.mau.fi/util v0.9.7 h1:AWGNbJfz1zRcQOKeOEYhKUG2fT+/26Gy6kyqcH8tnBg=
+go.mau.fi/util v0.9.7/go.mod h1:5T2f3ZWZFAGgmFwg3dGw7YK6kIsb9lryDzvynoR98pE=
 go.mau.fi/whatsmeow v0.0.0-20260219150138-7ae702b1eed4 h1:hsmlwsM+VqfF70cpdZEeIUKer2XWCQmQPK0u0tHy3ZQ=
 go.mau.fi/whatsmeow v0.0.0-20260219150138-7ae702b1eed4/go.mod h1:mXCRFyPEPn4jqWz6Afirn8vY7DpHCPnlKq6I2cWwFHM=
 go.uber.org/mock v0.6.0 h1:hyF9dfmbgIX5EfOdasqLsWD6xqpNZlXblLB/Dbnwv3Y=
@@ -232,16 +284,16 @@ golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPh
 golang.org/x/crypto v0.0.0-20210421170649-83a5a9bb288b/go.mod h1:T9bdIzuCu7OtxOm1hfPfRQxPLYneinmdGuTeoZ9dtd4=
 golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
 golang.org/x/crypto v0.16.0/go.mod h1:gCAAfMLgwOJRpTjQ2zCCt2OcSfYMTeZVSRtQlPC7Nq4=
-golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
-golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
-golang.org/x/exp v0.0.0-20260212183809-81e46e3db34a h1:ovFr6Z0MNmU7nH8VaX5xqw+05ST2uO1exVfZPVqRC5o=
-golang.org/x/exp v0.0.0-20260212183809-81e46e3db34a/go.mod h1:K79w1Vqn7PoiZn+TkNpx3BUWUQksGO3JcVX6qIjytmA=
+golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
+golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
+golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90 h1:jiDhWWeC7jfWqR9c/uplMOqJ0sbNlNWv0UkzE0vX1MA=
+golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90/go.mod h1:xE1HEv6b+1SCZ5/uscMRjUBKtIxworgEcEi+/n9NQDQ=
 golang.org/x/mod v0.2.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
-golang.org/x/mod v0.33.0 h1:tHFzIWbBifEmbwtGz65eaWyGiGZatSrT9prnU8DbVL8=
-golang.org/x/mod v0.33.0/go.mod h1:swjeQEj+6r7fODbD2cqrnje9PnziFuw4bmLbBZFrQ5w=
+golang.org/x/mod v0.34.0 h1:xIHgNUUnW6sYkcM5Jleh05DvLOtwc6RitGHbDk4akRI=
+golang.org/x/mod v0.34.0/go.mod h1:ykgH52iCZe79kzLLMhyCUzhMci+nQj+0XkbXpNYtVjY=
 golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
@@ -255,19 +307,19 @@ golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug
 golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
 golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
 golang.org/x/net v0.19.0/go.mod h1:CfAk/cbD4CthTvqiEl8NpboMuiuOYsAr/7NOjZJtv1U=
-golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
-golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
+golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
+golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
 golang.org/x/oauth2 v0.23.0/go.mod h1:XYTD2NtWslqkgxebSiOHnXEap4TF09sJSc7H1sXbhtI=
-golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
-golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
+golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
+golang.org/x/oauth2 v0.36.0/go.mod h1:YDBUJMTkDnJS+A4BP4eZBjCqtokkg1hODuPjwiGPO7Q=
 golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20190911185100-cd5d95a43a6e/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
-golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -281,7 +333,6 @@ golang.org/x/sys v0.0.0-20210112080510-489259a85091/go.mod h1:h1NjWce9XRLGQEsW7w
 golang.org/x/sys v0.0.0-20210330210617-4fbd30eecc44/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.0.0-20220310020820-b874c991c1a5/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
@@ -290,15 +341,15 @@ golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
-golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
+golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
 golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
 golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo=
 golang.org/x/term v0.15.0/go.mod h1:BDl952bC7+uMoWR75FIrCDx79TPU9oHkTZ9yRbYOrX0=
-golang.org/x/term v0.40.0 h1:36e4zGLqU4yhjlmxEaagx2KuYbJq3EwY8K943ZsHcvg=
-golang.org/x/term v0.40.0/go.mod h1:w2P8uVp06p2iyKKuvXIm7N/y0UCRt3UfJTfZ7oOpglM=
+golang.org/x/term v0.41.0 h1:QCgPso/Q3RTJx2Th4bDLqML4W6iJiaXFq2/ftQF13YU=
+golang.org/x/term v0.41.0/go.mod h1:3pfBgksrReYfZ5lvYM0kSO0LIkAl4Yl2bXOkKP7Ec2A=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
@@ -306,8 +357,8 @@ golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
 golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
 golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
 golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
-golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
-golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
+golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
+golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
 golang.org/x/time v0.14.0 h1:MRx4UaLrDotUKUdCIqzPC48t1Y9hANFKIRpNx+Te8PI=
 golang.org/x/time v0.14.0/go.mod h1:eL/Oa2bBBK0TkX57Fyni+NgnyQQN4LitPmob2Hjnqw4=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
@@ -317,8 +368,8 @@ golang.org/x/tools v0.0.0-20201224043029-2b0845dc783e/go.mod h1:emZCQorbCU4vsT4f
 golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
 golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
-golang.org/x/tools v0.42.0 h1:uNgphsn75Tdz5Ji2q36v/nsFSfR/9BRFvqhGBaJGd5k=
-golang.org/x/tools v0.42.0/go.mod h1:Ma6lCIwGZvHK6XtgbswSoWroEkhugApmsXyrUmBhfr0=
+golang.org/x/tools v0.43.0 h1:12BdW9CeB3Z+J/I/wj34VMl8X+fEXBxVR90JeMX5E7s=
+golang.org/x/tools v0.43.0/go.mod h1:uHkMso649BX2cZK6+RpuIPXS3ho2hZo4FVwfoy1vIk0=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
@@ -343,10 +394,13 @@ gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWD
 gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.2.4/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
 gopkg.in/yaml.v2 v2.3.0/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
+gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY=
 gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+maunium.net/go/mautrix v0.26.4 h1:enHSnkf0L2V9+VnfJfNhKSReSW6pBKS/x3Su+v+Vovs=
+maunium.net/go/mautrix v0.26.4/go.mod h1:YWw8NWTszsbyFAznboicBObwHPgTSLcuTbVX2kY7U2M=
 modernc.org/cc/v4 v4.27.1 h1:9W30zRlYrefrDV2JE2O8VDtJ1yPGownxciz5rrbQZis=
 modernc.org/cc/v4 v4.27.1/go.mod h1:uVtb5OGqUKpoLWhqwNQo/8LwvoiEBLvZXIQ/SmO6mL0=
 modernc.org/ccgo/v4 v4.30.1 h1:4r4U1J6Fhj98NKfSjnPUN7Ze2c6MnAdL0hWw6+LrJpc=
diff --git a/pkg/agent/context.go b/pkg/agent/context.go
index 1fbab552c..21054337e 100644
--- a/pkg/agent/context.go
+++ b/pkg/agent/context.go
@@ -12,15 +12,20 @@ import (
 	"sync"
 	"time"
 
+	"github.com/sipeed/picoclaw/pkg"
+	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/skills"
+	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
 type ContextBuilder struct {
-	workspace    string
-	skillsLoader *skills.SkillsLoader
-	memory       *MemoryStore
+	workspace          string
+	skillsLoader       *skills.SkillsLoader
+	memory             *MemoryStore
+	toolDiscoveryBM25  bool
+	toolDiscoveryRegex bool
 
 	// Cache for system prompt to avoid rebuilding on every call.
 	// This fixes issue #607: repeated reprocessing of the entire context.
@@ -34,21 +39,38 @@ type ContextBuilder struct {
 	// created (didn't exist at cache time, now exist) or deleted (existed at
 	// cache time, now gone) — both of which should trigger a cache rebuild.
 	existedAtCache map[string]bool
+
+	// skillFilesAtCache snapshots the skill tree file set and mtimes at cache
+	// build time. This catches nested file creations/deletions/mtime changes
+	// that may not update the top-level skill root directory mtime.
+	skillFilesAtCache map[string]time.Time
+}
+
+func (cb *ContextBuilder) WithToolDiscovery(useBM25, useRegex bool) *ContextBuilder {
+	cb.toolDiscoveryBM25 = useBM25
+	cb.toolDiscoveryRegex = useRegex
+	return cb
 }
 
 func getGlobalConfigDir() string {
+	if home := os.Getenv(config.EnvHome); home != "" {
+		return home
+	}
 	home, err := os.UserHomeDir()
 	if err != nil {
 		return ""
 	}
-	return filepath.Join(home, ".picoclaw")
+	return filepath.Join(home, pkg.DefaultPicoClawHome)
 }
 
 func NewContextBuilder(workspace string) *ContextBuilder {
 	// builtin skills: skills directory in current project
 	// Use the skills/ directory under the current working directory
-	wd, _ := os.Getwd()
-	builtinSkillsDir := filepath.Join(wd, "skills")
+	builtinSkillsDir := strings.TrimSpace(os.Getenv(config.EnvBuiltinSkills))
+	if builtinSkillsDir == "" {
+		wd, _ := os.Getwd()
+		builtinSkillsDir = filepath.Join(wd, "skills")
+	}
 	globalSkillsDir := filepath.Join(getGlobalConfigDir(), "skills")
 
 	return &ContextBuilder{
@@ -60,8 +82,11 @@ func NewContextBuilder(workspace string) *ContextBuilder {
 
 func (cb *ContextBuilder) getIdentity() string {
 	workspacePath, _ := filepath.Abs(filepath.Join(cb.workspace))
+	toolDiscovery := cb.getDiscoveryRule()
+	version := config.FormatVersion()
 
-	return fmt.Sprintf(`# picoclaw 🦞
+	return fmt.Sprintf(
+		`# picoclaw 🦞 (%s)
 
 You are picoclaw, a helpful AI assistant.
 
@@ -79,8 +104,29 @@ Your workspace is at: %s
 
 3. **Memory** - When interacting with me if something seems memorable, update %s/memory/MEMORY.md
 
-4. **Context summaries** - Conversation summaries provided as context are approximate references only. They may be incomplete or outdated. Always defer to explicit user instructions over summary content.`,
-		workspacePath, workspacePath, workspacePath, workspacePath, workspacePath)
+4. **Context summaries** - Conversation summaries provided as context are approximate references only. They may be incomplete or outdated. Always defer to explicit user instructions over summary content.
+
+%s`,
+		version, workspacePath, workspacePath, workspacePath, workspacePath, workspacePath, toolDiscovery)
+}
+
+func (cb *ContextBuilder) getDiscoveryRule() string {
+	if !cb.toolDiscoveryBM25 && !cb.toolDiscoveryRegex {
+		return ""
+	}
+
+	var toolNames []string
+	if cb.toolDiscoveryBM25 {
+		toolNames = append(toolNames, `"tool_search_tool_bm25"`)
+	}
+	if cb.toolDiscoveryRegex {
+		toolNames = append(toolNames, `"tool_search_tool_regex"`)
+	}
+
+	return fmt.Sprintf(
+		`5. **Tool Discovery** - Your visible tools are limited to save memory, but a vast hidden library exists. If you lack the right tool for a task, BEFORE giving up, you MUST search using the %s tool. Do not refuse a request unless the search returns nothing. Found tools will temporarily unlock for your next turn.`,
+		strings.Join(toolNames, " or "),
+	)
 }
 
 func (cb *ContextBuilder) BuildSystemPrompt() string {
@@ -148,6 +194,7 @@ func (cb *ContextBuilder) BuildSystemPromptWithCache() string {
 	cb.cachedSystemPrompt = prompt
 	cb.cachedAt = baseline.maxMtime
 	cb.existedAtCache = baseline.existed
+	cb.skillFilesAtCache = baseline.skillFiles
 
 	logger.DebugCF("agent", "System prompt cached",
 		map[string]any{
@@ -167,41 +214,54 @@ func (cb *ContextBuilder) InvalidateCache() {
 	cb.cachedSystemPrompt = ""
 	cb.cachedAt = time.Time{}
 	cb.existedAtCache = nil
+	cb.skillFilesAtCache = nil
 
 	logger.DebugCF("agent", "System prompt cache invalidated", nil)
 }
 
-// sourcePaths returns the workspace source file paths tracked for cache
-// invalidation (bootstrap files + memory). The skills directory is handled
-// separately in sourceFilesChangedLocked because it requires both directory-
-// level and recursive file-level mtime checks.
+// sourcePaths returns non-skill workspace source files tracked for cache
+// invalidation (bootstrap files + memory). Skill roots are handled separately
+// because they require both directory-level and recursive file-level checks.
 func (cb *ContextBuilder) sourcePaths() []string {
-	return []string{
-		filepath.Join(cb.workspace, "AGENTS.md"),
-		filepath.Join(cb.workspace, "SOUL.md"),
-		filepath.Join(cb.workspace, "USER.md"),
-		filepath.Join(cb.workspace, "IDENTITY.md"),
-		filepath.Join(cb.workspace, "memory", "MEMORY.md"),
+	agentDefinition := cb.LoadAgentDefinition()
+	paths := agentDefinition.trackedPaths(cb.workspace)
+	paths = append(paths, filepath.Join(cb.workspace, "memory", "MEMORY.md"))
+	return uniquePaths(paths)
+}
+
+// skillRoots returns all skill root directories that can affect
+// BuildSkillsSummary output (workspace/global/builtin).
+func (cb *ContextBuilder) skillRoots() []string {
+	if cb.skillsLoader == nil {
+		return []string{filepath.Join(cb.workspace, "skills")}
 	}
+
+	roots := cb.skillsLoader.SkillRoots()
+	if len(roots) == 0 {
+		return []string{filepath.Join(cb.workspace, "skills")}
+	}
+	return roots
 }
 
 // cacheBaseline holds the file existence snapshot and the latest observed
 // mtime across all tracked paths. Used as the cache reference point.
 type cacheBaseline struct {
-	existed  map[string]bool
-	maxMtime time.Time
+	existed    map[string]bool
+	skillFiles map[string]time.Time
+	maxMtime   time.Time
 }
 
 // buildCacheBaseline records which tracked paths currently exist and computes
 // the latest mtime across all tracked files + skills directory contents.
 // Called under write lock when the cache is built.
 func (cb *ContextBuilder) buildCacheBaseline() cacheBaseline {
-	skillsDir := filepath.Join(cb.workspace, "skills")
+	skillRoots := cb.skillRoots()
 
-	// All paths whose existence we track: source files + skills dir.
-	allPaths := append(cb.sourcePaths(), skillsDir)
+	// All paths whose existence we track: source files + all skill roots.
+	allPaths := append(cb.sourcePaths(), skillRoots...)
 
 	existed := make(map[string]bool, len(allPaths))
+	skillFiles := make(map[string]time.Time)
 	var maxMtime time.Time
 
 	for _, p := range allPaths {
@@ -212,17 +272,21 @@ func (cb *ContextBuilder) buildCacheBaseline() cacheBaseline {
 		}
 	}
 
-	// Walk skills files to capture their mtimes too.
-	// Use os.Stat (not d.Info) to match the stat method used in
-	// fileChangedSince / skillFilesModifiedSince for consistency.
-	_ = filepath.WalkDir(skillsDir, func(path string, d fs.DirEntry, walkErr error) error {
-		if walkErr == nil && !d.IsDir() {
-			if info, err := os.Stat(path); err == nil && info.ModTime().After(maxMtime) {
-				maxMtime = info.ModTime()
+	// Walk all skill roots recursively to snapshot skill files and mtimes.
+	// Use os.Stat (not d.Info) for consistency with sourceFilesChanged checks.
+	for _, root := range skillRoots {
+		_ = filepath.WalkDir(root, func(path string, d fs.DirEntry, walkErr error) error {
+			if walkErr == nil && !d.IsDir() {
+				if info, err := os.Stat(path); err == nil {
+					skillFiles[path] = info.ModTime()
+					if info.ModTime().After(maxMtime) {
+						maxMtime = info.ModTime()
+					}
+				}
 			}
-		}
-		return nil
-	})
+			return nil
+		})
+	}
 
 	// If no tracked files exist yet (empty workspace), maxMtime is zero.
 	// Use a very old non-zero time so that:
@@ -234,7 +298,7 @@ func (cb *ContextBuilder) buildCacheBaseline() cacheBaseline {
 		maxMtime = time.Unix(1, 0)
 	}
 
-	return cacheBaseline{existed: existed, maxMtime: maxMtime}
+	return cacheBaseline{existed: existed, skillFiles: skillFiles, maxMtime: maxMtime}
 }
 
 // sourceFilesChangedLocked checks whether any workspace source file has been
@@ -254,21 +318,17 @@ func (cb *ContextBuilder) sourceFilesChangedLocked() bool {
 		return true
 	}
 
-	// --- Skills directory (handled separately from sourcePaths) ---
+	// --- Skill roots (workspace/global/builtin) ---
 	//
-	// 1. Creation/deletion: tracked via existedAtCache, same as bootstrap files.
-	skillsDir := filepath.Join(cb.workspace, "skills")
-	if cb.fileChangedSince(skillsDir) {
-		return true
+	// For each root:
+	// 1. Creation/deletion and root directory mtime changes are tracked by fileChangedSince.
+	// 2. Nested file create/delete/mtime changes are tracked by the skill file snapshot.
+	for _, root := range cb.skillRoots() {
+		if cb.fileChangedSince(root) {
+			return true
+		}
 	}
-
-	// 2. Structural changes (add/remove entries inside the dir) are reflected
-	//    in the directory's own mtime, which fileChangedSince already checks.
-	//
-	// 3. Content-only edits to files inside skills/ do NOT update the parent
-	//    directory mtime on most filesystems, so we recursively walk to check
-	//    individual file mtimes at any nesting depth.
-	if skillFilesModifiedSince(skillsDir, cb.cachedAt) {
+	if skillFilesChangedSince(cb.skillRoots(), cb.skillFilesAtCache) {
 		return true
 	}
 
@@ -309,43 +369,93 @@ func (cb *ContextBuilder) fileChangedSince(path string) bool {
 // if the callback returned nil when its err parameter is non-nil.
 var errWalkStop = errors.New("walk stop")
 
-// skillFilesModifiedSince recursively walks the skills directory and checks
-// whether any file was modified after t. This catches content-only edits at
-// any nesting depth (e.g. skills/name/docs/extra.md) that don't update
-// parent directory mtimes.
-func skillFilesModifiedSince(skillsDir string, t time.Time) bool {
-	changed := false
-	err := filepath.WalkDir(skillsDir, func(path string, d fs.DirEntry, walkErr error) error {
-		if walkErr == nil && !d.IsDir() {
-			if info, statErr := os.Stat(path); statErr == nil && info.ModTime().After(t) {
-				changed = true
-				return errWalkStop // stop walking
-			}
-		}
-		return nil
-	})
-	// errWalkStop is expected (early exit on first changed file).
-	// os.IsNotExist means the skills dir doesn't exist yet — not an error.
-	// Any other error is unexpected and worth logging.
-	if err != nil && !errors.Is(err, errWalkStop) && !os.IsNotExist(err) {
-		logger.DebugCF("agent", "skills walk error", map[string]any{"error": err.Error()})
+// skillFilesChangedSince compares the current recursive skill file tree
+// against the cache-time snapshot. Any create/delete/mtime drift invalidates
+// the cache.
+func skillFilesChangedSince(skillRoots []string, filesAtCache map[string]time.Time) bool {
+	// Defensive: if the snapshot was never initialized, force rebuild.
+	if filesAtCache == nil {
+		return true
 	}
-	return changed
+
+	// Check cached files still exist and keep the same mtime.
+	for path, cachedMtime := range filesAtCache {
+		info, err := os.Stat(path)
+		if err != nil {
+			// A previously tracked file disappeared (or became inaccessible):
+			// either way, cached skill summary may now be stale.
+			return true
+		}
+		if !info.ModTime().Equal(cachedMtime) {
+			return true
+		}
+	}
+
+	// Check no new files appeared under any skill root.
+	changed := false
+	for _, root := range skillRoots {
+		if strings.TrimSpace(root) == "" {
+			continue
+		}
+
+		err := filepath.WalkDir(root, func(path string, d fs.DirEntry, walkErr error) error {
+			if walkErr != nil {
+				// Treat unexpected walk errors as changed to avoid stale cache.
+				if !os.IsNotExist(walkErr) {
+					changed = true
+					return errWalkStop
+				}
+				return nil
+			}
+			if d.IsDir() {
+				return nil
+			}
+			if _, ok := filesAtCache[path]; !ok {
+				changed = true
+				return errWalkStop
+			}
+			return nil
+		})
+
+		if changed {
+			return true
+		}
+		if err != nil && !errors.Is(err, errWalkStop) && !os.IsNotExist(err) {
+			logger.DebugCF("agent", "skills walk error", map[string]any{"error": err.Error()})
+			return true
+		}
+	}
+
+	return false
 }
 
 func (cb *ContextBuilder) LoadBootstrapFiles() string {
-	bootstrapFiles := []string{
-		"AGENTS.md",
-		"SOUL.md",
-		"USER.md",
-		"IDENTITY.md",
+	var sb strings.Builder
+
+	agentDefinition := cb.LoadAgentDefinition()
+	if agentDefinition.Agent != nil {
+		label := string(agentDefinition.Source)
+		if label == "" {
+			label = relativeWorkspacePath(cb.workspace, agentDefinition.Agent.Path)
+		}
+		fmt.Fprintf(&sb, "## %s\n\n%s\n\n", label, agentDefinition.Agent.Body)
+	}
+	if agentDefinition.Soul != nil {
+		fmt.Fprintf(
+			&sb,
+			"## %s\n\n%s\n\n",
+			relativeWorkspacePath(cb.workspace, agentDefinition.Soul.Path),
+			agentDefinition.Soul.Content,
+		)
+	}
+	if agentDefinition.User != nil {
+		fmt.Fprintf(&sb, "## %s\n\n%s\n\n", "USER.md", agentDefinition.User.Content)
 	}
 
-	var sb strings.Builder
-	for _, filename := range bootstrapFiles {
-		filePath := filepath.Join(cb.workspace, filename)
+	if agentDefinition.Source != AgentDefinitionSourceAgent {
+		filePath := filepath.Join(cb.workspace, "IDENTITY.md")
 		if data, err := os.ReadFile(filePath); err == nil {
-			fmt.Fprintf(&sb, "## %s\n\n%s\n\n", filename, data)
+			fmt.Fprintf(&sb, "## %s\n\n%s\n\n", "IDENTITY.md", data)
 		}
 	}
 
@@ -366,7 +476,23 @@ func (cb *ContextBuilder) LoadBootstrapFiles() string {
 //
 // See: https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
 // See: https://platform.openai.com/docs/guides/prompt-caching
-func (cb *ContextBuilder) buildDynamicContext(channel, chatID string) string {
+func formatCurrentSenderLine(senderID, senderDisplayName string) string {
+	senderID = strings.TrimSpace(senderID)
+	senderDisplayName = strings.TrimSpace(senderDisplayName)
+
+	switch {
+	case senderDisplayName != "" && senderID != "":
+		return fmt.Sprintf("Current sender: %s (ID: %s)", senderDisplayName, senderID)
+	case senderDisplayName != "":
+		return fmt.Sprintf("Current sender: %s", senderDisplayName)
+	case senderID != "":
+		return fmt.Sprintf("Current sender: %s", senderID)
+	default:
+		return ""
+	}
+}
+
+func (cb *ContextBuilder) buildDynamicContext(channel, chatID, senderID, senderDisplayName string) string {
 	now := time.Now().Format("2006-01-02 15:04 (Monday)")
 	rt := fmt.Sprintf("%s %s, Go %s", runtime.GOOS, runtime.GOARCH, runtime.Version())
 
@@ -376,6 +502,9 @@ func (cb *ContextBuilder) buildDynamicContext(channel, chatID string) string {
 	if channel != "" && chatID != "" {
 		fmt.Fprintf(&sb, "\n\n## Current Session\nChannel: %s\nChat ID: %s", channel, chatID)
 	}
+	if senderLine := formatCurrentSenderLine(senderID, senderDisplayName); senderLine != "" {
+		fmt.Fprintf(&sb, "\n\n## Current Sender\n%s", senderLine)
+	}
 
 	return sb.String()
 }
@@ -385,7 +514,8 @@ func (cb *ContextBuilder) BuildMessages(
 	summary string,
 	currentMessage string,
 	media []string,
-	channel, chatID string,
+	channel, chatID, senderID, senderDisplayName string,
+	activeSkills ...string,
 ) []providers.Message {
 	messages := []providers.Message{}
 
@@ -401,7 +531,7 @@ func (cb *ContextBuilder) BuildMessages(
 	staticPrompt := cb.BuildSystemPromptWithCache()
 
 	// Build short dynamic context (time, runtime, session) — changes per request
-	dynamicCtx := cb.buildDynamicContext(channel, chatID)
+	dynamicCtx := cb.buildDynamicContext(channel, chatID, senderID, senderDisplayName)
 
 	// Compose a single system message: static (cached) + dynamic + optional summary.
 	// Keeping all system content in one message ensures every provider adapter can
@@ -419,6 +549,11 @@ func (cb *ContextBuilder) BuildMessages(
 		{Type: "text", Text: dynamicCtx},
 	}
 
+	if skillsText := cb.buildActiveSkillsContext(activeSkills); skillsText != "" {
+		stringParts = append(stringParts, skillsText)
+		contentBlocks = append(contentBlocks, providers.ContentBlock{Type: "text", Text: skillsText})
+	}
+
 	if summary != "" {
 		summaryText := fmt.Sprintf(
 			"CONTEXT_SUMMARY: The following is an approximate summary of prior conversation "+
@@ -447,10 +582,7 @@ func (cb *ContextBuilder) BuildMessages(
 		})
 
 	// Log preview of system prompt (avoid logging huge content)
-	preview := fullSystemPrompt
-	if len(preview) > 500 {
-		preview = preview[:500] + "... (truncated)"
-	}
+	preview := utils.Truncate(fullSystemPrompt, 500)
 	logger.DebugCF("agent", "System prompt preview",
 		map[string]any{
 			"preview": preview,
@@ -472,10 +604,14 @@ func (cb *ContextBuilder) BuildMessages(
 
 	// Add current user message
 	if strings.TrimSpace(currentMessage) != "" {
-		messages = append(messages, providers.Message{
+		msg := providers.Message{
 			Role:    "user",
 			Content: currentMessage,
-		})
+		}
+		if len(media) > 0 {
+			msg.Media = media
+		}
+		messages = append(messages, msg)
 	}
 
 	return messages
@@ -543,7 +679,73 @@ func sanitizeHistoryForProvider(history []providers.Message) []providers.Message
 		}
 	}
 
-	return sanitized
+	// Second pass: ensure every assistant message with tool_calls has matching
+	// tool result messages following it. This is required by strict providers
+	// like DeepSeek that enforce: "An assistant message with 'tool_calls' must
+	// be followed by tool messages responding to each 'tool_call_id'."
+	final := make([]providers.Message, 0, len(sanitized))
+	seenToolCallID := make(map[string]bool)
+	for i := 0; i < len(sanitized); i++ {
+		msg := sanitized[i]
+
+		// Deduplicate tool results by ToolCallID
+		if msg.Role == "tool" && msg.ToolCallID != "" {
+			if seenToolCallID[msg.ToolCallID] {
+				logger.DebugCF("agent", "Dropping duplicate tool result", map[string]any{
+					"tool_call_id": msg.ToolCallID,
+				})
+				continue
+			}
+			seenToolCallID[msg.ToolCallID] = true
+		}
+
+		if msg.Role == "assistant" && len(msg.ToolCalls) > 0 {
+			// Collect expected tool_call IDs
+			expected := make(map[string]bool, len(msg.ToolCalls))
+			for _, tc := range msg.ToolCalls {
+				expected[tc.ID] = false
+			}
+
+			// Check following messages for matching tool results
+			toolMsgCount := 0
+			for j := i + 1; j < len(sanitized); j++ {
+				if sanitized[j].Role != "tool" {
+					break
+				}
+				toolMsgCount++
+				if _, exists := expected[sanitized[j].ToolCallID]; exists {
+					expected[sanitized[j].ToolCallID] = true
+				}
+			}
+
+			// If any tool_call_id is missing, drop this assistant message and its partial tool messages
+			allFound := true
+			for toolCallID, found := range expected {
+				if !found {
+					allFound = false
+					logger.DebugCF(
+						"agent",
+						"Dropping assistant message with incomplete tool results",
+						map[string]any{
+							"missing_tool_call_id": toolCallID,
+							"expected_count":       len(expected),
+							"found_count":          toolMsgCount,
+						},
+					)
+					break
+				}
+			}
+
+			if !allFound {
+				// Skip this assistant message and its tool messages
+				i += toolMsgCount
+				continue
+			}
+		}
+		final = append(final, msg)
+	}
+
+	return final
 }
 
 func (cb *ContextBuilder) AddToolResult(
@@ -572,6 +774,68 @@ func (cb *ContextBuilder) AddAssistantMessage(
 	return messages
 }
 
+func (cb *ContextBuilder) buildActiveSkillsContext(skillNames []string) string {
+	if cb.skillsLoader == nil || len(skillNames) == 0 {
+		return ""
+	}
+
+	var ordered []string
+	seen := make(map[string]struct{}, len(skillNames))
+	for _, name := range skillNames {
+		canonical, ok := cb.ResolveSkillName(name)
+		if !ok {
+			continue
+		}
+		if _, exists := seen[canonical]; exists {
+			continue
+		}
+		seen[canonical] = struct{}{}
+		ordered = append(ordered, canonical)
+	}
+	if len(ordered) == 0 {
+		return ""
+	}
+
+	content := cb.skillsLoader.LoadSkillsForContext(ordered)
+	if strings.TrimSpace(content) == "" {
+		return ""
+	}
+
+	return fmt.Sprintf(`# Active Skills
+
+The following skills are active for this request. Follow them when relevant.
+
+%s`, content)
+}
+
+func (cb *ContextBuilder) ListSkillNames() []string {
+	if cb.skillsLoader == nil {
+		return nil
+	}
+
+	allSkills := cb.skillsLoader.ListSkills()
+	names := make([]string, 0, len(allSkills))
+	for _, skill := range allSkills {
+		names = append(names, skill.Name)
+	}
+	return names
+}
+
+func (cb *ContextBuilder) ResolveSkillName(name string) (string, bool) {
+	name = strings.TrimSpace(name)
+	if name == "" || cb.skillsLoader == nil {
+		return "", false
+	}
+
+	for _, skill := range cb.skillsLoader.ListSkills() {
+		if strings.EqualFold(skill.Name, name) {
+			return skill.Name, true
+		}
+	}
+
+	return "", false
+}
+
 // GetSkillsInfo returns information about loaded skills.
 func (cb *ContextBuilder) GetSkillsInfo() map[string]any {
 	allSkills := cb.skillsLoader.ListSkills()
diff --git a/pkg/agent/context_budget.go b/pkg/agent/context_budget.go
new file mode 100644
index 000000000..c87695c7a
--- /dev/null
+++ b/pkg/agent/context_budget.go
@@ -0,0 +1,176 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package agent
+
+import (
+	"encoding/json"
+	"unicode/utf8"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// parseTurnBoundaries returns the starting index of each Turn in the history.
+// A Turn is a complete "user input → LLM iterations → final response" cycle
+// (as defined in #1316). Each Turn begins at a user message and extends
+// through all subsequent assistant/tool messages until the next user message.
+//
+// Cutting at a Turn boundary guarantees that no tool-call sequence
+// (assistant+ToolCalls → tool results) is split across the cut.
+func parseTurnBoundaries(history []providers.Message) []int {
+	var starts []int
+	for i, msg := range history {
+		if msg.Role == "user" {
+			starts = append(starts, i)
+		}
+	}
+	return starts
+}
+
+// isSafeBoundary reports whether index is a valid Turn boundary — i.e.,
+// a position where the kept portion (history[index:]) begins at a user
+// message, so no tool-call sequence is torn apart.
+func isSafeBoundary(history []providers.Message, index int) bool {
+	if index <= 0 || index >= len(history) {
+		return true
+	}
+	return history[index].Role == "user"
+}
+
+// findSafeBoundary locates the nearest Turn boundary to targetIndex.
+// It prefers the boundary at or before targetIndex (preserving more recent
+// context). Falls back to the nearest boundary after targetIndex, and
+// returns targetIndex unchanged only when no Turn boundary exists at all.
+func findSafeBoundary(history []providers.Message, targetIndex int) int {
+	if len(history) == 0 {
+		return 0
+	}
+	if targetIndex <= 0 {
+		return 0
+	}
+	if targetIndex >= len(history) {
+		return len(history)
+	}
+
+	turns := parseTurnBoundaries(history)
+	if len(turns) == 0 {
+		return targetIndex
+	}
+
+	// Find the last Turn boundary at or before targetIndex.
+	// Prefer backward: keeps more recent messages.
+	backward := -1
+	for _, t := range turns {
+		if t <= targetIndex {
+			backward = t
+		}
+	}
+	if backward > 0 {
+		return backward
+	}
+
+	// No valid Turn boundary before target (or only at index 0 which
+	// would keep everything). Use the first Turn after targetIndex.
+	for _, t := range turns {
+		if t > targetIndex {
+			return t
+		}
+	}
+
+	// No Turn boundary after targetIndex either. The only boundary is at
+	// index 0, meaning the entire history is a single Turn. Return 0 to
+	// signal that safe compression is not possible — callers check for
+	// mid <= 0 and skip compression in that case.
+	return 0
+}
+
+// estimateMessageTokens estimates the token count for a single message,
+// including Content, ReasoningContent, ToolCalls arguments, ToolCallID
+// metadata, and Media items. Uses a heuristic of 2.5 characters per token.
+func estimateMessageTokens(msg providers.Message) int {
+	chars := utf8.RuneCountInString(msg.Content)
+
+	// ReasoningContent (extended thinking / chain-of-thought) can be
+	// substantial and is stored in session history via AddFullMessage.
+	if msg.ReasoningContent != "" {
+		chars += utf8.RuneCountInString(msg.ReasoningContent)
+	}
+
+	for _, tc := range msg.ToolCalls {
+		chars += len(tc.ID) + len(tc.Type)
+		if tc.Function != nil {
+			// Count function name + arguments (the wire format for most providers).
+			// tc.Name mirrors tc.Function.Name — count only once to avoid double-counting.
+			chars += len(tc.Function.Name) + len(tc.Function.Arguments)
+		} else {
+			// Fallback: some provider formats use top-level Name without Function.
+			chars += len(tc.Name)
+		}
+	}
+
+	if msg.ToolCallID != "" {
+		chars += len(msg.ToolCallID)
+	}
+
+	// Per-message overhead for role label, JSON structure, separators.
+	const messageOverhead = 12
+	chars += messageOverhead
+
+	tokens := chars * 2 / 5
+
+	// Media items (images, files) are serialized by provider adapters into
+	// multipart or image_url payloads. Add a fixed per-item token estimate
+	// directly (not through the chars heuristic) since actual cost depends
+	// on resolution and provider-specific image tokenization.
+	const mediaTokensPerItem = 256
+	tokens += len(msg.Media) * mediaTokensPerItem
+
+	return tokens
+}
+
+// estimateToolDefsTokens estimates the total token cost of tool definitions
+// as they appear in the LLM request. Each tool's name, description, and
+// JSON schema parameters contribute to the context window budget.
+func estimateToolDefsTokens(defs []providers.ToolDefinition) int {
+	if len(defs) == 0 {
+		return 0
+	}
+
+	totalChars := 0
+	for _, d := range defs {
+		totalChars += len(d.Function.Name) + len(d.Function.Description)
+
+		if d.Function.Parameters != nil {
+			if paramJSON, err := json.Marshal(d.Function.Parameters); err == nil {
+				totalChars += len(paramJSON)
+			}
+		}
+
+		// Per-tool overhead: type field, JSON structure, separators.
+		totalChars += 20
+	}
+
+	return totalChars * 2 / 5
+}
+
+// isOverContextBudget checks whether the assembled messages plus tool definitions
+// and output reserve would exceed the model's context window. This enables
+// proactive compression before calling the LLM, rather than reacting to 400 errors.
+func isOverContextBudget(
+	contextWindow int,
+	messages []providers.Message,
+	toolDefs []providers.ToolDefinition,
+	maxTokens int,
+) bool {
+	msgTokens := 0
+	for _, m := range messages {
+		msgTokens += estimateMessageTokens(m)
+	}
+
+	toolTokens := estimateToolDefsTokens(toolDefs)
+	total := msgTokens + toolTokens + maxTokens
+
+	return total > contextWindow
+}
diff --git a/pkg/agent/context_budget_test.go b/pkg/agent/context_budget_test.go
new file mode 100644
index 000000000..870f0fbe6
--- /dev/null
+++ b/pkg/agent/context_budget_test.go
@@ -0,0 +1,826 @@
+package agent
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// msgUser creates a user message.
+func msgUser(content string) providers.Message {
+	return providers.Message{Role: "user", Content: content}
+}
+
+// msgAssistant creates a plain assistant message (no tool calls).
+func msgAssistant(content string) providers.Message {
+	return providers.Message{Role: "assistant", Content: content}
+}
+
+// msgAssistantTC creates an assistant message with tool calls.
+func msgAssistantTC(toolIDs ...string) providers.Message {
+	tcs := make([]providers.ToolCall, len(toolIDs))
+	for i, id := range toolIDs {
+		tcs[i] = providers.ToolCall{
+			ID:   id,
+			Type: "function",
+			Name: "tool_" + id,
+			Function: &providers.FunctionCall{
+				Name:      "tool_" + id,
+				Arguments: `{"key":"value"}`,
+			},
+		}
+	}
+	return providers.Message{Role: "assistant", ToolCalls: tcs}
+}
+
+// msgTool creates a tool result message.
+func msgTool(callID, content string) providers.Message {
+	return providers.Message{Role: "tool", ToolCallID: callID, Content: content}
+}
+
+func TestParseTurnBoundaries(t *testing.T) {
+	tests := []struct {
+		name    string
+		history []providers.Message
+		want    []int
+	}{
+		{
+			name:    "empty history",
+			history: nil,
+			want:    nil,
+		},
+		{
+			name: "simple exchange",
+			history: []providers.Message{
+				msgUser("q1"),
+				msgAssistant("a1"),
+				msgUser("q2"),
+				msgAssistant("a2"),
+			},
+			want: []int{0, 2},
+		},
+		{
+			name: "tool-call Turn",
+			history: []providers.Message{
+				msgUser("search"),
+				msgAssistantTC("tc1"),
+				msgTool("tc1", "result"),
+				msgAssistant("found it"),
+				msgUser("thanks"),
+				msgAssistant("welcome"),
+			},
+			want: []int{0, 4},
+		},
+		{
+			name: "chained tool calls in single Turn",
+			history: []providers.Message{
+				msgUser("save and notify"),
+				msgAssistantTC("tc_save"),
+				msgTool("tc_save", "saved"),
+				msgAssistantTC("tc_notify"),
+				msgTool("tc_notify", "notified"),
+				msgAssistant("done"),
+			},
+			want: []int{0},
+		},
+		{
+			name: "no user messages",
+			history: []providers.Message{
+				msgAssistant("a1"),
+				msgAssistant("a2"),
+			},
+			want: nil,
+		},
+		{
+			name: "leading non-user messages",
+			history: []providers.Message{
+				msgAssistantTC("tc1"),
+				msgTool("tc1", "r1"),
+				msgAssistant("greeting"),
+				msgUser("hello"),
+				msgAssistant("hi"),
+			},
+			want: []int{3},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := parseTurnBoundaries(tt.history)
+			if len(got) != len(tt.want) {
+				t.Errorf("parseTurnBoundaries() = %v, want %v", got, tt.want)
+				return
+			}
+			for i := range got {
+				if got[i] != tt.want[i] {
+					t.Errorf("parseTurnBoundaries()[%d] = %d, want %d", i, got[i], tt.want[i])
+				}
+			}
+		})
+	}
+}
+
+func TestIsSafeBoundary(t *testing.T) {
+	tests := []struct {
+		name    string
+		history []providers.Message
+		index   int
+		want    bool
+	}{
+		{
+			name:    "empty history, index 0",
+			history: nil,
+			index:   0,
+			want:    true,
+		},
+		{
+			name:    "single user message, index 0",
+			history: []providers.Message{msgUser("hi")},
+			index:   0,
+			want:    true,
+		},
+		{
+			name:    "single user message, index 1 (end)",
+			history: []providers.Message{msgUser("hi")},
+			index:   1,
+			want:    true,
+		},
+		{
+			name: "at user message",
+			history: []providers.Message{
+				msgAssistant("hello"),
+				msgUser("how are you"),
+				msgAssistant("fine"),
+			},
+			index: 1,
+			want:  true,
+		},
+		{
+			name: "at assistant without tool calls",
+			history: []providers.Message{
+				msgUser("hello"),
+				msgAssistant("response"),
+				msgUser("follow up"),
+			},
+			index: 1,
+			want:  false,
+		},
+		{
+			name: "at assistant with tool calls",
+			history: []providers.Message{
+				msgUser("search something"),
+				msgAssistantTC("tc1"),
+				msgTool("tc1", "result"),
+				msgAssistant("here is what I found"),
+			},
+			index: 1,
+			want:  false,
+		},
+		{
+			name: "at tool result",
+			history: []providers.Message{
+				msgUser("do something"),
+				msgAssistantTC("tc1"),
+				msgTool("tc1", "done"),
+				msgAssistant("completed"),
+			},
+			index: 2,
+			want:  false,
+		},
+		{
+			name: "negative index",
+			history: []providers.Message{
+				msgUser("hello"),
+			},
+			index: -1,
+			want:  true,
+		},
+		{
+			name: "index beyond length",
+			history: []providers.Message{
+				msgUser("hello"),
+			},
+			index: 5,
+			want:  true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isSafeBoundary(tt.history, tt.index)
+			if got != tt.want {
+				t.Errorf("isSafeBoundary(history, %d) = %v, want %v", tt.index, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFindSafeBoundary(t *testing.T) {
+	tests := []struct {
+		name        string
+		history     []providers.Message
+		targetIndex int
+		want        int
+	}{
+		{
+			name:        "empty history",
+			history:     nil,
+			targetIndex: 0,
+			want:        0,
+		},
+		{
+			name:        "target at 0",
+			history:     []providers.Message{msgUser("hi")},
+			targetIndex: 0,
+			want:        0,
+		},
+		{
+			name:        "target beyond length",
+			history:     []providers.Message{msgUser("hi")},
+			targetIndex: 5,
+			want:        1,
+		},
+		{
+			name: "target already at user message",
+			history: []providers.Message{
+				msgUser("q1"),
+				msgAssistant("a1"),
+				msgUser("q2"),
+				msgAssistant("a2"),
+			},
+			targetIndex: 2,
+			want:        2,
+		},
+		{
+			name: "target at assistant, scan backward finds user",
+			history: []providers.Message{
+				msgUser("q1"),
+				msgAssistant("a1"),
+				msgUser("q2"),
+				msgAssistant("a2"),
+				msgUser("q3"),
+			},
+			targetIndex: 3, // assistant "a2"
+			want:        2, // backward to user "q2"
+		},
+		{
+			name: "target inside tool sequence, scan backward finds user",
+			history: []providers.Message{
+				msgUser("q1"),
+				msgAssistant("a1"),
+				msgUser("q2"),
+				msgAssistantTC("tc1", "tc2"),
+				msgTool("tc1", "r1"),
+				msgTool("tc2", "r2"),
+				msgAssistant("summary"),
+				msgUser("q3"),
+			},
+			targetIndex: 4, // tool result "r1"
+			want:        2, // backward: 3=assistant+TC (not safe), 2=user → safe
+		},
+		{
+			name: "target inside tool sequence, backward finds user before chain",
+			history: []providers.Message{
+				msgUser("q1"),
+				msgAssistant("a1"),
+				msgUser("q2"),
+				msgAssistantTC("tc1", "tc2"),
+				msgTool("tc1", "r1"),
+				msgTool("tc2", "r2"),
+				msgAssistant("summary"),
+				msgUser("q3"),
+			},
+			targetIndex: 5, // tool result "r2"
+			want:        2, // backward: 4=tool, 3=assistant+TC, 2=user → safe
+		},
+		{
+			name: "no backward user, scan forward finds one",
+			history: []providers.Message{
+				msgAssistantTC("tc1"),
+				msgTool("tc1", "r1"),
+				msgAssistant("a1"),
+				msgUser("q1"),
+			},
+			targetIndex: 1, // tool result
+			want:        3, // forward to user "q1"
+		},
+		{
+			name: "multi-step tool chain preserves atomicity",
+			history: []providers.Message{
+				msgUser("q1"),
+				msgAssistant("a1"),
+				msgUser("q2"),
+				msgAssistantTC("tc1"),
+				msgTool("tc1", "r1"),
+				msgAssistantTC("tc2"),
+				msgTool("tc2", "r2"),
+				msgAssistant("final"),
+				msgUser("q3"),
+				msgAssistant("a3"),
+			},
+			targetIndex: 5, // second assistant+TC
+			want:        2, // backward: 4=tool, 3=assistant+TC, 2=user → safe
+		},
+		{
+			name: "all non-user messages returns target unchanged",
+			history: []providers.Message{
+				msgAssistant("a1"),
+				msgAssistant("a2"),
+				msgAssistant("a3"),
+			},
+			targetIndex: 1,
+			want:        1,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := findSafeBoundary(tt.history, tt.targetIndex)
+			if got != tt.want {
+				t.Errorf("findSafeBoundary(history, %d) = %d, want %d",
+					tt.targetIndex, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFindSafeBoundary_SingleTurnReturnsZero(t *testing.T) {
+	// A single Turn with no subsequent user message. The only Turn boundary
+	// is at index 0; cutting anywhere else would split the Turn's tool
+	// sequence. findSafeBoundary must return 0 so callers skip compression.
+	history := []providers.Message{
+		msgUser("do everything"), // 0 ← only Turn boundary
+		msgAssistantTC("tc1"),    // 1
+		msgTool("tc1", "result"), // 2
+		msgAssistant("all done"), // 3
+	}
+
+	got := findSafeBoundary(history, 2)
+	if got != 0 {
+		t.Errorf("findSafeBoundary(single_turn, 2) = %d, want 0 (cannot split single Turn)", got)
+	}
+}
+
+func TestFindSafeBoundary_BackwardScanSkipsToolSequence(t *testing.T) {
+	// A long tool-call chain: user → assistant+TC → tool → tool → ... → assistant → user
+	// Target is inside the chain; boundary should skip the entire chain backward.
+	history := []providers.Message{
+		msgUser("start"),                 // 0
+		msgAssistant("before chain"),     // 1
+		msgUser("trigger"),               // 2 ← expected safe boundary
+		msgAssistantTC("t1", "t2", "t3"), // 3
+		msgTool("t1", "r1"),              // 4
+		msgTool("t2", "r2"),              // 5
+		msgTool("t3", "r3"),              // 6
+		msgAssistantTC("t4"),             // 7
+		msgTool("t4", "r4"),              // 8
+		msgAssistant("chain done"),       // 9
+		msgUser("next"),                  // 10
+	}
+
+	// Target at index 6 (middle of tool results)
+	got := findSafeBoundary(history, 6)
+	if got != 2 {
+		t.Errorf("findSafeBoundary(history, 6) = %d, want 2 (user before chain)", got)
+	}
+}
+
+func TestEstimateMessageTokens(t *testing.T) {
+	tests := []struct {
+		name string
+		msg  providers.Message
+		want int // minimum expected tokens (exact value depends on overhead)
+	}{
+		{
+			name: "plain user message",
+			msg:  msgUser("Hello, world!"),
+			want: 1, // at least some tokens
+		},
+		{
+			name: "empty message still has overhead",
+			msg:  providers.Message{Role: "user"},
+			want: 1, // message overhead alone
+		},
+		{
+			name: "assistant with tool calls",
+			msg:  msgAssistantTC("tc_123"),
+			want: 1,
+		},
+		{
+			name: "tool result with ID",
+			msg:  msgTool("call_abc", "Here is the search result with lots of content"),
+			want: 1,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := estimateMessageTokens(tt.msg)
+			if got < tt.want {
+				t.Errorf("estimateMessageTokens() = %d, want >= %d", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestEstimateMessageTokens_ToolCallsContribute(t *testing.T) {
+	plain := msgAssistant("thinking")
+	withTC := providers.Message{
+		Role:    "assistant",
+		Content: "thinking",
+		ToolCalls: []providers.ToolCall{
+			{
+				ID:   "call_1",
+				Type: "function",
+				Name: "web_search",
+				Function: &providers.FunctionCall{
+					Name:      "web_search",
+					Arguments: `{"query":"picoclaw agent framework","max_results":5}`,
+				},
+			},
+		},
+	}
+
+	plainTokens := estimateMessageTokens(plain)
+	withTCTokens := estimateMessageTokens(withTC)
+
+	if withTCTokens <= plainTokens {
+		t.Errorf("message with ToolCalls (%d tokens) should exceed plain message (%d tokens)",
+			withTCTokens, plainTokens)
+	}
+}
+
+func TestEstimateMessageTokens_MultibyteContent(t *testing.T) {
+	// Multi-byte characters (e.g. emoji, accented letters) are single runes
+	// but may map to different token counts. The heuristic should still produce
+	// reasonable estimates via RuneCountInString.
+	msg := msgUser("caf\u00e9 na\u00efve r\u00e9sum\u00e9 \u00fcber stra\u00dfe")
+	tokens := estimateMessageTokens(msg)
+	if tokens <= 0 {
+		t.Errorf("multibyte message should produce positive token count, got %d", tokens)
+	}
+}
+
+func TestEstimateMessageTokens_LargeArguments(t *testing.T) {
+	// Simulate a tool call with large JSON arguments.
+	largeArgs := fmt.Sprintf(`{"content":"%s"}`, strings.Repeat("x", 5000))
+	msg := providers.Message{
+		Role: "assistant",
+		ToolCalls: []providers.ToolCall{
+			{
+				ID:   "call_large",
+				Type: "function",
+				Name: "write_file",
+				Function: &providers.FunctionCall{
+					Name:      "write_file",
+					Arguments: largeArgs,
+				},
+			},
+		},
+	}
+
+	tokens := estimateMessageTokens(msg)
+	// 5000+ chars → at least 2000 tokens with the 2.5 char/token heuristic
+	if tokens < 2000 {
+		t.Errorf("large tool call arguments should produce significant token count, got %d", tokens)
+	}
+}
+
+func TestEstimateMessageTokens_ReasoningContent(t *testing.T) {
+	plain := msgAssistant("result")
+	withReasoning := providers.Message{
+		Role:             "assistant",
+		Content:          "result",
+		ReasoningContent: strings.Repeat("thinking step ", 200),
+	}
+
+	plainTokens := estimateMessageTokens(plain)
+	reasoningTokens := estimateMessageTokens(withReasoning)
+
+	if reasoningTokens <= plainTokens {
+		t.Errorf("message with ReasoningContent (%d tokens) should exceed plain message (%d tokens)",
+			reasoningTokens, plainTokens)
+	}
+}
+
+func TestEstimateMessageTokens_MediaItems(t *testing.T) {
+	plain := msgUser("describe this")
+	withMedia := providers.Message{
+		Role:    "user",
+		Content: "describe this",
+		Media:   []string{"media://img1.png", "media://img2.png"},
+	}
+
+	plainTokens := estimateMessageTokens(plain)
+	mediaTokens := estimateMessageTokens(withMedia)
+
+	if mediaTokens <= plainTokens {
+		t.Errorf("message with Media (%d tokens) should exceed plain message (%d tokens)",
+			mediaTokens, plainTokens)
+	}
+
+	// Each media item should add exactly 256 tokens (not run through chars*2/5).
+	expectedDelta := 256 * 2
+	actualDelta := mediaTokens - plainTokens
+	if actualDelta != expectedDelta {
+		t.Errorf("2 media items should add %d tokens, got delta %d", expectedDelta, actualDelta)
+	}
+}
+
+// --- estimateToolDefsTokens tests ---
+
+func TestEstimateToolDefsTokens(t *testing.T) {
+	tests := []struct {
+		name string
+		defs []providers.ToolDefinition
+		want int // minimum expected tokens
+	}{
+		{
+			name: "empty tool list",
+			defs: nil,
+			want: 0,
+		},
+		{
+			name: "single tool with params",
+			defs: []providers.ToolDefinition{
+				{
+					Type: "function",
+					Function: providers.ToolFunctionDefinition{
+						Name:        "web_search",
+						Description: "Search the web for information",
+						Parameters: map[string]any{
+							"type": "object",
+							"properties": map[string]any{
+								"query": map[string]any{"type": "string"},
+							},
+							"required": []any{"query"},
+						},
+					},
+				},
+			},
+			want: 1,
+		},
+		{
+			name: "tool without params",
+			defs: []providers.ToolDefinition{
+				{
+					Type: "function",
+					Function: providers.ToolFunctionDefinition{
+						Name:        "list_dir",
+						Description: "List directory contents",
+					},
+				},
+			},
+			want: 1,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := estimateToolDefsTokens(tt.defs)
+			if got < tt.want {
+				t.Errorf("estimateToolDefsTokens() = %d, want >= %d", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestEstimateToolDefsTokens_ScalesWithCount(t *testing.T) {
+	makeTool := func(name string) providers.ToolDefinition {
+		return providers.ToolDefinition{
+			Type: "function",
+			Function: providers.ToolFunctionDefinition{
+				Name:        name,
+				Description: "A test tool that does something useful",
+				Parameters: map[string]any{
+					"type": "object",
+					"properties": map[string]any{
+						"input": map[string]any{"type": "string", "description": "Input value"},
+					},
+				},
+			},
+		}
+	}
+
+	one := estimateToolDefsTokens([]providers.ToolDefinition{makeTool("tool_a")})
+	three := estimateToolDefsTokens([]providers.ToolDefinition{
+		makeTool("tool_a"), makeTool("tool_b"), makeTool("tool_c"),
+	})
+
+	if three <= one {
+		t.Errorf("3 tools (%d tokens) should exceed 1 tool (%d tokens)", three, one)
+	}
+}
+
+// --- isOverContextBudget tests ---
+
+func TestIsOverContextBudget(t *testing.T) {
+	systemMsg := providers.Message{Role: "system", Content: strings.Repeat("x", 1000)}
+	userMsg := msgUser("hello")
+	smallHistory := []providers.Message{systemMsg, msgUser("q1"), msgAssistant("a1"), userMsg}
+
+	tools := []providers.ToolDefinition{
+		{
+			Type: "function",
+			Function: providers.ToolFunctionDefinition{
+				Name:        "test_tool",
+				Description: "A test tool",
+				Parameters:  map[string]any{"type": "object"},
+			},
+		},
+	}
+
+	tests := []struct {
+		name          string
+		contextWindow int
+		messages      []providers.Message
+		toolDefs      []providers.ToolDefinition
+		maxTokens     int
+		want          bool
+	}{
+		{
+			name:          "within budget",
+			contextWindow: 100000,
+			messages:      smallHistory,
+			toolDefs:      tools,
+			maxTokens:     4096,
+			want:          false,
+		},
+		{
+			name:          "over budget with small window",
+			contextWindow: 100, // very small window
+			messages:      smallHistory,
+			toolDefs:      tools,
+			maxTokens:     4096,
+			want:          true,
+		},
+		{
+			name:          "large max_tokens eats budget",
+			contextWindow: 2000,
+			messages:      smallHistory,
+			toolDefs:      tools,
+			maxTokens:     1800, // leaves almost no room
+			want:          true,
+		},
+		{
+			name:          "empty messages within budget",
+			contextWindow: 10000,
+			messages:      nil,
+			toolDefs:      nil,
+			maxTokens:     4096,
+			want:          false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isOverContextBudget(tt.contextWindow, tt.messages, tt.toolDefs, tt.maxTokens)
+			if got != tt.want {
+				t.Errorf("isOverContextBudget() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+// --- Tests reflecting actual session data shape ---
+// Session history never contains system messages. The system prompt is
+// built dynamically by BuildMessages. These tests use realistic history
+// shapes: user/assistant/tool only, with tool chains and reasoning content.
+
+func TestFindSafeBoundary_SessionHistoryNoSystem(t *testing.T) {
+	// Real session history starts with a user message, not a system message.
+	history := []providers.Message{
+		msgUser("hello"),               // 0
+		msgAssistant("hi there"),       // 1
+		msgUser("search for X"),        // 2
+		msgAssistantTC("tc1"),          // 3
+		msgTool("tc1", "found X"),      // 4
+		msgAssistant("here is X"),      // 5
+		msgUser("thanks"),              // 6
+		msgAssistant("you're welcome"), // 7
+	}
+
+	// Mid-point is 4 (tool result). Should snap backward to 2 (user).
+	got := findSafeBoundary(history, 4)
+	if got != 2 {
+		t.Errorf("findSafeBoundary(session_history, 4) = %d, want 2", got)
+	}
+}
+
+func TestFindSafeBoundary_SessionWithChainedTools(t *testing.T) {
+	// Session with chained tool calls (save then notify).
+	history := []providers.Message{
+		msgUser("save and notify"),       // 0
+		msgAssistantTC("tc_save"),        // 1
+		msgTool("tc_save", "saved"),      // 2
+		msgAssistantTC("tc_notify"),      // 3
+		msgTool("tc_notify", "notified"), // 4
+		msgAssistant("done"),             // 5
+		msgUser("check status"),          // 6
+		msgAssistant("all good"),         // 7
+	}
+
+	// Target at 3 (inside chain). Should find user at 0, but backward
+	// scan stops at i>0, so forward scan finds user at 6.
+	// Actually: backward from 3: 2=tool (no), 1=assistantTC (no). Forward: 4=tool, 5=asst, 6=user ✓
+	got := findSafeBoundary(history, 3)
+	if got != 6 {
+		t.Errorf("findSafeBoundary(chained_tools, 3) = %d, want 6", got)
+	}
+}
+
+func TestEstimateMessageTokens_WithReasoningAndMedia(t *testing.T) {
+	// Message with all fields populated — mirrors what AddFullMessage stores.
+	msg := providers.Message{
+		Role:             "assistant",
+		Content:          "Here is the analysis.",
+		ReasoningContent: strings.Repeat("Let me think about this carefully. ", 50),
+		ToolCalls: []providers.ToolCall{
+			{
+				ID:   "call_1",
+				Type: "function",
+				Name: "analyze",
+				Function: &providers.FunctionCall{
+					Name:      "analyze",
+					Arguments: `{"data":"sample","depth":3}`,
+				},
+			},
+		},
+	}
+
+	tokens := estimateMessageTokens(msg)
+
+	// ReasoningContent alone is ~1700 chars → ~680 tokens.
+	// Content + TC + overhead adds more. Should be well above 500.
+	if tokens < 500 {
+		t.Errorf("message with reasoning+toolcalls should have significant tokens, got %d", tokens)
+	}
+
+	// Compare without reasoning to ensure it's counted.
+	msgNoReasoning := msg
+	msgNoReasoning.ReasoningContent = ""
+	tokensNoReasoning := estimateMessageTokens(msgNoReasoning)
+
+	if tokens <= tokensNoReasoning {
+		t.Errorf("reasoning content should add tokens: with=%d, without=%d", tokens, tokensNoReasoning)
+	}
+}
+
+func TestIsOverContextBudget_RealisticSession(t *testing.T) {
+	// Simulate what BuildMessages produces: system + session history + current user.
+	// System message is built by BuildMessages, not stored in session.
+	systemMsg := providers.Message{
+		Role:    "system",
+		Content: strings.Repeat("system prompt content ", 100),
+	}
+	sessionHistory := []providers.Message{
+		msgUser("first question"),
+		msgAssistant("first answer"),
+		msgUser("use tool X"),
+		{
+			Role:    "assistant",
+			Content: "I'll use tool X",
+			ToolCalls: []providers.ToolCall{
+				{
+					ID: "tc1", Type: "function", Name: "tool_x",
+					Function: &providers.FunctionCall{
+						Name:      "tool_x",
+						Arguments: `{"query":"test","verbose":true}`,
+					},
+				},
+			},
+		},
+		{Role: "tool", Content: strings.Repeat("result data ", 200), ToolCallID: "tc1"},
+		msgAssistant("Here are the results from tool X."),
+	}
+	currentUser := msgUser("follow up question")
+
+	// Assemble as BuildMessages would.
+	messages := make([]providers.Message, 0, 1+len(sessionHistory)+1)
+	messages = append(messages, systemMsg)
+	messages = append(messages, sessionHistory...)
+	messages = append(messages, currentUser)
+
+	tools := []providers.ToolDefinition{
+		{
+			Type: "function",
+			Function: providers.ToolFunctionDefinition{
+				Name:        "tool_x",
+				Description: "A useful tool",
+				Parameters:  map[string]any{"type": "object"},
+			},
+		},
+	}
+
+	// With a large context window, should be within budget.
+	if isOverContextBudget(131072, messages, tools, 32768) {
+		t.Error("realistic session should be within 131072 context window")
+	}
+
+	// With a tiny context window, should exceed budget.
+	if !isOverContextBudget(500, messages, tools, 32768) {
+		t.Error("realistic session should exceed 500 context window")
+	}
+}
diff --git a/pkg/agent/context_cache_test.go b/pkg/agent/context_cache_test.go
index 0905e8a46..81a1534b9 100644
--- a/pkg/agent/context_cache_test.go
+++ b/pkg/agent/context_cache_test.go
@@ -37,7 +37,7 @@ func setupWorkspace(t *testing.T, files map[string]string) string {
 // Codex (only reads last system message as instructions).
 func TestSingleSystemMessage(t *testing.T) {
 	tmpDir := setupWorkspace(t, map[string]string{
-		"IDENTITY.md": "# Identity\nTest agent.",
+		"AGENT.md": "# Agent\nTest agent.",
 	})
 	defer os.RemoveAll(tmpDir)
 
@@ -82,7 +82,7 @@ func TestSingleSystemMessage(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			msgs := cb.BuildMessages(tt.history, tt.summary, tt.message, nil, "test", "chat1")
+			msgs := cb.BuildMessages(tt.history, tt.summary, tt.message, nil, "test", "chat1", "", "")
 
 			systemCount := 0
 			for _, m := range msgs {
@@ -126,6 +126,68 @@ func TestSingleSystemMessage(t *testing.T) {
 	}
 }
 
+func TestBuildMessages_CurrentSenderDynamicContext(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"IDENTITY.md": "# Identity\nTest agent.",
+	})
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	tests := []struct {
+		name              string
+		senderID          string
+		senderDisplayName string
+		wantLine          string
+		wantSection       bool
+	}{
+		{
+			name:              "both id and display name",
+			senderID:          "feishu:ou_xxx",
+			senderDisplayName: "Zhang San",
+			wantLine:          "Current sender: Zhang San (ID: feishu:ou_xxx)",
+			wantSection:       true,
+		},
+		{
+			name:              "display name only",
+			senderDisplayName: "Alice",
+			wantLine:          "Current sender: Alice",
+			wantSection:       true,
+		},
+		{
+			name:        "id only",
+			senderID:    "discord:123",
+			wantLine:    "Current sender: discord:123",
+			wantSection: true,
+		},
+		{
+			name:        "no sender info",
+			wantSection: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			msgs := cb.BuildMessages(nil, "", "hello", nil, "discord", "chat1", tt.senderID, tt.senderDisplayName)
+			sys := msgs[0].Content
+
+			if tt.wantSection {
+				if !strings.Contains(sys, "## Current Sender") {
+					t.Fatalf("system prompt missing Current Sender section:\n%s", sys)
+				}
+				if !strings.Contains(sys, tt.wantLine) {
+					t.Fatalf("system prompt missing sender line %q:\n%s", tt.wantLine, sys)
+				}
+				return
+			}
+
+			if strings.Contains(sys, "## Current Sender") {
+				t.Fatalf("system prompt should omit Current Sender section:\n%s", sys)
+			}
+		})
+	}
+}
+
 // TestMtimeAutoInvalidation verifies that the cache detects source file changes
 // via mtime without requiring explicit InvalidateCache().
 // Fix: original implementation had no auto-invalidation — edits to bootstrap files,
@@ -140,10 +202,10 @@ func TestMtimeAutoInvalidation(t *testing.T) {
 	}{
 		{
 			name:       "bootstrap file change",
-			file:       "IDENTITY.md",
-			contentV1:  "# Original Identity",
-			contentV2:  "# Updated Identity",
-			checkField: "Updated Identity",
+			file:       "AGENT.md",
+			contentV1:  "# Original Agent",
+			contentV2:  "# Updated Agent",
+			checkField: "Updated Agent",
 		},
 		{
 			name:       "memory file change",
@@ -218,7 +280,7 @@ func TestMtimeAutoInvalidation(t *testing.T) {
 // even when source files haven't changed (useful for tests and reload commands).
 func TestExplicitInvalidateCache(t *testing.T) {
 	tmpDir := setupWorkspace(t, map[string]string{
-		"IDENTITY.md": "# Test Identity",
+		"AGENT.md": "# Test Agent",
 	})
 	defer os.RemoveAll(tmpDir)
 
@@ -245,8 +307,8 @@ func TestExplicitInvalidateCache(t *testing.T) {
 // when no files change (regression test for issue #607).
 func TestCacheStability(t *testing.T) {
 	tmpDir := setupWorkspace(t, map[string]string{
-		"IDENTITY.md": "# Identity\nContent",
-		"SOUL.md":     "# Soul\nContent",
+		"AGENT.md": "# Agent\nContent",
+		"SOUL.md":  "# Soul\nContent",
 	})
 	defer os.RemoveAll(tmpDir)
 
@@ -383,13 +445,169 @@ Updated content.`
 	}
 }
 
+// TestGlobalSkillFileContentChange verifies that modifying a global skill
+// (~/.picoclaw/skills) invalidates the cached system prompt.
+func TestGlobalSkillFileContentChange(t *testing.T) {
+	tmpHome := t.TempDir()
+	t.Setenv("HOME", tmpHome)
+
+	tmpDir := setupWorkspace(t, nil)
+	defer os.RemoveAll(tmpDir)
+
+	globalSkillPath := filepath.Join(tmpHome, ".picoclaw", "skills", "global-skill", "SKILL.md")
+	if err := os.MkdirAll(filepath.Dir(globalSkillPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	v1 := `---
+name: global-skill
+description: global-v1
+---
+# Global Skill v1`
+	if err := os.WriteFile(globalSkillPath, []byte(v1), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cb := NewContextBuilder(tmpDir)
+	sp1 := cb.BuildSystemPromptWithCache()
+	if !strings.Contains(sp1, "global-v1") {
+		t.Fatal("expected initial prompt to contain global skill description")
+	}
+
+	v2 := `---
+name: global-skill
+description: global-v2
+---
+# Global Skill v2`
+	if err := os.WriteFile(globalSkillPath, []byte(v2), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	future := time.Now().Add(2 * time.Second)
+	if err := os.Chtimes(globalSkillPath, future, future); err != nil {
+		t.Fatalf("failed to update mtime for %s: %v", globalSkillPath, err)
+	}
+
+	cb.systemPromptMutex.RLock()
+	changed := cb.sourceFilesChangedLocked()
+	cb.systemPromptMutex.RUnlock()
+	if !changed {
+		t.Fatal("sourceFilesChangedLocked() should detect global skill file content change")
+	}
+
+	sp2 := cb.BuildSystemPromptWithCache()
+	if !strings.Contains(sp2, "global-v2") {
+		t.Error("rebuilt prompt should contain updated global skill description")
+	}
+	if sp1 == sp2 {
+		t.Error("cache should be invalidated when global skill file content changes")
+	}
+}
+
+// TestBuiltinSkillFileContentChange verifies that modifying a builtin skill
+// invalidates the cached system prompt.
+func TestBuiltinSkillFileContentChange(t *testing.T) {
+	tmpHome := t.TempDir()
+	t.Setenv("HOME", tmpHome)
+
+	tmpDir := setupWorkspace(t, nil)
+	defer os.RemoveAll(tmpDir)
+
+	builtinRoot := t.TempDir()
+	t.Setenv("PICOCLAW_BUILTIN_SKILLS", builtinRoot)
+
+	builtinSkillPath := filepath.Join(builtinRoot, "builtin-skill", "SKILL.md")
+	if err := os.MkdirAll(filepath.Dir(builtinSkillPath), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	v1 := `---
+name: builtin-skill
+description: builtin-v1
+---
+# Builtin Skill v1`
+	if err := os.WriteFile(builtinSkillPath, []byte(v1), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	cb := NewContextBuilder(tmpDir)
+	sp1 := cb.BuildSystemPromptWithCache()
+	if !strings.Contains(sp1, "builtin-v1") {
+		t.Fatal("expected initial prompt to contain builtin skill description")
+	}
+
+	v2 := `---
+name: builtin-skill
+description: builtin-v2
+---
+# Builtin Skill v2`
+	if err := os.WriteFile(builtinSkillPath, []byte(v2), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	future := time.Now().Add(2 * time.Second)
+	if err := os.Chtimes(builtinSkillPath, future, future); err != nil {
+		t.Fatalf("failed to update mtime for %s: %v", builtinSkillPath, err)
+	}
+
+	cb.systemPromptMutex.RLock()
+	changed := cb.sourceFilesChangedLocked()
+	cb.systemPromptMutex.RUnlock()
+	if !changed {
+		t.Fatal("sourceFilesChangedLocked() should detect builtin skill file content change")
+	}
+
+	sp2 := cb.BuildSystemPromptWithCache()
+	if !strings.Contains(sp2, "builtin-v2") {
+		t.Error("rebuilt prompt should contain updated builtin skill description")
+	}
+	if sp1 == sp2 {
+		t.Error("cache should be invalidated when builtin skill file content changes")
+	}
+}
+
+// TestSkillFileDeletionInvalidatesCache verifies that deleting a nested skill
+// file invalidates the cached system prompt.
+func TestSkillFileDeletionInvalidatesCache(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"skills/delete-me/SKILL.md": `---
+name: delete-me
+description: delete-me-v1
+---
+# Delete Me`,
+	})
+	defer os.RemoveAll(tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+	sp1 := cb.BuildSystemPromptWithCache()
+	if !strings.Contains(sp1, "delete-me-v1") {
+		t.Fatal("expected initial prompt to contain skill description")
+	}
+
+	skillPath := filepath.Join(tmpDir, "skills", "delete-me", "SKILL.md")
+	if err := os.Remove(skillPath); err != nil {
+		t.Fatal(err)
+	}
+
+	cb.systemPromptMutex.RLock()
+	changed := cb.sourceFilesChangedLocked()
+	cb.systemPromptMutex.RUnlock()
+	if !changed {
+		t.Fatal("sourceFilesChangedLocked() should detect deleted skill file")
+	}
+
+	sp2 := cb.BuildSystemPromptWithCache()
+	if strings.Contains(sp2, "delete-me-v1") {
+		t.Error("rebuilt prompt should not contain deleted skill description")
+	}
+	if sp1 == sp2 {
+		t.Error("cache should be invalidated when skill file is deleted")
+	}
+}
+
 // TestConcurrentBuildSystemPromptWithCache verifies that multiple goroutines
 // can safely call BuildSystemPromptWithCache concurrently without producing
 // empty results, panics, or data races.
 // Run with: go test -race ./pkg/agent/ -run TestConcurrentBuildSystemPromptWithCache
 func TestConcurrentBuildSystemPromptWithCache(t *testing.T) {
 	tmpDir := setupWorkspace(t, map[string]string{
-		"IDENTITY.md":          "# Identity\nConcurrency test agent.",
+		"AGENT.md":             "# Agent\nConcurrency test agent.",
 		"SOUL.md":              "# Soul\nBe helpful.",
 		"memory/MEMORY.md":     "# Memory\nUser prefers Go.",
 		"skills/demo/SKILL.md": "---\nname: demo\ndescription: \"demo skill\"\n---\n# Demo",
@@ -420,7 +638,7 @@ func TestConcurrentBuildSystemPromptWithCache(t *testing.T) {
 				}
 
 				// Also exercise BuildMessages concurrently
-				msgs := cb.BuildMessages(nil, "", "hello", nil, "test", "chat")
+				msgs := cb.BuildMessages(nil, "", "hello", nil, "test", "chat", "", "")
 				if len(msgs) < 2 {
 					errs <- "BuildMessages returned fewer than 2 messages"
 					return
@@ -496,7 +714,7 @@ func BenchmarkBuildMessagesWithCache(b *testing.B) {
 
 	os.MkdirAll(filepath.Join(tmpDir, "memory"), 0o755)
 	os.MkdirAll(filepath.Join(tmpDir, "skills"), 0o755)
-	for _, name := range []string{"IDENTITY.md", "SOUL.md", "USER.md"} {
+	for _, name := range []string{"AGENT.md", "SOUL.md"} {
 		os.WriteFile(filepath.Join(tmpDir, name), []byte(strings.Repeat("Content.\n", 10)), 0o644)
 	}
 
@@ -508,6 +726,6 @@ func BenchmarkBuildMessagesWithCache(b *testing.B) {
 
 	b.ResetTimer()
 	for i := 0; i < b.N; i++ {
-		_ = cb.BuildMessages(history, "summary", "new message", nil, "cli", "test")
+		_ = cb.BuildMessages(history, "summary", "new message", nil, "cli", "test", "", "")
 	}
 }
diff --git a/pkg/agent/context_test.go b/pkg/agent/context_test.go
index e023c9c30..0d7948eef 100644
--- a/pkg/agent/context_test.go
+++ b/pkg/agent/context_test.go
@@ -188,6 +188,31 @@ func TestSanitizeHistoryForProvider_PlainConversation(t *testing.T) {
 	assertRoles(t, result, "user", "assistant", "user", "assistant")
 }
 
+func TestSanitizeHistoryForProvider_DuplicateToolResults(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "do something"),
+		assistantWithTools("A", "B"),
+		toolResult("A"),
+		toolResult("B"),
+		toolResult("A"), // duplicate
+		toolResult("B"), // duplicate
+		msg("assistant", "done"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	if len(result) != 5 {
+		t.Fatalf("expected 5 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "assistant", "tool", "tool", "assistant")
+	// Verify the kept tool results have the correct IDs
+	if result[2].ToolCallID != "A" {
+		t.Errorf("expected tool result A, got %q", result[2].ToolCallID)
+	}
+	if result[3].ToolCallID != "B" {
+		t.Errorf("expected tool result B, got %q", result[3].ToolCallID)
+	}
+}
+
 func roles(msgs []providers.Message) []string {
 	r := make([]string, len(msgs))
 	for i, m := range msgs {
@@ -207,3 +232,77 @@ func assertRoles(t *testing.T, msgs []providers.Message, expected ...string) {
 		}
 	}
 }
+
+// TestSanitizeHistoryForProvider_IncompleteToolResults tests the forward validation
+// that ensures assistant messages with tool_calls have ALL matching tool results.
+// This fixes the DeepSeek error: "An assistant message with 'tool_calls' must be
+// followed by tool messages responding to each 'tool_call_id'."
+func TestSanitizeHistoryForProvider_IncompleteToolResults(t *testing.T) {
+	// Assistant expects tool results for both A and B, but only A is present
+	history := []providers.Message{
+		msg("user", "do two things"),
+		assistantWithTools("A", "B"),
+		toolResult("A"),
+		// toolResult("B") is missing - this would cause DeepSeek to fail
+		msg("user", "next question"),
+		msg("assistant", "answer"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	// The assistant message with incomplete tool results should be dropped,
+	// along with its partial tool result. The remaining messages are:
+	// user ("do two things"), user ("next question"), assistant ("answer")
+	if len(result) != 3 {
+		t.Fatalf("expected 3 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "user", "assistant")
+}
+
+// TestSanitizeHistoryForProvider_MissingAllToolResults tests the case where
+// an assistant message has tool_calls but no tool results follow at all.
+func TestSanitizeHistoryForProvider_MissingAllToolResults(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "do something"),
+		assistantWithTools("A"),
+		// No tool results at all
+		msg("user", "hello"),
+		msg("assistant", "hi"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	// The assistant message with no tool results should be dropped.
+	// Remaining: user ("do something"), user ("hello"), assistant ("hi")
+	if len(result) != 3 {
+		t.Fatalf("expected 3 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "user", "assistant")
+}
+
+// TestSanitizeHistoryForProvider_PartialToolResultsInMiddle tests that
+// incomplete tool results in the middle of a conversation are properly handled.
+func TestSanitizeHistoryForProvider_PartialToolResultsInMiddle(t *testing.T) {
+	history := []providers.Message{
+		msg("user", "first"),
+		assistantWithTools("A"),
+		toolResult("A"),
+		msg("assistant", "done"),
+		msg("user", "second"),
+		assistantWithTools("B", "C"),
+		toolResult("B"),
+		// toolResult("C") is missing
+		msg("user", "third"),
+		assistantWithTools("D"),
+		toolResult("D"),
+		msg("assistant", "all done"),
+	}
+
+	result := sanitizeHistoryForProvider(history)
+	// First round is complete (user, assistant+tools, tool, assistant),
+	// second round is incomplete and dropped (assistant+tools, partial tool),
+	// third round is complete (user, assistant+tools, tool, assistant).
+	// Remaining: user, assistant, tool, assistant, user, user, assistant, tool, assistant
+	if len(result) != 9 {
+		t.Fatalf("expected 9 messages, got %d: %+v", len(result), roles(result))
+	}
+	assertRoles(t, result, "user", "assistant", "tool", "assistant", "user", "user", "assistant", "tool", "assistant")
+}
diff --git a/pkg/agent/definition.go b/pkg/agent/definition.go
new file mode 100644
index 000000000..cf73d607c
--- /dev/null
+++ b/pkg/agent/definition.go
@@ -0,0 +1,255 @@
+package agent
+
+import (
+	"os"
+	"path/filepath"
+	"slices"
+	"strings"
+
+	"github.com/gomarkdown/markdown/parser"
+	"gopkg.in/yaml.v3"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// AgentDefinitionSource identifies which agent bootstrap file produced the definition.
+type AgentDefinitionSource string
+
+const (
+	// AgentDefinitionSourceAgent indicates the new AGENT.md format.
+	AgentDefinitionSourceAgent AgentDefinitionSource = "AGENT.md"
+	// AgentDefinitionSourceAgents indicates the legacy AGENTS.md format.
+	AgentDefinitionSourceAgents AgentDefinitionSource = "AGENTS.md"
+)
+
+// AgentFrontmatter holds machine-readable AGENT.md configuration.
+//
+// Known fields are exposed directly for convenience. Fields keeps the full
+// parsed frontmatter so future refactors can read additional keys without
+// changing the loader contract again.
+type AgentFrontmatter struct {
+	Name        string         `json:"name"`
+	Description string         `json:"description"`
+	Tools       []string       `json:"tools,omitempty"`
+	Model       string         `json:"model,omitempty"`
+	MaxTurns    *int           `json:"maxTurns,omitempty"`
+	Skills      []string       `json:"skills,omitempty"`
+	MCPServers  []string       `json:"mcpServers,omitempty"`
+	Fields      map[string]any `json:"fields,omitempty"`
+}
+
+// AgentPromptDefinition represents the parsed AGENT.md or AGENTS.md prompt file.
+type AgentPromptDefinition struct {
+	Path           string           `json:"path"`
+	Raw            string           `json:"raw"`
+	Body           string           `json:"body"`
+	RawFrontmatter string           `json:"raw_frontmatter,omitempty"`
+	Frontmatter    AgentFrontmatter `json:"frontmatter"`
+}
+
+// SoulDefinition represents the resolved SOUL.md file linked to the agent.
+type SoulDefinition struct {
+	Path    string `json:"path"`
+	Content string `json:"content"`
+}
+
+// UserDefinition represents the resolved USER.md file linked to the workspace.
+type UserDefinition struct {
+	Path    string `json:"path"`
+	Content string `json:"content"`
+}
+
+// AgentContextDefinition captures the workspace agent definition in a runtime-friendly shape.
+type AgentContextDefinition struct {
+	Source AgentDefinitionSource  `json:"source,omitempty"`
+	Agent  *AgentPromptDefinition `json:"agent,omitempty"`
+	Soul   *SoulDefinition        `json:"soul,omitempty"`
+	User   *UserDefinition        `json:"user,omitempty"`
+}
+
+// LoadAgentDefinition parses the workspace agent bootstrap files.
+//
+// It prefers the new AGENT.md format and its paired SOUL.md file. When the
+// structured files are absent, it falls back to the legacy AGENTS.md layout so
+// the current runtime can transition incrementally.
+func (cb *ContextBuilder) LoadAgentDefinition() AgentContextDefinition {
+	return loadAgentDefinition(cb.workspace)
+}
+
+func loadAgentDefinition(workspace string) AgentContextDefinition {
+	definition := AgentContextDefinition{}
+	definition.User = loadUserDefinition(workspace)
+	agentPath := filepath.Join(workspace, string(AgentDefinitionSourceAgent))
+	if content, err := os.ReadFile(agentPath); err == nil {
+		prompt := parseAgentPromptDefinition(agentPath, string(content))
+		definition.Source = AgentDefinitionSourceAgent
+		definition.Agent = &prompt
+		soulPath := filepath.Join(workspace, "SOUL.md")
+		if content, err := os.ReadFile(soulPath); err == nil {
+			definition.Soul = &SoulDefinition{
+				Path:    soulPath,
+				Content: string(content),
+			}
+		}
+		return definition
+	}
+
+	legacyPath := filepath.Join(workspace, string(AgentDefinitionSourceAgents))
+	if content, err := os.ReadFile(legacyPath); err == nil {
+		definition.Source = AgentDefinitionSourceAgents
+		definition.Agent = &AgentPromptDefinition{
+			Path: legacyPath,
+			Raw:  string(content),
+			Body: string(content),
+		}
+	}
+
+	defaultSoulPath := filepath.Join(workspace, "SOUL.md")
+	if definition.Source != "" || fileExists(defaultSoulPath) {
+		if content, err := os.ReadFile(defaultSoulPath); err == nil {
+			definition.Soul = &SoulDefinition{
+				Path:    defaultSoulPath,
+				Content: string(content),
+			}
+		}
+	}
+
+	return definition
+}
+
+func (definition AgentContextDefinition) trackedPaths(workspace string) []string {
+	paths := []string{
+		filepath.Join(workspace, string(AgentDefinitionSourceAgent)),
+		filepath.Join(workspace, "SOUL.md"),
+		filepath.Join(workspace, "USER.md"),
+	}
+	if definition.Source != AgentDefinitionSourceAgent {
+		paths = append(paths,
+			filepath.Join(workspace, string(AgentDefinitionSourceAgents)),
+			filepath.Join(workspace, "IDENTITY.md"),
+		)
+	}
+	return uniquePaths(paths)
+}
+
+func loadUserDefinition(workspace string) *UserDefinition {
+	userPath := filepath.Join(workspace, "USER.md")
+	if content, err := os.ReadFile(userPath); err == nil {
+		return &UserDefinition{
+			Path:    userPath,
+			Content: string(content),
+		}
+	}
+
+	return nil
+}
+
+func parseAgentPromptDefinition(path, content string) AgentPromptDefinition {
+	frontmatter, body := splitAgentFrontmatter(content)
+	return AgentPromptDefinition{
+		Path:           path,
+		Raw:            content,
+		Body:           body,
+		RawFrontmatter: frontmatter,
+		Frontmatter:    parseAgentFrontmatter(path, frontmatter),
+	}
+}
+
+func parseAgentFrontmatter(path, frontmatter string) AgentFrontmatter {
+	frontmatter = strings.TrimSpace(frontmatter)
+	if frontmatter == "" {
+		return AgentFrontmatter{}
+	}
+
+	rawFields := make(map[string]any)
+	if err := yaml.Unmarshal([]byte(frontmatter), &rawFields); err != nil {
+		logger.WarnCF("agent", "Failed to parse AGENT.md frontmatter", map[string]any{
+			"path":  path,
+			"error": err.Error(),
+		})
+		return AgentFrontmatter{}
+	}
+
+	var typed struct {
+		Name        string   `yaml:"name"`
+		Description string   `yaml:"description"`
+		Tools       []string `yaml:"tools"`
+		Model       string   `yaml:"model"`
+		MaxTurns    *int     `yaml:"maxTurns"`
+		Skills      []string `yaml:"skills"`
+		MCPServers  []string `yaml:"mcpServers"`
+	}
+	if err := yaml.Unmarshal([]byte(frontmatter), &typed); err != nil {
+		logger.WarnCF("agent", "Failed to decode AGENT.md frontmatter fields", map[string]any{
+			"path":  path,
+			"error": err.Error(),
+		})
+		return AgentFrontmatter{}
+	}
+
+	return AgentFrontmatter{
+		Name:        strings.TrimSpace(typed.Name),
+		Description: strings.TrimSpace(typed.Description),
+		Tools:       append([]string(nil), typed.Tools...),
+		Model:       strings.TrimSpace(typed.Model),
+		MaxTurns:    typed.MaxTurns,
+		Skills:      append([]string(nil), typed.Skills...),
+		MCPServers:  append([]string(nil), typed.MCPServers...),
+		Fields:      rawFields,
+	}
+}
+
+func splitAgentFrontmatter(content string) (frontmatter, body string) {
+	normalized := string(parser.NormalizeNewlines([]byte(content)))
+	lines := strings.Split(normalized, "\n")
+	if len(lines) == 0 || lines[0] != "---" {
+		return "", content
+	}
+
+	end := -1
+	for i := 1; i < len(lines); i++ {
+		if lines[i] == "---" {
+			end = i
+			break
+		}
+	}
+	if end == -1 {
+		return "", content
+	}
+
+	frontmatter = strings.Join(lines[1:end], "\n")
+	body = strings.Join(lines[end+1:], "\n")
+	body = strings.TrimLeft(body, "\n")
+	return frontmatter, body
+}
+
+func relativeWorkspacePath(workspace, path string) string {
+	if strings.TrimSpace(path) == "" {
+		return ""
+	}
+	relativePath, err := filepath.Rel(workspace, path)
+	if err == nil && relativePath != "." && !strings.HasPrefix(relativePath, "..") {
+		return filepath.ToSlash(relativePath)
+	}
+	return filepath.Clean(path)
+}
+
+func uniquePaths(paths []string) []string {
+	result := make([]string, 0, len(paths))
+	for _, path := range paths {
+		if strings.TrimSpace(path) == "" {
+			continue
+		}
+		cleaned := filepath.Clean(path)
+		if slices.Contains(result, cleaned) {
+			continue
+		}
+		result = append(result, cleaned)
+	}
+	return result
+}
+
+func fileExists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
diff --git a/pkg/agent/definition_test.go b/pkg/agent/definition_test.go
new file mode 100644
index 000000000..5ee996967
--- /dev/null
+++ b/pkg/agent/definition_test.go
@@ -0,0 +1,302 @@
+package agent
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestLoadAgentDefinitionParsesFrontmatterAndSoul(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"AGENT.md": `---
+name: pico
+description: Structured agent
+model: claude-3-7-sonnet
+tools:
+  - shell
+  - search
+maxTurns: 8
+skills:
+  - review
+  - search-docs
+mcpServers:
+  - github
+metadata:
+  mode: strict
+---
+# Agent
+
+Act directly and use tools first.
+`,
+		"SOUL.md": "# Soul\nStay precise.",
+	})
+	defer cleanupWorkspace(t, tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+	definition := cb.LoadAgentDefinition()
+
+	if definition.Source != AgentDefinitionSourceAgent {
+		t.Fatalf("expected source %q, got %q", AgentDefinitionSourceAgent, definition.Source)
+	}
+	if definition.Agent == nil {
+		t.Fatal("expected AGENT.md definition to be loaded")
+	}
+	if definition.Agent.Body == "" || !strings.Contains(definition.Agent.Body, "Act directly") {
+		t.Fatalf("expected AGENT.md body to be preserved, got %q", definition.Agent.Body)
+	}
+	if definition.Agent.Frontmatter.Name != "pico" {
+		t.Fatalf("expected name to be parsed, got %q", definition.Agent.Frontmatter.Name)
+	}
+	if definition.Agent.Frontmatter.Model != "claude-3-7-sonnet" {
+		t.Fatalf("expected model to be parsed, got %q", definition.Agent.Frontmatter.Model)
+	}
+	if len(definition.Agent.Frontmatter.Tools) != 2 {
+		t.Fatalf("expected tools to be parsed, got %v", definition.Agent.Frontmatter.Tools)
+	}
+	if definition.Agent.Frontmatter.MaxTurns == nil || *definition.Agent.Frontmatter.MaxTurns != 8 {
+		t.Fatalf("expected maxTurns to be parsed, got %v", definition.Agent.Frontmatter.MaxTurns)
+	}
+	if len(definition.Agent.Frontmatter.Skills) != 2 {
+		t.Fatalf("expected skills to be parsed, got %v", definition.Agent.Frontmatter.Skills)
+	}
+	if len(definition.Agent.Frontmatter.MCPServers) != 1 || definition.Agent.Frontmatter.MCPServers[0] != "github" {
+		t.Fatalf("expected mcpServers to be parsed, got %v", definition.Agent.Frontmatter.MCPServers)
+	}
+	if definition.Agent.Frontmatter.Fields["metadata"] == nil {
+		t.Fatal("expected arbitrary frontmatter fields to remain available")
+	}
+
+	if definition.Soul == nil {
+		t.Fatal("expected SOUL.md to be loaded")
+	}
+	if !strings.Contains(definition.Soul.Content, "Stay precise") {
+		t.Fatalf("expected soul content to be loaded, got %q", definition.Soul.Content)
+	}
+	if definition.Soul.Path != filepath.Join(tmpDir, "SOUL.md") {
+		t.Fatalf("expected default SOUL.md path, got %q", definition.Soul.Path)
+	}
+}
+
+func TestLoadAgentDefinitionFallsBackToLegacyAgentsMarkdown(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"AGENTS.md": "# Legacy Agent\nKeep compatibility.",
+		"SOUL.md":   "# Soul\nLegacy soul.",
+	})
+	defer cleanupWorkspace(t, tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+	definition := cb.LoadAgentDefinition()
+
+	if definition.Source != AgentDefinitionSourceAgents {
+		t.Fatalf("expected source %q, got %q", AgentDefinitionSourceAgents, definition.Source)
+	}
+	if definition.Agent == nil {
+		t.Fatal("expected AGENTS.md to be loaded")
+	}
+	if definition.Agent.RawFrontmatter != "" {
+		t.Fatalf("legacy AGENTS.md should not have frontmatter, got %q", definition.Agent.RawFrontmatter)
+	}
+	if !strings.Contains(definition.Agent.Body, "Keep compatibility") {
+		t.Fatalf("expected legacy body to be preserved, got %q", definition.Agent.Body)
+	}
+	if definition.Soul == nil || !strings.Contains(definition.Soul.Content, "Legacy soul") {
+		t.Fatal("expected default SOUL.md to be loaded for legacy format")
+	}
+}
+
+func TestLoadAgentDefinitionLoadsWorkspaceUserMarkdown(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"AGENT.md": "# Agent\nStructured agent.",
+		"USER.md":  "# User\nWorkspace preferences.",
+	})
+	defer cleanupWorkspace(t, tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+	definition := cb.LoadAgentDefinition()
+
+	if definition.User == nil {
+		t.Fatal("expected USER.md to be loaded")
+	}
+	if definition.User.Path != filepath.Join(tmpDir, "USER.md") {
+		t.Fatalf("expected workspace USER.md path, got %q", definition.User.Path)
+	}
+	if !strings.Contains(definition.User.Content, "Workspace preferences") {
+		t.Fatalf("expected workspace USER.md content, got %q", definition.User.Content)
+	}
+}
+
+func TestLoadAgentDefinitionInvalidFrontmatterFallsBackToEmptyStructuredFields(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"AGENT.md": `---
+name: pico
+tools:
+  - shell
+  broken
+---
+# Agent
+
+Keep going.
+`,
+	})
+	defer cleanupWorkspace(t, tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+	definition := cb.LoadAgentDefinition()
+
+	if definition.Agent == nil {
+		t.Fatal("expected AGENT.md definition to be loaded")
+	}
+	if !strings.Contains(definition.Agent.Body, "Keep going.") {
+		t.Fatalf("expected AGENT.md body to be preserved, got %q", definition.Agent.Body)
+	}
+	if definition.Agent.Frontmatter.Name != "" ||
+		definition.Agent.Frontmatter.Description != "" ||
+		definition.Agent.Frontmatter.Model != "" ||
+		definition.Agent.Frontmatter.MaxTurns != nil ||
+		len(definition.Agent.Frontmatter.Tools) != 0 ||
+		len(definition.Agent.Frontmatter.Skills) != 0 ||
+		len(definition.Agent.Frontmatter.MCPServers) != 0 ||
+		len(definition.Agent.Frontmatter.Fields) != 0 {
+		t.Fatalf("expected invalid frontmatter to decode as empty struct, got %+v", definition.Agent.Frontmatter)
+	}
+}
+
+func TestLoadBootstrapFilesUsesAgentBodyNotFrontmatter(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"AGENT.md": `---
+name: pico
+model: codex-mini
+---
+# Agent
+
+Follow the body prompt.
+`,
+		"SOUL.md":     "# Soul\nSpeak plainly.",
+		"IDENTITY.md": "# Identity\nWorkspace identity.",
+	})
+	defer cleanupWorkspace(t, tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+	bootstrap := cb.LoadBootstrapFiles()
+
+	if !strings.Contains(bootstrap, "Follow the body prompt") {
+		t.Fatalf("expected AGENT.md body in bootstrap, got %q", bootstrap)
+	}
+	if !strings.Contains(bootstrap, "Speak plainly") {
+		t.Fatalf("expected resolved soul content in bootstrap, got %q", bootstrap)
+	}
+	if strings.Contains(bootstrap, "name: pico") {
+		t.Fatalf("bootstrap should not expose raw frontmatter, got %q", bootstrap)
+	}
+	if strings.Contains(bootstrap, "model: codex-mini") {
+		t.Fatalf("bootstrap should not expose raw frontmatter, got %q", bootstrap)
+	}
+	if !strings.Contains(bootstrap, "SOUL.md") {
+		t.Fatalf("expected bootstrap to label SOUL.md, got %q", bootstrap)
+	}
+	if strings.Contains(bootstrap, "Workspace identity") {
+		t.Fatalf("structured bootstrap should ignore IDENTITY.md, got %q", bootstrap)
+	}
+}
+
+func TestLoadBootstrapFilesIncludesWorkspaceUserMarkdown(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"AGENT.md": "# Agent\nFollow the new structure.",
+		"SOUL.md":  "# Soul\nSpeak plainly.",
+		"USER.md":  "# User\nShared profile.",
+	})
+	defer cleanupWorkspace(t, tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+	bootstrap := cb.LoadBootstrapFiles()
+
+	if !strings.Contains(bootstrap, "Shared profile") {
+		t.Fatalf("expected workspace USER.md in bootstrap, got %q", bootstrap)
+	}
+	if !strings.Contains(bootstrap, "## USER.md") {
+		t.Fatalf("expected USER.md heading in bootstrap, got %q", bootstrap)
+	}
+}
+
+func TestStructuredAgentIgnoresIdentityChanges(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"AGENT.md":    "# Agent\nFollow the new structure.",
+		"SOUL.md":     "# Soul\nVersion one.",
+		"IDENTITY.md": "# Identity\nLegacy identity.",
+	})
+	defer cleanupWorkspace(t, tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	promptV1 := cb.BuildSystemPromptWithCache()
+	if strings.Contains(promptV1, "Legacy identity") {
+		t.Fatalf("structured prompt should not include IDENTITY.md, got %q", promptV1)
+	}
+
+	identityPath := filepath.Join(tmpDir, "IDENTITY.md")
+	if err := os.WriteFile(identityPath, []byte("# Identity\nVersion two."), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	future := time.Now().Add(2 * time.Second)
+	if err := os.Chtimes(identityPath, future, future); err != nil {
+		t.Fatal(err)
+	}
+
+	cb.systemPromptMutex.RLock()
+	changed := cb.sourceFilesChangedLocked()
+	cb.systemPromptMutex.RUnlock()
+	if changed {
+		t.Fatal("IDENTITY.md should not invalidate cache for structured agent definitions")
+	}
+
+	promptV2 := cb.BuildSystemPromptWithCache()
+	if promptV1 != promptV2 {
+		t.Fatal("structured prompt should remain stable after IDENTITY.md changes")
+	}
+}
+
+func TestStructuredAgentUserChangesInvalidateCache(t *testing.T) {
+	tmpDir := setupWorkspace(t, map[string]string{
+		"AGENT.md": "# Agent\nFollow the new structure.",
+		"SOUL.md":  "# Soul\nVersion one.",
+		"USER.md":  "# User\nInitial workspace preferences.",
+	})
+	defer cleanupWorkspace(t, tmpDir)
+
+	cb := NewContextBuilder(tmpDir)
+
+	promptV1 := cb.BuildSystemPromptWithCache()
+	if !strings.Contains(promptV1, "Initial workspace preferences") {
+		t.Fatalf("expected workspace USER.md in prompt, got %q", promptV1)
+	}
+
+	userPath := filepath.Join(tmpDir, "USER.md")
+	if err := os.WriteFile(userPath, []byte("# User\nUpdated workspace preferences."), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	future := time.Now().Add(2 * time.Second)
+	if err := os.Chtimes(userPath, future, future); err != nil {
+		t.Fatal(err)
+	}
+
+	cb.systemPromptMutex.RLock()
+	changed := cb.sourceFilesChangedLocked()
+	cb.systemPromptMutex.RUnlock()
+	if !changed {
+		t.Fatal("workspace USER.md changes should invalidate cache")
+	}
+
+	promptV2 := cb.BuildSystemPromptWithCache()
+	if !strings.Contains(promptV2, "Updated workspace preferences") {
+		t.Fatalf("expected updated workspace USER.md in prompt, got %q", promptV2)
+	}
+}
+
+func cleanupWorkspace(t *testing.T, path string) {
+	t.Helper()
+	if err := os.RemoveAll(path); err != nil {
+		t.Fatalf("failed to clean up workspace %s: %v", path, err)
+	}
+}
diff --git a/pkg/agent/eventbus.go b/pkg/agent/eventbus.go
new file mode 100644
index 000000000..546d8436d
--- /dev/null
+++ b/pkg/agent/eventbus.go
@@ -0,0 +1,121 @@
+package agent
+
+import (
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+const defaultEventSubscriberBuffer = 16
+
+// EventSubscription identifies a subscriber channel returned by EventBus.Subscribe.
+type EventSubscription struct {
+	ID uint64
+	C  <-chan Event
+}
+
+type eventSubscriber struct {
+	ch chan Event
+}
+
+// EventBus is a lightweight multi-subscriber broadcaster for agent-loop events.
+type EventBus struct {
+	mu      sync.RWMutex
+	subs    map[uint64]eventSubscriber
+	nextID  uint64
+	closed  bool
+	dropped [eventKindCount]atomic.Int64
+}
+
+// NewEventBus creates a new in-process event broadcaster.
+func NewEventBus() *EventBus {
+	return &EventBus{
+		subs: make(map[uint64]eventSubscriber),
+	}
+}
+
+// Subscribe registers a new subscriber with the requested channel buffer size.
+// A non-positive buffer uses the default size.
+func (b *EventBus) Subscribe(buffer int) EventSubscription {
+	if buffer <= 0 {
+		buffer = defaultEventSubscriberBuffer
+	}
+
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	if b.closed {
+		ch := make(chan Event)
+		close(ch)
+		return EventSubscription{C: ch}
+	}
+
+	b.nextID++
+	id := b.nextID
+	ch := make(chan Event, buffer)
+	b.subs[id] = eventSubscriber{ch: ch}
+	return EventSubscription{ID: id, C: ch}
+}
+
+// Unsubscribe removes a subscriber and closes its channel.
+func (b *EventBus) Unsubscribe(id uint64) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	sub, ok := b.subs[id]
+	if !ok {
+		return
+	}
+
+	delete(b.subs, id)
+	close(sub.ch)
+}
+
+// Emit broadcasts an event to all current subscribers without blocking.
+// When a subscriber channel is full, the event is dropped for that subscriber.
+func (b *EventBus) Emit(evt Event) {
+	if evt.Time.IsZero() {
+		evt.Time = time.Now()
+	}
+
+	b.mu.RLock()
+	defer b.mu.RUnlock()
+
+	if b.closed {
+		return
+	}
+
+	for _, sub := range b.subs {
+		select {
+		case sub.ch <- evt:
+		default:
+			if evt.Kind < eventKindCount {
+				b.dropped[evt.Kind].Add(1)
+			}
+		}
+	}
+}
+
+// Dropped returns the number of dropped events for a given kind.
+func (b *EventBus) Dropped(kind EventKind) int64 {
+	if kind >= eventKindCount {
+		return 0
+	}
+	return b.dropped[kind].Load()
+}
+
+// Close closes all subscriber channels and stops future broadcasts.
+func (b *EventBus) Close() {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+
+	if b.closed {
+		return
+	}
+
+	b.closed = true
+	for id, sub := range b.subs {
+		close(sub.ch)
+		delete(b.subs, id)
+	}
+}
diff --git a/pkg/agent/eventbus_test.go b/pkg/agent/eventbus_test.go
new file mode 100644
index 000000000..19a1ea9eb
--- /dev/null
+++ b/pkg/agent/eventbus_test.go
@@ -0,0 +1,684 @@
+package agent
+
+import (
+	"context"
+	"os"
+	"slices"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+func TestEventBus_SubscribeEmitUnsubscribeClose(t *testing.T) {
+	eventBus := NewEventBus()
+	sub := eventBus.Subscribe(1)
+
+	eventBus.Emit(Event{
+		Kind: EventKindTurnStart,
+		Meta: EventMeta{TurnID: "turn-1"},
+	})
+
+	select {
+	case evt := <-sub.C:
+		if evt.Kind != EventKindTurnStart {
+			t.Fatalf("expected %v, got %v", EventKindTurnStart, evt.Kind)
+		}
+		if evt.Meta.TurnID != "turn-1" {
+			t.Fatalf("expected turn id turn-1, got %q", evt.Meta.TurnID)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("timed out waiting for event")
+	}
+
+	eventBus.Unsubscribe(sub.ID)
+	if _, ok := <-sub.C; ok {
+		t.Fatal("expected subscriber channel to be closed after unsubscribe")
+	}
+
+	eventBus.Close()
+	closedSub := eventBus.Subscribe(1)
+	if _, ok := <-closedSub.C; ok {
+		t.Fatal("expected closed bus to return a closed subscriber channel")
+	}
+}
+
+func TestEventBus_DropsWhenSubscriberIsFull(t *testing.T) {
+	eventBus := NewEventBus()
+	sub := eventBus.Subscribe(1)
+	defer eventBus.Unsubscribe(sub.ID)
+
+	start := time.Now()
+	for i := 0; i < 1000; i++ {
+		eventBus.Emit(Event{Kind: EventKindLLMRequest})
+	}
+
+	if elapsed := time.Since(start); elapsed > 100*time.Millisecond {
+		t.Fatalf("Emit took too long with a blocked subscriber: %s", elapsed)
+	}
+
+	if got := eventBus.Dropped(EventKindLLMRequest); got != 999 {
+		t.Fatalf("expected 999 dropped events, got %d", got)
+	}
+}
+
+type scriptedToolProvider struct {
+	calls int
+}
+
+func (m *scriptedToolProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	toolDefs []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	m.calls++
+	if m.calls == 1 {
+		return &providers.LLMResponse{
+			ToolCalls: []providers.ToolCall{
+				{
+					ID:        "call-1",
+					Name:      "mock_custom",
+					Arguments: map[string]any{"task": "ping"},
+				},
+			},
+		}, nil
+	}
+
+	return &providers.LLMResponse{
+		Content: "done",
+	}, nil
+}
+
+func (m *scriptedToolProvider) GetDefaultModel() string {
+	return "scripted-tool-model"
+}
+
+func TestAgentLoop_EmitsMinimalTurnEvents(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-eventbus-*")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &scriptedToolProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+	al.RegisterTool(&mockCustomTool{})
+	defaultAgent := al.registry.GetDefaultAgent()
+	if defaultAgent == nil {
+		t.Fatal("expected default agent")
+	}
+
+	sub := al.SubscribeEvents(16)
+	defer al.UnsubscribeEvents(sub.ID)
+
+	response, err := al.runAgentLoop(context.Background(), defaultAgent, processOptions{
+		SessionKey:      "session-1",
+		Channel:         "cli",
+		ChatID:          "direct",
+		UserMessage:     "run tool",
+		DefaultResponse: defaultResponse,
+		EnableSummary:   false,
+		SendResponse:    false,
+	})
+	if err != nil {
+		t.Fatalf("runAgentLoop failed: %v", err)
+	}
+	if response != "done" {
+		t.Fatalf("expected final response 'done', got %q", response)
+	}
+
+	events := collectEventStream(sub.C)
+	if len(events) != 8 {
+		t.Fatalf("expected 8 events, got %d", len(events))
+	}
+
+	kinds := make([]EventKind, 0, len(events))
+	for _, evt := range events {
+		kinds = append(kinds, evt.Kind)
+	}
+
+	expectedKinds := []EventKind{
+		EventKindTurnStart,
+		EventKindLLMRequest,
+		EventKindLLMResponse,
+		EventKindToolExecStart,
+		EventKindToolExecEnd,
+		EventKindLLMRequest,
+		EventKindLLMResponse,
+		EventKindTurnEnd,
+	}
+	if !slices.Equal(kinds, expectedKinds) {
+		t.Fatalf("unexpected event sequence: got %v want %v", kinds, expectedKinds)
+	}
+
+	turnID := events[0].Meta.TurnID
+	for i, evt := range events {
+		if evt.Meta.TurnID != turnID {
+			t.Fatalf("event %d has mismatched turn id %q, want %q", i, evt.Meta.TurnID, turnID)
+		}
+		if evt.Meta.SessionKey != "session-1" {
+			t.Fatalf("event %d has session key %q, want session-1", i, evt.Meta.SessionKey)
+		}
+	}
+
+	startPayload, ok := events[0].Payload.(TurnStartPayload)
+	if !ok {
+		t.Fatalf("expected TurnStartPayload, got %T", events[0].Payload)
+	}
+	if startPayload.UserMessage != "run tool" {
+		t.Fatalf("expected user message 'run tool', got %q", startPayload.UserMessage)
+	}
+
+	toolStartPayload, ok := events[3].Payload.(ToolExecStartPayload)
+	if !ok {
+		t.Fatalf("expected ToolExecStartPayload, got %T", events[3].Payload)
+	}
+	if toolStartPayload.Tool != "mock_custom" {
+		t.Fatalf("expected tool name mock_custom, got %q", toolStartPayload.Tool)
+	}
+
+	toolEndPayload, ok := events[4].Payload.(ToolExecEndPayload)
+	if !ok {
+		t.Fatalf("expected ToolExecEndPayload, got %T", events[4].Payload)
+	}
+	if toolEndPayload.Tool != "mock_custom" {
+		t.Fatalf("expected tool end payload for mock_custom, got %q", toolEndPayload.Tool)
+	}
+	if toolEndPayload.IsError {
+		t.Fatal("expected mock_custom tool to succeed")
+	}
+
+	turnEndPayload, ok := events[len(events)-1].Payload.(TurnEndPayload)
+	if !ok {
+		t.Fatalf("expected TurnEndPayload, got %T", events[len(events)-1].Payload)
+	}
+	if turnEndPayload.Status != TurnEndStatusCompleted {
+		t.Fatalf("expected completed turn, got %q", turnEndPayload.Status)
+	}
+	if turnEndPayload.Iterations != 2 {
+		t.Fatalf("expected 2 iterations, got %d", turnEndPayload.Iterations)
+	}
+}
+
+func TestAgentLoop_EmitsSteeringAndSkippedToolEvents(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-eventbus-steering-*")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	tool1ExecCh := make(chan struct{})
+	tool1 := &slowTool{name: "tool_one", duration: 50 * time.Millisecond, execCh: tool1ExecCh}
+	tool2 := &slowTool{name: "tool_two", duration: 50 * time.Millisecond}
+
+	provider := &toolCallProvider{
+		toolCalls: []providers.ToolCall{
+			{
+				ID:   "call_1",
+				Type: "function",
+				Name: "tool_one",
+				Function: &providers.FunctionCall{
+					Name:      "tool_one",
+					Arguments: "{}",
+				},
+				Arguments: map[string]any{},
+			},
+			{
+				ID:   "call_2",
+				Type: "function",
+				Name: "tool_two",
+				Function: &providers.FunctionCall{
+					Name:      "tool_two",
+					Arguments: "{}",
+				},
+				Arguments: map[string]any{},
+			},
+		},
+		finalResp: "steered response",
+	}
+
+	msgBus := bus.NewMessageBus()
+	al := NewAgentLoop(cfg, msgBus, provider)
+	al.RegisterTool(tool1)
+	al.RegisterTool(tool2)
+
+	sub := al.SubscribeEvents(32)
+	defer al.UnsubscribeEvents(sub.ID)
+
+	resultCh := make(chan string, 1)
+	go func() {
+		resp, _ := al.ProcessDirectWithChannel(context.Background(), "do something", "test-session", "test", "chat1")
+		resultCh <- resp
+	}()
+
+	select {
+	case <-tool1ExecCh:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timeout waiting for tool_one to start")
+	}
+
+	if err := al.Steer(providers.Message{Role: "user", Content: "change course"}); err != nil {
+		t.Fatalf("Steer failed: %v", err)
+	}
+
+	select {
+	case resp := <-resultCh:
+		if resp != "steered response" {
+			t.Fatalf("expected steered response, got %q", resp)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("timeout waiting for steered response")
+	}
+
+	events := collectEventStream(sub.C)
+	steeringEvt, ok := findEvent(events, EventKindSteeringInjected)
+	if !ok {
+		t.Fatal("expected steering injected event")
+	}
+	steeringPayload, ok := steeringEvt.Payload.(SteeringInjectedPayload)
+	if !ok {
+		t.Fatalf("expected SteeringInjectedPayload, got %T", steeringEvt.Payload)
+	}
+	if steeringPayload.Count != 1 {
+		t.Fatalf("expected 1 steering message, got %d", steeringPayload.Count)
+	}
+
+	skippedEvt, ok := findEvent(events, EventKindToolExecSkipped)
+	if !ok {
+		t.Fatal("expected skipped tool event")
+	}
+	skippedPayload, ok := skippedEvt.Payload.(ToolExecSkippedPayload)
+	if !ok {
+		t.Fatalf("expected ToolExecSkippedPayload, got %T", skippedEvt.Payload)
+	}
+	if skippedPayload.Tool != "tool_two" {
+		t.Fatalf("expected skipped tool_two, got %q", skippedPayload.Tool)
+	}
+
+	interruptEvt, ok := findEvent(events, EventKindInterruptReceived)
+	if !ok {
+		t.Fatal("expected interrupt received event")
+	}
+	interruptPayload, ok := interruptEvt.Payload.(InterruptReceivedPayload)
+	if !ok {
+		t.Fatalf("expected InterruptReceivedPayload, got %T", interruptEvt.Payload)
+	}
+	if interruptPayload.Role != "user" {
+		t.Fatalf("expected interrupt role user, got %q", interruptPayload.Role)
+	}
+	if interruptPayload.Kind != InterruptKindSteering {
+		t.Fatalf("expected steering interrupt kind, got %q", interruptPayload.Kind)
+	}
+	if interruptPayload.ContentLen != len("change course") {
+		t.Fatalf("expected interrupt content len %d, got %d", len("change course"), interruptPayload.ContentLen)
+	}
+}
+
+func TestAgentLoop_EmitsContextCompressEventOnRetry(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-eventbus-compress-*")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	contextErr := stringError("InvalidParameter: Total tokens of image and text exceed max message tokens")
+	provider := &failFirstMockProvider{
+		failures:    1,
+		failError:   contextErr,
+		successResp: "Recovered from context error",
+	}
+	msgBus := bus.NewMessageBus()
+	al := NewAgentLoop(cfg, msgBus, provider)
+	defaultAgent := al.registry.GetDefaultAgent()
+	if defaultAgent == nil {
+		t.Fatal("expected default agent")
+	}
+
+	defaultAgent.Sessions.SetHistory("session-1", []providers.Message{
+		{Role: "user", Content: "Old message 1"},
+		{Role: "assistant", Content: "Old response 1"},
+		{Role: "user", Content: "Old message 2"},
+		{Role: "assistant", Content: "Old response 2"},
+		{Role: "user", Content: "Trigger message"},
+	})
+
+	sub := al.SubscribeEvents(16)
+	defer al.UnsubscribeEvents(sub.ID)
+
+	resp, err := al.runAgentLoop(context.Background(), defaultAgent, processOptions{
+		SessionKey:      "session-1",
+		Channel:         "cli",
+		ChatID:          "direct",
+		UserMessage:     "Trigger message",
+		DefaultResponse: defaultResponse,
+		EnableSummary:   false,
+		SendResponse:    false,
+	})
+	if err != nil {
+		t.Fatalf("runAgentLoop failed: %v", err)
+	}
+	if resp != "Recovered from context error" {
+		t.Fatalf("expected retry success, got %q", resp)
+	}
+
+	events := collectEventStream(sub.C)
+	retryEvt, ok := findEvent(events, EventKindLLMRetry)
+	if !ok {
+		t.Fatal("expected llm retry event")
+	}
+	retryPayload, ok := retryEvt.Payload.(LLMRetryPayload)
+	if !ok {
+		t.Fatalf("expected LLMRetryPayload, got %T", retryEvt.Payload)
+	}
+	if retryPayload.Reason != "context_limit" {
+		t.Fatalf("expected context_limit retry reason, got %q", retryPayload.Reason)
+	}
+	if retryPayload.Attempt != 1 {
+		t.Fatalf("expected retry attempt 1, got %d", retryPayload.Attempt)
+	}
+
+	compressEvt, ok := findEvent(events, EventKindContextCompress)
+	if !ok {
+		t.Fatal("expected context compress event")
+	}
+	payload, ok := compressEvt.Payload.(ContextCompressPayload)
+	if !ok {
+		t.Fatalf("expected ContextCompressPayload, got %T", compressEvt.Payload)
+	}
+	if payload.Reason != ContextCompressReasonRetry {
+		t.Fatalf("expected retry compress reason, got %q", payload.Reason)
+	}
+	if payload.DroppedMessages == 0 {
+		t.Fatal("expected dropped messages to be recorded")
+	}
+}
+
+func TestAgentLoop_EmitsSessionSummarizeEvent(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-eventbus-summary-*")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:                 tmpDir,
+				ModelName:                 "test-model",
+				MaxTokens:                 4096,
+				MaxToolIterations:         10,
+				ContextWindow:             8000,
+				SummarizeMessageThreshold: 2,
+				SummarizeTokenPercent:     75,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	al := NewAgentLoop(cfg, msgBus, &simpleMockProvider{response: "summary text"})
+	defaultAgent := al.registry.GetDefaultAgent()
+	if defaultAgent == nil {
+		t.Fatal("expected default agent")
+	}
+
+	defaultAgent.Sessions.SetHistory("session-1", []providers.Message{
+		{Role: "user", Content: "Question one"},
+		{Role: "assistant", Content: "Answer one"},
+		{Role: "user", Content: "Question two"},
+		{Role: "assistant", Content: "Answer two"},
+		{Role: "user", Content: "Question three"},
+		{Role: "assistant", Content: "Answer three"},
+	})
+
+	sub := al.SubscribeEvents(16)
+	defer al.UnsubscribeEvents(sub.ID)
+
+	turnScope := al.newTurnEventScope(defaultAgent.ID, "session-1")
+	al.summarizeSession(defaultAgent, "session-1", turnScope)
+
+	events := collectEventStream(sub.C)
+	summaryEvt, ok := findEvent(events, EventKindSessionSummarize)
+	if !ok {
+		t.Fatal("expected session summarize event")
+	}
+	payload, ok := summaryEvt.Payload.(SessionSummarizePayload)
+	if !ok {
+		t.Fatalf("expected SessionSummarizePayload, got %T", summaryEvt.Payload)
+	}
+	if payload.SummaryLen == 0 {
+		t.Fatal("expected non-empty summary length")
+	}
+}
+
+func TestAgentLoop_EmitsFollowUpQueuedEvent(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-eventbus-followup-*")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	provider := &toolCallProvider{
+		toolCalls: []providers.ToolCall{
+			{
+				ID:   "call_async_1",
+				Type: "function",
+				Name: "async_followup",
+				Function: &providers.FunctionCall{
+					Name:      "async_followup",
+					Arguments: "{}",
+				},
+				Arguments: map[string]any{},
+			},
+		},
+		finalResp: "async launched",
+	}
+
+	msgBus := bus.NewMessageBus()
+	al := NewAgentLoop(cfg, msgBus, provider)
+	doneCh := make(chan struct{})
+	al.RegisterTool(&asyncFollowUpTool{
+		name:          "async_followup",
+		followUpText:  "background result",
+		completionSig: doneCh,
+	})
+	defaultAgent := al.registry.GetDefaultAgent()
+	if defaultAgent == nil {
+		t.Fatal("expected default agent")
+	}
+
+	sub := al.SubscribeEvents(32)
+	defer al.UnsubscribeEvents(sub.ID)
+
+	resp, err := al.runAgentLoop(context.Background(), defaultAgent, processOptions{
+		SessionKey:      "session-1",
+		Channel:         "cli",
+		ChatID:          "direct",
+		UserMessage:     "run async tool",
+		DefaultResponse: defaultResponse,
+		EnableSummary:   false,
+		SendResponse:    false,
+	})
+	if err != nil {
+		t.Fatalf("runAgentLoop failed: %v", err)
+	}
+	if resp != "async launched" {
+		t.Fatalf("expected final response 'async launched', got %q", resp)
+	}
+
+	select {
+	case <-doneCh:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timeout waiting for async tool completion")
+	}
+
+	followUpEvt := waitForEvent(t, sub.C, 2*time.Second, func(evt Event) bool {
+		return evt.Kind == EventKindFollowUpQueued
+	})
+	payload, ok := followUpEvt.Payload.(FollowUpQueuedPayload)
+	if !ok {
+		t.Fatalf("expected FollowUpQueuedPayload, got %T", followUpEvt.Payload)
+	}
+	if payload.SourceTool != "async_followup" {
+		t.Fatalf("expected source tool async_followup, got %q", payload.SourceTool)
+	}
+	if payload.Channel != "cli" {
+		t.Fatalf("expected channel cli, got %q", payload.Channel)
+	}
+	if payload.ChatID != "direct" {
+		t.Fatalf("expected chat id direct, got %q", payload.ChatID)
+	}
+	if payload.ContentLen != len("background result") {
+		t.Fatalf("expected content len %d, got %d", len("background result"), payload.ContentLen)
+	}
+	if followUpEvt.Meta.SessionKey != "session-1" {
+		t.Fatalf("expected session key session-1, got %q", followUpEvt.Meta.SessionKey)
+	}
+	if followUpEvt.Meta.TurnID == "" {
+		t.Fatal("expected follow-up event to include turn id")
+	}
+}
+
+func collectEventStream(ch <-chan Event) []Event {
+	var events []Event
+	for {
+		select {
+		case evt, ok := <-ch:
+			if !ok {
+				return events
+			}
+			events = append(events, evt)
+		default:
+			return events
+		}
+	}
+}
+
+func waitForEvent(t *testing.T, ch <-chan Event, timeout time.Duration, match func(Event) bool) Event {
+	t.Helper()
+
+	timer := time.NewTimer(timeout)
+	defer timer.Stop()
+
+	for {
+		select {
+		case evt, ok := <-ch:
+			if !ok {
+				t.Fatal("event stream closed before expected event arrived")
+			}
+			if match(evt) {
+				return evt
+			}
+		case <-timer.C:
+			t.Fatal("timed out waiting for expected event")
+		}
+	}
+}
+
+func findEvent(events []Event, kind EventKind) (Event, bool) {
+	for _, evt := range events {
+		if evt.Kind == kind {
+			return evt, true
+		}
+	}
+	return Event{}, false
+}
+
+type stringError string
+
+func (e stringError) Error() string {
+	return string(e)
+}
+
+type asyncFollowUpTool struct {
+	name          string
+	followUpText  string
+	completionSig chan struct{}
+}
+
+func (t *asyncFollowUpTool) Name() string {
+	return t.name
+}
+
+func (t *asyncFollowUpTool) Description() string {
+	return "async follow-up tool for testing"
+}
+
+func (t *asyncFollowUpTool) Parameters() map[string]any {
+	return map[string]any{
+		"type":       "object",
+		"properties": map[string]any{},
+	}
+}
+
+func (t *asyncFollowUpTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+	return tools.AsyncResult("async follow-up scheduled")
+}
+
+func (t *asyncFollowUpTool) ExecuteAsync(
+	ctx context.Context,
+	args map[string]any,
+	cb tools.AsyncCallback,
+) *tools.ToolResult {
+	go func() {
+		cb(ctx, &tools.ToolResult{ForLLM: t.followUpText})
+		if t.completionSig != nil {
+			close(t.completionSig)
+		}
+	}()
+	return tools.AsyncResult("async follow-up scheduled")
+}
+
+var (
+	_ tools.Tool          = (*mockCustomTool)(nil)
+	_ tools.AsyncExecutor = (*asyncFollowUpTool)(nil)
+)
diff --git a/pkg/agent/events.go b/pkg/agent/events.go
new file mode 100644
index 000000000..f4562b360
--- /dev/null
+++ b/pkg/agent/events.go
@@ -0,0 +1,271 @@
+package agent
+
+import (
+	"fmt"
+	"time"
+)
+
+// EventKind identifies a structured agent-loop event.
+type EventKind uint8
+
+const (
+	// EventKindTurnStart is emitted when a turn begins processing.
+	EventKindTurnStart EventKind = iota
+	// EventKindTurnEnd is emitted when a turn finishes, successfully or with an error.
+	EventKindTurnEnd
+	// EventKindLLMRequest is emitted before a provider chat request is made.
+	EventKindLLMRequest
+	// EventKindLLMDelta is emitted when a streaming provider yields a partial delta.
+	EventKindLLMDelta
+	// EventKindLLMResponse is emitted after a provider chat response is received.
+	EventKindLLMResponse
+	// EventKindLLMRetry is emitted when an LLM request is retried.
+	EventKindLLMRetry
+	// EventKindContextCompress is emitted when session history is forcibly compressed.
+	EventKindContextCompress
+	// EventKindSessionSummarize is emitted when asynchronous summarization completes.
+	EventKindSessionSummarize
+	// EventKindToolExecStart is emitted immediately before a tool executes.
+	EventKindToolExecStart
+	// EventKindToolExecEnd is emitted immediately after a tool finishes executing.
+	EventKindToolExecEnd
+	// EventKindToolExecSkipped is emitted when a queued tool call is skipped.
+	EventKindToolExecSkipped
+	// EventKindSteeringInjected is emitted when queued steering is injected into context.
+	EventKindSteeringInjected
+	// EventKindFollowUpQueued is emitted when an async tool queues a follow-up system message.
+	EventKindFollowUpQueued
+	// EventKindInterruptReceived is emitted when a soft interrupt message is accepted.
+	EventKindInterruptReceived
+	// EventKindSubTurnSpawn is emitted when a sub-turn is spawned.
+	EventKindSubTurnSpawn
+	// EventKindSubTurnEnd is emitted when a sub-turn finishes.
+	EventKindSubTurnEnd
+	// EventKindSubTurnResultDelivered is emitted when a sub-turn result is delivered.
+	EventKindSubTurnResultDelivered
+	// EventKindSubTurnOrphan is emitted when a sub-turn result cannot be delivered.
+	EventKindSubTurnOrphan
+	// EventKindError is emitted when a turn encounters an execution error.
+	EventKindError
+
+	eventKindCount
+)
+
+var eventKindNames = [...]string{
+	"turn_start",
+	"turn_end",
+	"llm_request",
+	"llm_delta",
+	"llm_response",
+	"llm_retry",
+	"context_compress",
+	"session_summarize",
+	"tool_exec_start",
+	"tool_exec_end",
+	"tool_exec_skipped",
+	"steering_injected",
+	"follow_up_queued",
+	"interrupt_received",
+	"subturn_spawn",
+	"subturn_end",
+	"subturn_result_delivered",
+	"subturn_orphan",
+	"error",
+}
+
+// String returns the stable string form of an EventKind.
+func (k EventKind) String() string {
+	if k >= eventKindCount {
+		return fmt.Sprintf("event_kind(%d)", k)
+	}
+	return eventKindNames[k]
+}
+
+// Event is the structured envelope broadcast by the agent EventBus.
+type Event struct {
+	Kind    EventKind
+	Time    time.Time
+	Meta    EventMeta
+	Payload any
+}
+
+// EventMeta contains correlation fields shared by all agent-loop events.
+type EventMeta struct {
+	AgentID      string
+	TurnID       string
+	ParentTurnID string
+	SessionKey   string
+	Iteration    int
+	TracePath    string
+	Source       string
+}
+
+// TurnEndStatus describes the terminal state of a turn.
+type TurnEndStatus string
+
+const (
+	// TurnEndStatusCompleted indicates the turn finished normally.
+	TurnEndStatusCompleted TurnEndStatus = "completed"
+	// TurnEndStatusError indicates the turn ended because of an error.
+	TurnEndStatusError TurnEndStatus = "error"
+	// TurnEndStatusAborted indicates the turn was hard-aborted and rolled back.
+	TurnEndStatusAborted TurnEndStatus = "aborted"
+)
+
+// TurnStartPayload describes the start of a turn.
+type TurnStartPayload struct {
+	Channel     string
+	ChatID      string
+	UserMessage string
+	MediaCount  int
+}
+
+// TurnEndPayload describes the completion of a turn.
+type TurnEndPayload struct {
+	Status          TurnEndStatus
+	Iterations      int
+	Duration        time.Duration
+	FinalContentLen int
+}
+
+// LLMRequestPayload describes an outbound LLM request.
+type LLMRequestPayload struct {
+	Model         string
+	MessagesCount int
+	ToolsCount    int
+	MaxTokens     int
+	Temperature   float64
+}
+
+// LLMResponsePayload describes an inbound LLM response.
+type LLMResponsePayload struct {
+	ContentLen   int
+	ToolCalls    int
+	HasReasoning bool
+}
+
+// LLMDeltaPayload describes a streamed LLM delta.
+type LLMDeltaPayload struct {
+	ContentDeltaLen   int
+	ReasoningDeltaLen int
+}
+
+// LLMRetryPayload describes a retry of an LLM request.
+type LLMRetryPayload struct {
+	Attempt    int
+	MaxRetries int
+	Reason     string
+	Error      string
+	Backoff    time.Duration
+}
+
+// ContextCompressReason identifies why emergency compression ran.
+type ContextCompressReason string
+
+const (
+	// ContextCompressReasonProactive indicates compression before the first LLM call.
+	ContextCompressReasonProactive ContextCompressReason = "proactive_budget"
+	// ContextCompressReasonRetry indicates compression during context-error retry handling.
+	ContextCompressReasonRetry ContextCompressReason = "llm_retry"
+)
+
+// ContextCompressPayload describes a forced history compression.
+type ContextCompressPayload struct {
+	Reason            ContextCompressReason
+	DroppedMessages   int
+	RemainingMessages int
+}
+
+// SessionSummarizePayload describes a completed async session summarization.
+type SessionSummarizePayload struct {
+	SummarizedMessages int
+	KeptMessages       int
+	SummaryLen         int
+	OmittedOversized   bool
+}
+
+// ToolExecStartPayload describes a tool execution request.
+type ToolExecStartPayload struct {
+	Tool      string
+	Arguments map[string]any
+}
+
+// ToolExecEndPayload describes the outcome of a tool execution.
+type ToolExecEndPayload struct {
+	Tool       string
+	Duration   time.Duration
+	ForLLMLen  int
+	ForUserLen int
+	IsError    bool
+	Async      bool
+}
+
+// ToolExecSkippedPayload describes a skipped tool call.
+type ToolExecSkippedPayload struct {
+	Tool   string
+	Reason string
+}
+
+// SteeringInjectedPayload describes steering messages appended before the next LLM call.
+type SteeringInjectedPayload struct {
+	Count           int
+	TotalContentLen int
+}
+
+// FollowUpQueuedPayload describes an async follow-up queued back into the inbound bus.
+type FollowUpQueuedPayload struct {
+	SourceTool string
+	Channel    string
+	ChatID     string
+	ContentLen int
+}
+
+type InterruptKind string
+
+const (
+	InterruptKindSteering InterruptKind = "steering"
+	InterruptKindGraceful InterruptKind = "graceful"
+	InterruptKindHard     InterruptKind = "hard_abort"
+)
+
+// InterruptReceivedPayload describes accepted turn-control input.
+type InterruptReceivedPayload struct {
+	Kind       InterruptKind
+	Role       string
+	ContentLen int
+	QueueDepth int
+	HintLen    int
+}
+
+// SubTurnSpawnPayload describes the creation of a child turn.
+type SubTurnSpawnPayload struct {
+	AgentID      string
+	Label        string
+	ParentTurnID string
+}
+
+// SubTurnEndPayload describes the completion of a child turn.
+type SubTurnEndPayload struct {
+	AgentID string
+	Status  string
+}
+
+// SubTurnResultDeliveredPayload describes delivery of a sub-turn result.
+type SubTurnResultDeliveredPayload struct {
+	TargetChannel string
+	TargetChatID  string
+	ContentLen    int
+}
+
+// SubTurnOrphanPayload describes a sub-turn result that could not be delivered.
+type SubTurnOrphanPayload struct {
+	ParentTurnID string
+	ChildTurnID  string
+	Reason       string
+}
+
+// ErrorPayload describes an execution error inside the agent loop.
+type ErrorPayload struct {
+	Stage   string
+	Message string
+}
diff --git a/pkg/agent/hook_mount.go b/pkg/agent/hook_mount.go
new file mode 100644
index 000000000..c92145f1f
--- /dev/null
+++ b/pkg/agent/hook_mount.go
@@ -0,0 +1,317 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"sync"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+type hookRuntime struct {
+	initOnce sync.Once
+	mu       sync.Mutex
+	initErr  error
+	mounted  []string
+}
+
+func (r *hookRuntime) setInitErr(err error) {
+	r.mu.Lock()
+	r.initErr = err
+	r.mu.Unlock()
+}
+
+func (r *hookRuntime) getInitErr() error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.initErr
+}
+
+func (r *hookRuntime) setMounted(names []string) {
+	r.mu.Lock()
+	r.mounted = append([]string(nil), names...)
+	r.mu.Unlock()
+}
+
+func (r *hookRuntime) reset(al *AgentLoop) {
+	r.mu.Lock()
+	names := append([]string(nil), r.mounted...)
+	r.mounted = nil
+	r.initErr = nil
+	r.initOnce = sync.Once{}
+	r.mu.Unlock()
+
+	for _, name := range names {
+		al.UnmountHook(name)
+	}
+}
+
+// BuiltinHookFactory constructs an in-process hook from config.
+type BuiltinHookFactory func(ctx context.Context, spec config.BuiltinHookConfig) (any, error)
+
+var (
+	builtinHookRegistryMu sync.RWMutex
+	builtinHookRegistry   = map[string]BuiltinHookFactory{}
+)
+
+// RegisterBuiltinHook registers a named in-process hook factory for config-driven mounting.
+func RegisterBuiltinHook(name string, factory BuiltinHookFactory) error {
+	if name == "" {
+		return fmt.Errorf("builtin hook name is required")
+	}
+	if factory == nil {
+		return fmt.Errorf("builtin hook %q factory is nil", name)
+	}
+
+	builtinHookRegistryMu.Lock()
+	defer builtinHookRegistryMu.Unlock()
+
+	if _, exists := builtinHookRegistry[name]; exists {
+		return fmt.Errorf("builtin hook %q is already registered", name)
+	}
+	builtinHookRegistry[name] = factory
+	return nil
+}
+
+func unregisterBuiltinHook(name string) {
+	if name == "" {
+		return
+	}
+	builtinHookRegistryMu.Lock()
+	delete(builtinHookRegistry, name)
+	builtinHookRegistryMu.Unlock()
+}
+
+func lookupBuiltinHook(name string) (BuiltinHookFactory, bool) {
+	builtinHookRegistryMu.RLock()
+	defer builtinHookRegistryMu.RUnlock()
+
+	factory, ok := builtinHookRegistry[name]
+	return factory, ok
+}
+
+func configureHookManagerFromConfig(hm *HookManager, cfg *config.Config) {
+	if hm == nil || cfg == nil {
+		return
+	}
+	hm.ConfigureTimeouts(
+		hookTimeoutFromMS(cfg.Hooks.Defaults.ObserverTimeoutMS),
+		hookTimeoutFromMS(cfg.Hooks.Defaults.InterceptorTimeoutMS),
+		hookTimeoutFromMS(cfg.Hooks.Defaults.ApprovalTimeoutMS),
+	)
+}
+
+func hookTimeoutFromMS(ms int) time.Duration {
+	if ms <= 0 {
+		return 0
+	}
+	return time.Duration(ms) * time.Millisecond
+}
+
+func (al *AgentLoop) ensureHooksInitialized(ctx context.Context) error {
+	if al == nil || al.cfg == nil || al.hooks == nil {
+		return nil
+	}
+
+	al.hookRuntime.initOnce.Do(func() {
+		al.hookRuntime.setInitErr(al.loadConfiguredHooks(ctx))
+	})
+
+	return al.hookRuntime.getInitErr()
+}
+
+func (al *AgentLoop) loadConfiguredHooks(ctx context.Context) (err error) {
+	if al == nil || al.cfg == nil || !al.cfg.Hooks.Enabled {
+		return nil
+	}
+
+	mounted := make([]string, 0)
+	defer func() {
+		if err != nil {
+			for _, name := range mounted {
+				al.UnmountHook(name)
+			}
+			return
+		}
+		al.hookRuntime.setMounted(mounted)
+	}()
+
+	builtinNames := enabledBuiltinHookNames(al.cfg.Hooks.Builtins)
+	for _, name := range builtinNames {
+		spec := al.cfg.Hooks.Builtins[name]
+		factory, ok := lookupBuiltinHook(name)
+		if !ok {
+			return fmt.Errorf("builtin hook %q is not registered", name)
+		}
+
+		hook, factoryErr := factory(ctx, spec)
+		if factoryErr != nil {
+			return fmt.Errorf("build builtin hook %q: %w", name, factoryErr)
+		}
+		if err := al.MountHook(HookRegistration{
+			Name:     name,
+			Priority: spec.Priority,
+			Source:   HookSourceInProcess,
+			Hook:     hook,
+		}); err != nil {
+			return fmt.Errorf("mount builtin hook %q: %w", name, err)
+		}
+		mounted = append(mounted, name)
+	}
+
+	processNames := enabledProcessHookNames(al.cfg.Hooks.Processes)
+	for _, name := range processNames {
+		spec := al.cfg.Hooks.Processes[name]
+		opts, buildErr := processHookOptionsFromConfig(spec)
+		if buildErr != nil {
+			return fmt.Errorf("configure process hook %q: %w", name, buildErr)
+		}
+
+		processHook, buildErr := NewProcessHook(ctx, name, opts)
+		if buildErr != nil {
+			return fmt.Errorf("start process hook %q: %w", name, buildErr)
+		}
+		if err := al.MountHook(HookRegistration{
+			Name:     name,
+			Priority: spec.Priority,
+			Source:   HookSourceProcess,
+			Hook:     processHook,
+		}); err != nil {
+			_ = processHook.Close()
+			return fmt.Errorf("mount process hook %q: %w", name, err)
+		}
+		mounted = append(mounted, name)
+	}
+
+	return nil
+}
+
+func enabledBuiltinHookNames(specs map[string]config.BuiltinHookConfig) []string {
+	if len(specs) == 0 {
+		return nil
+	}
+
+	names := make([]string, 0, len(specs))
+	for name, spec := range specs {
+		if spec.Enabled {
+			names = append(names, name)
+		}
+	}
+	sort.Strings(names)
+	return names
+}
+
+func enabledProcessHookNames(specs map[string]config.ProcessHookConfig) []string {
+	if len(specs) == 0 {
+		return nil
+	}
+
+	names := make([]string, 0, len(specs))
+	for name, spec := range specs {
+		if spec.Enabled {
+			names = append(names, name)
+		}
+	}
+	sort.Strings(names)
+	return names
+}
+
+func processHookOptionsFromConfig(spec config.ProcessHookConfig) (ProcessHookOptions, error) {
+	transport := spec.Transport
+	if transport == "" {
+		transport = "stdio"
+	}
+	if transport != "stdio" {
+		return ProcessHookOptions{}, fmt.Errorf("unsupported transport %q", transport)
+	}
+	if len(spec.Command) == 0 {
+		return ProcessHookOptions{}, fmt.Errorf("command is required")
+	}
+
+	opts := ProcessHookOptions{
+		Command: append([]string(nil), spec.Command...),
+		Dir:     spec.Dir,
+		Env:     processHookEnvFromMap(spec.Env),
+	}
+
+	observeKinds, observeEnabled, err := processHookObserveKindsFromConfig(spec.Observe)
+	if err != nil {
+		return ProcessHookOptions{}, err
+	}
+	opts.Observe = observeEnabled
+	opts.ObserveKinds = observeKinds
+
+	for _, intercept := range spec.Intercept {
+		switch intercept {
+		case "before_llm", "after_llm":
+			opts.InterceptLLM = true
+		case "before_tool", "after_tool":
+			opts.InterceptTool = true
+		case "approve_tool":
+			opts.ApproveTool = true
+		case "":
+			continue
+		default:
+			return ProcessHookOptions{}, fmt.Errorf("unsupported intercept %q", intercept)
+		}
+	}
+
+	if !opts.Observe && !opts.InterceptLLM && !opts.InterceptTool && !opts.ApproveTool {
+		return ProcessHookOptions{}, fmt.Errorf("no hook modes enabled")
+	}
+
+	return opts, nil
+}
+
+func processHookEnvFromMap(envMap map[string]string) []string {
+	if len(envMap) == 0 {
+		return nil
+	}
+
+	keys := make([]string, 0, len(envMap))
+	for key := range envMap {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+
+	env := make([]string, 0, len(keys))
+	for _, key := range keys {
+		env = append(env, key+"="+envMap[key])
+	}
+	return env
+}
+
+func processHookObserveKindsFromConfig(observe []string) ([]string, bool, error) {
+	if len(observe) == 0 {
+		return nil, false, nil
+	}
+
+	validKinds := validHookEventKinds()
+	normalized := make([]string, 0, len(observe))
+	for _, kind := range observe {
+		switch kind {
+		case "", "*", "all":
+			return nil, true, nil
+		default:
+			if _, ok := validKinds[kind]; !ok {
+				return nil, false, fmt.Errorf("unsupported observe event %q", kind)
+			}
+			normalized = append(normalized, kind)
+		}
+	}
+
+	if len(normalized) == 0 {
+		return nil, false, nil
+	}
+	return normalized, true, nil
+}
+
+func validHookEventKinds() map[string]struct{} {
+	kinds := make(map[string]struct{}, int(eventKindCount))
+	for kind := EventKind(0); kind < eventKindCount; kind++ {
+		kinds[kind.String()] = struct{}{}
+	}
+	return kinds
+}
diff --git a/pkg/agent/hook_mount_test.go b/pkg/agent/hook_mount_test.go
new file mode 100644
index 000000000..85d8f5c11
--- /dev/null
+++ b/pkg/agent/hook_mount_test.go
@@ -0,0 +1,179 @@
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+type builtinAutoHookConfig struct {
+	Model  string `json:"model"`
+	Suffix string `json:"suffix"`
+}
+
+type builtinAutoHook struct {
+	model  string
+	suffix string
+}
+
+func (h *builtinAutoHook) BeforeLLM(
+	ctx context.Context,
+	req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+	next := req.Clone()
+	next.Model = h.model
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *builtinAutoHook) AfterLLM(
+	ctx context.Context,
+	resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+	next := resp.Clone()
+	if next.Response != nil {
+		next.Response.Content += h.suffix
+	}
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func newConfiguredHookLoop(t *testing.T, provider *llmHookTestProvider, hooks config.HooksConfig) *AgentLoop {
+	t.Helper()
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         t.TempDir(),
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+		Hooks: hooks,
+	}
+
+	return NewAgentLoop(cfg, bus.NewMessageBus(), provider)
+}
+
+func TestAgentLoop_ProcessDirectWithChannel_AutoMountsBuiltinHook(t *testing.T) {
+	const hookName = "test-auto-builtin-hook"
+
+	if err := RegisterBuiltinHook(hookName, func(
+		ctx context.Context,
+		spec config.BuiltinHookConfig,
+	) (any, error) {
+		var hookCfg builtinAutoHookConfig
+		if len(spec.Config) > 0 {
+			if err := json.Unmarshal(spec.Config, &hookCfg); err != nil {
+				return nil, err
+			}
+		}
+		return &builtinAutoHook{
+			model:  hookCfg.Model,
+			suffix: hookCfg.Suffix,
+		}, nil
+	}); err != nil {
+		t.Fatalf("RegisterBuiltinHook failed: %v", err)
+	}
+	t.Cleanup(func() {
+		unregisterBuiltinHook(hookName)
+	})
+
+	rawCfg, err := json.Marshal(builtinAutoHookConfig{
+		Model:  "builtin-model",
+		Suffix: "|builtin",
+	})
+	if err != nil {
+		t.Fatalf("json.Marshal failed: %v", err)
+	}
+
+	provider := &llmHookTestProvider{}
+	al := newConfiguredHookLoop(t, provider, config.HooksConfig{
+		Enabled: true,
+		Builtins: map[string]config.BuiltinHookConfig{
+			hookName: {
+				Enabled: true,
+				Config:  rawCfg,
+			},
+		},
+	})
+	defer al.Close()
+
+	resp, err := al.ProcessDirectWithChannel(context.Background(), "hello", "session-1", "cli", "direct")
+	if err != nil {
+		t.Fatalf("ProcessDirectWithChannel failed: %v", err)
+	}
+	if resp != "provider content|builtin" {
+		t.Fatalf("expected builtin-hooked content, got %q", resp)
+	}
+
+	provider.mu.Lock()
+	lastModel := provider.lastModel
+	provider.mu.Unlock()
+	if lastModel != "builtin-model" {
+		t.Fatalf("expected builtin model, got %q", lastModel)
+	}
+}
+
+func TestAgentLoop_ProcessDirectWithChannel_AutoMountsProcessHook(t *testing.T) {
+	provider := &llmHookTestProvider{}
+	eventLog := filepath.Join(t.TempDir(), "events.log")
+
+	al := newConfiguredHookLoop(t, provider, config.HooksConfig{
+		Enabled: true,
+		Processes: map[string]config.ProcessHookConfig{
+			"ipc-auto": {
+				Enabled: true,
+				Command: processHookHelperCommand(),
+				Env: map[string]string{
+					"PICOCLAW_HOOK_HELPER":    "1",
+					"PICOCLAW_HOOK_MODE":      "rewrite",
+					"PICOCLAW_HOOK_EVENT_LOG": eventLog,
+				},
+				Observe:   []string{"turn_end"},
+				Intercept: []string{"before_llm", "after_llm"},
+			},
+		},
+	})
+	defer al.Close()
+
+	resp, err := al.ProcessDirectWithChannel(context.Background(), "hello", "session-1", "cli", "direct")
+	if err != nil {
+		t.Fatalf("ProcessDirectWithChannel failed: %v", err)
+	}
+	if resp != "provider content|ipc" {
+		t.Fatalf("expected process-hooked content, got %q", resp)
+	}
+
+	provider.mu.Lock()
+	lastModel := provider.lastModel
+	provider.mu.Unlock()
+	if lastModel != "process-model" {
+		t.Fatalf("expected process model, got %q", lastModel)
+	}
+
+	waitForFileContains(t, eventLog, "turn_end")
+}
+
+func TestAgentLoop_ProcessDirectWithChannel_InvalidConfiguredHookFails(t *testing.T) {
+	provider := &llmHookTestProvider{}
+	al := newConfiguredHookLoop(t, provider, config.HooksConfig{
+		Enabled: true,
+		Processes: map[string]config.ProcessHookConfig{
+			"bad-hook": {
+				Enabled:   true,
+				Command:   processHookHelperCommand(),
+				Intercept: []string{"not_supported"},
+			},
+		},
+	})
+	defer al.Close()
+
+	_, err := al.ProcessDirectWithChannel(context.Background(), "hello", "session-1", "cli", "direct")
+	if err == nil {
+		t.Fatal("expected invalid configured hook error")
+	}
+}
diff --git a/pkg/agent/hook_process.go b/pkg/agent/hook_process.go
new file mode 100644
index 000000000..e5632913d
--- /dev/null
+++ b/pkg/agent/hook_process.go
@@ -0,0 +1,511 @@
+package agent
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+const (
+	processHookJSONRPCVersion = "2.0"
+	processHookReadBufferSize = 1024 * 1024
+	processHookCloseTimeout   = 2 * time.Second
+)
+
+type ProcessHookOptions struct {
+	Command       []string
+	Dir           string
+	Env           []string
+	Observe       bool
+	ObserveKinds  []string
+	InterceptLLM  bool
+	InterceptTool bool
+	ApproveTool   bool
+}
+
+type ProcessHook struct {
+	name string
+	opts ProcessHookOptions
+
+	cmd          *exec.Cmd
+	stdin        io.WriteCloser
+	observeKinds map[string]struct{}
+
+	writeMu sync.Mutex
+
+	pendingMu sync.Mutex
+	pending   map[uint64]chan processHookRPCMessage
+	nextID    atomic.Uint64
+
+	closed    atomic.Bool
+	done      chan struct{}
+	closeErr  error
+	closeMu   sync.Mutex
+	closeOnce sync.Once
+}
+
+type processHookRPCMessage struct {
+	JSONRPC string               `json:"jsonrpc,omitempty"`
+	ID      uint64               `json:"id,omitempty"`
+	Method  string               `json:"method,omitempty"`
+	Params  json.RawMessage      `json:"params,omitempty"`
+	Result  json.RawMessage      `json:"result,omitempty"`
+	Error   *processHookRPCError `json:"error,omitempty"`
+}
+
+type processHookRPCError struct {
+	Code    int    `json:"code"`
+	Message string `json:"message"`
+}
+
+type processHookHelloParams struct {
+	Name    string   `json:"name"`
+	Version int      `json:"version"`
+	Modes   []string `json:"modes,omitempty"`
+}
+
+type processHookDecisionResponse struct {
+	Action HookAction `json:"action"`
+	Reason string     `json:"reason,omitempty"`
+}
+
+type processHookBeforeLLMResponse struct {
+	processHookDecisionResponse
+	Request *LLMHookRequest `json:"request,omitempty"`
+}
+
+type processHookAfterLLMResponse struct {
+	processHookDecisionResponse
+	Response *LLMHookResponse `json:"response,omitempty"`
+}
+
+type processHookBeforeToolResponse struct {
+	processHookDecisionResponse
+	Call *ToolCallHookRequest `json:"call,omitempty"`
+}
+
+type processHookAfterToolResponse struct {
+	processHookDecisionResponse
+	Result *ToolResultHookResponse `json:"result,omitempty"`
+}
+
+func NewProcessHook(ctx context.Context, name string, opts ProcessHookOptions) (*ProcessHook, error) {
+	if len(opts.Command) == 0 {
+		return nil, fmt.Errorf("process hook command is required")
+	}
+
+	cmd := exec.Command(opts.Command[0], opts.Command[1:]...)
+	cmd.Dir = opts.Dir
+	if len(opts.Env) > 0 {
+		cmd.Env = append(os.Environ(), opts.Env...)
+	}
+	stdin, err := cmd.StdinPipe()
+	if err != nil {
+		return nil, fmt.Errorf("create process hook stdin: %w", err)
+	}
+	stdout, err := cmd.StdoutPipe()
+	if err != nil {
+		return nil, fmt.Errorf("create process hook stdout: %w", err)
+	}
+	stderr, err := cmd.StderrPipe()
+	if err != nil {
+		return nil, fmt.Errorf("create process hook stderr: %w", err)
+	}
+	if err := cmd.Start(); err != nil {
+		return nil, fmt.Errorf("start process hook: %w", err)
+	}
+
+	ph := &ProcessHook{
+		name:         name,
+		opts:         opts,
+		cmd:          cmd,
+		stdin:        stdin,
+		observeKinds: newProcessHookObserveKinds(opts.ObserveKinds),
+		pending:      make(map[uint64]chan processHookRPCMessage),
+		done:         make(chan struct{}),
+	}
+
+	go ph.readLoop(stdout)
+	go ph.readStderr(stderr)
+	go ph.waitLoop()
+
+	helloCtx := ctx
+	if helloCtx == nil {
+		var cancel context.CancelFunc
+		helloCtx, cancel = context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+	}
+	if err := ph.hello(helloCtx); err != nil {
+		_ = ph.Close()
+		return nil, err
+	}
+
+	return ph, nil
+}
+
+func (ph *ProcessHook) Close() error {
+	if ph == nil {
+		return nil
+	}
+
+	ph.closeOnce.Do(func() {
+		ph.closed.Store(true)
+		if ph.stdin != nil {
+			_ = ph.stdin.Close()
+		}
+
+		select {
+		case <-ph.done:
+		case <-time.After(processHookCloseTimeout):
+			if ph.cmd != nil && ph.cmd.Process != nil {
+				_ = ph.cmd.Process.Kill()
+			}
+			<-ph.done
+		}
+	})
+
+	ph.closeMu.Lock()
+	defer ph.closeMu.Unlock()
+	return ph.closeErr
+}
+
+func (ph *ProcessHook) OnEvent(ctx context.Context, evt Event) error {
+	if ph == nil || !ph.opts.Observe {
+		return nil
+	}
+	if len(ph.observeKinds) > 0 {
+		if _, ok := ph.observeKinds[evt.Kind.String()]; !ok {
+			return nil
+		}
+	}
+	return ph.notify(ctx, "hook.event", evt)
+}
+
+func (ph *ProcessHook) BeforeLLM(
+	ctx context.Context,
+	req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+	if ph == nil || !ph.opts.InterceptLLM {
+		return req, HookDecision{Action: HookActionContinue}, nil
+	}
+
+	var resp processHookBeforeLLMResponse
+	if err := ph.call(ctx, "hook.before_llm", req, &resp); err != nil {
+		return nil, HookDecision{}, err
+	}
+	if resp.Request == nil {
+		resp.Request = req
+	}
+	return resp.Request, HookDecision{Action: resp.Action, Reason: resp.Reason}, nil
+}
+
+func (ph *ProcessHook) AfterLLM(
+	ctx context.Context,
+	resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+	if ph == nil || !ph.opts.InterceptLLM {
+		return resp, HookDecision{Action: HookActionContinue}, nil
+	}
+
+	var result processHookAfterLLMResponse
+	if err := ph.call(ctx, "hook.after_llm", resp, &result); err != nil {
+		return nil, HookDecision{}, err
+	}
+	if result.Response == nil {
+		result.Response = resp
+	}
+	return result.Response, HookDecision{Action: result.Action, Reason: result.Reason}, nil
+}
+
+func (ph *ProcessHook) BeforeTool(
+	ctx context.Context,
+	call *ToolCallHookRequest,
+) (*ToolCallHookRequest, HookDecision, error) {
+	if ph == nil || !ph.opts.InterceptTool {
+		return call, HookDecision{Action: HookActionContinue}, nil
+	}
+
+	var resp processHookBeforeToolResponse
+	if err := ph.call(ctx, "hook.before_tool", call, &resp); err != nil {
+		return nil, HookDecision{}, err
+	}
+	if resp.Call == nil {
+		resp.Call = call
+	}
+	return resp.Call, HookDecision{Action: resp.Action, Reason: resp.Reason}, nil
+}
+
+func (ph *ProcessHook) AfterTool(
+	ctx context.Context,
+	result *ToolResultHookResponse,
+) (*ToolResultHookResponse, HookDecision, error) {
+	if ph == nil || !ph.opts.InterceptTool {
+		return result, HookDecision{Action: HookActionContinue}, nil
+	}
+
+	var resp processHookAfterToolResponse
+	if err := ph.call(ctx, "hook.after_tool", result, &resp); err != nil {
+		return nil, HookDecision{}, err
+	}
+	if resp.Result == nil {
+		resp.Result = result
+	}
+	return resp.Result, HookDecision{Action: resp.Action, Reason: resp.Reason}, nil
+}
+
+func (ph *ProcessHook) ApproveTool(ctx context.Context, req *ToolApprovalRequest) (ApprovalDecision, error) {
+	if ph == nil || !ph.opts.ApproveTool {
+		return ApprovalDecision{Approved: true}, nil
+	}
+
+	var resp ApprovalDecision
+	if err := ph.call(ctx, "hook.approve_tool", req, &resp); err != nil {
+		return ApprovalDecision{}, err
+	}
+	return resp, nil
+}
+
+func (ph *ProcessHook) hello(ctx context.Context) error {
+	modes := make([]string, 0, 4)
+	if ph.opts.Observe {
+		modes = append(modes, "observe")
+	}
+	if ph.opts.InterceptLLM {
+		modes = append(modes, "llm")
+	}
+	if ph.opts.InterceptTool {
+		modes = append(modes, "tool")
+	}
+	if ph.opts.ApproveTool {
+		modes = append(modes, "approve")
+	}
+
+	var result map[string]any
+	return ph.call(ctx, "hook.hello", processHookHelloParams{
+		Name:    ph.name,
+		Version: 1,
+		Modes:   modes,
+	}, &result)
+}
+
+func (ph *ProcessHook) notify(ctx context.Context, method string, params any) error {
+	msg := processHookRPCMessage{
+		JSONRPC: processHookJSONRPCVersion,
+		Method:  method,
+	}
+	if params != nil {
+		body, err := json.Marshal(params)
+		if err != nil {
+			return err
+		}
+		msg.Params = body
+	}
+	return ph.send(ctx, msg)
+}
+
+func (ph *ProcessHook) call(ctx context.Context, method string, params any, out any) error {
+	if ph.closed.Load() {
+		return fmt.Errorf("process hook %q is closed", ph.name)
+	}
+
+	id := ph.nextID.Add(1)
+	respCh := make(chan processHookRPCMessage, 1)
+	ph.pendingMu.Lock()
+	ph.pending[id] = respCh
+	ph.pendingMu.Unlock()
+
+	msg := processHookRPCMessage{
+		JSONRPC: processHookJSONRPCVersion,
+		ID:      id,
+		Method:  method,
+	}
+	if params != nil {
+		body, err := json.Marshal(params)
+		if err != nil {
+			ph.removePending(id)
+			return err
+		}
+		msg.Params = body
+	}
+
+	if err := ph.send(ctx, msg); err != nil {
+		ph.removePending(id)
+		return err
+	}
+
+	select {
+	case resp, ok := <-respCh:
+		if !ok {
+			return fmt.Errorf("process hook %q closed while waiting for %s", ph.name, method)
+		}
+		if resp.Error != nil {
+			return fmt.Errorf("process hook %q %s failed: %s", ph.name, method, resp.Error.Message)
+		}
+		if out != nil && len(resp.Result) > 0 {
+			if err := json.Unmarshal(resp.Result, out); err != nil {
+				return fmt.Errorf("decode process hook %q %s result: %w", ph.name, method, err)
+			}
+		}
+		return nil
+	case <-ctx.Done():
+		ph.removePending(id)
+		return ctx.Err()
+	}
+}
+
+func (ph *ProcessHook) send(ctx context.Context, msg processHookRPCMessage) error {
+	body, err := json.Marshal(msg)
+	if err != nil {
+		return err
+	}
+	body = append(body, '\n')
+
+	ph.writeMu.Lock()
+	defer ph.writeMu.Unlock()
+
+	if ph.closed.Load() {
+		return fmt.Errorf("process hook %q is closed", ph.name)
+	}
+
+	done := make(chan error, 1)
+	go func() {
+		_, writeErr := ph.stdin.Write(body)
+		done <- writeErr
+	}()
+
+	select {
+	case err := <-done:
+		if err != nil {
+			return fmt.Errorf("write process hook %q message: %w", ph.name, err)
+		}
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	}
+}
+
+func (ph *ProcessHook) readLoop(stdout io.Reader) {
+	scanner := bufio.NewScanner(stdout)
+	scanner.Buffer(make([]byte, 0, 64*1024), processHookReadBufferSize)
+
+	for scanner.Scan() {
+		var msg processHookRPCMessage
+		if err := json.Unmarshal(scanner.Bytes(), &msg); err != nil {
+			logger.WarnCF("hooks", "Failed to decode process hook message", map[string]any{
+				"hook":  ph.name,
+				"error": err.Error(),
+			})
+			continue
+		}
+		if msg.ID == 0 {
+			continue
+		}
+		ph.pendingMu.Lock()
+		respCh, ok := ph.pending[msg.ID]
+		if ok {
+			delete(ph.pending, msg.ID)
+		}
+		ph.pendingMu.Unlock()
+		if ok {
+			respCh <- msg
+			close(respCh)
+		}
+	}
+}
+
+func (ph *ProcessHook) readStderr(stderr io.Reader) {
+	scanner := bufio.NewScanner(stderr)
+	scanner.Buffer(make([]byte, 0, 16*1024), processHookReadBufferSize)
+	for scanner.Scan() {
+		logger.WarnCF("hooks", "Process hook stderr", map[string]any{
+			"hook":   ph.name,
+			"stderr": scanner.Text(),
+		})
+	}
+}
+
+func (ph *ProcessHook) waitLoop() {
+	err := ph.cmd.Wait()
+	ph.closeMu.Lock()
+	ph.closeErr = err
+	ph.closeMu.Unlock()
+	ph.failPending(err)
+	close(ph.done)
+}
+
+func (ph *ProcessHook) failPending(err error) {
+	ph.pendingMu.Lock()
+	defer ph.pendingMu.Unlock()
+
+	msg := processHookRPCMessage{
+		Error: &processHookRPCError{
+			Code:    -32000,
+			Message: "process exited",
+		},
+	}
+	if err != nil {
+		msg.Error.Message = err.Error()
+	}
+
+	for id, ch := range ph.pending {
+		delete(ph.pending, id)
+		ch <- msg
+		close(ch)
+	}
+}
+
+func (ph *ProcessHook) removePending(id uint64) {
+	ph.pendingMu.Lock()
+	defer ph.pendingMu.Unlock()
+
+	if ch, ok := ph.pending[id]; ok {
+		delete(ph.pending, id)
+		close(ch)
+	}
+}
+
+func (al *AgentLoop) MountProcessHook(ctx context.Context, name string, opts ProcessHookOptions) error {
+	if al == nil {
+		return fmt.Errorf("agent loop is nil")
+	}
+	processHook, err := NewProcessHook(ctx, name, opts)
+	if err != nil {
+		return err
+	}
+	if err := al.MountHook(HookRegistration{
+		Name:   name,
+		Source: HookSourceProcess,
+		Hook:   processHook,
+	}); err != nil {
+		_ = processHook.Close()
+		return err
+	}
+	return nil
+}
+
+func newProcessHookObserveKinds(kinds []string) map[string]struct{} {
+	if len(kinds) == 0 {
+		return nil
+	}
+
+	normalized := make(map[string]struct{}, len(kinds))
+	for _, kind := range kinds {
+		if kind == "" {
+			continue
+		}
+		normalized[kind] = struct{}{}
+	}
+	if len(normalized) == 0 {
+		return nil
+	}
+	return normalized
+}
diff --git a/pkg/agent/hook_process_test.go b/pkg/agent/hook_process_test.go
new file mode 100644
index 000000000..50f89811f
--- /dev/null
+++ b/pkg/agent/hook_process_test.go
@@ -0,0 +1,339 @@
+package agent
+
+import (
+	"bufio"
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func TestProcessHook_HelperProcess(t *testing.T) {
+	if os.Getenv("PICOCLAW_HOOK_HELPER") != "1" {
+		return
+	}
+	if err := runProcessHookHelper(); err != nil {
+		fmt.Fprintln(os.Stderr, err.Error())
+		os.Exit(1)
+	}
+	os.Exit(0)
+}
+
+func TestAgentLoop_MountProcessHook_LLMAndObserver(t *testing.T) {
+	provider := &llmHookTestProvider{}
+	al, agent, cleanup := newHookTestLoop(t, provider)
+	defer cleanup()
+
+	eventLog := filepath.Join(t.TempDir(), "events.log")
+	if err := al.MountProcessHook(context.Background(), "ipc-llm", ProcessHookOptions{
+		Command:      processHookHelperCommand(),
+		Env:          processHookHelperEnv("rewrite", eventLog),
+		Observe:      true,
+		InterceptLLM: true,
+	}); err != nil {
+		t.Fatalf("MountProcessHook failed: %v", err)
+	}
+
+	resp, err := al.runAgentLoop(context.Background(), agent, processOptions{
+		SessionKey:      "session-1",
+		Channel:         "cli",
+		ChatID:          "direct",
+		UserMessage:     "hello",
+		DefaultResponse: defaultResponse,
+		EnableSummary:   false,
+		SendResponse:    false,
+	})
+	if err != nil {
+		t.Fatalf("runAgentLoop failed: %v", err)
+	}
+	if resp != "provider content|ipc" {
+		t.Fatalf("expected process-hooked llm content, got %q", resp)
+	}
+
+	provider.mu.Lock()
+	lastModel := provider.lastModel
+	provider.mu.Unlock()
+	if lastModel != "process-model" {
+		t.Fatalf("expected process model, got %q", lastModel)
+	}
+
+	waitForFileContains(t, eventLog, "turn_end")
+}
+
+func TestAgentLoop_MountProcessHook_ToolRewrite(t *testing.T) {
+	provider := &toolHookProvider{}
+	al, agent, cleanup := newHookTestLoop(t, provider)
+	defer cleanup()
+
+	al.RegisterTool(&echoTextTool{})
+	if err := al.MountProcessHook(context.Background(), "ipc-tool", ProcessHookOptions{
+		Command:       processHookHelperCommand(),
+		Env:           processHookHelperEnv("rewrite", ""),
+		InterceptTool: true,
+	}); err != nil {
+		t.Fatalf("MountProcessHook failed: %v", err)
+	}
+
+	resp, err := al.runAgentLoop(context.Background(), agent, processOptions{
+		SessionKey:      "session-1",
+		Channel:         "cli",
+		ChatID:          "direct",
+		UserMessage:     "run tool",
+		DefaultResponse: defaultResponse,
+		EnableSummary:   false,
+		SendResponse:    false,
+	})
+	if err != nil {
+		t.Fatalf("runAgentLoop failed: %v", err)
+	}
+	if resp != "ipc:ipc" {
+		t.Fatalf("expected rewritten process-hook tool result, got %q", resp)
+	}
+}
+
+type blockedToolProvider struct {
+	calls int
+}
+
+func (p *blockedToolProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	p.calls++
+	if p.calls == 1 {
+		return &providers.LLMResponse{
+			ToolCalls: []providers.ToolCall{
+				{
+					ID:        "call-1",
+					Name:      "blocked_tool",
+					Arguments: map[string]any{},
+				},
+			},
+		}, nil
+	}
+
+	return &providers.LLMResponse{
+		Content: messages[len(messages)-1].Content,
+	}, nil
+}
+
+func (p *blockedToolProvider) GetDefaultModel() string {
+	return "blocked-tool-provider"
+}
+
+func TestAgentLoop_MountProcessHook_ApprovalDeny(t *testing.T) {
+	provider := &blockedToolProvider{}
+	al, agent, cleanup := newHookTestLoop(t, provider)
+	defer cleanup()
+
+	if err := al.MountProcessHook(context.Background(), "ipc-approval", ProcessHookOptions{
+		Command:     processHookHelperCommand(),
+		Env:         processHookHelperEnv("deny", ""),
+		ApproveTool: true,
+	}); err != nil {
+		t.Fatalf("MountProcessHook failed: %v", err)
+	}
+
+	sub := al.SubscribeEvents(16)
+	defer al.UnsubscribeEvents(sub.ID)
+
+	resp, err := al.runAgentLoop(context.Background(), agent, processOptions{
+		SessionKey:      "session-1",
+		Channel:         "cli",
+		ChatID:          "direct",
+		UserMessage:     "run blocked tool",
+		DefaultResponse: defaultResponse,
+		EnableSummary:   false,
+		SendResponse:    false,
+	})
+	if err != nil {
+		t.Fatalf("runAgentLoop failed: %v", err)
+	}
+
+	expected := "Tool execution denied by approval hook: blocked by ipc hook"
+	if resp != expected {
+		t.Fatalf("expected %q, got %q", expected, resp)
+	}
+
+	events := collectEventStream(sub.C)
+	skippedEvt, ok := findEvent(events, EventKindToolExecSkipped)
+	if !ok {
+		t.Fatal("expected tool skipped event")
+	}
+	payload, ok := skippedEvt.Payload.(ToolExecSkippedPayload)
+	if !ok {
+		t.Fatalf("expected ToolExecSkippedPayload, got %T", skippedEvt.Payload)
+	}
+	if payload.Reason != expected {
+		t.Fatalf("expected reason %q, got %q", expected, payload.Reason)
+	}
+}
+
+func processHookHelperCommand() []string {
+	return []string{os.Args[0], "-test.run=TestProcessHook_HelperProcess", "--"}
+}
+
+func processHookHelperEnv(mode, eventLog string) []string {
+	env := []string{
+		"PICOCLAW_HOOK_HELPER=1",
+		"PICOCLAW_HOOK_MODE=" + mode,
+	}
+	if eventLog != "" {
+		env = append(env, "PICOCLAW_HOOK_EVENT_LOG="+eventLog)
+	}
+	return env
+}
+
+func waitForFileContains(t *testing.T, path, substring string) {
+	t.Helper()
+
+	deadline := time.Now().Add(3 * time.Second)
+	for time.Now().Before(deadline) {
+		data, err := os.ReadFile(path)
+		if err == nil && strings.Contains(string(data), substring) {
+			return
+		}
+		time.Sleep(20 * time.Millisecond)
+	}
+
+	data, _ := os.ReadFile(path)
+	t.Fatalf("timed out waiting for %q in %s; current content: %q", substring, path, string(data))
+}
+
+func runProcessHookHelper() error {
+	mode := os.Getenv("PICOCLAW_HOOK_MODE")
+	eventLog := os.Getenv("PICOCLAW_HOOK_EVENT_LOG")
+
+	scanner := bufio.NewScanner(os.Stdin)
+	scanner.Buffer(make([]byte, 0, 64*1024), processHookReadBufferSize)
+	encoder := json.NewEncoder(os.Stdout)
+
+	for scanner.Scan() {
+		var msg processHookRPCMessage
+		if err := json.Unmarshal(scanner.Bytes(), &msg); err != nil {
+			return err
+		}
+
+		if msg.ID == 0 {
+			if msg.Method == "hook.event" && eventLog != "" {
+				var evt map[string]any
+				if err := json.Unmarshal(msg.Params, &evt); err == nil {
+					if rawKind, ok := evt["Kind"].(float64); ok {
+						kind := EventKind(rawKind)
+						_ = os.WriteFile(eventLog, []byte(kind.String()+"\n"), 0o644)
+					}
+				}
+			}
+			continue
+		}
+
+		result, rpcErr := handleProcessHookRequest(mode, msg)
+		resp := processHookRPCMessage{
+			JSONRPC: processHookJSONRPCVersion,
+			ID:      msg.ID,
+		}
+		if rpcErr != nil {
+			resp.Error = rpcErr
+		} else if result != nil {
+			body, err := json.Marshal(result)
+			if err != nil {
+				return err
+			}
+			resp.Result = body
+		} else {
+			resp.Result = []byte("{}")
+		}
+
+		if err := encoder.Encode(resp); err != nil {
+			return err
+		}
+	}
+
+	return scanner.Err()
+}
+
+func handleProcessHookRequest(mode string, msg processHookRPCMessage) (any, *processHookRPCError) {
+	switch msg.Method {
+	case "hook.hello":
+		return map[string]any{"ok": true}, nil
+	case "hook.before_llm":
+		if mode != "rewrite" {
+			return map[string]any{"action": HookActionContinue}, nil
+		}
+		var req map[string]any
+		_ = json.Unmarshal(msg.Params, &req)
+		req["model"] = "process-model"
+		return map[string]any{
+			"action":  HookActionModify,
+			"request": req,
+		}, nil
+	case "hook.after_llm":
+		if mode != "rewrite" {
+			return map[string]any{"action": HookActionContinue}, nil
+		}
+		var resp map[string]any
+		_ = json.Unmarshal(msg.Params, &resp)
+		if rawResponse, ok := resp["response"].(map[string]any); ok {
+			if content, ok := rawResponse["content"].(string); ok {
+				rawResponse["content"] = content + "|ipc"
+			}
+		}
+		return map[string]any{
+			"action":   HookActionModify,
+			"response": resp,
+		}, nil
+	case "hook.before_tool":
+		if mode != "rewrite" {
+			return map[string]any{"action": HookActionContinue}, nil
+		}
+		var call map[string]any
+		_ = json.Unmarshal(msg.Params, &call)
+		rawArgs, ok := call["arguments"].(map[string]any)
+		if !ok || rawArgs == nil {
+			rawArgs = map[string]any{}
+		}
+		rawArgs["text"] = "ipc"
+		call["arguments"] = rawArgs
+		return map[string]any{
+			"action": HookActionModify,
+			"call":   call,
+		}, nil
+	case "hook.after_tool":
+		if mode != "rewrite" {
+			return map[string]any{"action": HookActionContinue}, nil
+		}
+		var result map[string]any
+		_ = json.Unmarshal(msg.Params, &result)
+		if rawResult, ok := result["result"].(map[string]any); ok {
+			if forLLM, ok := rawResult["for_llm"].(string); ok {
+				rawResult["for_llm"] = "ipc:" + forLLM
+			}
+		}
+		return map[string]any{
+			"action": HookActionModify,
+			"result": result,
+		}, nil
+	case "hook.approve_tool":
+		if mode == "deny" {
+			return ApprovalDecision{
+				Approved: false,
+				Reason:   "blocked by ipc hook",
+			}, nil
+		}
+		return ApprovalDecision{Approved: true}, nil
+	default:
+		return nil, &processHookRPCError{
+			Code:    -32601,
+			Message: "method not found",
+		}
+	}
+}
diff --git a/pkg/agent/hooks.go b/pkg/agent/hooks.go
new file mode 100644
index 000000000..c1ef58ffd
--- /dev/null
+++ b/pkg/agent/hooks.go
@@ -0,0 +1,809 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"sort"
+	"sync"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+const (
+	defaultHookObserverTimeout    = 500 * time.Millisecond
+	defaultHookInterceptorTimeout = 5 * time.Second
+	defaultHookApprovalTimeout    = 60 * time.Second
+	hookObserverBufferSize        = 64
+)
+
+type HookAction string
+
+const (
+	HookActionContinue  HookAction = "continue"
+	HookActionModify    HookAction = "modify"
+	HookActionDenyTool  HookAction = "deny_tool"
+	HookActionAbortTurn HookAction = "abort_turn"
+	HookActionHardAbort HookAction = "hard_abort"
+)
+
+type HookDecision struct {
+	Action HookAction `json:"action"`
+	Reason string     `json:"reason,omitempty"`
+}
+
+func (d HookDecision) normalizedAction() HookAction {
+	if d.Action == "" {
+		return HookActionContinue
+	}
+	return d.Action
+}
+
+type ApprovalDecision struct {
+	Approved bool   `json:"approved"`
+	Reason   string `json:"reason,omitempty"`
+}
+
+type HookSource uint8
+
+const (
+	HookSourceInProcess HookSource = iota
+	HookSourceProcess
+)
+
+type HookRegistration struct {
+	Name     string
+	Priority int
+	Source   HookSource
+	Hook     any
+}
+
+func NamedHook(name string, hook any) HookRegistration {
+	return HookRegistration{
+		Name:   name,
+		Source: HookSourceInProcess,
+		Hook:   hook,
+	}
+}
+
+type EventObserver interface {
+	OnEvent(ctx context.Context, evt Event) error
+}
+
+type LLMInterceptor interface {
+	BeforeLLM(ctx context.Context, req *LLMHookRequest) (*LLMHookRequest, HookDecision, error)
+	AfterLLM(ctx context.Context, resp *LLMHookResponse) (*LLMHookResponse, HookDecision, error)
+}
+
+type ToolInterceptor interface {
+	BeforeTool(ctx context.Context, call *ToolCallHookRequest) (*ToolCallHookRequest, HookDecision, error)
+	AfterTool(ctx context.Context, result *ToolResultHookResponse) (*ToolResultHookResponse, HookDecision, error)
+}
+
+type ToolApprover interface {
+	ApproveTool(ctx context.Context, req *ToolApprovalRequest) (ApprovalDecision, error)
+}
+
+type LLMHookRequest struct {
+	Meta             EventMeta                  `json:"meta"`
+	Model            string                     `json:"model"`
+	Messages         []providers.Message        `json:"messages,omitempty"`
+	Tools            []providers.ToolDefinition `json:"tools,omitempty"`
+	Options          map[string]any             `json:"options,omitempty"`
+	Channel          string                     `json:"channel,omitempty"`
+	ChatID           string                     `json:"chat_id,omitempty"`
+	GracefulTerminal bool                       `json:"graceful_terminal,omitempty"`
+}
+
+func (r *LLMHookRequest) Clone() *LLMHookRequest {
+	if r == nil {
+		return nil
+	}
+	cloned := *r
+	cloned.Messages = cloneProviderMessages(r.Messages)
+	cloned.Tools = cloneToolDefinitions(r.Tools)
+	cloned.Options = cloneStringAnyMap(r.Options)
+	return &cloned
+}
+
+type LLMHookResponse struct {
+	Meta     EventMeta              `json:"meta"`
+	Model    string                 `json:"model"`
+	Response *providers.LLMResponse `json:"response,omitempty"`
+	Channel  string                 `json:"channel,omitempty"`
+	ChatID   string                 `json:"chat_id,omitempty"`
+}
+
+func (r *LLMHookResponse) Clone() *LLMHookResponse {
+	if r == nil {
+		return nil
+	}
+	cloned := *r
+	cloned.Response = cloneLLMResponse(r.Response)
+	return &cloned
+}
+
+type ToolCallHookRequest struct {
+	Meta      EventMeta      `json:"meta"`
+	Tool      string         `json:"tool"`
+	Arguments map[string]any `json:"arguments,omitempty"`
+	Channel   string         `json:"channel,omitempty"`
+	ChatID    string         `json:"chat_id,omitempty"`
+}
+
+func (r *ToolCallHookRequest) Clone() *ToolCallHookRequest {
+	if r == nil {
+		return nil
+	}
+	cloned := *r
+	cloned.Arguments = cloneStringAnyMap(r.Arguments)
+	return &cloned
+}
+
+type ToolApprovalRequest struct {
+	Meta      EventMeta      `json:"meta"`
+	Tool      string         `json:"tool"`
+	Arguments map[string]any `json:"arguments,omitempty"`
+	Channel   string         `json:"channel,omitempty"`
+	ChatID    string         `json:"chat_id,omitempty"`
+}
+
+func (r *ToolApprovalRequest) Clone() *ToolApprovalRequest {
+	if r == nil {
+		return nil
+	}
+	cloned := *r
+	cloned.Arguments = cloneStringAnyMap(r.Arguments)
+	return &cloned
+}
+
+type ToolResultHookResponse struct {
+	Meta      EventMeta         `json:"meta"`
+	Tool      string            `json:"tool"`
+	Arguments map[string]any    `json:"arguments,omitempty"`
+	Result    *tools.ToolResult `json:"result,omitempty"`
+	Duration  time.Duration     `json:"duration"`
+	Channel   string            `json:"channel,omitempty"`
+	ChatID    string            `json:"chat_id,omitempty"`
+}
+
+func (r *ToolResultHookResponse) Clone() *ToolResultHookResponse {
+	if r == nil {
+		return nil
+	}
+	cloned := *r
+	cloned.Arguments = cloneStringAnyMap(r.Arguments)
+	cloned.Result = cloneToolResult(r.Result)
+	return &cloned
+}
+
+type HookManager struct {
+	eventBus           *EventBus
+	observerTimeout    time.Duration
+	interceptorTimeout time.Duration
+	approvalTimeout    time.Duration
+
+	mu      sync.RWMutex
+	hooks   map[string]HookRegistration
+	ordered []HookRegistration
+
+	sub       EventSubscription
+	done      chan struct{}
+	closeOnce sync.Once
+}
+
+func NewHookManager(eventBus *EventBus) *HookManager {
+	hm := &HookManager{
+		eventBus:           eventBus,
+		observerTimeout:    defaultHookObserverTimeout,
+		interceptorTimeout: defaultHookInterceptorTimeout,
+		approvalTimeout:    defaultHookApprovalTimeout,
+		hooks:              make(map[string]HookRegistration),
+		done:               make(chan struct{}),
+	}
+
+	if eventBus == nil {
+		close(hm.done)
+		return hm
+	}
+
+	hm.sub = eventBus.Subscribe(hookObserverBufferSize)
+	go hm.dispatchEvents()
+	return hm
+}
+
+func (hm *HookManager) Close() {
+	if hm == nil {
+		return
+	}
+
+	hm.closeOnce.Do(func() {
+		if hm.eventBus != nil {
+			hm.eventBus.Unsubscribe(hm.sub.ID)
+		}
+		<-hm.done
+		hm.closeAllHooks()
+	})
+}
+
+func (hm *HookManager) ConfigureTimeouts(observer, interceptor, approval time.Duration) {
+	if hm == nil {
+		return
+	}
+	if observer > 0 {
+		hm.observerTimeout = observer
+	}
+	if interceptor > 0 {
+		hm.interceptorTimeout = interceptor
+	}
+	if approval > 0 {
+		hm.approvalTimeout = approval
+	}
+}
+
+func (hm *HookManager) Mount(reg HookRegistration) error {
+	if hm == nil {
+		return fmt.Errorf("hook manager is nil")
+	}
+	if reg.Name == "" {
+		return fmt.Errorf("hook name is required")
+	}
+	if reg.Hook == nil {
+		return fmt.Errorf("hook %q is nil", reg.Name)
+	}
+
+	hm.mu.Lock()
+	defer hm.mu.Unlock()
+
+	if existing, ok := hm.hooks[reg.Name]; ok {
+		closeHookIfPossible(existing.Hook)
+	}
+	hm.hooks[reg.Name] = reg
+	hm.rebuildOrdered()
+	return nil
+}
+
+func (hm *HookManager) Unmount(name string) {
+	if hm == nil || name == "" {
+		return
+	}
+
+	hm.mu.Lock()
+	defer hm.mu.Unlock()
+
+	if existing, ok := hm.hooks[name]; ok {
+		closeHookIfPossible(existing.Hook)
+	}
+	delete(hm.hooks, name)
+	hm.rebuildOrdered()
+}
+
+func (hm *HookManager) dispatchEvents() {
+	defer close(hm.done)
+
+	for evt := range hm.sub.C {
+		for _, reg := range hm.snapshotHooks() {
+			observer, ok := reg.Hook.(EventObserver)
+			if !ok {
+				continue
+			}
+			hm.runObserver(reg.Name, observer, evt)
+		}
+	}
+}
+
+func (hm *HookManager) BeforeLLM(ctx context.Context, req *LLMHookRequest) (*LLMHookRequest, HookDecision) {
+	if hm == nil || req == nil {
+		return req, HookDecision{Action: HookActionContinue}
+	}
+
+	current := req.Clone()
+	for _, reg := range hm.snapshotHooks() {
+		interceptor, ok := reg.Hook.(LLMInterceptor)
+		if !ok {
+			continue
+		}
+
+		next, decision, ok := hm.callBeforeLLM(ctx, reg.Name, interceptor, current.Clone())
+		if !ok {
+			continue
+		}
+
+		switch decision.normalizedAction() {
+		case HookActionContinue, HookActionModify:
+			if next != nil {
+				current = next
+			}
+		case HookActionAbortTurn, HookActionHardAbort:
+			return current, decision
+		default:
+			hm.logUnsupportedAction(reg.Name, "before_llm", decision.Action)
+		}
+	}
+	return current, HookDecision{Action: HookActionContinue}
+}
+
+func (hm *HookManager) AfterLLM(ctx context.Context, resp *LLMHookResponse) (*LLMHookResponse, HookDecision) {
+	if hm == nil || resp == nil {
+		return resp, HookDecision{Action: HookActionContinue}
+	}
+
+	current := resp.Clone()
+	for _, reg := range hm.snapshotHooks() {
+		interceptor, ok := reg.Hook.(LLMInterceptor)
+		if !ok {
+			continue
+		}
+
+		next, decision, ok := hm.callAfterLLM(ctx, reg.Name, interceptor, current.Clone())
+		if !ok {
+			continue
+		}
+
+		switch decision.normalizedAction() {
+		case HookActionContinue, HookActionModify:
+			if next != nil {
+				current = next
+			}
+		case HookActionAbortTurn, HookActionHardAbort:
+			return current, decision
+		default:
+			hm.logUnsupportedAction(reg.Name, "after_llm", decision.Action)
+		}
+	}
+	return current, HookDecision{Action: HookActionContinue}
+}
+
+func (hm *HookManager) BeforeTool(
+	ctx context.Context,
+	call *ToolCallHookRequest,
+) (*ToolCallHookRequest, HookDecision) {
+	if hm == nil || call == nil {
+		return call, HookDecision{Action: HookActionContinue}
+	}
+
+	current := call.Clone()
+	for _, reg := range hm.snapshotHooks() {
+		interceptor, ok := reg.Hook.(ToolInterceptor)
+		if !ok {
+			continue
+		}
+
+		next, decision, ok := hm.callBeforeTool(ctx, reg.Name, interceptor, current.Clone())
+		if !ok {
+			continue
+		}
+
+		switch decision.normalizedAction() {
+		case HookActionContinue, HookActionModify:
+			if next != nil {
+				current = next
+			}
+		case HookActionDenyTool, HookActionAbortTurn, HookActionHardAbort:
+			return current, decision
+		default:
+			hm.logUnsupportedAction(reg.Name, "before_tool", decision.Action)
+		}
+	}
+	return current, HookDecision{Action: HookActionContinue}
+}
+
+func (hm *HookManager) AfterTool(
+	ctx context.Context,
+	result *ToolResultHookResponse,
+) (*ToolResultHookResponse, HookDecision) {
+	if hm == nil || result == nil {
+		return result, HookDecision{Action: HookActionContinue}
+	}
+
+	current := result.Clone()
+	for _, reg := range hm.snapshotHooks() {
+		interceptor, ok := reg.Hook.(ToolInterceptor)
+		if !ok {
+			continue
+		}
+
+		next, decision, ok := hm.callAfterTool(ctx, reg.Name, interceptor, current.Clone())
+		if !ok {
+			continue
+		}
+
+		switch decision.normalizedAction() {
+		case HookActionContinue, HookActionModify:
+			if next != nil {
+				current = next
+			}
+		case HookActionAbortTurn, HookActionHardAbort:
+			return current, decision
+		default:
+			hm.logUnsupportedAction(reg.Name, "after_tool", decision.Action)
+		}
+	}
+	return current, HookDecision{Action: HookActionContinue}
+}
+
+func (hm *HookManager) ApproveTool(ctx context.Context, req *ToolApprovalRequest) ApprovalDecision {
+	if hm == nil || req == nil {
+		return ApprovalDecision{Approved: true}
+	}
+
+	for _, reg := range hm.snapshotHooks() {
+		approver, ok := reg.Hook.(ToolApprover)
+		if !ok {
+			continue
+		}
+
+		decision, ok := hm.callApproveTool(ctx, reg.Name, approver, req.Clone())
+		if !ok {
+			return ApprovalDecision{
+				Approved: false,
+				Reason:   fmt.Sprintf("tool approval hook %q failed", reg.Name),
+			}
+		}
+		if !decision.Approved {
+			return decision
+		}
+	}
+
+	return ApprovalDecision{Approved: true}
+}
+
+func (hm *HookManager) rebuildOrdered() {
+	hm.ordered = hm.ordered[:0]
+	for _, reg := range hm.hooks {
+		hm.ordered = append(hm.ordered, reg)
+	}
+	sort.SliceStable(hm.ordered, func(i, j int) bool {
+		if hm.ordered[i].Source != hm.ordered[j].Source {
+			return hm.ordered[i].Source < hm.ordered[j].Source
+		}
+		if hm.ordered[i].Priority == hm.ordered[j].Priority {
+			return hm.ordered[i].Name < hm.ordered[j].Name
+		}
+		return hm.ordered[i].Priority < hm.ordered[j].Priority
+	})
+}
+
+func (hm *HookManager) snapshotHooks() []HookRegistration {
+	hm.mu.RLock()
+	defer hm.mu.RUnlock()
+
+	snapshot := make([]HookRegistration, len(hm.ordered))
+	copy(snapshot, hm.ordered)
+	return snapshot
+}
+
+func (hm *HookManager) closeAllHooks() {
+	hm.mu.Lock()
+	defer hm.mu.Unlock()
+
+	for name, reg := range hm.hooks {
+		closeHookIfPossible(reg.Hook)
+		delete(hm.hooks, name)
+	}
+	hm.ordered = nil
+}
+
+func (hm *HookManager) runObserver(name string, observer EventObserver, evt Event) {
+	ctx, cancel := context.WithTimeout(context.Background(), hm.observerTimeout)
+	defer cancel()
+
+	done := make(chan error, 1)
+	go func() {
+		done <- observer.OnEvent(ctx, evt)
+	}()
+
+	select {
+	case err := <-done:
+		if err != nil {
+			logger.WarnCF("hooks", "Event observer failed", map[string]any{
+				"hook":  name,
+				"event": evt.Kind.String(),
+				"error": err.Error(),
+			})
+		}
+	case <-ctx.Done():
+		logger.WarnCF("hooks", "Event observer timed out", map[string]any{
+			"hook":       name,
+			"event":      evt.Kind.String(),
+			"timeout_ms": hm.observerTimeout.Milliseconds(),
+		})
+	}
+}
+
+func (hm *HookManager) callBeforeLLM(
+	parent context.Context,
+	name string,
+	interceptor LLMInterceptor,
+	req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, bool) {
+	return runInterceptorHook(
+		parent,
+		hm.interceptorTimeout,
+		name,
+		"before_llm",
+		func(ctx context.Context) (*LLMHookRequest, HookDecision, error) {
+			return interceptor.BeforeLLM(ctx, req)
+		},
+	)
+}
+
+func (hm *HookManager) callAfterLLM(
+	parent context.Context,
+	name string,
+	interceptor LLMInterceptor,
+	resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, bool) {
+	return runInterceptorHook(
+		parent,
+		hm.interceptorTimeout,
+		name,
+		"after_llm",
+		func(ctx context.Context) (*LLMHookResponse, HookDecision, error) {
+			return interceptor.AfterLLM(ctx, resp)
+		},
+	)
+}
+
+func (hm *HookManager) callBeforeTool(
+	parent context.Context,
+	name string,
+	interceptor ToolInterceptor,
+	call *ToolCallHookRequest,
+) (*ToolCallHookRequest, HookDecision, bool) {
+	return runInterceptorHook(
+		parent,
+		hm.interceptorTimeout,
+		name,
+		"before_tool",
+		func(ctx context.Context) (*ToolCallHookRequest, HookDecision, error) {
+			return interceptor.BeforeTool(ctx, call)
+		},
+	)
+}
+
+func (hm *HookManager) callAfterTool(
+	parent context.Context,
+	name string,
+	interceptor ToolInterceptor,
+	resultView *ToolResultHookResponse,
+) (*ToolResultHookResponse, HookDecision, bool) {
+	return runInterceptorHook(
+		parent,
+		hm.interceptorTimeout,
+		name,
+		"after_tool",
+		func(ctx context.Context) (*ToolResultHookResponse, HookDecision, error) {
+			return interceptor.AfterTool(ctx, resultView)
+		},
+	)
+}
+
+func (hm *HookManager) callApproveTool(
+	parent context.Context,
+	name string,
+	approver ToolApprover,
+	req *ToolApprovalRequest,
+) (ApprovalDecision, bool) {
+	return runApprovalHook(
+		parent,
+		hm.approvalTimeout,
+		name,
+		"approve_tool",
+		func(ctx context.Context) (ApprovalDecision, error) {
+			return approver.ApproveTool(ctx, req)
+		},
+	)
+}
+
+func runInterceptorHook[T any](
+	parent context.Context,
+	timeout time.Duration,
+	name string,
+	stage string,
+	fn func(ctx context.Context) (T, HookDecision, error),
+) (T, HookDecision, bool) {
+	var zero T
+
+	ctx, cancel := context.WithTimeout(parent, timeout)
+	defer cancel()
+
+	type result struct {
+		value    T
+		decision HookDecision
+		err      error
+	}
+	done := make(chan result, 1)
+	go func() {
+		value, decision, err := fn(ctx)
+		done <- result{value: value, decision: decision, err: err}
+	}()
+
+	select {
+	case res := <-done:
+		if res.err != nil {
+			logger.WarnCF("hooks", "Interceptor hook failed", map[string]any{
+				"hook":  name,
+				"stage": stage,
+				"error": res.err.Error(),
+			})
+			return zero, HookDecision{}, false
+		}
+		return res.value, res.decision, true
+	case <-ctx.Done():
+		logger.WarnCF("hooks", "Interceptor hook timed out", map[string]any{
+			"hook":       name,
+			"stage":      stage,
+			"timeout_ms": timeout.Milliseconds(),
+		})
+		return zero, HookDecision{}, false
+	}
+}
+
+func runApprovalHook(
+	parent context.Context,
+	timeout time.Duration,
+	name string,
+	stage string,
+	fn func(ctx context.Context) (ApprovalDecision, error),
+) (ApprovalDecision, bool) {
+	ctx, cancel := context.WithTimeout(parent, timeout)
+	defer cancel()
+
+	type result struct {
+		decision ApprovalDecision
+		err      error
+	}
+	done := make(chan result, 1)
+	go func() {
+		decision, err := fn(ctx)
+		done <- result{decision: decision, err: err}
+	}()
+
+	select {
+	case res := <-done:
+		if res.err != nil {
+			logger.WarnCF("hooks", "Approval hook failed", map[string]any{
+				"hook":  name,
+				"stage": stage,
+				"error": res.err.Error(),
+			})
+			return ApprovalDecision{}, false
+		}
+		return res.decision, true
+	case <-ctx.Done():
+		logger.WarnCF("hooks", "Approval hook timed out", map[string]any{
+			"hook":       name,
+			"stage":      stage,
+			"timeout_ms": timeout.Milliseconds(),
+		})
+		return ApprovalDecision{
+			Approved: false,
+			Reason:   fmt.Sprintf("tool approval hook %q timed out", name),
+		}, true
+	}
+}
+
+func (hm *HookManager) logUnsupportedAction(name, stage string, action HookAction) {
+	logger.WarnCF("hooks", "Hook returned unsupported action for stage", map[string]any{
+		"hook":   name,
+		"stage":  stage,
+		"action": action,
+	})
+}
+
+func cloneProviderMessages(messages []providers.Message) []providers.Message {
+	if len(messages) == 0 {
+		return nil
+	}
+
+	cloned := make([]providers.Message, len(messages))
+	for i, msg := range messages {
+		cloned[i] = msg
+		if len(msg.Media) > 0 {
+			cloned[i].Media = append([]string(nil), msg.Media...)
+		}
+		if len(msg.SystemParts) > 0 {
+			cloned[i].SystemParts = append([]providers.ContentBlock(nil), msg.SystemParts...)
+		}
+		if len(msg.ToolCalls) > 0 {
+			cloned[i].ToolCalls = cloneProviderToolCalls(msg.ToolCalls)
+		}
+	}
+	return cloned
+}
+
+func cloneProviderToolCalls(calls []providers.ToolCall) []providers.ToolCall {
+	if len(calls) == 0 {
+		return nil
+	}
+
+	cloned := make([]providers.ToolCall, len(calls))
+	for i, call := range calls {
+		cloned[i] = call
+		if call.Function != nil {
+			fn := *call.Function
+			cloned[i].Function = &fn
+		}
+		if call.Arguments != nil {
+			cloned[i].Arguments = cloneStringAnyMap(call.Arguments)
+		}
+		if call.ExtraContent != nil {
+			extra := *call.ExtraContent
+			if call.ExtraContent.Google != nil {
+				google := *call.ExtraContent.Google
+				extra.Google = &google
+			}
+			cloned[i].ExtraContent = &extra
+		}
+	}
+	return cloned
+}
+
+func cloneToolDefinitions(defs []providers.ToolDefinition) []providers.ToolDefinition {
+	if len(defs) == 0 {
+		return nil
+	}
+
+	cloned := make([]providers.ToolDefinition, len(defs))
+	for i, def := range defs {
+		cloned[i] = def
+		cloned[i].Function.Parameters = cloneStringAnyMap(def.Function.Parameters)
+	}
+	return cloned
+}
+
+func cloneLLMResponse(resp *providers.LLMResponse) *providers.LLMResponse {
+	if resp == nil {
+		return nil
+	}
+	cloned := *resp
+	cloned.ToolCalls = cloneProviderToolCalls(resp.ToolCalls)
+	if len(resp.ReasoningDetails) > 0 {
+		cloned.ReasoningDetails = append(cloned.ReasoningDetails[:0:0], resp.ReasoningDetails...)
+	}
+	if resp.Usage != nil {
+		usage := *resp.Usage
+		cloned.Usage = &usage
+	}
+	return &cloned
+}
+
+func cloneStringAnyMap(src map[string]any) map[string]any {
+	if len(src) == 0 {
+		return nil
+	}
+
+	cloned := make(map[string]any, len(src))
+	for k, v := range src {
+		cloned[k] = v
+	}
+	return cloned
+}
+
+func cloneToolResult(result *tools.ToolResult) *tools.ToolResult {
+	if result == nil {
+		return nil
+	}
+
+	cloned := *result
+	if len(result.Media) > 0 {
+		cloned.Media = append([]string(nil), result.Media...)
+	}
+	return &cloned
+}
+
+func closeHookIfPossible(hook any) {
+	closer, ok := hook.(io.Closer)
+	if !ok {
+		return
+	}
+	if err := closer.Close(); err != nil {
+		logger.WarnCF("hooks", "Failed to close hook", map[string]any{
+			"error": err.Error(),
+		})
+	}
+}
diff --git a/pkg/agent/hooks_test.go b/pkg/agent/hooks_test.go
new file mode 100644
index 000000000..49e1b1784
--- /dev/null
+++ b/pkg/agent/hooks_test.go
@@ -0,0 +1,345 @@
+package agent
+
+import (
+	"context"
+	"os"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+func newHookTestLoop(
+	t *testing.T,
+	provider providers.LLMProvider,
+) (*AgentLoop, *AgentInstance, func()) {
+	t.Helper()
+
+	tmpDir, err := os.MkdirTemp("", "agent-hooks-*")
+	if err != nil {
+		t.Fatalf("failed to create temp dir: %v", err)
+	}
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	al := NewAgentLoop(cfg, bus.NewMessageBus(), provider)
+	agent := al.registry.GetDefaultAgent()
+	if agent == nil {
+		t.Fatal("expected default agent")
+	}
+
+	return al, agent, func() {
+		al.Close()
+		_ = os.RemoveAll(tmpDir)
+	}
+}
+
+func TestHookManager_SortsInProcessBeforeProcess(t *testing.T) {
+	hm := NewHookManager(nil)
+	defer hm.Close()
+
+	if err := hm.Mount(HookRegistration{
+		Name:     "process",
+		Priority: -10,
+		Source:   HookSourceProcess,
+		Hook:     struct{}{},
+	}); err != nil {
+		t.Fatalf("mount process hook: %v", err)
+	}
+	if err := hm.Mount(HookRegistration{
+		Name:     "in-process",
+		Priority: 100,
+		Source:   HookSourceInProcess,
+		Hook:     struct{}{},
+	}); err != nil {
+		t.Fatalf("mount in-process hook: %v", err)
+	}
+
+	ordered := hm.snapshotHooks()
+	if len(ordered) != 2 {
+		t.Fatalf("expected 2 hooks, got %d", len(ordered))
+	}
+	if ordered[0].Name != "in-process" {
+		t.Fatalf("expected in-process hook first, got %q", ordered[0].Name)
+	}
+	if ordered[1].Name != "process" {
+		t.Fatalf("expected process hook second, got %q", ordered[1].Name)
+	}
+}
+
+type llmHookTestProvider struct {
+	mu        sync.Mutex
+	lastModel string
+}
+
+func (p *llmHookTestProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	p.mu.Lock()
+	p.lastModel = model
+	p.mu.Unlock()
+
+	return &providers.LLMResponse{
+		Content: "provider content",
+	}, nil
+}
+
+func (p *llmHookTestProvider) GetDefaultModel() string {
+	return "llm-hook-provider"
+}
+
+type llmObserverHook struct {
+	eventCh chan Event
+}
+
+func (h *llmObserverHook) OnEvent(ctx context.Context, evt Event) error {
+	if evt.Kind == EventKindTurnEnd {
+		select {
+		case h.eventCh <- evt:
+		default:
+		}
+	}
+	return nil
+}
+
+func (h *llmObserverHook) BeforeLLM(
+	ctx context.Context,
+	req *LLMHookRequest,
+) (*LLMHookRequest, HookDecision, error) {
+	next := req.Clone()
+	next.Model = "hook-model"
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *llmObserverHook) AfterLLM(
+	ctx context.Context,
+	resp *LLMHookResponse,
+) (*LLMHookResponse, HookDecision, error) {
+	next := resp.Clone()
+	next.Response.Content = "hooked content"
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func TestAgentLoop_Hooks_ObserverAndLLMInterceptor(t *testing.T) {
+	provider := &llmHookTestProvider{}
+	al, agent, cleanup := newHookTestLoop(t, provider)
+	defer cleanup()
+
+	hook := &llmObserverHook{eventCh: make(chan Event, 1)}
+	if err := al.MountHook(NamedHook("llm-observer", hook)); err != nil {
+		t.Fatalf("MountHook failed: %v", err)
+	}
+
+	resp, err := al.runAgentLoop(context.Background(), agent, processOptions{
+		SessionKey:      "session-1",
+		Channel:         "cli",
+		ChatID:          "direct",
+		UserMessage:     "hello",
+		DefaultResponse: defaultResponse,
+		EnableSummary:   false,
+		SendResponse:    false,
+	})
+	if err != nil {
+		t.Fatalf("runAgentLoop failed: %v", err)
+	}
+	if resp != "hooked content" {
+		t.Fatalf("expected hooked content, got %q", resp)
+	}
+
+	provider.mu.Lock()
+	lastModel := provider.lastModel
+	provider.mu.Unlock()
+	if lastModel != "hook-model" {
+		t.Fatalf("expected model hook-model, got %q", lastModel)
+	}
+
+	select {
+	case evt := <-hook.eventCh:
+		if evt.Kind != EventKindTurnEnd {
+			t.Fatalf("expected turn end event, got %v", evt.Kind)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("timed out waiting for hook observer event")
+	}
+}
+
+type toolHookProvider struct {
+	mu    sync.Mutex
+	calls int
+}
+
+func (p *toolHookProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	p.calls++
+	if p.calls == 1 {
+		return &providers.LLMResponse{
+			ToolCalls: []providers.ToolCall{
+				{
+					ID:        "call-1",
+					Name:      "echo_text",
+					Arguments: map[string]any{"text": "original"},
+				},
+			},
+		}, nil
+	}
+
+	last := messages[len(messages)-1]
+	return &providers.LLMResponse{
+		Content: last.Content,
+	}, nil
+}
+
+func (p *toolHookProvider) GetDefaultModel() string {
+	return "tool-hook-provider"
+}
+
+type echoTextTool struct{}
+
+func (t *echoTextTool) Name() string {
+	return "echo_text"
+}
+
+func (t *echoTextTool) Description() string {
+	return "echo a text argument"
+}
+
+func (t *echoTextTool) Parameters() map[string]any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"text": map[string]any{
+				"type": "string",
+			},
+		},
+	}
+}
+
+func (t *echoTextTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+	text, _ := args["text"].(string)
+	return tools.SilentResult(text)
+}
+
+type toolRewriteHook struct{}
+
+func (h *toolRewriteHook) BeforeTool(
+	ctx context.Context,
+	call *ToolCallHookRequest,
+) (*ToolCallHookRequest, HookDecision, error) {
+	next := call.Clone()
+	next.Arguments["text"] = "modified"
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func (h *toolRewriteHook) AfterTool(
+	ctx context.Context,
+	result *ToolResultHookResponse,
+) (*ToolResultHookResponse, HookDecision, error) {
+	next := result.Clone()
+	next.Result.ForLLM = "after:" + next.Result.ForLLM
+	return next, HookDecision{Action: HookActionModify}, nil
+}
+
+func TestAgentLoop_Hooks_ToolInterceptorCanRewrite(t *testing.T) {
+	provider := &toolHookProvider{}
+	al, agent, cleanup := newHookTestLoop(t, provider)
+	defer cleanup()
+
+	al.RegisterTool(&echoTextTool{})
+	if err := al.MountHook(NamedHook("tool-rewrite", &toolRewriteHook{})); err != nil {
+		t.Fatalf("MountHook failed: %v", err)
+	}
+
+	resp, err := al.runAgentLoop(context.Background(), agent, processOptions{
+		SessionKey:      "session-1",
+		Channel:         "cli",
+		ChatID:          "direct",
+		UserMessage:     "run tool",
+		DefaultResponse: defaultResponse,
+		EnableSummary:   false,
+		SendResponse:    false,
+	})
+	if err != nil {
+		t.Fatalf("runAgentLoop failed: %v", err)
+	}
+	if resp != "after:modified" {
+		t.Fatalf("expected rewritten tool result, got %q", resp)
+	}
+}
+
+type denyApprovalHook struct{}
+
+func (h *denyApprovalHook) ApproveTool(ctx context.Context, req *ToolApprovalRequest) (ApprovalDecision, error) {
+	return ApprovalDecision{
+		Approved: false,
+		Reason:   "blocked",
+	}, nil
+}
+
+func TestAgentLoop_Hooks_ToolApproverCanDeny(t *testing.T) {
+	provider := &toolHookProvider{}
+	al, agent, cleanup := newHookTestLoop(t, provider)
+	defer cleanup()
+
+	al.RegisterTool(&echoTextTool{})
+	if err := al.MountHook(NamedHook("deny-approval", &denyApprovalHook{})); err != nil {
+		t.Fatalf("MountHook failed: %v", err)
+	}
+
+	sub := al.SubscribeEvents(16)
+	defer al.UnsubscribeEvents(sub.ID)
+
+	resp, err := al.runAgentLoop(context.Background(), agent, processOptions{
+		SessionKey:      "session-1",
+		Channel:         "cli",
+		ChatID:          "direct",
+		UserMessage:     "run tool",
+		DefaultResponse: defaultResponse,
+		EnableSummary:   false,
+		SendResponse:    false,
+	})
+	if err != nil {
+		t.Fatalf("runAgentLoop failed: %v", err)
+	}
+	expected := "Tool execution denied by approval hook: blocked"
+	if resp != expected {
+		t.Fatalf("expected %q, got %q", expected, resp)
+	}
+
+	events := collectEventStream(sub.C)
+	skippedEvt, ok := findEvent(events, EventKindToolExecSkipped)
+	if !ok {
+		t.Fatal("expected tool skipped event")
+	}
+	payload, ok := skippedEvt.Payload.(ToolExecSkippedPayload)
+	if !ok {
+		t.Fatalf("expected ToolExecSkippedPayload, got %T", skippedEvt.Payload)
+	}
+	if payload.Reason != expected {
+		t.Fatalf("expected skipped reason %q, got %q", expected, payload.Reason)
+	}
+}
diff --git a/pkg/agent/instance.go b/pkg/agent/instance.go
index ed438059f..34d401186 100644
--- a/pkg/agent/instance.go
+++ b/pkg/agent/instance.go
@@ -1,14 +1,17 @@
 package agent
 
 import (
+	"context"
 	"fmt"
-	"log"
 	"os"
 	"path/filepath"
 	"regexp"
 	"strings"
 
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
+	"github.com/sipeed/picoclaw/pkg/memory"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/routing"
 	"github.com/sipeed/picoclaw/pkg/session"
@@ -18,22 +21,33 @@ import (
 // AgentInstance represents a fully configured agent with its own workspace,
 // session manager, context builder, and tool registry.
 type AgentInstance struct {
-	ID             string
-	Name           string
-	Model          string
-	Fallbacks      []string
-	Workspace      string
-	MaxIterations  int
-	MaxTokens      int
-	Temperature    float64
-	ContextWindow  int
-	Provider       providers.LLMProvider
-	Sessions       *session.SessionManager
-	ContextBuilder *ContextBuilder
-	Tools          *tools.ToolRegistry
-	Subagents      *config.SubagentsConfig
-	SkillsFilter   []string
-	Candidates     []providers.FallbackCandidate
+	ID                        string
+	Name                      string
+	Model                     string
+	Fallbacks                 []string
+	Workspace                 string
+	MaxIterations             int
+	MaxTokens                 int
+	Temperature               float64
+	ThinkingLevel             ThinkingLevel
+	ContextWindow             int
+	SummarizeMessageThreshold int
+	SummarizeTokenPercent     int
+	Provider                  providers.LLMProvider
+	Sessions                  session.SessionStore
+	ContextBuilder            *ContextBuilder
+	Tools                     *tools.ToolRegistry
+	Subagents                 *config.SubagentsConfig
+	SkillsFilter              []string
+	Candidates                []providers.FallbackCandidate
+
+	// Router is non-nil when model routing is configured and the light model
+	// was successfully resolved. It scores each incoming message and decides
+	// whether to route to LightCandidates or stay with Candidates.
+	Router *routing.Router
+	// LightCandidates holds the resolved provider candidates for the light model.
+	// Pre-computed at agent creation to avoid repeated model_list lookups at runtime.
+	LightCandidates []providers.FallbackCandidate
 }
 
 // NewAgentInstance creates an agent instance from config.
@@ -53,26 +67,46 @@ func NewAgentInstance(
 	readRestrict := restrict && !defaults.AllowReadOutsideWorkspace
 
 	// Compile path whitelist patterns from config.
-	allowReadPaths := compilePatterns(cfg.Tools.AllowReadPaths)
+	allowReadPaths := buildAllowReadPatterns(cfg)
 	allowWritePaths := compilePatterns(cfg.Tools.AllowWritePaths)
 
 	toolsRegistry := tools.NewToolRegistry()
-	toolsRegistry.Register(tools.NewReadFileTool(workspace, readRestrict, allowReadPaths))
-	toolsRegistry.Register(tools.NewWriteFileTool(workspace, restrict, allowWritePaths))
-	toolsRegistry.Register(tools.NewListDirTool(workspace, readRestrict, allowReadPaths))
-	execTool, err := tools.NewExecToolWithConfig(workspace, restrict, cfg)
-	if err != nil {
-		log.Fatalf("Critical error: unable to initialize exec tool: %v", err)
-	}
-	toolsRegistry.Register(execTool)
 
-	toolsRegistry.Register(tools.NewEditFileTool(workspace, restrict, allowWritePaths))
-	toolsRegistry.Register(tools.NewAppendFileTool(workspace, restrict, allowWritePaths))
+	if cfg.Tools.IsToolEnabled("read_file") {
+		maxReadFileSize := cfg.Tools.ReadFile.MaxReadFileSize
+		toolsRegistry.Register(tools.NewReadFileTool(workspace, readRestrict, maxReadFileSize, allowReadPaths))
+	}
+	if cfg.Tools.IsToolEnabled("write_file") {
+		toolsRegistry.Register(tools.NewWriteFileTool(workspace, restrict, allowWritePaths))
+	}
+	if cfg.Tools.IsToolEnabled("list_dir") {
+		toolsRegistry.Register(tools.NewListDirTool(workspace, readRestrict, allowReadPaths))
+	}
+	if cfg.Tools.IsToolEnabled("exec") {
+		execTool, err := tools.NewExecToolWithConfig(workspace, restrict, cfg, allowReadPaths)
+		if err != nil {
+			logger.ErrorCF("agent", "Failed to initialize exec tool; continuing without exec",
+				map[string]any{"error": err.Error()})
+		} else {
+			toolsRegistry.Register(execTool)
+		}
+	}
+
+	if cfg.Tools.IsToolEnabled("edit_file") {
+		toolsRegistry.Register(tools.NewEditFileTool(workspace, restrict, allowWritePaths))
+	}
+	if cfg.Tools.IsToolEnabled("append_file") {
+		toolsRegistry.Register(tools.NewAppendFileTool(workspace, restrict, allowWritePaths))
+	}
 
 	sessionsDir := filepath.Join(workspace, "sessions")
-	sessionsManager := session.NewSessionManager(sessionsDir)
+	sessions := initSessionStore(sessionsDir)
 
-	contextBuilder := NewContextBuilder(workspace)
+	mcpDiscoveryActive := cfg.Tools.MCP.Enabled && cfg.Tools.MCP.Discovery.Enabled
+	contextBuilder := NewContextBuilder(workspace).WithToolDiscovery(
+		mcpDiscoveryActive && cfg.Tools.MCP.Discovery.UseBM25,
+		mcpDiscoveryActive && cfg.Tools.MCP.Discovery.UseRegex,
+	)
 
 	agentID := routing.DefaultAgentID
 	agentName := ""
@@ -96,75 +130,81 @@ func NewAgentInstance(
 		maxTokens = 8192
 	}
 
+	contextWindow := defaults.ContextWindow
+	if contextWindow == 0 {
+		// Default heuristic: 4x the output token limit.
+		// Most models have context windows well above their output limits
+		// (e.g., GPT-4o 128k ctx / 16k out, Claude 200k ctx / 8k out).
+		// 4x is a conservative lower bound that avoids premature
+		// summarization while remaining safe — the reactive
+		// forceCompression handles any overshoot.
+		contextWindow = maxTokens * 4
+	}
+
 	temperature := 0.7
 	if defaults.Temperature != nil {
 		temperature = *defaults.Temperature
 	}
 
+	var thinkingLevelStr string
+	if mc, err := cfg.GetModelConfig(model); err == nil {
+		thinkingLevelStr = mc.ThinkingLevel
+	}
+	thinkingLevel := parseThinkingLevel(thinkingLevelStr)
+
+	summarizeMessageThreshold := defaults.SummarizeMessageThreshold
+	if summarizeMessageThreshold == 0 {
+		summarizeMessageThreshold = 20
+	}
+
+	summarizeTokenPercent := defaults.SummarizeTokenPercent
+	if summarizeTokenPercent == 0 {
+		summarizeTokenPercent = 75
+	}
+
 	// Resolve fallback candidates
-	modelCfg := providers.ModelConfig{
-		Primary:   model,
-		Fallbacks: fallbacks,
+	candidates := resolveModelCandidates(cfg, defaults.Provider, model, fallbacks)
+
+	// Model routing setup: pre-resolve light model candidates at creation time
+	// to avoid repeated model_list lookups on every incoming message.
+	var router *routing.Router
+	var lightCandidates []providers.FallbackCandidate
+	if rc := defaults.Routing; rc != nil && rc.Enabled && rc.LightModel != "" {
+		resolved := resolveModelCandidates(cfg, defaults.Provider, rc.LightModel, nil)
+		if len(resolved) > 0 {
+			router = routing.New(routing.RouterConfig{
+				LightModel: rc.LightModel,
+				Threshold:  rc.Threshold,
+			})
+			lightCandidates = resolved
+		} else {
+			logger.WarnCF("agent", "Routing light model not found; routing disabled",
+				map[string]any{"light_model": rc.LightModel, "agent_id": agentID})
+		}
 	}
-	resolveFromModelList := func(raw string) (string, bool) {
-		ensureProtocol := func(model string) string {
-			model = strings.TrimSpace(model)
-			if model == "" {
-				return ""
-			}
-			if strings.Contains(model, "/") {
-				return model
-			}
-			return "openai/" + model
-		}
-
-		raw = strings.TrimSpace(raw)
-		if raw == "" {
-			return "", false
-		}
-
-		if cfg != nil {
-			if mc, err := cfg.GetModelConfig(raw); err == nil && mc != nil && strings.TrimSpace(mc.Model) != "" {
-				return ensureProtocol(mc.Model), true
-			}
-
-			for i := range cfg.ModelList {
-				fullModel := strings.TrimSpace(cfg.ModelList[i].Model)
-				if fullModel == "" {
-					continue
-				}
-				if fullModel == raw {
-					return ensureProtocol(fullModel), true
-				}
-				_, modelID := providers.ExtractProtocol(fullModel)
-				if modelID == raw {
-					return ensureProtocol(fullModel), true
-				}
-			}
-		}
-
-		return "", false
-	}
-
-	candidates := providers.ResolveCandidatesWithLookup(modelCfg, defaults.Provider, resolveFromModelList)
 
 	return &AgentInstance{
-		ID:             agentID,
-		Name:           agentName,
-		Model:          model,
-		Fallbacks:      fallbacks,
-		Workspace:      workspace,
-		MaxIterations:  maxIter,
-		MaxTokens:      maxTokens,
-		Temperature:    temperature,
-		ContextWindow:  maxTokens,
-		Provider:       provider,
-		Sessions:       sessionsManager,
-		ContextBuilder: contextBuilder,
-		Tools:          toolsRegistry,
-		Subagents:      subagents,
-		SkillsFilter:   skillsFilter,
-		Candidates:     candidates,
+		ID:                        agentID,
+		Name:                      agentName,
+		Model:                     model,
+		Fallbacks:                 fallbacks,
+		Workspace:                 workspace,
+		MaxIterations:             maxIter,
+		MaxTokens:                 maxTokens,
+		Temperature:               temperature,
+		ThinkingLevel:             thinkingLevel,
+		ContextWindow:             contextWindow,
+		SummarizeMessageThreshold: summarizeMessageThreshold,
+		SummarizeTokenPercent:     summarizeTokenPercent,
+		Provider:                  provider,
+		Sessions:                  sessions,
+		ContextBuilder:            contextBuilder,
+		Tools:                     toolsRegistry,
+		Subagents:                 subagents,
+		SkillsFilter:              skillsFilter,
+		Candidates:                candidates,
+		Router:                    router,
+		LightCandidates:           lightCandidates,
 	}
 }
 
@@ -173,12 +213,13 @@ func resolveAgentWorkspace(agentCfg *config.AgentConfig, defaults *config.AgentD
 	if agentCfg != nil && strings.TrimSpace(agentCfg.Workspace) != "" {
 		return expandHome(strings.TrimSpace(agentCfg.Workspace))
 	}
+	// Use the configured default workspace (respects PICOCLAW_HOME)
 	if agentCfg == nil || agentCfg.Default || agentCfg.ID == "" || routing.NormalizeAgentID(agentCfg.ID) == "main" {
 		return expandHome(defaults.Workspace)
 	}
-	home, _ := os.UserHomeDir()
+	// For named agents without explicit workspace, use default workspace with agent ID suffix
 	id := routing.NormalizeAgentID(agentCfg.ID)
-	return filepath.Join(home, ".picoclaw", "workspace-"+id)
+	return filepath.Join(expandHome(defaults.Workspace), "..", "workspace-"+id)
 }
 
 // resolveAgentModel resolves the primary model for an agent.
@@ -210,6 +251,63 @@ func compilePatterns(patterns []string) []*regexp.Regexp {
 	return compiled
 }
 
+func buildAllowReadPatterns(cfg *config.Config) []*regexp.Regexp {
+	var configured []string
+	if cfg != nil {
+		configured = cfg.Tools.AllowReadPaths
+	}
+
+	compiled := compilePatterns(configured)
+	mediaDirPattern := regexp.MustCompile(mediaTempDirPattern())
+	for _, pattern := range compiled {
+		if pattern.String() == mediaDirPattern.String() {
+			return compiled
+		}
+	}
+
+	return append(compiled, mediaDirPattern)
+}
+
+func mediaTempDirPattern() string {
+	sep := regexp.QuoteMeta(string(os.PathSeparator))
+	return "^" + regexp.QuoteMeta(filepath.Clean(media.TempDir())) + "(?:" + sep + "|$)"
+}
+
+// Close releases resources held by the agent's session store.
+func (a *AgentInstance) Close() error {
+	if a.Sessions != nil {
+		return a.Sessions.Close()
+	}
+	return nil
+}
+
+// initSessionStore creates the session persistence backend.
+// It uses the JSONL store by default and auto-migrates legacy JSON sessions.
+// Falls back to SessionManager if the JSONL store cannot be initialized or
+// if migration fails (which indicates the store cannot write reliably).
+func initSessionStore(dir string) session.SessionStore {
+	store, err := memory.NewJSONLStore(dir)
+	if err != nil {
+		logger.WarnCF("agent", "Memory JSONL store init failed; falling back to json sessions",
+			map[string]any{"error": err.Error()})
+		return session.NewSessionManager(dir)
+	}
+
+	if n, merr := memory.MigrateFromJSON(context.Background(), dir, store); merr != nil {
+		// Migration failure means the store could not write data.
+		// Fall back to SessionManager to avoid a split state where
+		// some sessions are in JSONL and others remain in JSON.
+		logger.WarnCF("agent", "Memory migration failed; falling back to json sessions",
+			map[string]any{"error": merr.Error()})
+		store.Close()
+		return session.NewSessionManager(dir)
+	} else if n > 0 {
+		logger.InfoCF("agent", "Memory migrated to JSONL", map[string]any{"sessions_migrated": n})
+	}
+
+	return session.NewJSONLBackend(store)
+}
+
 func expandHome(path string) string {
 	if path == "" {
 		return path
diff --git a/pkg/agent/instance_test.go b/pkg/agent/instance_test.go
index af1bf2ead..e073cb929 100644
--- a/pkg/agent/instance_test.go
+++ b/pkg/agent/instance_test.go
@@ -1,10 +1,14 @@
 package agent
 
 import (
+	"context"
 	"os"
+	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/media"
 )
 
 func TestNewAgentInstance_UsesDefaultsTemperatureAndMaxTokens(t *testing.T) {
@@ -18,7 +22,7 @@ func TestNewAgentInstance_UsesDefaultsTemperatureAndMaxTokens(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
-				Model:             "test-model",
+				ModelName:         "test-model",
 				MaxTokens:         1234,
 				MaxToolIterations: 5,
 			},
@@ -50,7 +54,7 @@ func TestNewAgentInstance_DefaultsTemperatureWhenZero(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
-				Model:             "test-model",
+				ModelName:         "test-model",
 				MaxTokens:         1234,
 				MaxToolIterations: 5,
 			},
@@ -79,7 +83,7 @@ func TestNewAgentInstance_DefaultsTemperatureWhenUnset(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
-				Model:             "test-model",
+				ModelName:         "test-model",
 				MaxTokens:         1234,
 				MaxToolIterations: 5,
 			},
@@ -95,75 +99,184 @@ func TestNewAgentInstance_DefaultsTemperatureWhenUnset(t *testing.T) {
 }
 
 func TestNewAgentInstance_ResolveCandidatesFromModelListAlias(t *testing.T) {
-	tmpDir, err := os.MkdirTemp("", "agent-instance-test-*")
-	if err != nil {
-		t.Fatalf("Failed to create temp dir: %v", err)
+	tests := []struct {
+		name         string
+		aliasName    string
+		modelName    string
+		apiBase      string
+		wantProvider string
+		wantModel    string
+	}{
+		{
+			name:         "alias with provider prefix",
+			aliasName:    "step-3.5-flash",
+			modelName:    "openrouter/stepfun/step-3.5-flash:free",
+			apiBase:      "https://openrouter.ai/api/v1",
+			wantProvider: "openrouter",
+			wantModel:    "stepfun/step-3.5-flash:free",
+		},
+		{
+			name:         "alias without provider prefix",
+			aliasName:    "glm-5",
+			modelName:    "glm-5",
+			apiBase:      "https://api.z.ai/api/coding/paas/v4",
+			wantProvider: "openai",
+			wantModel:    "glm-5",
+		},
 	}
-	defer os.RemoveAll(tmpDir)
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tmpDir, err := os.MkdirTemp("", "agent-instance-test-*")
+			if err != nil {
+				t.Fatalf("Failed to create temp dir: %v", err)
+			}
+			defer os.RemoveAll(tmpDir)
+
+			cfg := &config.Config{
+				Agents: config.AgentsConfig{
+					Defaults: config.AgentDefaults{
+						Workspace: tmpDir,
+						ModelName: tt.aliasName,
+					},
+				},
+				ModelList: []*config.ModelConfig{
+					{
+						ModelName: tt.aliasName,
+						Model:     tt.modelName,
+						APIBase:   tt.apiBase,
+					},
+				},
+			}
+
+			provider := &mockProvider{}
+			agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider)
+
+			if len(agent.Candidates) != 1 {
+				t.Fatalf("len(Candidates) = %d, want 1", len(agent.Candidates))
+			}
+			if agent.Candidates[0].Provider != tt.wantProvider {
+				t.Fatalf("candidate provider = %q, want %q", agent.Candidates[0].Provider, tt.wantProvider)
+			}
+			if agent.Candidates[0].Model != tt.wantModel {
+				t.Fatalf("candidate model = %q, want %q", agent.Candidates[0].Model, tt.wantModel)
+			}
+		})
+	}
+}
+
+func TestNewAgentInstance_AllowsMediaTempDirForReadListAndExec(t *testing.T) {
+	workspace := t.TempDir()
+	mediaDir := media.TempDir()
+	if err := os.MkdirAll(mediaDir, 0o700); err != nil {
+		t.Fatalf("MkdirAll(mediaDir) error = %v", err)
+	}
+
+	mediaFile, err := os.CreateTemp(mediaDir, "instance-tool-*.txt")
+	if err != nil {
+		t.Fatalf("CreateTemp(mediaDir) error = %v", err)
+	}
+	mediaPath := mediaFile.Name()
+	if _, err := mediaFile.WriteString("attachment content"); err != nil {
+		mediaFile.Close()
+		t.Fatalf("WriteString(mediaFile) error = %v", err)
+	}
+	if err := mediaFile.Close(); err != nil {
+		t.Fatalf("Close(mediaFile) error = %v", err)
+	}
+	t.Cleanup(func() { _ = os.Remove(mediaPath) })
 
 	cfg := &config.Config{
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
-				Workspace: tmpDir,
-				Model:     "step-3.5-flash",
+				Workspace:           workspace,
+				ModelName:           "test-model",
+				RestrictToWorkspace: true,
 			},
 		},
-		ModelList: []config.ModelConfig{
-			{
-				ModelName: "step-3.5-flash",
-				Model:     "openrouter/stepfun/step-3.5-flash:free",
-				APIBase:   "https://openrouter.ai/api/v1",
+		Tools: config.ToolsConfig{
+			ReadFile: config.ReadFileToolConfig{Enabled: true},
+			ListDir:  config.ToolConfig{Enabled: true},
+			Exec: config.ExecConfig{
+				ToolConfig:         config.ToolConfig{Enabled: true},
+				EnableDenyPatterns: true,
+				AllowRemote:        true,
 			},
 		},
 	}
 
-	provider := &mockProvider{}
-	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider)
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, &mockProvider{})
 
-	if len(agent.Candidates) != 1 {
-		t.Fatalf("len(Candidates) = %d, want 1", len(agent.Candidates))
+	readTool, ok := agent.Tools.Get("read_file")
+	if !ok {
+		t.Fatal("read_file tool not registered")
 	}
-	if agent.Candidates[0].Provider != "openrouter" {
-		t.Fatalf("candidate provider = %q, want %q", agent.Candidates[0].Provider, "openrouter")
+	readResult := readTool.Execute(context.Background(), map[string]any{"path": mediaPath})
+	if readResult.IsError {
+		t.Fatalf("read_file should allow media temp dir, got: %s", readResult.ForLLM)
 	}
-	if agent.Candidates[0].Model != "stepfun/step-3.5-flash:free" {
-		t.Fatalf("candidate model = %q, want %q", agent.Candidates[0].Model, "stepfun/step-3.5-flash:free")
+	if !strings.Contains(readResult.ForLLM, "attachment content") {
+		t.Fatalf("read_file output missing media content: %s", readResult.ForLLM)
+	}
+
+	listTool, ok := agent.Tools.Get("list_dir")
+	if !ok {
+		t.Fatal("list_dir tool not registered")
+	}
+	listResult := listTool.Execute(context.Background(), map[string]any{"path": mediaDir})
+	if listResult.IsError {
+		t.Fatalf("list_dir should allow media temp dir, got: %s", listResult.ForLLM)
+	}
+	if !strings.Contains(listResult.ForLLM, filepath.Base(mediaPath)) {
+		t.Fatalf("list_dir output missing media file: %s", listResult.ForLLM)
+	}
+
+	execTool, ok := agent.Tools.Get("exec")
+	if !ok {
+		t.Fatal("exec tool not registered")
+	}
+	execResult := execTool.Execute(context.Background(), map[string]any{
+		"command":     "cat " + filepath.Base(mediaPath),
+		"working_dir": mediaDir,
+	})
+	if execResult.IsError {
+		t.Fatalf("exec should allow media temp dir, got: %s", execResult.ForLLM)
+	}
+	if !strings.Contains(execResult.ForLLM, "attachment content") {
+		t.Fatalf("exec output missing media content: %s", execResult.ForLLM)
 	}
 }
 
-func TestNewAgentInstance_ResolveCandidatesFromModelListAliasWithoutProtocol(t *testing.T) {
-	tmpDir, err := os.MkdirTemp("", "agent-instance-test-*")
-	if err != nil {
-		t.Fatalf("Failed to create temp dir: %v", err)
-	}
-	defer os.RemoveAll(tmpDir)
+func TestNewAgentInstance_InvalidExecConfigDoesNotExit(t *testing.T) {
+	workspace := t.TempDir()
 
 	cfg := &config.Config{
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
-				Workspace: tmpDir,
-				Model:     "glm-5",
+				Workspace: workspace,
+				ModelName: "test-model",
 			},
 		},
-		ModelList: []config.ModelConfig{
-			{
-				ModelName: "glm-5",
-				Model:     "glm-5",
-				APIBase:   "https://api.z.ai/api/coding/paas/v4",
+		Tools: config.ToolsConfig{
+			ReadFile: config.ReadFileToolConfig{Enabled: true},
+			Exec: config.ExecConfig{
+				ToolConfig:         config.ToolConfig{Enabled: true},
+				EnableDenyPatterns: true,
+				CustomDenyPatterns: []string{"[invalid-regex"},
 			},
 		},
 	}
 
-	provider := &mockProvider{}
-	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, provider)
+	agent := NewAgentInstance(nil, &cfg.Agents.Defaults, cfg, &mockProvider{})
+	if agent == nil {
+		t.Fatal("expected agent instance, got nil")
+	}
 
-	if len(agent.Candidates) != 1 {
-		t.Fatalf("len(Candidates) = %d, want 1", len(agent.Candidates))
+	if _, ok := agent.Tools.Get("exec"); ok {
+		t.Fatal("exec tool should not be registered when exec config is invalid")
 	}
-	if agent.Candidates[0].Provider != "openai" {
-		t.Fatalf("candidate provider = %q, want %q", agent.Candidates[0].Provider, "openai")
-	}
-	if agent.Candidates[0].Model != "glm-5" {
-		t.Fatalf("candidate model = %q, want %q", agent.Candidates[0].Model, "glm-5")
+
+	if _, ok := agent.Tools.Get("read_file"); !ok {
+		t.Fatal("read_file tool should still be registered")
 	}
 }
diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index 00b0f096a..995c5720b 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -12,14 +12,15 @@ import (
 	"errors"
 	"fmt"
 	"path/filepath"
+	"regexp"
 	"strings"
 	"sync"
 	"sync/atomic"
 	"time"
-	"unicode/utf8"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/commands"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/constants"
 	"github.com/sipeed/picoclaw/pkg/logger"
@@ -30,40 +31,89 @@ import (
 	"github.com/sipeed/picoclaw/pkg/state"
 	"github.com/sipeed/picoclaw/pkg/tools"
 	"github.com/sipeed/picoclaw/pkg/utils"
+	"github.com/sipeed/picoclaw/pkg/voice"
 )
 
 type AgentLoop struct {
-	bus            *bus.MessageBus
-	cfg            *config.Config
-	registry       *AgentRegistry
-	state          *state.Manager
+	// Core dependencies
+	bus      *bus.MessageBus
+	cfg      *config.Config
+	registry *AgentRegistry
+	state    *state.Manager
+
+	// Event system (from Incoming)
+	eventBus *EventBus
+	hooks    *HookManager
+
+	// Runtime state
 	running        atomic.Bool
 	summarizing    sync.Map
 	fallback       *providers.FallbackChain
 	channelManager *channels.Manager
 	mediaStore     media.MediaStore
+	transcriber    voice.Transcriber
+	cmdRegistry    *commands.Registry
+	mcp            mcpRuntime
+	hookRuntime    hookRuntime
+	steering       *steeringQueue
+	pendingSkills  sync.Map
+	mu             sync.RWMutex
+
+	// Concurrent turn management (from HEAD)
+	activeTurnStates sync.Map     // key: sessionKey (string), value: *turnState
+	subTurnCounter   atomic.Int64 // Counter for generating unique SubTurn IDs
+
+	// Turn tracking (from Incoming)
+	turnSeq        atomic.Uint64
+	activeRequests sync.WaitGroup
+
+	reloadFunc func() error
 }
 
 // processOptions configures how a message is processed
 type processOptions struct {
-	SessionKey      string // Session identifier for history/context
-	Channel         string // Target channel for tool execution
-	ChatID          string // Target chat ID for tool execution
-	UserMessage     string // User message content (may include prefix)
-	DefaultResponse string // Response when LLM returns empty
-	EnableSummary   bool   // Whether to trigger summarization
-	SendResponse    bool   // Whether to send response via bus
-	NoHistory       bool   // If true, don't load session history (for heartbeat)
+	SessionKey              string              // Session identifier for history/context
+	Channel                 string              // Target channel for tool execution
+	ChatID                  string              // Target chat ID for tool execution
+	SenderID                string              // Current sender ID for dynamic context
+	SenderDisplayName       string              // Current sender display name for dynamic context
+	UserMessage             string              // User message content (may include prefix)
+	ForcedSkills            []string            // Skills explicitly requested for this message
+	SystemPromptOverride    string              // Override the default system prompt (Used by SubTurns)
+	Media                   []string            // media:// refs from inbound message
+	InitialSteeringMessages []providers.Message // Steering messages from refactor/agent
+	DefaultResponse         string              // Response when LLM returns empty
+	EnableSummary           bool                // Whether to trigger summarization
+	SendResponse            bool                // Whether to send response via bus
+	NoHistory               bool                // If true, don't load session history (for heartbeat)
+	SkipInitialSteeringPoll bool                // If true, skip the steering poll at loop start (used by Continue)
 }
 
-const defaultResponse = "I've completed processing but have no response to give. Increase `max_tool_iterations` in config.json."
+type continuationTarget struct {
+	SessionKey string
+	Channel    string
+	ChatID     string
+}
 
-func NewAgentLoop(cfg *config.Config, msgBus *bus.MessageBus, provider providers.LLMProvider) *AgentLoop {
+const (
+	defaultResponse            = "The model returned an empty response. This may indicate a provider error or token limit."
+	toolLimitResponse          = "I've reached `max_tool_iterations` without a final response. Increase `max_tool_iterations` in config.json if this task needs more tool steps."
+	handledToolResponseSummary = "Requested output delivered via tool attachment."
+	sessionKeyAgentPrefix      = "agent:"
+	metadataKeyAccountID       = "account_id"
+	metadataKeyGuildID         = "guild_id"
+	metadataKeyTeamID          = "team_id"
+	metadataKeyParentPeerKind  = "parent_peer_kind"
+	metadataKeyParentPeerID    = "parent_peer_id"
+)
+
+func NewAgentLoop(
+	cfg *config.Config,
+	msgBus *bus.MessageBus,
+	provider providers.LLMProvider,
+) *AgentLoop {
 	registry := NewAgentRegistry(cfg, provider)
 
-	// Register shared tools to all agents
-	registerSharedTools(cfg, msgBus, registry, provider)
-
 	// Set up shared fallback chain
 	cooldown := providers.NewCooldownTracker()
 	fallbackChain := providers.NewFallbackChain(cooldown)
@@ -75,113 +125,299 @@ func NewAgentLoop(cfg *config.Config, msgBus *bus.MessageBus, provider providers
 		stateManager = state.NewManager(defaultAgent.Workspace)
 	}
 
-	return &AgentLoop{
+	eventBus := NewEventBus()
+	al := &AgentLoop{
 		bus:         msgBus,
 		cfg:         cfg,
 		registry:    registry,
 		state:       stateManager,
+		eventBus:    eventBus,
 		summarizing: sync.Map{},
 		fallback:    fallbackChain,
+		cmdRegistry: commands.NewRegistry(commands.BuiltinDefinitions()),
+		steering:    newSteeringQueue(parseSteeringMode(cfg.Agents.Defaults.SteeringMode)),
 	}
+	al.hooks = NewHookManager(eventBus)
+	configureHookManagerFromConfig(al.hooks, cfg)
+
+	// Register shared tools to all agents (now that al is created)
+	registerSharedTools(al, cfg, msgBus, registry, provider)
+
+	return al
 }
 
 // registerSharedTools registers tools that are shared across all agents (web, message, spawn).
 func registerSharedTools(
+	al *AgentLoop,
 	cfg *config.Config,
 	msgBus *bus.MessageBus,
 	registry *AgentRegistry,
 	provider providers.LLMProvider,
 ) {
+	allowReadPaths := buildAllowReadPatterns(cfg)
+
 	for _, agentID := range registry.ListAgentIDs() {
 		agent, ok := registry.GetAgent(agentID)
 		if !ok {
 			continue
 		}
 
-		// Web tools
-		searchTool, err := tools.NewWebSearchTool(tools.WebSearchToolOptions{
-			BraveAPIKey:          cfg.Tools.Web.Brave.APIKey,
-			BraveMaxResults:      cfg.Tools.Web.Brave.MaxResults,
-			BraveEnabled:         cfg.Tools.Web.Brave.Enabled,
-			TavilyAPIKey:         cfg.Tools.Web.Tavily.APIKey,
-			TavilyBaseURL:        cfg.Tools.Web.Tavily.BaseURL,
-			TavilyMaxResults:     cfg.Tools.Web.Tavily.MaxResults,
-			TavilyEnabled:        cfg.Tools.Web.Tavily.Enabled,
-			DuckDuckGoMaxResults: cfg.Tools.Web.DuckDuckGo.MaxResults,
-			DuckDuckGoEnabled:    cfg.Tools.Web.DuckDuckGo.Enabled,
-			PerplexityAPIKey:     cfg.Tools.Web.Perplexity.APIKey,
-			PerplexityMaxResults: cfg.Tools.Web.Perplexity.MaxResults,
-			PerplexityEnabled:    cfg.Tools.Web.Perplexity.Enabled,
-			Proxy:                cfg.Tools.Web.Proxy,
-		})
-		if err != nil {
-			logger.ErrorCF("agent", "Failed to create web search tool", map[string]any{"error": err.Error()})
-		} else if searchTool != nil {
-			agent.Tools.Register(searchTool)
+		if cfg.Tools.IsToolEnabled("web") {
+			searchTool, err := tools.NewWebSearchTool(tools.WebSearchToolOptions{
+				BraveAPIKeys:    config.MergeAPIKeys(cfg.Tools.Web.Brave.APIKey(), cfg.Tools.Web.Brave.APIKeys()),
+				BraveMaxResults: cfg.Tools.Web.Brave.MaxResults,
+				BraveEnabled:    cfg.Tools.Web.Brave.Enabled,
+				TavilyAPIKeys: config.MergeAPIKeys(
+					cfg.Tools.Web.Tavily.APIKey(),
+					cfg.Tools.Web.Tavily.APIKeys(),
+				),
+				TavilyBaseURL:        cfg.Tools.Web.Tavily.BaseURL,
+				TavilyMaxResults:     cfg.Tools.Web.Tavily.MaxResults,
+				TavilyEnabled:        cfg.Tools.Web.Tavily.Enabled,
+				DuckDuckGoMaxResults: cfg.Tools.Web.DuckDuckGo.MaxResults,
+				DuckDuckGoEnabled:    cfg.Tools.Web.DuckDuckGo.Enabled,
+				PerplexityAPIKeys: config.MergeAPIKeys(
+					cfg.Tools.Web.Perplexity.APIKey(),
+					cfg.Tools.Web.Perplexity.APIKeys(),
+				),
+				PerplexityMaxResults:  cfg.Tools.Web.Perplexity.MaxResults,
+				PerplexityEnabled:     cfg.Tools.Web.Perplexity.Enabled,
+				SearXNGBaseURL:        cfg.Tools.Web.SearXNG.BaseURL,
+				SearXNGMaxResults:     cfg.Tools.Web.SearXNG.MaxResults,
+				SearXNGEnabled:        cfg.Tools.Web.SearXNG.Enabled,
+				GLMSearchAPIKey:       cfg.Tools.Web.GLMSearch.APIKey(),
+				GLMSearchBaseURL:      cfg.Tools.Web.GLMSearch.BaseURL,
+				GLMSearchEngine:       cfg.Tools.Web.GLMSearch.SearchEngine,
+				GLMSearchMaxResults:   cfg.Tools.Web.GLMSearch.MaxResults,
+				GLMSearchEnabled:      cfg.Tools.Web.GLMSearch.Enabled,
+				BaiduSearchAPIKey:     cfg.Tools.Web.BaiduSearch.APIKey(),
+				BaiduSearchBaseURL:    cfg.Tools.Web.BaiduSearch.BaseURL,
+				BaiduSearchMaxResults: cfg.Tools.Web.BaiduSearch.MaxResults,
+				BaiduSearchEnabled:    cfg.Tools.Web.BaiduSearch.Enabled,
+				Proxy:                 cfg.Tools.Web.Proxy,
+			})
+			if err != nil {
+				logger.ErrorCF("agent", "Failed to create web search tool", map[string]any{"error": err.Error()})
+			} else if searchTool != nil {
+				agent.Tools.Register(searchTool)
+			}
 		}
-		fetchTool, err := tools.NewWebFetchToolWithProxy(50000, cfg.Tools.Web.Proxy, cfg.Tools.Web.FetchLimitBytes)
-		if err != nil {
-			logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
-		} else {
-			agent.Tools.Register(fetchTool)
+		if cfg.Tools.IsToolEnabled("web_fetch") {
+			fetchTool, err := tools.NewWebFetchToolWithProxy(
+				50000,
+				cfg.Tools.Web.Proxy,
+				cfg.Tools.Web.Format,
+				cfg.Tools.Web.FetchLimitBytes,
+				cfg.Tools.Web.PrivateHostWhitelist)
+			if err != nil {
+				logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
+			} else {
+				agent.Tools.Register(fetchTool)
+			}
 		}
 
 		// Hardware tools (I2C, SPI) - Linux only, returns error on other platforms
-		agent.Tools.Register(tools.NewI2CTool())
-		agent.Tools.Register(tools.NewSPITool())
+		if cfg.Tools.IsToolEnabled("i2c") {
+			agent.Tools.Register(tools.NewI2CTool())
+		}
+		if cfg.Tools.IsToolEnabled("spi") {
+			agent.Tools.Register(tools.NewSPITool())
+		}
 
 		// Message tool
-		messageTool := tools.NewMessageTool()
-		messageTool.SetSendCallback(func(channel, chatID, content string) error {
-			pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
-			defer pubCancel()
-			return msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
-				Channel: channel,
-				ChatID:  chatID,
-				Content: content,
+		if cfg.Tools.IsToolEnabled("message") {
+			messageTool := tools.NewMessageTool()
+			messageTool.SetSendCallback(func(channel, chatID, content string) error {
+				pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+				defer pubCancel()
+				return msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
+					Channel: channel,
+					ChatID:  chatID,
+					Content: content,
+				})
 			})
-		})
-		agent.Tools.Register(messageTool)
+			agent.Tools.Register(messageTool)
+		}
+
+		// Send file tool (outbound media via MediaStore — store injected later by SetMediaStore)
+		if cfg.Tools.IsToolEnabled("send_file") {
+			sendFileTool := tools.NewSendFileTool(
+				agent.Workspace,
+				cfg.Agents.Defaults.RestrictToWorkspace,
+				cfg.Agents.Defaults.GetMaxMediaSize(),
+				nil,
+				allowReadPaths,
+			)
+			agent.Tools.Register(sendFileTool)
+		}
 
 		// Skill discovery and installation tools
-		registryMgr := skills.NewRegistryManagerFromConfig(skills.RegistryConfig{
-			MaxConcurrentSearches: cfg.Tools.Skills.MaxConcurrentSearches,
-			ClawHub:               skills.ClawHubConfig(cfg.Tools.Skills.Registries.ClawHub),
-		})
-		searchCache := skills.NewSearchCache(
-			cfg.Tools.Skills.SearchCache.MaxSize,
-			time.Duration(cfg.Tools.Skills.SearchCache.TTLSeconds)*time.Second,
-		)
-		agent.Tools.Register(tools.NewFindSkillsTool(registryMgr, searchCache))
-		agent.Tools.Register(tools.NewInstallSkillTool(registryMgr, agent.Workspace))
+		skills_enabled := cfg.Tools.IsToolEnabled("skills")
+		find_skills_enable := cfg.Tools.IsToolEnabled("find_skills")
+		install_skills_enable := cfg.Tools.IsToolEnabled("install_skill")
+		if skills_enabled && (find_skills_enable || install_skills_enable) {
+			clawHubConfig := cfg.Tools.Skills.Registries.ClawHub
+			registryMgr := skills.NewRegistryManagerFromConfig(skills.RegistryConfig{
+				MaxConcurrentSearches: cfg.Tools.Skills.MaxConcurrentSearches,
+				ClawHub: skills.ClawHubConfig{
+					Enabled:         clawHubConfig.Enabled,
+					BaseURL:         clawHubConfig.BaseURL,
+					AuthToken:       clawHubConfig.AuthToken(),
+					SearchPath:      clawHubConfig.SearchPath,
+					SkillsPath:      clawHubConfig.SkillsPath,
+					DownloadPath:    clawHubConfig.DownloadPath,
+					Timeout:         clawHubConfig.Timeout,
+					MaxZipSize:      clawHubConfig.MaxZipSize,
+					MaxResponseSize: clawHubConfig.MaxResponseSize,
+				},
+			})
 
-		// Spawn tool with allowlist checker
-		subagentManager := tools.NewSubagentManager(provider, agent.Model, agent.Workspace, msgBus)
-		subagentManager.SetLLMOptions(agent.MaxTokens, agent.Temperature)
-		spawnTool := tools.NewSpawnTool(subagentManager)
-		currentAgentID := agentID
-		spawnTool.SetAllowlistChecker(func(targetAgentID string) bool {
-			return registry.CanSpawnSubagent(currentAgentID, targetAgentID)
-		})
-		agent.Tools.Register(spawnTool)
+			if find_skills_enable {
+				searchCache := skills.NewSearchCache(
+					cfg.Tools.Skills.SearchCache.MaxSize,
+					time.Duration(cfg.Tools.Skills.SearchCache.TTLSeconds)*time.Second,
+				)
+				agent.Tools.Register(tools.NewFindSkillsTool(registryMgr, searchCache))
+			}
+
+			if install_skills_enable {
+				agent.Tools.Register(tools.NewInstallSkillTool(registryMgr, agent.Workspace))
+			}
+		}
+
+		// Spawn and spawn_status tools share a SubagentManager.
+		// Construct it when either tool is enabled (both require subagent).
+		spawnEnabled := cfg.Tools.IsToolEnabled("spawn")
+		spawnStatusEnabled := cfg.Tools.IsToolEnabled("spawn_status")
+		if (spawnEnabled || spawnStatusEnabled) && cfg.Tools.IsToolEnabled("subagent") {
+			subagentManager := tools.NewSubagentManager(provider, agent.Model, agent.Workspace)
+			subagentManager.SetLLMOptions(agent.MaxTokens, agent.Temperature)
+
+			// Set the spawner that links into AgentLoop's turnState
+			subagentManager.SetSpawner(func(
+				ctx context.Context,
+				task, label, targetAgentID string,
+				tls *tools.ToolRegistry,
+				maxTokens int,
+				temperature float64,
+				hasMaxTokens, hasTemperature bool,
+			) (*tools.ToolResult, error) {
+				// 1. Recover parent Turn State from Context
+				parentTS := turnStateFromContext(ctx)
+				if parentTS == nil {
+					// Fallback: If no turnState exists in context, create an isolated ad-hoc root turn state
+					// so that the tool can still function outside of an agent loop (e.g. tests, raw invocations).
+					parentTS = &turnState{
+						ctx:            ctx,
+						turnID:         "adhoc-root",
+						depth:          0,
+						session:        nil, // Ephemeral session not needed for adhoc spawn
+						pendingResults: make(chan *tools.ToolResult, 16),
+						concurrencySem: make(chan struct{}, 5),
+					}
+				}
+
+				// 2. Build Tools slice from registry
+				var tlSlice []tools.Tool
+				for _, name := range tls.List() {
+					if t, ok := tls.Get(name); ok {
+						tlSlice = append(tlSlice, t)
+					}
+				}
+
+				// 3. System Prompt
+				systemPrompt := "You are a subagent. Complete the given task independently and report the result.\n" +
+					"You have access to tools - use them as needed to complete your task.\n" +
+					"After completing the task, provide a clear summary of what was done.\n\n" +
+					"Task: " + task
+
+				// 4. Resolve Model
+				modelToUse := agent.Model
+				if targetAgentID != "" {
+					if targetAgent, ok := al.GetRegistry().GetAgent(targetAgentID); ok {
+						modelToUse = targetAgent.Model
+					}
+				}
+
+				// 5. Build SubTurnConfig
+				cfg := SubTurnConfig{
+					Model:        modelToUse,
+					Tools:        tlSlice,
+					SystemPrompt: systemPrompt,
+				}
+				if hasMaxTokens {
+					cfg.MaxTokens = maxTokens
+				}
+
+				// 6. Spawn SubTurn
+				return spawnSubTurn(ctx, al, parentTS, cfg)
+			})
+
+			// Clone the parent's tool registry so subagents can use all
+			// tools registered so far (file, web, etc.) but NOT spawn/
+			// spawn_status which are added below — preventing recursive
+			// subagent spawning.
+			subagentManager.SetTools(agent.Tools.Clone())
+			if spawnEnabled {
+				spawnTool := tools.NewSpawnTool(subagentManager)
+				spawnTool.SetSpawner(NewSubTurnSpawner(al))
+				currentAgentID := agentID
+				spawnTool.SetAllowlistChecker(func(targetAgentID string) bool {
+					return registry.CanSpawnSubagent(currentAgentID, targetAgentID)
+				})
+
+				agent.Tools.Register(spawnTool)
+
+				// Also register the synchronous subagent tool
+				subagentTool := tools.NewSubagentTool(subagentManager)
+				subagentTool.SetSpawner(NewSubTurnSpawner(al))
+				agent.Tools.Register(subagentTool)
+			}
+			if spawnStatusEnabled {
+				agent.Tools.Register(tools.NewSpawnStatusTool(subagentManager))
+			}
+		} else if (spawnEnabled || spawnStatusEnabled) && !cfg.Tools.IsToolEnabled("subagent") {
+			logger.WarnCF("agent", "spawn/spawn_status tools require subagent to be enabled", nil)
+		}
 	}
 }
 
 func (al *AgentLoop) Run(ctx context.Context) error {
 	al.running.Store(true)
 
+	if err := al.ensureHooksInitialized(ctx); err != nil {
+		return err
+	}
+	if err := al.ensureMCPInitialized(ctx); err != nil {
+		return err
+	}
+
 	for al.running.Load() {
 		select {
 		case <-ctx.Done():
 			return nil
-		default:
-			msg, ok := al.bus.ConsumeInbound(ctx)
+		case msg, ok := <-al.bus.InboundChan():
 			if !ok {
-				continue
+				return nil
+			}
+
+			// Start a goroutine that drains the bus while processMessage is
+			// running. Only messages that resolve to the active turn scope are
+			// redirected into steering; other inbound messages are requeued.
+			drainCancel := func() {}
+			if activeScope, activeAgentID, ok := al.resolveSteeringTarget(msg); ok {
+				drainCtx, cancel := context.WithCancel(ctx)
+				drainCancel = cancel
+				go al.drainBusToSteering(drainCtx, activeScope, activeAgentID)
 			}
 
 			// Process message
 			func() {
+				defer func() {
+					if al.channelManager != nil {
+						al.channelManager.InvokeTypingStop(msg.Channel, msg.ChatID)
+					}
+				}()
 				// TODO: Re-enable media cleanup after inbound media is properly consumed by the agent.
 				// Currently disabled because files are deleted before the LLM can access their content.
 				// defer func() {
@@ -195,59 +431,480 @@ func (al *AgentLoop) Run(ctx context.Context) error {
 				// 	}
 				// }()
 
+				drainCanceled := false
+				cancelDrain := func() {
+					if drainCanceled {
+						return
+					}
+					drainCancel()
+					drainCanceled = true
+				}
+				defer cancelDrain()
+
 				response, err := al.processMessage(ctx, msg)
 				if err != nil {
 					response = fmt.Sprintf("Error processing message: %v", err)
 				}
+				finalResponse := response
 
-				if response != "" {
-					// Check if the message tool already sent a response during this round.
-					// If so, skip publishing to avoid duplicate messages to the user.
-					// Use default agent's tools to check (message tool is shared).
-					alreadySent := false
-					defaultAgent := al.registry.GetDefaultAgent()
-					if defaultAgent != nil {
-						if tool, ok := defaultAgent.Tools.Get("message"); ok {
-							if mt, ok := tool.(*tools.MessageTool); ok {
-								alreadySent = mt.HasSentInRound()
-							}
-						}
-					}
-
-					if !alreadySent {
-						al.bus.PublishOutbound(ctx, bus.OutboundMessage{
-							Channel: msg.Channel,
-							ChatID:  msg.ChatID,
-							Content: response,
+				target, targetErr := al.buildContinuationTarget(msg)
+				if targetErr != nil {
+					logger.WarnCF("agent", "Failed to build steering continuation target",
+						map[string]any{
+							"channel": msg.Channel,
+							"error":   targetErr.Error(),
 						})
-						logger.InfoCF("agent", "Published outbound response",
-							map[string]any{
-								"channel":     msg.Channel,
-								"chat_id":     msg.ChatID,
-								"content_len": len(response),
-							})
-					} else {
-						logger.DebugCF(
-							"agent",
-							"Skipped outbound (message tool already sent)",
-							map[string]any{"channel": msg.Channel},
-						)
+					return
+				}
+				if target == nil {
+					cancelDrain()
+					if finalResponse != "" {
+						al.publishResponseIfNeeded(ctx, msg.Channel, msg.ChatID, finalResponse)
 					}
+					return
+				}
+
+				for al.pendingSteeringCountForScope(target.SessionKey) > 0 {
+					logger.InfoCF("agent", "Continuing queued steering after turn end",
+						map[string]any{
+							"channel":     target.Channel,
+							"chat_id":     target.ChatID,
+							"session_key": target.SessionKey,
+							"queue_depth": al.pendingSteeringCountForScope(target.SessionKey),
+						})
+
+					continued, continueErr := al.Continue(ctx, target.SessionKey, target.Channel, target.ChatID)
+					if continueErr != nil {
+						logger.WarnCF("agent", "Failed to continue queued steering",
+							map[string]any{
+								"channel": target.Channel,
+								"chat_id": target.ChatID,
+								"error":   continueErr.Error(),
+							})
+						return
+					}
+					if continued == "" {
+						return
+					}
+
+					finalResponse = continued
+				}
+
+				cancelDrain()
+
+				for al.pendingSteeringCountForScope(target.SessionKey) > 0 {
+					logger.InfoCF("agent", "Draining steering queued during turn shutdown",
+						map[string]any{
+							"channel":     target.Channel,
+							"chat_id":     target.ChatID,
+							"session_key": target.SessionKey,
+							"queue_depth": al.pendingSteeringCountForScope(target.SessionKey),
+						})
+
+					continued, continueErr := al.Continue(ctx, target.SessionKey, target.Channel, target.ChatID)
+					if continueErr != nil {
+						logger.WarnCF("agent", "Failed to continue queued steering after shutdown drain",
+							map[string]any{
+								"channel": target.Channel,
+								"chat_id": target.ChatID,
+								"error":   continueErr.Error(),
+							})
+						return
+					}
+					if continued == "" {
+						break
+					}
+
+					finalResponse = continued
+				}
+
+				if finalResponse != "" {
+					al.publishResponseIfNeeded(ctx, target.Channel, target.ChatID, finalResponse)
 				}
 			}()
+		default:
+			time.Sleep(time.Microsecond * 200)
 		}
 	}
 
 	return nil
 }
 
+// drainBusToSteering consumes inbound messages and redirects messages from the
+// active scope into the steering queue. Messages from other scopes are requeued
+// so they can be processed normally after the active turn. It drains all
+// immediately available messages, blocking for the first one until ctx is done.
+func (al *AgentLoop) drainBusToSteering(ctx context.Context, activeScope, activeAgentID string) {
+	blocking := true
+	for {
+		var msg bus.InboundMessage
+
+		if blocking {
+			// Block waiting for the first available message or ctx cancellation.
+			select {
+			case <-ctx.Done():
+				return
+			case m, ok := <-al.bus.InboundChan():
+				if !ok {
+					return
+				}
+				msg = m
+			}
+		} else {
+			// Non-blocking: drain any remaining queued messages, return when empty.
+			select {
+			case m, ok := <-al.bus.InboundChan():
+				if !ok {
+					return
+				}
+				msg = m
+			default:
+				return
+			}
+		}
+		blocking = false
+
+		msgScope, _, scopeOK := al.resolveSteeringTarget(msg)
+		if !scopeOK || msgScope != activeScope {
+			if err := al.requeueInboundMessage(msg); err != nil {
+				logger.WarnCF("agent", "Failed to requeue non-steering inbound message", map[string]any{
+					"error":     err.Error(),
+					"channel":   msg.Channel,
+					"sender_id": msg.SenderID,
+				})
+			}
+			continue
+		}
+
+		// Transcribe audio if needed before steering, so the agent sees text.
+		msg, _ = al.transcribeAudioInMessage(ctx, msg)
+
+		logger.InfoCF("agent", "Redirecting inbound message to steering queue",
+			map[string]any{
+				"channel":     msg.Channel,
+				"sender_id":   msg.SenderID,
+				"content_len": len(msg.Content),
+				"scope":       activeScope,
+			})
+
+		if err := al.enqueueSteeringMessage(activeScope, activeAgentID, providers.Message{
+			Role:    "user",
+			Content: msg.Content,
+			Media:   append([]string(nil), msg.Media...),
+		}); err != nil {
+			logger.WarnCF("agent", "Failed to steer message, will be lost",
+				map[string]any{
+					"error":   err.Error(),
+					"channel": msg.Channel,
+				})
+		}
+	}
+}
+
 func (al *AgentLoop) Stop() {
 	al.running.Store(false)
 }
 
+func (al *AgentLoop) publishResponseIfNeeded(ctx context.Context, channel, chatID, response string) {
+	if response == "" {
+		return
+	}
+
+	alreadySent := false
+	defaultAgent := al.GetRegistry().GetDefaultAgent()
+	if defaultAgent != nil {
+		if tool, ok := defaultAgent.Tools.Get("message"); ok {
+			if mt, ok := tool.(*tools.MessageTool); ok {
+				alreadySent = mt.HasSentInRound()
+			}
+		}
+	}
+
+	if alreadySent {
+		logger.DebugCF(
+			"agent",
+			"Skipped outbound (message tool already sent)",
+			map[string]any{"channel": channel},
+		)
+		return
+	}
+
+	al.bus.PublishOutbound(ctx, bus.OutboundMessage{
+		Channel: channel,
+		ChatID:  chatID,
+		Content: response,
+	})
+	logger.InfoCF("agent", "Published outbound response",
+		map[string]any{
+			"channel":     channel,
+			"chat_id":     chatID,
+			"content_len": len(response),
+		})
+}
+
+func (al *AgentLoop) buildContinuationTarget(msg bus.InboundMessage) (*continuationTarget, error) {
+	if msg.Channel == "system" {
+		return nil, nil
+	}
+
+	route, _, err := al.resolveMessageRoute(msg)
+	if err != nil {
+		return nil, err
+	}
+
+	return &continuationTarget{
+		SessionKey: resolveScopeKey(route, msg.SessionKey),
+		Channel:    msg.Channel,
+		ChatID:     msg.ChatID,
+	}, nil
+}
+
+// Close releases resources held by agent session stores. Call after Stop.
+func (al *AgentLoop) Close() {
+	mcpManager := al.mcp.takeManager()
+
+	if mcpManager != nil {
+		if err := mcpManager.Close(); err != nil {
+			logger.ErrorCF("agent", "Failed to close MCP manager",
+				map[string]any{
+					"error": err.Error(),
+				})
+		}
+	}
+
+	al.GetRegistry().Close()
+	if al.hooks != nil {
+		al.hooks.Close()
+	}
+	if al.eventBus != nil {
+		al.eventBus.Close()
+	}
+}
+
+// MountHook registers an in-process hook on the agent loop.
+func (al *AgentLoop) MountHook(reg HookRegistration) error {
+	if al == nil || al.hooks == nil {
+		return fmt.Errorf("hook manager is not initialized")
+	}
+	return al.hooks.Mount(reg)
+}
+
+// UnmountHook removes a previously registered in-process hook.
+func (al *AgentLoop) UnmountHook(name string) {
+	if al == nil || al.hooks == nil {
+		return
+	}
+	al.hooks.Unmount(name)
+}
+
+// SubscribeEvents registers a subscriber for agent-loop events.
+func (al *AgentLoop) SubscribeEvents(buffer int) EventSubscription {
+	if al == nil || al.eventBus == nil {
+		ch := make(chan Event)
+		close(ch)
+		return EventSubscription{C: ch}
+	}
+	return al.eventBus.Subscribe(buffer)
+}
+
+// UnsubscribeEvents removes a previously registered event subscriber.
+func (al *AgentLoop) UnsubscribeEvents(id uint64) {
+	if al == nil || al.eventBus == nil {
+		return
+	}
+	al.eventBus.Unsubscribe(id)
+}
+
+// EventDrops returns the number of dropped events for the given kind.
+func (al *AgentLoop) EventDrops(kind EventKind) int64 {
+	if al == nil || al.eventBus == nil {
+		return 0
+	}
+	return al.eventBus.Dropped(kind)
+}
+
+type turnEventScope struct {
+	agentID    string
+	sessionKey string
+	turnID     string
+}
+
+func (al *AgentLoop) newTurnEventScope(agentID, sessionKey string) turnEventScope {
+	seq := al.turnSeq.Add(1)
+	return turnEventScope{
+		agentID:    agentID,
+		sessionKey: sessionKey,
+		turnID:     fmt.Sprintf("%s-turn-%d", agentID, seq),
+	}
+}
+
+func (ts turnEventScope) meta(iteration int, source, tracePath string) EventMeta {
+	return EventMeta{
+		AgentID:    ts.agentID,
+		TurnID:     ts.turnID,
+		SessionKey: ts.sessionKey,
+		Iteration:  iteration,
+		Source:     source,
+		TracePath:  tracePath,
+	}
+}
+
+func (al *AgentLoop) emitEvent(kind EventKind, meta EventMeta, payload any) {
+	evt := Event{
+		Kind:    kind,
+		Meta:    meta,
+		Payload: payload,
+	}
+
+	if al == nil || al.eventBus == nil {
+		return
+	}
+
+	al.logEvent(evt)
+
+	al.eventBus.Emit(evt)
+}
+
+func cloneEventArguments(args map[string]any) map[string]any {
+	if len(args) == 0 {
+		return nil
+	}
+
+	cloned := make(map[string]any, len(args))
+	for k, v := range args {
+		cloned[k] = v
+	}
+	return cloned
+}
+
+func (al *AgentLoop) hookAbortError(ts *turnState, stage string, decision HookDecision) error {
+	reason := decision.Reason
+	if reason == "" {
+		reason = "hook requested turn abort"
+	}
+
+	err := fmt.Errorf("hook aborted turn during %s: %s", stage, reason)
+	al.emitEvent(
+		EventKindError,
+		ts.eventMeta("hooks", "turn.error"),
+		ErrorPayload{
+			Stage:   "hook." + stage,
+			Message: err.Error(),
+		},
+	)
+	return err
+}
+
+func hookDeniedToolContent(prefix, reason string) string {
+	if reason == "" {
+		return prefix
+	}
+	return prefix + ": " + reason
+}
+
+func (al *AgentLoop) logEvent(evt Event) {
+	fields := map[string]any{
+		"event_kind":  evt.Kind.String(),
+		"agent_id":    evt.Meta.AgentID,
+		"turn_id":     evt.Meta.TurnID,
+		"session_key": evt.Meta.SessionKey,
+		"iteration":   evt.Meta.Iteration,
+	}
+
+	if evt.Meta.TracePath != "" {
+		fields["trace"] = evt.Meta.TracePath
+	}
+	if evt.Meta.Source != "" {
+		fields["source"] = evt.Meta.Source
+	}
+
+	switch payload := evt.Payload.(type) {
+	case TurnStartPayload:
+		fields["channel"] = payload.Channel
+		fields["chat_id"] = payload.ChatID
+		fields["user_len"] = len(payload.UserMessage)
+		fields["media_count"] = payload.MediaCount
+	case TurnEndPayload:
+		fields["status"] = payload.Status
+		fields["iterations_total"] = payload.Iterations
+		fields["duration_ms"] = payload.Duration.Milliseconds()
+		fields["final_len"] = payload.FinalContentLen
+	case LLMRequestPayload:
+		fields["model"] = payload.Model
+		fields["messages"] = payload.MessagesCount
+		fields["tools"] = payload.ToolsCount
+		fields["max_tokens"] = payload.MaxTokens
+	case LLMDeltaPayload:
+		fields["content_delta_len"] = payload.ContentDeltaLen
+		fields["reasoning_delta_len"] = payload.ReasoningDeltaLen
+	case LLMResponsePayload:
+		fields["content_len"] = payload.ContentLen
+		fields["tool_calls"] = payload.ToolCalls
+		fields["has_reasoning"] = payload.HasReasoning
+	case LLMRetryPayload:
+		fields["attempt"] = payload.Attempt
+		fields["max_retries"] = payload.MaxRetries
+		fields["reason"] = payload.Reason
+		fields["error"] = payload.Error
+		fields["backoff_ms"] = payload.Backoff.Milliseconds()
+	case ContextCompressPayload:
+		fields["reason"] = payload.Reason
+		fields["dropped_messages"] = payload.DroppedMessages
+		fields["remaining_messages"] = payload.RemainingMessages
+	case SessionSummarizePayload:
+		fields["summarized_messages"] = payload.SummarizedMessages
+		fields["kept_messages"] = payload.KeptMessages
+		fields["summary_len"] = payload.SummaryLen
+		fields["omitted_oversized"] = payload.OmittedOversized
+	case ToolExecStartPayload:
+		fields["tool"] = payload.Tool
+		fields["args_count"] = len(payload.Arguments)
+	case ToolExecEndPayload:
+		fields["tool"] = payload.Tool
+		fields["duration_ms"] = payload.Duration.Milliseconds()
+		fields["for_llm_len"] = payload.ForLLMLen
+		fields["for_user_len"] = payload.ForUserLen
+		fields["is_error"] = payload.IsError
+		fields["async"] = payload.Async
+	case ToolExecSkippedPayload:
+		fields["tool"] = payload.Tool
+		fields["reason"] = payload.Reason
+	case SteeringInjectedPayload:
+		fields["count"] = payload.Count
+		fields["total_content_len"] = payload.TotalContentLen
+	case FollowUpQueuedPayload:
+		fields["source_tool"] = payload.SourceTool
+		fields["channel"] = payload.Channel
+		fields["chat_id"] = payload.ChatID
+		fields["content_len"] = payload.ContentLen
+	case InterruptReceivedPayload:
+		fields["interrupt_kind"] = payload.Kind
+		fields["role"] = payload.Role
+		fields["content_len"] = payload.ContentLen
+		fields["queue_depth"] = payload.QueueDepth
+		fields["hint_len"] = payload.HintLen
+	case SubTurnSpawnPayload:
+		fields["child_agent_id"] = payload.AgentID
+		fields["label"] = payload.Label
+	case SubTurnEndPayload:
+		fields["child_agent_id"] = payload.AgentID
+		fields["status"] = payload.Status
+	case SubTurnResultDeliveredPayload:
+		fields["target_channel"] = payload.TargetChannel
+		fields["target_chat_id"] = payload.TargetChatID
+		fields["content_len"] = payload.ContentLen
+	case ErrorPayload:
+		fields["stage"] = payload.Stage
+		fields["error"] = payload.Message
+	}
+
+	logger.InfoCF("eventbus", fmt.Sprintf("Agent event: %s", evt.Kind.String()), fields)
+}
+
 func (al *AgentLoop) RegisterTool(tool tools.Tool) {
-	for _, agentID := range al.registry.ListAgentIDs() {
-		if agent, ok := al.registry.GetAgent(agentID); ok {
+	registry := al.GetRegistry()
+	for _, agentID := range registry.ListAgentIDs() {
+		if agent, ok := registry.GetAgent(agentID); ok {
 			agent.Tools.Register(tool)
 		}
 	}
@@ -257,9 +914,237 @@ func (al *AgentLoop) SetChannelManager(cm *channels.Manager) {
 	al.channelManager = cm
 }
 
+// ReloadProviderAndConfig atomically swaps the provider and config with proper synchronization.
+// It uses a context to allow timeout control from the caller.
+// Returns an error if the reload fails or context is canceled.
+func (al *AgentLoop) ReloadProviderAndConfig(
+	ctx context.Context,
+	provider providers.LLMProvider,
+	cfg *config.Config,
+) error {
+	// Validate inputs
+	if provider == nil {
+		return fmt.Errorf("provider cannot be nil")
+	}
+	if cfg == nil {
+		return fmt.Errorf("config cannot be nil")
+	}
+
+	// Create new registry with updated config and provider
+	// Wrap in defer/recover to handle any panics gracefully
+	var registry *AgentRegistry
+	var panicErr error
+	done := make(chan struct{}, 1)
+
+	go func() {
+		defer func() {
+			if r := recover(); r != nil {
+				panicErr = fmt.Errorf("panic during registry creation: %v", r)
+				logger.ErrorCF("agent", "Panic during registry creation",
+					map[string]any{"panic": r})
+			}
+			close(done)
+		}()
+
+		registry = NewAgentRegistry(cfg, provider)
+	}()
+
+	// Wait for completion or context cancellation
+	select {
+	case <-done:
+		if registry == nil {
+			if panicErr != nil {
+				return fmt.Errorf("registry creation failed: %w", panicErr)
+			}
+			return fmt.Errorf("registry creation failed (nil result)")
+		}
+	case <-ctx.Done():
+		return fmt.Errorf("context canceled during registry creation: %w", ctx.Err())
+	}
+
+	// Check context again before proceeding
+	if err := ctx.Err(); err != nil {
+		return fmt.Errorf("context canceled after registry creation: %w", err)
+	}
+
+	// Ensure shared tools are re-registered on the new registry
+	registerSharedTools(al, cfg, al.bus, registry, provider)
+
+	// Atomically swap the config and registry under write lock
+	// This ensures readers see a consistent pair
+	al.mu.Lock()
+	oldRegistry := al.registry
+
+	// Store new values
+	al.cfg = cfg
+	al.registry = registry
+
+	// Also update fallback chain with new config
+	al.fallback = providers.NewFallbackChain(providers.NewCooldownTracker())
+
+	al.mu.Unlock()
+
+	al.hookRuntime.reset(al)
+	configureHookManagerFromConfig(al.hooks, cfg)
+
+	// Close old provider after releasing the lock
+	// This prevents blocking readers while closing
+	if oldProvider, ok := extractProvider(oldRegistry); ok {
+		if stateful, ok := oldProvider.(providers.StatefulProvider); ok {
+			// Give in-flight requests a moment to complete
+			// Use a reasonable timeout that balances cleanup vs resource usage
+			select {
+			case <-time.After(100 * time.Millisecond):
+				stateful.Close()
+			case <-ctx.Done():
+				// Context canceled, close immediately but log warning
+				logger.WarnCF("agent", "Context canceled during provider cleanup, forcing close",
+					map[string]any{"error": ctx.Err()})
+				stateful.Close()
+			}
+		}
+	}
+
+	logger.InfoCF("agent", "Provider and config reloaded successfully",
+		map[string]any{
+			"model": cfg.Agents.Defaults.GetModelName(),
+		})
+
+	return nil
+}
+
+// GetRegistry returns the current registry (thread-safe)
+func (al *AgentLoop) GetRegistry() *AgentRegistry {
+	al.mu.RLock()
+	defer al.mu.RUnlock()
+	return al.registry
+}
+
+// GetConfig returns the current config (thread-safe)
+func (al *AgentLoop) GetConfig() *config.Config {
+	al.mu.RLock()
+	defer al.mu.RUnlock()
+	return al.cfg
+}
+
 // SetMediaStore injects a MediaStore for media lifecycle management.
 func (al *AgentLoop) SetMediaStore(s media.MediaStore) {
 	al.mediaStore = s
+
+	// Propagate store to all registered tools that can emit media.
+	registry := al.GetRegistry()
+	for _, agentID := range registry.ListAgentIDs() {
+		if agent, ok := registry.GetAgent(agentID); ok {
+			agent.Tools.SetMediaStore(s)
+		}
+	}
+}
+
+// SetTranscriber injects a voice transcriber for agent-level audio transcription.
+func (al *AgentLoop) SetTranscriber(t voice.Transcriber) {
+	al.transcriber = t
+}
+
+// SetReloadFunc sets the callback function for triggering config reload.
+func (al *AgentLoop) SetReloadFunc(fn func() error) {
+	al.reloadFunc = fn
+}
+
+var audioAnnotationRe = regexp.MustCompile(`\[(voice|audio)(?::[^\]]*)?\]`)
+
+// transcribeAudioInMessage resolves audio media refs, transcribes them, and
+// replaces audio annotations in msg.Content with the transcribed text.
+// Returns the (possibly modified) message and true if audio was transcribed.
+func (al *AgentLoop) transcribeAudioInMessage(ctx context.Context, msg bus.InboundMessage) (bus.InboundMessage, bool) {
+	if al.transcriber == nil || al.mediaStore == nil || len(msg.Media) == 0 {
+		return msg, false
+	}
+
+	// Transcribe each audio media ref in order.
+	var transcriptions []string
+	for _, ref := range msg.Media {
+		path, meta, err := al.mediaStore.ResolveWithMeta(ref)
+		if err != nil {
+			logger.WarnCF("voice", "Failed to resolve media ref", map[string]any{"ref": ref, "error": err})
+			continue
+		}
+		if !utils.IsAudioFile(meta.Filename, meta.ContentType) {
+			continue
+		}
+		result, err := al.transcriber.Transcribe(ctx, path)
+		if err != nil {
+			logger.WarnCF("voice", "Transcription failed", map[string]any{"ref": ref, "error": err})
+			transcriptions = append(transcriptions, "")
+			continue
+		}
+		transcriptions = append(transcriptions, result.Text)
+	}
+
+	if len(transcriptions) == 0 {
+		return msg, false
+	}
+
+	al.sendTranscriptionFeedback(ctx, msg.Channel, msg.ChatID, msg.MessageID, transcriptions)
+
+	// Replace audio annotations sequentially with transcriptions.
+	idx := 0
+	newContent := audioAnnotationRe.ReplaceAllStringFunc(msg.Content, func(match string) string {
+		if idx >= len(transcriptions) {
+			return match
+		}
+		text := transcriptions[idx]
+		idx++
+		return "[voice: " + text + "]"
+	})
+
+	// Append any remaining transcriptions not matched by an annotation.
+	for ; idx < len(transcriptions); idx++ {
+		newContent += "\n[voice: " + transcriptions[idx] + "]"
+	}
+
+	msg.Content = newContent
+	return msg, true
+}
+
+// sendTranscriptionFeedback sends feedback to the user with the result of
+// audio transcription if the option is enabled. It uses Manager.SendMessage
+// which executes synchronously (rate limiting, splitting, retry) so that
+// ordering with the subsequent placeholder is guaranteed.
+func (al *AgentLoop) sendTranscriptionFeedback(
+	ctx context.Context,
+	channel, chatID, messageID string,
+	validTexts []string,
+) {
+	if !al.cfg.Voice.EchoTranscription {
+		return
+	}
+	if al.channelManager == nil {
+		return
+	}
+
+	var nonEmpty []string
+	for _, t := range validTexts {
+		if t != "" {
+			nonEmpty = append(nonEmpty, t)
+		}
+	}
+
+	var feedbackMsg string
+	if len(nonEmpty) > 0 {
+		feedbackMsg = "Transcript: " + strings.Join(nonEmpty, "\n")
+	} else {
+		feedbackMsg = "No voice detected in the audio"
+	}
+
+	err := al.channelManager.SendMessage(ctx, bus.OutboundMessage{
+		Channel:          channel,
+		ChatID:           chatID,
+		Content:          feedbackMsg,
+		ReplyToMessageID: messageID,
+	})
+	if err != nil {
+		logger.WarnCF("voice", "Failed to send transcription feedback", map[string]any{"error": err.Error()})
+	}
 }
 
 // inferMediaType determines the media type ("image", "audio", "video", "file")
@@ -310,7 +1195,10 @@ func (al *AgentLoop) RecordLastChatID(chatID string) error {
 	return al.state.SetLastChatID(chatID)
 }
 
-func (al *AgentLoop) ProcessDirect(ctx context.Context, content, sessionKey string) (string, error) {
+func (al *AgentLoop) ProcessDirect(
+	ctx context.Context,
+	content, sessionKey string,
+) (string, error) {
 	return al.ProcessDirectWithChannel(ctx, content, sessionKey, "cli", "direct")
 }
 
@@ -318,6 +1206,13 @@ func (al *AgentLoop) ProcessDirectWithChannel(
 	ctx context.Context,
 	content, sessionKey, channel, chatID string,
 ) (string, error) {
+	if err := al.ensureHooksInitialized(ctx); err != nil {
+		return "", err
+	}
+	if err := al.ensureMCPInitialized(ctx); err != nil {
+		return "", err
+	}
+
 	msg := bus.InboundMessage{
 		Channel:    channel,
 		SenderID:   "cron",
@@ -331,8 +1226,18 @@ func (al *AgentLoop) ProcessDirectWithChannel(
 
 // ProcessHeartbeat processes a heartbeat request without session history.
 // Each heartbeat is independent and doesn't accumulate context.
-func (al *AgentLoop) ProcessHeartbeat(ctx context.Context, content, channel, chatID string) (string, error) {
-	agent := al.registry.GetDefaultAgent()
+func (al *AgentLoop) ProcessHeartbeat(
+	ctx context.Context,
+	content, channel, chatID string,
+) (string, error) {
+	if err := al.ensureHooksInitialized(ctx); err != nil {
+		return "", err
+	}
+	if err := al.ensureMCPInitialized(ctx); err != nil {
+		return "", err
+	}
+
+	agent := al.GetRegistry().GetDefaultAgent()
 	if agent == nil {
 		return "", fmt.Errorf("no default agent for heartbeat")
 	}
@@ -356,76 +1261,152 @@ func (al *AgentLoop) processMessage(ctx context.Context, msg bus.InboundMessage)
 	} else {
 		logContent = utils.Truncate(msg.Content, 80)
 	}
-	logger.InfoCF("agent", fmt.Sprintf("Processing message from %s:%s: %s", msg.Channel, msg.SenderID, logContent),
+	logger.InfoCF(
+		"agent",
+		fmt.Sprintf("Processing message from %s:%s: %s", msg.Channel, msg.SenderID, logContent),
 		map[string]any{
 			"channel":     msg.Channel,
 			"chat_id":     msg.ChatID,
 			"sender_id":   msg.SenderID,
 			"session_key": msg.SessionKey,
-		})
+		},
+	)
+
+	var hadAudio bool
+	msg, hadAudio = al.transcribeAudioInMessage(ctx, msg)
+
+	// For audio messages the placeholder was deferred by the channel.
+	// Now that transcription (and optional feedback) is done, send it.
+	if hadAudio && al.channelManager != nil {
+		al.channelManager.SendPlaceholder(ctx, msg.Channel, msg.ChatID)
+	}
 
 	// Route system messages to processSystemMessage
 	if msg.Channel == "system" {
 		return al.processSystemMessage(ctx, msg)
 	}
 
-	// Check for commands
-	if response, handled := al.handleCommand(ctx, msg); handled {
-		return response, nil
-	}
-
-	// Route to determine agent and session key
-	route := al.registry.ResolveRoute(routing.RouteInput{
-		Channel:    msg.Channel,
-		AccountID:  msg.Metadata["account_id"],
-		Peer:       extractPeer(msg),
-		ParentPeer: extractParentPeer(msg),
-		GuildID:    msg.Metadata["guild_id"],
-		TeamID:     msg.Metadata["team_id"],
-	})
-
-	agent, ok := al.registry.GetAgent(route.AgentID)
-	if !ok {
-		agent = al.registry.GetDefaultAgent()
-	}
-	if agent == nil {
-		return "", fmt.Errorf("no agent available for route (agent_id=%s)", route.AgentID)
+	route, agent, routeErr := al.resolveMessageRoute(msg)
+	if routeErr != nil {
+		return "", routeErr
 	}
 
 	// Reset message-tool state for this round so we don't skip publishing due to a previous round.
 	if tool, ok := agent.Tools.Get("message"); ok {
-		if mt, ok := tool.(tools.ContextualTool); ok {
-			mt.SetContext(msg.Channel, msg.ChatID)
+		if resetter, ok := tool.(interface{ ResetSentInRound() }); ok {
+			resetter.ResetSentInRound()
 		}
 	}
 
-	// Use routed session key, but honor pre-set agent-scoped keys (for ProcessDirect/cron)
-	sessionKey := route.SessionKey
-	if msg.SessionKey != "" && strings.HasPrefix(msg.SessionKey, "agent:") {
-		sessionKey = msg.SessionKey
-	}
+	// Resolve session key from route, while preserving explicit agent-scoped keys.
+	scopeKey := resolveScopeKey(route, msg.SessionKey)
+	sessionKey := scopeKey
 
 	logger.InfoCF("agent", "Routed message",
 		map[string]any{
-			"agent_id":    agent.ID,
-			"session_key": sessionKey,
-			"matched_by":  route.MatchedBy,
+			"agent_id":      agent.ID,
+			"scope_key":     scopeKey,
+			"session_key":   sessionKey,
+			"matched_by":    route.MatchedBy,
+			"route_agent":   route.AgentID,
+			"route_channel": route.Channel,
 		})
 
-	return al.runAgentLoop(ctx, agent, processOptions{
-		SessionKey:      sessionKey,
-		Channel:         msg.Channel,
-		ChatID:          msg.ChatID,
-		UserMessage:     msg.Content,
-		DefaultResponse: defaultResponse,
-		EnableSummary:   true,
-		SendResponse:    false,
+	opts := processOptions{
+		SessionKey:        sessionKey,
+		Channel:           msg.Channel,
+		ChatID:            msg.ChatID,
+		SenderID:          msg.SenderID,
+		SenderDisplayName: msg.Sender.DisplayName,
+		UserMessage:       msg.Content,
+		Media:             msg.Media,
+		DefaultResponse:   defaultResponse,
+		EnableSummary:     true,
+		SendResponse:      false,
+	}
+
+	// context-dependent commands check their own Runtime fields and report
+	// "unavailable" when the required capability is nil.
+	if response, handled := al.handleCommand(ctx, msg, agent, &opts); handled {
+		return response, nil
+	}
+
+	if pending := al.takePendingSkills(opts.SessionKey); len(pending) > 0 {
+		opts.ForcedSkills = append(opts.ForcedSkills, pending...)
+		logger.InfoCF("agent", "Applying pending skill override",
+			map[string]any{
+				"session_key": opts.SessionKey,
+				"skills":      strings.Join(pending, ","),
+			})
+	}
+
+	return al.runAgentLoop(ctx, agent, opts)
+}
+
+func (al *AgentLoop) resolveMessageRoute(msg bus.InboundMessage) (routing.ResolvedRoute, *AgentInstance, error) {
+	registry := al.GetRegistry()
+	route := registry.ResolveRoute(routing.RouteInput{
+		Channel:    msg.Channel,
+		AccountID:  inboundMetadata(msg, metadataKeyAccountID),
+		Peer:       extractPeer(msg),
+		ParentPeer: extractParentPeer(msg),
+		GuildID:    inboundMetadata(msg, metadataKeyGuildID),
+		TeamID:     inboundMetadata(msg, metadataKeyTeamID),
+	})
+
+	agent, ok := registry.GetAgent(route.AgentID)
+	if !ok {
+		agent = registry.GetDefaultAgent()
+	}
+	if agent == nil {
+		return routing.ResolvedRoute{}, nil, fmt.Errorf("no agent available for route (agent_id=%s)", route.AgentID)
+	}
+
+	return route, agent, nil
+}
+
+func resolveScopeKey(route routing.ResolvedRoute, msgSessionKey string) string {
+	if msgSessionKey != "" && strings.HasPrefix(msgSessionKey, sessionKeyAgentPrefix) {
+		return msgSessionKey
+	}
+	return route.SessionKey
+}
+
+func (al *AgentLoop) resolveSteeringTarget(msg bus.InboundMessage) (string, string, bool) {
+	if msg.Channel == "system" {
+		return "", "", false
+	}
+
+	route, agent, err := al.resolveMessageRoute(msg)
+	if err != nil || agent == nil {
+		return "", "", false
+	}
+
+	return resolveScopeKey(route, msg.SessionKey), agent.ID, true
+}
+
+func (al *AgentLoop) requeueInboundMessage(msg bus.InboundMessage) error {
+	if al.bus == nil {
+		return nil
+	}
+	pubCtx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	return al.bus.PublishOutbound(pubCtx, bus.OutboundMessage{
+		Channel: msg.Channel,
+		ChatID:  msg.ChatID,
+		Content: msg.Content,
 	})
 }
 
-func (al *AgentLoop) processSystemMessage(ctx context.Context, msg bus.InboundMessage) (string, error) {
+func (al *AgentLoop) processSystemMessage(
+	ctx context.Context,
+	msg bus.InboundMessage,
+) (string, error) {
 	if msg.Channel != "system" {
-		return "", fmt.Errorf("processSystemMessage called with non-system message channel: %s", msg.Channel)
+		return "", fmt.Errorf(
+			"processSystemMessage called with non-system message channel: %s",
+			msg.Channel,
+		)
 	}
 
 	logger.InfoCF("agent", "Processing system message",
@@ -463,7 +1444,7 @@ func (al *AgentLoop) processSystemMessage(ctx context.Context, msg bus.InboundMe
 	}
 
 	// Use default agent for system messages
-	agent := al.registry.GetDefaultAgent()
+	agent := al.GetRegistry().GetDefaultAgent()
 	if agent == nil {
 		return "", fmt.Errorf("no default agent for system message")
 	}
@@ -482,84 +1463,64 @@ func (al *AgentLoop) processSystemMessage(ctx context.Context, msg bus.InboundMe
 	})
 }
 
-// runAgentLoop is the core message processing logic.
-func (al *AgentLoop) runAgentLoop(ctx context.Context, agent *AgentInstance, opts processOptions) (string, error) {
-	// 0. Record last channel for heartbeat notifications (skip internal channels)
-	if opts.Channel != "" && opts.ChatID != "" {
-		// Don't record internal channels (cli, system, subagent)
-		if !constants.IsInternalChannel(opts.Channel) {
-			channelKey := fmt.Sprintf("%s:%s", opts.Channel, opts.ChatID)
-			if err := al.RecordLastChannel(channelKey); err != nil {
-				logger.WarnCF("agent", "Failed to record last channel", map[string]any{"error": err.Error()})
-			}
+// runAgentLoop remains the top-level shell that starts a turn and publishes
+// any post-turn work. runTurn owns the full turn lifecycle.
+func (al *AgentLoop) runAgentLoop(
+	ctx context.Context,
+	agent *AgentInstance,
+	opts processOptions,
+) (string, error) {
+	// Record last channel for heartbeat notifications (skip internal channels and cli)
+	if opts.Channel != "" && opts.ChatID != "" && !constants.IsInternalChannel(opts.Channel) {
+		channelKey := fmt.Sprintf("%s:%s", opts.Channel, opts.ChatID)
+		if err := al.RecordLastChannel(channelKey); err != nil {
+			logger.WarnCF(
+				"agent",
+				"Failed to record last channel",
+				map[string]any{"error": err.Error()},
+			)
 		}
 	}
 
-	// 1. Update tool contexts
-	al.updateToolContexts(agent, opts.Channel, opts.ChatID)
-
-	// 2. Build messages (skip history for heartbeat)
-	var history []providers.Message
-	var summary string
-	if !opts.NoHistory {
-		history = agent.Sessions.GetHistory(opts.SessionKey)
-		summary = agent.Sessions.GetSummary(opts.SessionKey)
-	}
-	messages := agent.ContextBuilder.BuildMessages(
-		history,
-		summary,
-		opts.UserMessage,
-		nil,
-		opts.Channel,
-		opts.ChatID,
-	)
-
-	// 3. Save user message to session
-	agent.Sessions.AddMessage(opts.SessionKey, "user", opts.UserMessage)
-
-	// 4. Run LLM iteration loop
-	finalContent, iteration, err := al.runLLMIteration(ctx, agent, messages, opts)
+	ts := newTurnState(agent, opts, al.newTurnEventScope(agent.ID, opts.SessionKey))
+	result, err := al.runTurn(ctx, ts)
 	if err != nil {
 		return "", err
 	}
-
-	// If last tool had ForUser content and we already sent it, we might not need to send final response
-	// This is controlled by the tool's Silent flag and ForUser content
-
-	// 5. Handle empty response
-	if finalContent == "" {
-		finalContent = opts.DefaultResponse
+	if result.status == TurnEndStatusAborted {
+		return "", nil
 	}
 
-	// 6. Save final assistant message to session
-	agent.Sessions.AddMessage(opts.SessionKey, "assistant", finalContent)
-	agent.Sessions.Save(opts.SessionKey)
-
-	// 7. Optional: summarization
-	if opts.EnableSummary {
-		al.maybeSummarize(agent, opts.SessionKey, opts.Channel, opts.ChatID)
+	for _, followUp := range result.followUps {
+		if pubErr := al.bus.PublishInbound(ctx, followUp); pubErr != nil {
+			logger.WarnCF("agent", "Failed to publish follow-up after turn",
+				map[string]any{
+					"turn_id": ts.turnID,
+					"error":   pubErr.Error(),
+				})
+		}
 	}
 
-	// 8. Optional: send response via bus
-	if opts.SendResponse {
+	if opts.SendResponse && result.finalContent != "" {
 		al.bus.PublishOutbound(ctx, bus.OutboundMessage{
 			Channel: opts.Channel,
 			ChatID:  opts.ChatID,
-			Content: finalContent,
+			Content: result.finalContent,
 		})
 	}
 
-	// 9. Log response
-	responsePreview := utils.Truncate(finalContent, 120)
-	logger.InfoCF("agent", fmt.Sprintf("Response: %s", responsePreview),
-		map[string]any{
-			"agent_id":     agent.ID,
-			"session_key":  opts.SessionKey,
-			"iterations":   iteration,
-			"final_length": len(finalContent),
-		})
+	if result.finalContent != "" {
+		responsePreview := utils.Truncate(result.finalContent, 120)
+		logger.InfoCF("agent", fmt.Sprintf("Response: %s", responsePreview),
+			map[string]any{
+				"agent_id":     agent.ID,
+				"session_key":  opts.SessionKey,
+				"iterations":   ts.currentIteration(),
+				"final_length": len(result.finalContent),
+			})
+	}
 
-	return finalContent, nil
+	return result.finalContent, nil
 }
 
 func (al *AgentLoop) targetReasoningChannelID(channelName string) (chatID string) {
@@ -572,7 +1533,10 @@ func (al *AgentLoop) targetReasoningChannelID(channelName string) (chatID string
 	return ""
 }
 
-func (al *AgentLoop) handleReasoning(ctx context.Context, reasoningContent, channelName, channelID string) {
+func (al *AgentLoop) handleReasoning(
+	ctx context.Context,
+	reasoningContent, channelName, channelID string,
+) {
 	if reasoningContent == "" || channelName == "" || channelID == "" {
 		return
 	}
@@ -615,100 +1579,372 @@ func (al *AgentLoop) handleReasoning(ctx context.Context, reasoningContent, chan
 	}
 }
 
-// runLLMIteration executes the LLM call loop with tool handling.
-func (al *AgentLoop) runLLMIteration(
-	ctx context.Context,
-	agent *AgentInstance,
-	messages []providers.Message,
-	opts processOptions,
-) (string, int, error) {
-	iteration := 0
+func (al *AgentLoop) runTurn(ctx context.Context, ts *turnState) (turnResult, error) {
+	turnCtx, turnCancel := context.WithCancel(ctx)
+	defer turnCancel()
+	ts.setTurnCancel(turnCancel)
+
+	// Inject turnState and AgentLoop into context so tools (e.g. spawn) can retrieve them.
+	turnCtx = withTurnState(turnCtx, ts)
+	turnCtx = WithAgentLoop(turnCtx, al)
+
+	al.registerActiveTurn(ts)
+	defer al.clearActiveTurn(ts)
+
+	turnStatus := TurnEndStatusCompleted
+	defer func() {
+		al.emitEvent(
+			EventKindTurnEnd,
+			ts.eventMeta("runTurn", "turn.end"),
+			TurnEndPayload{
+				Status:          turnStatus,
+				Iterations:      ts.currentIteration(),
+				Duration:        time.Since(ts.startedAt),
+				FinalContentLen: ts.finalContentLen(),
+			},
+		)
+	}()
+
+	al.emitEvent(
+		EventKindTurnStart,
+		ts.eventMeta("runTurn", "turn.start"),
+		TurnStartPayload{
+			Channel:     ts.channel,
+			ChatID:      ts.chatID,
+			UserMessage: ts.userMessage,
+			MediaCount:  len(ts.media),
+		},
+	)
+
+	var history []providers.Message
+	var summary string
+	if !ts.opts.NoHistory {
+		history = ts.agent.Sessions.GetHistory(ts.sessionKey)
+		summary = ts.agent.Sessions.GetSummary(ts.sessionKey)
+	}
+	ts.captureRestorePoint(history, summary)
+
+	messages := ts.agent.ContextBuilder.BuildMessages(
+		history,
+		summary,
+		ts.userMessage,
+		ts.media,
+		ts.channel,
+		ts.chatID,
+		ts.opts.SenderID,
+		ts.opts.SenderDisplayName,
+		activeSkillNames(ts.agent, ts.opts)...,
+	)
+
+	cfg := al.GetConfig()
+	maxMediaSize := cfg.Agents.Defaults.GetMaxMediaSize()
+	messages = resolveMediaRefs(messages, al.mediaStore, maxMediaSize)
+
+	if !ts.opts.NoHistory {
+		toolDefs := ts.agent.Tools.ToProviderDefs()
+		if isOverContextBudget(ts.agent.ContextWindow, messages, toolDefs, ts.agent.MaxTokens) {
+			logger.WarnCF("agent", "Proactive compression: context budget exceeded before LLM call",
+				map[string]any{"session_key": ts.sessionKey})
+			if compression, ok := al.forceCompression(ts.agent, ts.sessionKey); ok {
+				al.emitEvent(
+					EventKindContextCompress,
+					ts.eventMeta("runTurn", "turn.context.compress"),
+					ContextCompressPayload{
+						Reason:            ContextCompressReasonProactive,
+						DroppedMessages:   compression.DroppedMessages,
+						RemainingMessages: compression.RemainingMessages,
+					},
+				)
+				ts.refreshRestorePointFromSession(ts.agent)
+			}
+			newHistory := ts.agent.Sessions.GetHistory(ts.sessionKey)
+			newSummary := ts.agent.Sessions.GetSummary(ts.sessionKey)
+			messages = ts.agent.ContextBuilder.BuildMessages(
+				newHistory, newSummary, ts.userMessage,
+				ts.media, ts.channel, ts.chatID,
+				ts.opts.SenderID, ts.opts.SenderDisplayName,
+				activeSkillNames(ts.agent, ts.opts)...,
+			)
+			messages = resolveMediaRefs(messages, al.mediaStore, maxMediaSize)
+		}
+	}
+
+	// Save user message to session (from Incoming)
+	if !ts.opts.NoHistory && (strings.TrimSpace(ts.userMessage) != "" || len(ts.media) > 0) {
+		rootMsg := providers.Message{
+			Role:    "user",
+			Content: ts.userMessage,
+			Media:   append([]string(nil), ts.media...),
+		}
+		if len(rootMsg.Media) > 0 {
+			ts.agent.Sessions.AddFullMessage(ts.sessionKey, rootMsg)
+		} else {
+			ts.agent.Sessions.AddMessage(ts.sessionKey, rootMsg.Role, rootMsg.Content)
+		}
+		ts.recordPersistedMessage(rootMsg)
+	}
+
+	activeCandidates, activeModel := al.selectCandidates(ts.agent, ts.userMessage, messages)
+	pendingMessages := append([]providers.Message(nil), ts.opts.InitialSteeringMessages...)
 	var finalContent string
 
-	for iteration < agent.MaxIterations {
-		iteration++
+turnLoop:
+	for ts.currentIteration() < ts.agent.MaxIterations || len(pendingMessages) > 0 || func() bool {
+		graceful, _ := ts.gracefulInterruptRequested()
+		return graceful
+	}() {
+		if ts.hardAbortRequested() {
+			turnStatus = TurnEndStatusAborted
+			return al.abortTurn(ts)
+		}
+
+		iteration := ts.currentIteration() + 1
+		ts.setIteration(iteration)
+		ts.setPhase(TurnPhaseRunning)
+
+		if iteration > 1 {
+			if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 {
+				pendingMessages = append(pendingMessages, steerMsgs...)
+			}
+		} else if !ts.opts.SkipInitialSteeringPoll {
+			if steerMsgs := al.dequeueSteeringMessagesForScopeWithFallback(ts.sessionKey); len(steerMsgs) > 0 {
+				pendingMessages = append(pendingMessages, steerMsgs...)
+			}
+		}
+
+		// Check if parent turn has ended (SubTurn support from HEAD)
+		if ts.parentTurnState != nil && ts.IsParentEnded() {
+			if !ts.critical {
+				logger.InfoCF("agent", "Parent turn ended, non-critical SubTurn exiting gracefully", map[string]any{
+					"agent_id":  ts.agentID,
+					"iteration": iteration,
+					"turn_id":   ts.turnID,
+				})
+				break
+			}
+			logger.InfoCF("agent", "Parent turn ended, critical SubTurn continues running", map[string]any{
+				"agent_id":  ts.agentID,
+				"iteration": iteration,
+				"turn_id":   ts.turnID,
+			})
+		}
+
+		// Poll for pending SubTurn results (from HEAD)
+		if ts.pendingResults != nil {
+			select {
+			case result, ok := <-ts.pendingResults:
+				if ok && result != nil && result.ForLLM != "" {
+					content := al.cfg.FilterSensitiveData(result.ForLLM)
+					msg := providers.Message{Role: "user", Content: fmt.Sprintf("[SubTurn Result] %s", content)}
+					pendingMessages = append(pendingMessages, msg)
+				}
+			default:
+				// No results available
+			}
+		}
+
+		// Inject pending steering messages
+		if len(pendingMessages) > 0 {
+			resolvedPending := resolveMediaRefs(pendingMessages, al.mediaStore, maxMediaSize)
+			totalContentLen := 0
+			for i, pm := range pendingMessages {
+				messages = append(messages, resolvedPending[i])
+				totalContentLen += len(pm.Content)
+				if !ts.opts.NoHistory {
+					ts.agent.Sessions.AddFullMessage(ts.sessionKey, pm)
+					ts.recordPersistedMessage(pm)
+				}
+				logger.InfoCF("agent", "Injected steering message into context",
+					map[string]any{
+						"agent_id":    ts.agent.ID,
+						"iteration":   iteration,
+						"content_len": len(pm.Content),
+						"media_count": len(pm.Media),
+					})
+			}
+			al.emitEvent(
+				EventKindSteeringInjected,
+				ts.eventMeta("runTurn", "turn.steering.injected"),
+				SteeringInjectedPayload{
+					Count:           len(pendingMessages),
+					TotalContentLen: totalContentLen,
+				},
+			)
+			pendingMessages = nil
+		}
 
 		logger.DebugCF("agent", "LLM iteration",
 			map[string]any{
-				"agent_id":  agent.ID,
+				"agent_id":  ts.agent.ID,
 				"iteration": iteration,
-				"max":       agent.MaxIterations,
+				"max":       ts.agent.MaxIterations,
 			})
 
-		// Build tool definitions
-		providerToolDefs := agent.Tools.ToProviderDefs()
+		gracefulTerminal, _ := ts.gracefulInterruptRequested()
+		providerToolDefs := ts.agent.Tools.ToProviderDefs()
+
+		// Native web search support (from HEAD)
+		_, hasWebSearch := ts.agent.Tools.Get("web_search")
+		useNativeSearch := al.cfg.Tools.Web.PreferNative &&
+			hasWebSearch &&
+			func() bool {
+				// Check if provider supports native search
+				if ns, ok := ts.agent.Provider.(interface{ SupportsNativeSearch() bool }); ok {
+					return ns.SupportsNativeSearch()
+				}
+				return false
+			}()
+
+		if useNativeSearch {
+			// Filter out client-side web_search tool
+			filtered := make([]providers.ToolDefinition, 0, len(providerToolDefs))
+			for _, td := range providerToolDefs {
+				if td.Function.Name != "web_search" {
+					filtered = append(filtered, td)
+				}
+			}
+			providerToolDefs = filtered
+		}
+
+		callMessages := messages
+		if gracefulTerminal {
+			callMessages = append(append([]providers.Message(nil), messages...), ts.interruptHintMessage())
+			providerToolDefs = nil
+			ts.markGracefulTerminalUsed()
+		}
+
+		llmOpts := map[string]any{
+			"max_tokens":       ts.agent.MaxTokens,
+			"temperature":      ts.agent.Temperature,
+			"prompt_cache_key": ts.agent.ID,
+		}
+		if useNativeSearch {
+			llmOpts["native_search"] = true
+		}
+		if ts.agent.ThinkingLevel != ThinkingOff {
+			if tc, ok := ts.agent.Provider.(providers.ThinkingCapable); ok && tc.SupportsThinking() {
+				llmOpts["thinking_level"] = string(ts.agent.ThinkingLevel)
+			} else {
+				logger.WarnCF("agent", "thinking_level is set but current provider does not support it, ignoring",
+					map[string]any{"agent_id": ts.agent.ID, "thinking_level": string(ts.agent.ThinkingLevel)})
+			}
+		}
+
+		llmModel := activeModel
+		if al.hooks != nil {
+			llmReq, decision := al.hooks.BeforeLLM(turnCtx, &LLMHookRequest{
+				Meta:             ts.eventMeta("runTurn", "turn.llm.request"),
+				Model:            llmModel,
+				Messages:         callMessages,
+				Tools:            providerToolDefs,
+				Options:          llmOpts,
+				Channel:          ts.channel,
+				ChatID:           ts.chatID,
+				GracefulTerminal: gracefulTerminal,
+			})
+			switch decision.normalizedAction() {
+			case HookActionContinue, HookActionModify:
+				if llmReq != nil {
+					llmModel = llmReq.Model
+					callMessages = llmReq.Messages
+					providerToolDefs = llmReq.Tools
+					llmOpts = llmReq.Options
+				}
+			case HookActionAbortTurn:
+				turnStatus = TurnEndStatusError
+				return turnResult{}, al.hookAbortError(ts, "before_llm", decision)
+			case HookActionHardAbort:
+				_ = ts.requestHardAbort()
+				turnStatus = TurnEndStatusAborted
+				return al.abortTurn(ts)
+			}
+		}
+
+		al.emitEvent(
+			EventKindLLMRequest,
+			ts.eventMeta("runTurn", "turn.llm.request"),
+			LLMRequestPayload{
+				Model:         llmModel,
+				MessagesCount: len(callMessages),
+				ToolsCount:    len(providerToolDefs),
+				MaxTokens:     ts.agent.MaxTokens,
+				Temperature:   ts.agent.Temperature,
+			},
+		)
 
-		// Log LLM request details
 		logger.DebugCF("agent", "LLM request",
 			map[string]any{
-				"agent_id":          agent.ID,
+				"agent_id":          ts.agent.ID,
 				"iteration":         iteration,
-				"model":             agent.Model,
-				"messages_count":    len(messages),
+				"model":             llmModel,
+				"messages_count":    len(callMessages),
 				"tools_count":       len(providerToolDefs),
-				"max_tokens":        agent.MaxTokens,
-				"temperature":       agent.Temperature,
-				"system_prompt_len": len(messages[0].Content),
+				"max_tokens":        ts.agent.MaxTokens,
+				"temperature":       ts.agent.Temperature,
+				"system_prompt_len": len(callMessages[0].Content),
 			})
-
-		// Log full messages (detailed)
 		logger.DebugCF("agent", "Full LLM request",
 			map[string]any{
 				"iteration":     iteration,
-				"messages_json": formatMessagesForLog(messages),
+				"messages_json": formatMessagesForLog(callMessages),
 				"tools_json":    formatToolsForLog(providerToolDefs),
 			})
 
-		// Call LLM with fallback chain if candidates are configured.
-		var response *providers.LLMResponse
-		var err error
+		callLLM := func(messagesForCall []providers.Message, toolDefsForCall []providers.ToolDefinition) (*providers.LLMResponse, error) {
+			providerCtx, providerCancel := context.WithCancel(turnCtx)
+			ts.setProviderCancel(providerCancel)
+			defer func() {
+				providerCancel()
+				ts.clearProviderCancel(providerCancel)
+			}()
 
-		callLLM := func() (*providers.LLMResponse, error) {
-			if len(agent.Candidates) > 1 && al.fallback != nil {
-				fbResult, fbErr := al.fallback.Execute(ctx, agent.Candidates,
+			al.activeRequests.Add(1)
+			defer al.activeRequests.Done()
+
+			if len(activeCandidates) > 1 && al.fallback != nil {
+				fbResult, fbErr := al.fallback.Execute(
+					providerCtx,
+					activeCandidates,
 					func(ctx context.Context, provider, model string) (*providers.LLMResponse, error) {
-						return agent.Provider.Chat(ctx, messages, providerToolDefs, model, map[string]any{
-							"max_tokens":       agent.MaxTokens,
-							"temperature":      agent.Temperature,
-							"prompt_cache_key": agent.ID,
-						})
+						return ts.agent.Provider.Chat(ctx, messagesForCall, toolDefsForCall, model, llmOpts)
 					},
 				)
 				if fbErr != nil {
 					return nil, fbErr
 				}
 				if fbResult.Provider != "" && len(fbResult.Attempts) > 0 {
-					logger.InfoCF("agent", fmt.Sprintf("Fallback: succeeded with %s/%s after %d attempts",
-						fbResult.Provider, fbResult.Model, len(fbResult.Attempts)+1),
-						map[string]any{"agent_id": agent.ID, "iteration": iteration})
+					logger.InfoCF(
+						"agent",
+						fmt.Sprintf("Fallback: succeeded with %s/%s after %d attempts",
+							fbResult.Provider, fbResult.Model, len(fbResult.Attempts)+1),
+						map[string]any{"agent_id": ts.agent.ID, "iteration": iteration},
+					)
 				}
 				return fbResult.Response, nil
 			}
-			return agent.Provider.Chat(ctx, messages, providerToolDefs, agent.Model, map[string]any{
-				"max_tokens":       agent.MaxTokens,
-				"temperature":      agent.Temperature,
-				"prompt_cache_key": agent.ID,
-			})
+			return ts.agent.Provider.Chat(providerCtx, messagesForCall, toolDefsForCall, llmModel, llmOpts)
 		}
 
-		// Retry loop for context/token errors
+		var response *providers.LLMResponse
+		var err error
 		maxRetries := 2
 		for retry := 0; retry <= maxRetries; retry++ {
-			response, err = callLLM()
+			response, err = callLLM(callMessages, providerToolDefs)
 			if err == nil {
 				break
 			}
+			if ts.hardAbortRequested() && errors.Is(err, context.Canceled) {
+				turnStatus = TurnEndStatusAborted
+				return al.abortTurn(ts)
+			}
 
 			errMsg := strings.ToLower(err.Error())
-
-			// Check if this is a network/HTTP timeout — not a context window error.
 			isTimeoutError := errors.Is(err, context.DeadlineExceeded) ||
 				strings.Contains(errMsg, "deadline exceeded") ||
 				strings.Contains(errMsg, "client.timeout") ||
 				strings.Contains(errMsg, "timed out") ||
 				strings.Contains(errMsg, "timeout exceeded")
 
-			// Detect real context window / token limit errors, excluding network timeouts.
 			isContextError := !isTimeoutError && (strings.Contains(errMsg, "context_length_exceeded") ||
 				strings.Contains(errMsg, "context window") ||
 				strings.Contains(errMsg, "maximum context length") ||
@@ -721,69 +1957,192 @@ func (al *AgentLoop) runLLMIteration(
 
 			if isTimeoutError && retry < maxRetries {
 				backoff := time.Duration(retry+1) * 5 * time.Second
+				al.emitEvent(
+					EventKindLLMRetry,
+					ts.eventMeta("runTurn", "turn.llm.retry"),
+					LLMRetryPayload{
+						Attempt:    retry + 1,
+						MaxRetries: maxRetries,
+						Reason:     "timeout",
+						Error:      err.Error(),
+						Backoff:    backoff,
+					},
+				)
 				logger.WarnCF("agent", "Timeout error, retrying after backoff", map[string]any{
 					"error":   err.Error(),
 					"retry":   retry,
 					"backoff": backoff.String(),
 				})
-				time.Sleep(backoff)
+				if sleepErr := sleepWithContext(turnCtx, backoff); sleepErr != nil {
+					if ts.hardAbortRequested() {
+						turnStatus = TurnEndStatusAborted
+						return al.abortTurn(ts)
+					}
+					err = sleepErr
+					break
+				}
 				continue
 			}
 
-			if isContextError && retry < maxRetries {
-				logger.WarnCF("agent", "Context window error detected, attempting compression", map[string]any{
-					"error": err.Error(),
-					"retry": retry,
-				})
+			if isContextError && retry < maxRetries && !ts.opts.NoHistory {
+				al.emitEvent(
+					EventKindLLMRetry,
+					ts.eventMeta("runTurn", "turn.llm.retry"),
+					LLMRetryPayload{
+						Attempt:    retry + 1,
+						MaxRetries: maxRetries,
+						Reason:     "context_limit",
+						Error:      err.Error(),
+					},
+				)
+				logger.WarnCF(
+					"agent",
+					"Context window error detected, attempting compression",
+					map[string]any{
+						"error": err.Error(),
+						"retry": retry,
+					},
+				)
 
-				if retry == 0 && !constants.IsInternalChannel(opts.Channel) {
+				if retry == 0 && !constants.IsInternalChannel(ts.channel) {
 					al.bus.PublishOutbound(ctx, bus.OutboundMessage{
-						Channel: opts.Channel,
-						ChatID:  opts.ChatID,
+						Channel: ts.channel,
+						ChatID:  ts.chatID,
 						Content: "Context window exceeded. Compressing history and retrying...",
 					})
 				}
 
-				al.forceCompression(agent, opts.SessionKey)
-				newHistory := agent.Sessions.GetHistory(opts.SessionKey)
-				newSummary := agent.Sessions.GetSummary(opts.SessionKey)
-				messages = agent.ContextBuilder.BuildMessages(
+				if compression, ok := al.forceCompression(ts.agent, ts.sessionKey); ok {
+					al.emitEvent(
+						EventKindContextCompress,
+						ts.eventMeta("runTurn", "turn.context.compress"),
+						ContextCompressPayload{
+							Reason:            ContextCompressReasonRetry,
+							DroppedMessages:   compression.DroppedMessages,
+							RemainingMessages: compression.RemainingMessages,
+						},
+					)
+					ts.refreshRestorePointFromSession(ts.agent)
+				}
+
+				newHistory := ts.agent.Sessions.GetHistory(ts.sessionKey)
+				newSummary := ts.agent.Sessions.GetSummary(ts.sessionKey)
+				messages = ts.agent.ContextBuilder.BuildMessages(
 					newHistory, newSummary, "",
-					nil, opts.Channel, opts.ChatID,
+					nil, ts.channel, ts.chatID, ts.opts.SenderID, ts.opts.SenderDisplayName,
+					activeSkillNames(ts.agent, ts.opts)...,
 				)
+				callMessages = messages
+				if gracefulTerminal {
+					callMessages = append(append([]providers.Message(nil), messages...), ts.interruptHintMessage())
+				}
 				continue
 			}
 			break
 		}
 
 		if err != nil {
+			turnStatus = TurnEndStatusError
+			al.emitEvent(
+				EventKindError,
+				ts.eventMeta("runTurn", "turn.error"),
+				ErrorPayload{
+					Stage:   "llm",
+					Message: err.Error(),
+				},
+			)
 			logger.ErrorCF("agent", "LLM call failed",
 				map[string]any{
-					"agent_id":  agent.ID,
+					"agent_id":  ts.agent.ID,
 					"iteration": iteration,
+					"model":     llmModel,
 					"error":     err.Error(),
 				})
-			return "", iteration, fmt.Errorf("LLM call failed after retries: %w", err)
+			return turnResult{}, fmt.Errorf("LLM call failed after retries: %w", err)
 		}
 
-		go al.handleReasoning(ctx, response.Reasoning, opts.Channel, al.targetReasoningChannelID(opts.Channel))
+		if al.hooks != nil {
+			llmResp, decision := al.hooks.AfterLLM(turnCtx, &LLMHookResponse{
+				Meta:     ts.eventMeta("runTurn", "turn.llm.response"),
+				Model:    llmModel,
+				Response: response,
+				Channel:  ts.channel,
+				ChatID:   ts.chatID,
+			})
+			switch decision.normalizedAction() {
+			case HookActionContinue, HookActionModify:
+				if llmResp != nil && llmResp.Response != nil {
+					response = llmResp.Response
+				}
+			case HookActionAbortTurn:
+				turnStatus = TurnEndStatusError
+				return turnResult{}, al.hookAbortError(ts, "after_llm", decision)
+			case HookActionHardAbort:
+				_ = ts.requestHardAbort()
+				turnStatus = TurnEndStatusAborted
+				return al.abortTurn(ts)
+			}
+		}
+
+		// Save finishReason to turnState for SubTurn truncation detection
+		if innerTS := turnStateFromContext(ctx); innerTS != nil {
+			innerTS.SetLastFinishReason(response.FinishReason)
+			// Save usage for token budget tracking
+			if response.Usage != nil {
+				innerTS.SetLastUsage(response.Usage)
+			}
+		}
+
+		reasoningContent := response.Reasoning
+		if reasoningContent == "" {
+			reasoningContent = response.ReasoningContent
+		}
+		go al.handleReasoning(
+			turnCtx,
+			reasoningContent,
+			ts.channel,
+			al.targetReasoningChannelID(ts.channel),
+		)
+		al.emitEvent(
+			EventKindLLMResponse,
+			ts.eventMeta("runTurn", "turn.llm.response"),
+			LLMResponsePayload{
+				ContentLen:   len(response.Content),
+				ToolCalls:    len(response.ToolCalls),
+				HasReasoning: response.Reasoning != "" || response.ReasoningContent != "",
+			},
+		)
 
 		logger.DebugCF("agent", "LLM response",
 			map[string]any{
-				"agent_id":       agent.ID,
+				"agent_id":       ts.agent.ID,
 				"iteration":      iteration,
 				"content_chars":  len(response.Content),
 				"tool_calls":     len(response.ToolCalls),
 				"reasoning":      response.Reasoning,
-				"target_channel": al.targetReasoningChannelID(opts.Channel),
-				"channel":        opts.Channel,
+				"target_channel": al.targetReasoningChannelID(ts.channel),
+				"channel":        ts.channel,
 			})
-		// Check if no tool calls - we're done
-		if len(response.ToolCalls) == 0 {
-			finalContent = response.Content
+
+		if len(response.ToolCalls) == 0 || gracefulTerminal {
+			responseContent := response.Content
+			if responseContent == "" && response.ReasoningContent != "" {
+				responseContent = response.ReasoningContent
+			}
+			if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 {
+				logger.InfoCF("agent", "Steering arrived after direct LLM response; continuing turn",
+					map[string]any{
+						"agent_id":       ts.agent.ID,
+						"iteration":      iteration,
+						"steering_count": len(steerMsgs),
+					})
+				pendingMessages = append(pendingMessages, steerMsgs...)
+				continue
+			}
+			finalContent = responseContent
 			logger.InfoCF("agent", "LLM response without tool calls (direct answer)",
 				map[string]any{
-					"agent_id":      agent.ID,
+					"agent_id":      ts.agent.ID,
 					"iteration":     iteration,
 					"content_chars": len(finalContent),
 				})
@@ -795,20 +2154,19 @@ func (al *AgentLoop) runLLMIteration(
 			normalizedToolCalls = append(normalizedToolCalls, providers.NormalizeToolCall(tc))
 		}
 
-		// Log tool calls
 		toolNames := make([]string, 0, len(normalizedToolCalls))
 		for _, tc := range normalizedToolCalls {
 			toolNames = append(toolNames, tc.Name)
 		}
 		logger.InfoCF("agent", "LLM requested tool calls",
 			map[string]any{
-				"agent_id":  agent.ID,
+				"agent_id":  ts.agent.ID,
 				"tools":     toolNames,
 				"count":     len(normalizedToolCalls),
 				"iteration": iteration,
 			})
 
-		// Build assistant message with tool calls
+		allResponsesHandled := len(normalizedToolCalls) > 0
 		assistantMsg := providers.Message{
 			Role:             "assistant",
 			Content:          response.Content,
@@ -816,13 +2174,11 @@ func (al *AgentLoop) runLLMIteration(
 		}
 		for _, tc := range normalizedToolCalls {
 			argumentsJSON, _ := json.Marshal(tc.Arguments)
-			// Copy ExtraContent to ensure thought_signature is persisted for Gemini 3
 			extraContent := tc.ExtraContent
 			thoughtSignature := ""
 			if tc.Function != nil {
 				thoughtSignature = tc.Function.ThoughtSignature
 			}
-
 			assistantMsg.ToolCalls = append(assistantMsg.ToolCalls, providers.ToolCall{
 				ID:   tc.ID,
 				Type: "function",
@@ -837,66 +2193,238 @@ func (al *AgentLoop) runLLMIteration(
 			})
 		}
 		messages = append(messages, assistantMsg)
+		if !ts.opts.NoHistory {
+			ts.agent.Sessions.AddFullMessage(ts.sessionKey, assistantMsg)
+			ts.recordPersistedMessage(assistantMsg)
+		}
 
-		// Save assistant message with tool calls to session
-		agent.Sessions.AddFullMessage(opts.SessionKey, assistantMsg)
+		ts.setPhase(TurnPhaseTools)
+		for i, tc := range normalizedToolCalls {
+			if ts.hardAbortRequested() {
+				turnStatus = TurnEndStatusAborted
+				return al.abortTurn(ts)
+			}
 
-		// Execute tool calls
-		for _, tc := range normalizedToolCalls {
-			argsJSON, _ := json.Marshal(tc.Arguments)
-			argsPreview := utils.Truncate(string(argsJSON), 200)
-			logger.InfoCF("agent", fmt.Sprintf("Tool call: %s(%s)", tc.Name, argsPreview),
-				map[string]any{
-					"agent_id":  agent.ID,
-					"tool":      tc.Name,
-					"iteration": iteration,
+			toolName := tc.Name
+			toolArgs := cloneStringAnyMap(tc.Arguments)
+
+			if al.hooks != nil {
+				toolReq, decision := al.hooks.BeforeTool(turnCtx, &ToolCallHookRequest{
+					Meta:      ts.eventMeta("runTurn", "turn.tool.before"),
+					Tool:      toolName,
+					Arguments: toolArgs,
+					Channel:   ts.channel,
+					ChatID:    ts.chatID,
 				})
-
-			// Create async callback for tools that implement AsyncTool
-			// NOTE: Following openclaw's design, async tools do NOT send results directly to users.
-			// Instead, they notify the agent via PublishInbound, and the agent decides
-			// whether to forward the result to the user (in processSystemMessage).
-			asyncCallback := func(callbackCtx context.Context, result *tools.ToolResult) {
-				// Log the async completion but don't send directly to user
-				// The agent will handle user notification via processSystemMessage
-				if !result.Silent && result.ForUser != "" {
-					logger.InfoCF("agent", "Async tool completed, agent will handle notification",
-						map[string]any{
-							"tool":        tc.Name,
-							"content_len": len(result.ForUser),
-						})
+				switch decision.normalizedAction() {
+				case HookActionContinue, HookActionModify:
+					if toolReq != nil {
+						toolName = toolReq.Tool
+						toolArgs = toolReq.Arguments
+					}
+				case HookActionDenyTool:
+					allResponsesHandled = false
+					denyContent := hookDeniedToolContent("Tool execution denied by hook", decision.Reason)
+					al.emitEvent(
+						EventKindToolExecSkipped,
+						ts.eventMeta("runTurn", "turn.tool.skipped"),
+						ToolExecSkippedPayload{
+							Tool:   toolName,
+							Reason: denyContent,
+						},
+					)
+					deniedMsg := providers.Message{
+						Role:       "tool",
+						Content:    denyContent,
+						ToolCallID: tc.ID,
+					}
+					messages = append(messages, deniedMsg)
+					if !ts.opts.NoHistory {
+						ts.agent.Sessions.AddFullMessage(ts.sessionKey, deniedMsg)
+						ts.recordPersistedMessage(deniedMsg)
+					}
+					continue
+				case HookActionAbortTurn:
+					turnStatus = TurnEndStatusError
+					return turnResult{}, al.hookAbortError(ts, "before_tool", decision)
+				case HookActionHardAbort:
+					_ = ts.requestHardAbort()
+					turnStatus = TurnEndStatusAborted
+					return al.abortTurn(ts)
 				}
 			}
 
-			toolResult := agent.Tools.ExecuteWithContext(
-				ctx,
-				tc.Name,
-				tc.Arguments,
-				opts.Channel,
-				opts.ChatID,
-				asyncCallback,
-			)
-
-			// Send ForUser content to user immediately if not Silent
-			if !toolResult.Silent && toolResult.ForUser != "" && opts.SendResponse {
-				al.bus.PublishOutbound(ctx, bus.OutboundMessage{
-					Channel: opts.Channel,
-					ChatID:  opts.ChatID,
-					Content: toolResult.ForUser,
+			if al.hooks != nil {
+				approval := al.hooks.ApproveTool(turnCtx, &ToolApprovalRequest{
+					Meta:      ts.eventMeta("runTurn", "turn.tool.approve"),
+					Tool:      toolName,
+					Arguments: toolArgs,
+					Channel:   ts.channel,
+					ChatID:    ts.chatID,
 				})
-				logger.DebugCF("agent", "Sent tool result to user",
-					map[string]any{
-						"tool":        tc.Name,
-						"content_len": len(toolResult.ForUser),
-					})
+				if !approval.Approved {
+					allResponsesHandled = false
+					denyContent := hookDeniedToolContent("Tool execution denied by approval hook", approval.Reason)
+					al.emitEvent(
+						EventKindToolExecSkipped,
+						ts.eventMeta("runTurn", "turn.tool.skipped"),
+						ToolExecSkippedPayload{
+							Tool:   toolName,
+							Reason: denyContent,
+						},
+					)
+					deniedMsg := providers.Message{
+						Role:       "tool",
+						Content:    denyContent,
+						ToolCallID: tc.ID,
+					}
+					messages = append(messages, deniedMsg)
+					if !ts.opts.NoHistory {
+						ts.agent.Sessions.AddFullMessage(ts.sessionKey, deniedMsg)
+						ts.recordPersistedMessage(deniedMsg)
+					}
+					continue
+				}
 			}
 
-			// If tool returned media refs, publish them as outbound media
-			if len(toolResult.Media) > 0 && opts.SendResponse {
+			argsJSON, _ := json.Marshal(toolArgs)
+			argsPreview := utils.Truncate(string(argsJSON), 200)
+			logger.InfoCF("agent", fmt.Sprintf("Tool call: %s(%s)", toolName, argsPreview),
+				map[string]any{
+					"agent_id":  ts.agent.ID,
+					"tool":      toolName,
+					"iteration": iteration,
+				})
+			al.emitEvent(
+				EventKindToolExecStart,
+				ts.eventMeta("runTurn", "turn.tool.start"),
+				ToolExecStartPayload{
+					Tool:      toolName,
+					Arguments: cloneEventArguments(toolArgs),
+				},
+			)
+
+			// Send tool feedback to chat channel if enabled (from HEAD)
+			if al.cfg.Agents.Defaults.IsToolFeedbackEnabled() && ts.channel != "" {
+				feedbackPreview := utils.Truncate(
+					string(argsJSON),
+					al.cfg.Agents.Defaults.GetToolFeedbackMaxArgsLength(),
+				)
+				feedbackMsg := fmt.Sprintf("\U0001f527 `%s`\n```\n%s\n```", tc.Name, feedbackPreview)
+				fbCtx, fbCancel := context.WithTimeout(turnCtx, 3*time.Second)
+				_ = al.bus.PublishOutbound(fbCtx, bus.OutboundMessage{
+					Channel: ts.channel,
+					ChatID:  ts.chatID,
+					Content: feedbackMsg,
+				})
+				fbCancel()
+			}
+
+			toolCallID := tc.ID
+			toolIteration := iteration
+			asyncToolName := toolName
+			asyncCallback := func(_ context.Context, result *tools.ToolResult) {
+				// Send ForUser content directly to the user (immediate feedback),
+				// mirroring the synchronous tool execution path.
+				if !result.Silent && result.ForUser != "" {
+					outCtx, outCancel := context.WithTimeout(context.Background(), 5*time.Second)
+					defer outCancel()
+					_ = al.bus.PublishOutbound(outCtx, bus.OutboundMessage{
+						Channel: ts.channel,
+						ChatID:  ts.chatID,
+						Content: result.ForUser,
+					})
+				}
+
+				// Determine content for the agent loop (ForLLM or error).
+				content := result.ContentForLLM()
+				if content == "" {
+					return
+				}
+
+				// Filter sensitive data before publishing
+				content = al.cfg.FilterSensitiveData(content)
+
+				logger.InfoCF("agent", "Async tool completed, publishing result",
+					map[string]any{
+						"tool":        asyncToolName,
+						"content_len": len(content),
+						"channel":     ts.channel,
+					})
+				al.emitEvent(
+					EventKindFollowUpQueued,
+					ts.scope.meta(toolIteration, "runTurn", "turn.follow_up.queued"),
+					FollowUpQueuedPayload{
+						SourceTool: asyncToolName,
+						Channel:    ts.channel,
+						ChatID:     ts.chatID,
+						ContentLen: len(content),
+					},
+				)
+
+				pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+				defer pubCancel()
+				_ = al.bus.PublishInbound(pubCtx, bus.InboundMessage{
+					Channel:  "system",
+					SenderID: fmt.Sprintf("async:%s", asyncToolName),
+					ChatID:   fmt.Sprintf("%s:%s", ts.channel, ts.chatID),
+					Content:  content,
+				})
+			}
+
+			toolStart := time.Now()
+			toolResult := ts.agent.Tools.ExecuteWithContext(
+				turnCtx,
+				toolName,
+				toolArgs,
+				ts.channel,
+				ts.chatID,
+				asyncCallback,
+			)
+			toolDuration := time.Since(toolStart)
+
+			if ts.hardAbortRequested() {
+				turnStatus = TurnEndStatusAborted
+				return al.abortTurn(ts)
+			}
+
+			if al.hooks != nil {
+				toolResp, decision := al.hooks.AfterTool(turnCtx, &ToolResultHookResponse{
+					Meta:      ts.eventMeta("runTurn", "turn.tool.after"),
+					Tool:      toolName,
+					Arguments: toolArgs,
+					Result:    toolResult,
+					Duration:  toolDuration,
+					Channel:   ts.channel,
+					ChatID:    ts.chatID,
+				})
+				switch decision.normalizedAction() {
+				case HookActionContinue, HookActionModify:
+					if toolResp != nil {
+						if toolResp.Tool != "" {
+							toolName = toolResp.Tool
+						}
+						if toolResp.Result != nil {
+							toolResult = toolResp.Result
+						}
+					}
+				case HookActionAbortTurn:
+					turnStatus = TurnEndStatusError
+					return turnResult{}, al.hookAbortError(ts, "after_tool", decision)
+				case HookActionHardAbort:
+					_ = ts.requestHardAbort()
+					turnStatus = TurnEndStatusAborted
+					return al.abortTurn(ts)
+				}
+			}
+
+			if toolResult == nil {
+				toolResult = tools.ErrorResult("hook returned nil tool result")
+			}
+			if len(toolResult.Media) > 0 && toolResult.ResponseHandled {
 				parts := make([]bus.MediaPart, 0, len(toolResult.Media))
 				for _, ref := range toolResult.Media {
 					part := bus.MediaPart{Ref: ref}
-					// Populate metadata from MediaStore when available
 					if al.mediaStore != nil {
 						if _, meta, err := al.mediaStore.ResolveWithMeta(ref); err == nil {
 							part.Filename = meta.Filename
@@ -906,130 +2434,446 @@ func (al *AgentLoop) runLLMIteration(
 					}
 					parts = append(parts, part)
 				}
-				al.bus.PublishOutboundMedia(ctx, bus.OutboundMediaMessage{
-					Channel: opts.Channel,
-					ChatID:  opts.ChatID,
+				outboundMedia := bus.OutboundMediaMessage{
+					Channel: ts.channel,
+					ChatID:  ts.chatID,
 					Parts:   parts,
-				})
+				}
+				if al.channelManager != nil && ts.channel != "" && !constants.IsInternalChannel(ts.channel) {
+					if err := al.channelManager.SendMedia(ctx, outboundMedia); err != nil {
+						logger.WarnCF("agent", "Failed to deliver handled tool media",
+							map[string]any{
+								"agent_id": ts.agent.ID,
+								"tool":     toolName,
+								"channel":  ts.channel,
+								"chat_id":  ts.chatID,
+								"error":    err.Error(),
+							})
+						toolResult = tools.ErrorResult(fmt.Sprintf("failed to deliver attachment: %v", err)).WithError(err)
+					}
+				} else if al.bus != nil {
+					al.bus.PublishOutboundMedia(ctx, outboundMedia)
+					// Queuing media is only best-effort; it has not been delivered yet.
+					toolResult.ResponseHandled = false
+				}
 			}
 
-			// Determine content for LLM based on tool result
-			contentForLLM := toolResult.ForLLM
-			if contentForLLM == "" && toolResult.Err != nil {
-				contentForLLM = toolResult.Err.Error()
+			if len(toolResult.Media) > 0 && !toolResult.ResponseHandled {
+				toolResult.ArtifactTags = buildArtifactTags(al.mediaStore, toolResult.Media)
+			}
+
+			if !toolResult.ResponseHandled {
+				allResponsesHandled = false
+			}
+
+			if !toolResult.Silent && toolResult.ForUser != "" && ts.opts.SendResponse {
+				al.bus.PublishOutbound(ctx, bus.OutboundMessage{
+					Channel: ts.channel,
+					ChatID:  ts.chatID,
+					Content: toolResult.ForUser,
+				})
+				logger.DebugCF("agent", "Sent tool result to user",
+					map[string]any{
+						"tool":        toolName,
+						"content_len": len(toolResult.ForUser),
+					})
+			}
+
+			contentForLLM := toolResult.ContentForLLM()
+
+			// Filter sensitive data (API keys, tokens, secrets) before sending to LLM
+			if al.cfg.Tools.IsFilterSensitiveDataEnabled() {
+				contentForLLM = al.cfg.FilterSensitiveData(contentForLLM)
 			}
 
 			toolResultMsg := providers.Message{
 				Role:       "tool",
 				Content:    contentForLLM,
-				ToolCallID: tc.ID,
+				ToolCallID: toolCallID,
 			}
+			al.emitEvent(
+				EventKindToolExecEnd,
+				ts.eventMeta("runTurn", "turn.tool.end"),
+				ToolExecEndPayload{
+					Tool:       toolName,
+					Duration:   toolDuration,
+					ForLLMLen:  len(contentForLLM),
+					ForUserLen: len(toolResult.ForUser),
+					IsError:    toolResult.IsError,
+					Async:      toolResult.Async,
+				},
+			)
 			messages = append(messages, toolResultMsg)
+			if !ts.opts.NoHistory {
+				ts.agent.Sessions.AddFullMessage(ts.sessionKey, toolResultMsg)
+				ts.recordPersistedMessage(toolResultMsg)
+			}
 
-			// Save tool result message to session
-			agent.Sessions.AddFullMessage(opts.SessionKey, toolResultMsg)
+			if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 {
+				pendingMessages = append(pendingMessages, steerMsgs...)
+			}
+
+			skipReason := ""
+			skipMessage := ""
+			if len(pendingMessages) > 0 {
+				skipReason = "queued user steering message"
+				skipMessage = "Skipped due to queued user message."
+			} else if gracefulPending, _ := ts.gracefulInterruptRequested(); gracefulPending {
+				skipReason = "graceful interrupt requested"
+				skipMessage = "Skipped due to graceful interrupt."
+			}
+
+			if skipReason != "" {
+				remaining := len(normalizedToolCalls) - i - 1
+				if remaining > 0 {
+					logger.InfoCF("agent", "Turn checkpoint: skipping remaining tools",
+						map[string]any{
+							"agent_id":  ts.agent.ID,
+							"completed": i + 1,
+							"skipped":   remaining,
+							"reason":    skipReason,
+						})
+					for j := i + 1; j < len(normalizedToolCalls); j++ {
+						skippedTC := normalizedToolCalls[j]
+						al.emitEvent(
+							EventKindToolExecSkipped,
+							ts.eventMeta("runTurn", "turn.tool.skipped"),
+							ToolExecSkippedPayload{
+								Tool:   skippedTC.Name,
+								Reason: skipReason,
+							},
+						)
+						skippedMsg := providers.Message{
+							Role:       "tool",
+							Content:    skipMessage,
+							ToolCallID: skippedTC.ID,
+						}
+						messages = append(messages, skippedMsg)
+						if !ts.opts.NoHistory {
+							ts.agent.Sessions.AddFullMessage(ts.sessionKey, skippedMsg)
+							ts.recordPersistedMessage(skippedMsg)
+						}
+					}
+				}
+				break
+			}
+
+			// Also poll for any SubTurn results that arrived during tool execution.
+			if ts.pendingResults != nil {
+				select {
+				case result, ok := <-ts.pendingResults:
+					if ok && result != nil && result.ForLLM != "" {
+						content := al.cfg.FilterSensitiveData(result.ForLLM)
+						msg := providers.Message{Role: "user", Content: fmt.Sprintf("[SubTurn Result] %s", content)}
+						messages = append(messages, msg)
+						ts.agent.Sessions.AddFullMessage(ts.sessionKey, msg)
+					}
+				default:
+					// No results available
+				}
+			}
+		}
+
+		if allResponsesHandled {
+			if len(pendingMessages) > 0 {
+				logger.InfoCF("agent", "Pending steering exists after handled tool delivery; continuing turn before finalizing",
+					map[string]any{
+						"agent_id":       ts.agent.ID,
+						"steering_count": len(pendingMessages),
+						"session_key":    ts.sessionKey,
+					})
+				finalContent = ""
+				goto turnLoop
+			}
+
+			if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 {
+				logger.InfoCF("agent", "Steering arrived after handled tool delivery; continuing turn before finalizing",
+					map[string]any{
+						"agent_id":       ts.agent.ID,
+						"steering_count": len(steerMsgs),
+						"session_key":    ts.sessionKey,
+					})
+				pendingMessages = append(pendingMessages, steerMsgs...)
+				finalContent = ""
+				goto turnLoop
+			}
+
+			summaryMsg := providers.Message{
+				Role:    "assistant",
+				Content: handledToolResponseSummary,
+			}
+
+			if !ts.opts.NoHistory {
+				ts.agent.Sessions.AddMessage(ts.sessionKey, summaryMsg.Role, summaryMsg.Content)
+				ts.recordPersistedMessage(summaryMsg)
+				if err := ts.agent.Sessions.Save(ts.sessionKey); err != nil {
+					turnStatus = TurnEndStatusError
+					al.emitEvent(
+						EventKindError,
+						ts.eventMeta("runTurn", "turn.error"),
+						ErrorPayload{
+							Stage:   "session_save",
+							Message: err.Error(),
+						},
+					)
+					return turnResult{}, err
+				}
+			}
+			if ts.opts.EnableSummary {
+				al.maybeSummarize(ts.agent, ts.sessionKey, ts.scope)
+			}
+
+			ts.setPhase(TurnPhaseCompleted)
+			ts.setFinalContent("")
+			logger.InfoCF("agent", "Tool output satisfied delivery; ending turn without follow-up LLM",
+				map[string]any{
+					"agent_id":   ts.agent.ID,
+					"iteration":  iteration,
+					"tool_count": len(normalizedToolCalls),
+				})
+			return turnResult{
+				finalContent: "",
+				status:       turnStatus,
+				followUps:    append([]bus.InboundMessage(nil), ts.followUps...),
+			}, nil
+		}
+
+		ts.agent.Tools.TickTTL()
+		logger.DebugCF("agent", "TTL tick after tool execution", map[string]any{
+			"agent_id": ts.agent.ID, "iteration": iteration,
+		})
+	}
+
+	if steerMsgs := al.dequeueSteeringMessagesForScope(ts.sessionKey); len(steerMsgs) > 0 {
+		logger.InfoCF("agent", "Steering arrived after turn completion; continuing turn before finalizing",
+			map[string]any{
+				"agent_id":       ts.agent.ID,
+				"steering_count": len(steerMsgs),
+				"session_key":    ts.sessionKey,
+			})
+		pendingMessages = append(pendingMessages, steerMsgs...)
+		finalContent = ""
+		goto turnLoop
+	}
+
+	if ts.hardAbortRequested() {
+		turnStatus = TurnEndStatusAborted
+		return al.abortTurn(ts)
+	}
+
+	if finalContent == "" {
+		if ts.currentIteration() >= ts.agent.MaxIterations && ts.agent.MaxIterations > 0 {
+			finalContent = toolLimitResponse
+		} else {
+			finalContent = ts.opts.DefaultResponse
 		}
 	}
 
-	return finalContent, iteration, nil
+	ts.setPhase(TurnPhaseFinalizing)
+	ts.setFinalContent(finalContent)
+	if !ts.opts.NoHistory {
+		finalMsg := providers.Message{Role: "assistant", Content: finalContent}
+		ts.agent.Sessions.AddMessage(ts.sessionKey, finalMsg.Role, finalMsg.Content)
+		ts.recordPersistedMessage(finalMsg)
+		if err := ts.agent.Sessions.Save(ts.sessionKey); err != nil {
+			turnStatus = TurnEndStatusError
+			al.emitEvent(
+				EventKindError,
+				ts.eventMeta("runTurn", "turn.error"),
+				ErrorPayload{
+					Stage:   "session_save",
+					Message: err.Error(),
+				},
+			)
+			return turnResult{}, err
+		}
+	}
+
+	if ts.opts.EnableSummary {
+		al.maybeSummarize(ts.agent, ts.sessionKey, ts.scope)
+	}
+
+	ts.setPhase(TurnPhaseCompleted)
+	return turnResult{
+		finalContent: finalContent,
+		status:       turnStatus,
+		followUps:    append([]bus.InboundMessage(nil), ts.followUps...),
+	}, nil
 }
 
-// updateToolContexts updates the context for tools that need channel/chatID info.
-func (al *AgentLoop) updateToolContexts(agent *AgentInstance, channel, chatID string) {
-	// Use ContextualTool interface instead of type assertions
-	if tool, ok := agent.Tools.Get("message"); ok {
-		if mt, ok := tool.(tools.ContextualTool); ok {
-			mt.SetContext(channel, chatID)
+func (al *AgentLoop) abortTurn(ts *turnState) (turnResult, error) {
+	ts.setPhase(TurnPhaseAborted)
+	if !ts.opts.NoHistory {
+		if err := ts.restoreSession(ts.agent); err != nil {
+			al.emitEvent(
+				EventKindError,
+				ts.eventMeta("abortTurn", "turn.error"),
+				ErrorPayload{
+					Stage:   "session_restore",
+					Message: err.Error(),
+				},
+			)
+			return turnResult{}, err
 		}
 	}
-	if tool, ok := agent.Tools.Get("spawn"); ok {
-		if st, ok := tool.(tools.ContextualTool); ok {
-			st.SetContext(channel, chatID)
-		}
+	return turnResult{status: TurnEndStatusAborted}, nil
+}
+
+func sleepWithContext(ctx context.Context, d time.Duration) error {
+	timer := time.NewTimer(d)
+	defer timer.Stop()
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
 	}
-	if tool, ok := agent.Tools.Get("subagent"); ok {
-		if st, ok := tool.(tools.ContextualTool); ok {
-			st.SetContext(channel, chatID)
-		}
+}
+
+// selectCandidates returns the model candidates and resolved model name to use
+// for a conversation turn. When model routing is configured and the incoming
+// message scores below the complexity threshold, it returns the light model
+// candidates instead of the primary ones.
+//
+// The returned (candidates, model) pair is used for all LLM calls within one
+// turn — tool follow-up iterations use the same tier as the initial call so
+// that a multi-step tool chain doesn't switch models mid-way.
+func (al *AgentLoop) selectCandidates(
+	agent *AgentInstance,
+	userMsg string,
+	history []providers.Message,
+) (candidates []providers.FallbackCandidate, model string) {
+	if agent.Router == nil || len(agent.LightCandidates) == 0 {
+		return agent.Candidates, resolvedCandidateModel(agent.Candidates, agent.Model)
 	}
+
+	_, usedLight, score := agent.Router.SelectModel(userMsg, history, agent.Model)
+	if !usedLight {
+		logger.DebugCF("agent", "Model routing: primary model selected",
+			map[string]any{
+				"agent_id":  agent.ID,
+				"score":     score,
+				"threshold": agent.Router.Threshold(),
+			})
+		return agent.Candidates, resolvedCandidateModel(agent.Candidates, agent.Model)
+	}
+
+	logger.InfoCF("agent", "Model routing: light model selected",
+		map[string]any{
+			"agent_id":    agent.ID,
+			"light_model": agent.Router.LightModel(),
+			"score":       score,
+			"threshold":   agent.Router.Threshold(),
+		})
+	return agent.LightCandidates, resolvedCandidateModel(agent.LightCandidates, agent.Router.LightModel())
 }
 
 // maybeSummarize triggers summarization if the session history exceeds thresholds.
-func (al *AgentLoop) maybeSummarize(agent *AgentInstance, sessionKey, channel, chatID string) {
+func (al *AgentLoop) maybeSummarize(agent *AgentInstance, sessionKey string, turnScope turnEventScope) {
 	newHistory := agent.Sessions.GetHistory(sessionKey)
 	tokenEstimate := al.estimateTokens(newHistory)
-	threshold := agent.ContextWindow * 75 / 100
+	threshold := agent.ContextWindow * agent.SummarizeTokenPercent / 100
 
-	if len(newHistory) > 20 || tokenEstimate > threshold {
+	if len(newHistory) > agent.SummarizeMessageThreshold || tokenEstimate > threshold {
 		summarizeKey := agent.ID + ":" + sessionKey
 		if _, loading := al.summarizing.LoadOrStore(summarizeKey, true); !loading {
 			go func() {
 				defer al.summarizing.Delete(summarizeKey)
 				logger.Debug("Memory threshold reached. Optimizing conversation history...")
-				al.summarizeSession(agent, sessionKey)
+				al.summarizeSession(agent, sessionKey, turnScope)
 			}()
 		}
 	}
 }
 
+type compressionResult struct {
+	DroppedMessages   int
+	RemainingMessages int
+}
+
 // forceCompression aggressively reduces context when the limit is hit.
-// It drops the oldest 50% of messages (keeping system prompt and last user message).
-func (al *AgentLoop) forceCompression(agent *AgentInstance, sessionKey string) {
+// It drops the oldest ~50% of Turns (a Turn is a complete user→LLM→response
+// cycle, as defined in #1316), so tool-call sequences are never split.
+//
+// If the history is a single Turn with no safe split point, the function
+// falls back to keeping only the most recent user message. This breaks
+// Turn atomicity as a last resort to avoid a context-exceeded loop.
+//
+// Session history contains only user/assistant/tool messages — the system
+// prompt is built dynamically by BuildMessages and is NOT stored here.
+// The compression note is recorded in the session summary so that
+// BuildMessages can include it in the next system prompt.
+func (al *AgentLoop) forceCompression(agent *AgentInstance, sessionKey string) (compressionResult, bool) {
 	history := agent.Sessions.GetHistory(sessionKey)
-	if len(history) <= 4 {
-		return
+	if len(history) <= 2 {
+		return compressionResult{}, false
 	}
 
-	// Keep system prompt (usually [0]) and the very last message (user's trigger)
-	// We want to drop the oldest half of the *conversation*
-	// Assuming [0] is system, [1:] is conversation
-	conversation := history[1 : len(history)-1]
-	if len(conversation) == 0 {
-		return
+	// Split at a Turn boundary so no tool-call sequence is torn apart.
+	// parseTurnBoundaries gives us the start of each Turn; we drop the
+	// oldest half of Turns and keep the most recent ones.
+	turns := parseTurnBoundaries(history)
+	var mid int
+	if len(turns) >= 2 {
+		mid = turns[len(turns)/2]
+	} else {
+		// Fewer than 2 Turns — fall back to message-level midpoint
+		// aligned to the nearest Turn boundary.
+		mid = findSafeBoundary(history, len(history)/2)
+	}
+	var keptHistory []providers.Message
+	if mid <= 0 {
+		// No safe Turn boundary — the entire history is a single Turn
+		// (e.g. one user message followed by a massive tool response).
+		// Keeping everything would leave the agent stuck in a context-
+		// exceeded loop, so fall back to keeping only the most recent
+		// user message. This breaks Turn atomicity as a last resort.
+		for i := len(history) - 1; i >= 0; i-- {
+			if history[i].Role == "user" {
+				keptHistory = []providers.Message{history[i]}
+				break
+			}
+		}
+	} else {
+		keptHistory = history[mid:]
 	}
 
-	// Helper to find the mid-point of the conversation
-	mid := len(conversation) / 2
+	droppedCount := len(history) - len(keptHistory)
 
-	// New history structure:
-	// 1. System Prompt (with compression note appended)
-	// 2. Second half of conversation
-	// 3. Last message
-
-	droppedCount := mid
-	keptConversation := conversation[mid:]
-
-	newHistory := make([]providers.Message, 0, 1+len(keptConversation)+1)
-
-	// Append compression note to the original system prompt instead of adding a new system message
-	// This avoids having two consecutive system messages which some APIs (like Zhipu) reject
+	// Record compression in the session summary so BuildMessages includes it
+	// in the system prompt. We do not modify history messages themselves.
+	existingSummary := agent.Sessions.GetSummary(sessionKey)
 	compressionNote := fmt.Sprintf(
-		"\n\n[System Note: Emergency compression dropped %d oldest messages due to context limit]",
+		"[Emergency compression dropped %d oldest messages due to context limit]",
 		droppedCount,
 	)
-	enhancedSystemPrompt := history[0]
-	enhancedSystemPrompt.Content = enhancedSystemPrompt.Content + compressionNote
-	newHistory = append(newHistory, enhancedSystemPrompt)
+	if existingSummary != "" {
+		compressionNote = existingSummary + "\n\n" + compressionNote
+	}
+	agent.Sessions.SetSummary(sessionKey, compressionNote)
 
-	newHistory = append(newHistory, keptConversation...)
-	newHistory = append(newHistory, history[len(history)-1]) // Last message
-
-	// Update session
-	agent.Sessions.SetHistory(sessionKey, newHistory)
+	agent.Sessions.SetHistory(sessionKey, keptHistory)
 	agent.Sessions.Save(sessionKey)
 
 	logger.WarnCF("agent", "Forced compression executed", map[string]any{
 		"session_key":  sessionKey,
 		"dropped_msgs": droppedCount,
-		"new_count":    len(newHistory),
+		"new_count":    len(keptHistory),
 	})
+
+	return compressionResult{
+		DroppedMessages:   droppedCount,
+		RemainingMessages: len(keptHistory),
+	}, true
 }
 
 // GetStartupInfo returns information about loaded tools and skills for logging.
 func (al *AgentLoop) GetStartupInfo() map[string]any {
 	info := make(map[string]any)
 
-	agent := al.registry.GetDefaultAgent()
+	registry := al.GetRegistry()
+	agent := registry.GetDefaultAgent()
 	if agent == nil {
 		return info
 	}
@@ -1046,8 +2890,8 @@ func (al *AgentLoop) GetStartupInfo() map[string]any {
 
 	// Agents info
 	info["agents"] = map[string]any{
-		"count": len(al.registry.ListAgentIDs()),
-		"ids":   al.registry.ListAgentIDs(),
+		"count": len(registry.ListAgentIDs()),
+		"ids":   registry.ListAgentIDs(),
 	}
 
 	return info
@@ -1068,7 +2912,11 @@ func formatMessagesForLog(messages []providers.Message) string {
 			for _, tc := range msg.ToolCalls {
 				fmt.Fprintf(&sb, "    - ID: %s, Type: %s, Name: %s\n", tc.ID, tc.Type, tc.Name)
 				if tc.Function != nil {
-					fmt.Fprintf(&sb, "      Arguments: %s\n", utils.Truncate(tc.Function.Arguments, 200))
+					fmt.Fprintf(
+						&sb,
+						"      Arguments: %s\n",
+						utils.Truncate(tc.Function.Arguments, 200),
+					)
 				}
 			}
 		}
@@ -1097,7 +2945,11 @@ func formatToolsForLog(toolDefs []providers.ToolDefinition) string {
 		fmt.Fprintf(&sb, "  [%d] Type: %s, Name: %s\n", i, tool.Type, tool.Function.Name)
 		fmt.Fprintf(&sb, "      Description: %s\n", tool.Function.Description)
 		if len(tool.Function.Parameters) > 0 {
-			fmt.Fprintf(&sb, "      Parameters: %s\n", utils.Truncate(fmt.Sprintf("%v", tool.Function.Parameters), 200))
+			fmt.Fprintf(
+				&sb,
+				"      Parameters: %s\n",
+				utils.Truncate(fmt.Sprintf("%v", tool.Function.Parameters), 200),
+			)
 		}
 	}
 	sb.WriteString("]")
@@ -1105,19 +2957,25 @@ func formatToolsForLog(toolDefs []providers.ToolDefinition) string {
 }
 
 // summarizeSession summarizes the conversation history for a session.
-func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string) {
+func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string, turnScope turnEventScope) {
 	ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
 	defer cancel()
 
 	history := agent.Sessions.GetHistory(sessionKey)
 	summary := agent.Sessions.GetSummary(sessionKey)
 
-	// Keep last 4 messages for continuity
+	// Keep the most recent Turns for continuity, aligned to a Turn boundary
+	// so that no tool-call sequence is split.
 	if len(history) <= 4 {
 		return
 	}
 
-	toSummarize := history[:len(history)-4]
+	safeCut := findSafeBoundary(history, len(history)-4)
+	if safeCut <= 0 {
+		return
+	}
+	keepCount := len(history) - safeCut
+	toSummarize := history[:safeCut]
 
 	// Oversized Message Guard
 	maxMessageTokens := agent.ContextWindow / 2
@@ -1140,10 +2998,20 @@ func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string) {
 		return
 	}
 
+	const (
+		maxSummarizationMessages = 10
+		llmMaxRetries            = 3
+		llmTemperature           = 0.3
+		fallbackMaxContentLength = 200
+	)
+
 	// Multi-Part Summarization
 	var finalSummary string
-	if len(validMessages) > 10 {
+	if len(validMessages) > maxSummarizationMessages {
 		mid := len(validMessages) / 2
+
+		mid = al.findNearestUserMessage(validMessages, mid)
+
 		part1 := validMessages[:mid]
 		part2 := validMessages[mid:]
 
@@ -1155,18 +3023,9 @@ func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string) {
 			s1,
 			s2,
 		)
-		resp, err := agent.Provider.Chat(
-			ctx,
-			[]providers.Message{{Role: "user", Content: mergePrompt}},
-			nil,
-			agent.Model,
-			map[string]any{
-				"max_tokens":       1024,
-				"temperature":      0.3,
-				"prompt_cache_key": agent.ID,
-			},
-		)
-		if err == nil {
+
+		resp, err := al.retryLLMCall(ctx, agent, mergePrompt, llmMaxRetries)
+		if err == nil && resp.Content != "" {
 			finalSummary = resp.Content
 		} else {
 			finalSummary = s1 + " " + s2
@@ -1181,11 +3040,88 @@ func (al *AgentLoop) summarizeSession(agent *AgentInstance, sessionKey string) {
 
 	if finalSummary != "" {
 		agent.Sessions.SetSummary(sessionKey, finalSummary)
-		agent.Sessions.TruncateHistory(sessionKey, 4)
+		agent.Sessions.TruncateHistory(sessionKey, keepCount)
 		agent.Sessions.Save(sessionKey)
+		al.emitEvent(
+			EventKindSessionSummarize,
+			turnScope.meta(0, "summarizeSession", "turn.session.summarize"),
+			SessionSummarizePayload{
+				SummarizedMessages: len(validMessages),
+				KeptMessages:       keepCount,
+				SummaryLen:         len(finalSummary),
+				OmittedOversized:   omitted,
+			},
+		)
 	}
 }
 
+// findNearestUserMessage finds the nearest user message to the given index.
+// It searches backward first, then forward if no user message is found.
+func (al *AgentLoop) findNearestUserMessage(messages []providers.Message, mid int) int {
+	originalMid := mid
+
+	for mid > 0 && messages[mid].Role != "user" {
+		mid--
+	}
+
+	if messages[mid].Role == "user" {
+		return mid
+	}
+
+	mid = originalMid
+	for mid < len(messages) && messages[mid].Role != "user" {
+		mid++
+	}
+
+	if mid < len(messages) {
+		return mid
+	}
+
+	return originalMid
+}
+
+// retryLLMCall calls the LLM with retry logic.
+func (al *AgentLoop) retryLLMCall(
+	ctx context.Context,
+	agent *AgentInstance,
+	prompt string,
+	maxRetries int,
+) (*providers.LLMResponse, error) {
+	const (
+		llmTemperature = 0.3
+	)
+
+	var resp *providers.LLMResponse
+	var err error
+
+	for attempt := 0; attempt < maxRetries; attempt++ {
+		al.activeRequests.Add(1)
+		resp, err = func() (*providers.LLMResponse, error) {
+			defer al.activeRequests.Done()
+			return agent.Provider.Chat(
+				ctx,
+				[]providers.Message{{Role: "user", Content: prompt}},
+				nil,
+				agent.Model,
+				map[string]any{
+					"max_tokens":       agent.MaxTokens,
+					"temperature":      llmTemperature,
+					"prompt_cache_key": agent.ID,
+				},
+			)
+		}()
+
+		if err == nil && resp != nil && resp.Content != "" {
+			return resp, nil
+		}
+		if attempt < maxRetries-1 {
+			time.Sleep(time.Duration(attempt+1) * 100 * time.Millisecond)
+		}
+	}
+
+	return resp, err
+}
+
 // summarizeBatch summarizes a batch of messages.
 func (al *AgentLoop) summarizeBatch(
 	ctx context.Context,
@@ -1193,8 +3129,17 @@ func (al *AgentLoop) summarizeBatch(
 	batch []providers.Message,
 	existingSummary string,
 ) (string, error) {
+	const (
+		llmMaxRetries             = 3
+		llmTemperature            = 0.3
+		fallbackMinContentLength  = 200
+		fallbackMaxContentPercent = 10
+	)
+
 	var sb strings.Builder
-	sb.WriteString("Provide a concise summary of this conversation segment, preserving core context and key points.\n")
+	sb.WriteString(
+		"Provide a concise summary of this conversation segment, preserving core context and key points.\n",
+	)
 	if existingSummary != "" {
 		sb.WriteString("Existing context: ")
 		sb.WriteString(existingSummary)
@@ -1206,123 +3151,358 @@ func (al *AgentLoop) summarizeBatch(
 	}
 	prompt := sb.String()
 
-	response, err := agent.Provider.Chat(
-		ctx,
-		[]providers.Message{{Role: "user", Content: prompt}},
-		nil,
-		agent.Model,
-		map[string]any{
-			"max_tokens":       1024,
-			"temperature":      0.3,
-			"prompt_cache_key": agent.ID,
-		},
-	)
-	if err != nil {
-		return "", err
+	response, err := al.retryLLMCall(ctx, agent, prompt, llmMaxRetries)
+	if err == nil && response.Content != "" {
+		return strings.TrimSpace(response.Content), nil
 	}
-	return response.Content, nil
+
+	var fallback strings.Builder
+	fallback.WriteString("Conversation summary: ")
+	for i, m := range batch {
+		if i > 0 {
+			fallback.WriteString(" | ")
+		}
+		content := strings.TrimSpace(m.Content)
+		runes := []rune(content)
+		if len(runes) == 0 {
+			fallback.WriteString(fmt.Sprintf("%s: ", m.Role))
+			continue
+		}
+
+		keepLength := len(runes) * fallbackMaxContentPercent / 100
+		if keepLength < fallbackMinContentLength {
+			keepLength = fallbackMinContentLength
+		}
+
+		if keepLength > len(runes) {
+			keepLength = len(runes)
+		}
+
+		content = string(runes[:keepLength])
+		if keepLength < len(runes) {
+			content += "..."
+		}
+		fallback.WriteString(fmt.Sprintf("%s: %s", m.Role, content))
+	}
+	return fallback.String(), nil
 }
 
 // estimateTokens estimates the number of tokens in a message list.
-// Uses a safe heuristic of 2.5 characters per token to account for CJK and other
-// overheads better than the previous 3 chars/token.
+// Counts Content, ToolCalls arguments, and ToolCallID metadata so that
+// tool-heavy conversations are not systematically undercounted.
 func (al *AgentLoop) estimateTokens(messages []providers.Message) int {
-	totalChars := 0
+	total := 0
 	for _, m := range messages {
-		totalChars += utf8.RuneCountInString(m.Content)
+		total += estimateMessageTokens(m)
 	}
-	// 2.5 chars per token = totalChars * 2 / 5
-	return totalChars * 2 / 5
+	return total
 }
 
-func (al *AgentLoop) handleCommand(ctx context.Context, msg bus.InboundMessage) (string, bool) {
-	content := strings.TrimSpace(msg.Content)
-	if !strings.HasPrefix(content, "/") {
+func (al *AgentLoop) handleCommand(
+	ctx context.Context,
+	msg bus.InboundMessage,
+	agent *AgentInstance,
+	opts *processOptions,
+) (string, bool) {
+	if !commands.HasCommandPrefix(msg.Content) {
 		return "", false
 	}
 
-	parts := strings.Fields(content)
-	if len(parts) == 0 {
+	if matched, handled, reply := al.applyExplicitSkillCommand(msg.Content, agent, opts); matched {
+		return reply, handled
+	}
+
+	if al.cmdRegistry == nil {
 		return "", false
 	}
 
-	cmd := parts[0]
-	args := parts[1:]
+	rt := al.buildCommandsRuntime(agent, opts)
+	executor := commands.NewExecutor(al.cmdRegistry, rt)
 
-	switch cmd {
-	case "/show":
-		if len(args) < 1 {
-			return "Usage: /show [model|channel|agents]", true
+	var commandReply string
+	result := executor.Execute(ctx, commands.Request{
+		Channel:  msg.Channel,
+		ChatID:   msg.ChatID,
+		SenderID: msg.SenderID,
+		Text:     msg.Content,
+		Reply: func(text string) error {
+			commandReply = text
+			return nil
+		},
+	})
+
+	switch result.Outcome {
+	case commands.OutcomeHandled:
+		if result.Err != nil {
+			return mapCommandError(result), true
 		}
-		switch args[0] {
-		case "model":
-			defaultAgent := al.registry.GetDefaultAgent()
-			if defaultAgent == nil {
-				return "No default agent configured", true
+		if commandReply != "" {
+			return commandReply, true
+		}
+		return "", true
+	default: // OutcomePassthrough — let the message fall through to LLM
+		return "", false
+	}
+}
+
+func activeSkillNames(agent *AgentInstance, opts processOptions) []string {
+	if agent == nil {
+		return nil
+	}
+
+	combined := make([]string, 0, len(agent.SkillsFilter)+len(opts.ForcedSkills))
+	combined = append(combined, agent.SkillsFilter...)
+	combined = append(combined, opts.ForcedSkills...)
+	if len(combined) == 0 {
+		return nil
+	}
+
+	var resolved []string
+	seen := make(map[string]struct{}, len(combined))
+	for _, name := range combined {
+		name = strings.TrimSpace(name)
+		if name == "" {
+			continue
+		}
+		if agent.ContextBuilder != nil {
+			if canonical, ok := agent.ContextBuilder.ResolveSkillName(name); ok {
+				name = canonical
 			}
-			return fmt.Sprintf("Current model: %s", defaultAgent.Model), true
-		case "channel":
-			return fmt.Sprintf("Current channel: %s", msg.Channel), true
-		case "agents":
-			agentIDs := al.registry.ListAgentIDs()
-			return fmt.Sprintf("Registered agents: %s", strings.Join(agentIDs, ", ")), true
-		default:
-			return fmt.Sprintf("Unknown show target: %s", args[0]), true
 		}
+		key := strings.ToLower(name)
+		if _, ok := seen[key]; ok {
+			continue
+		}
+		seen[key] = struct{}{}
+		resolved = append(resolved, name)
+	}
 
-	case "/list":
-		if len(args) < 1 {
-			return "Usage: /list [models|channels|agents]", true
+	return resolved
+}
+
+func (al *AgentLoop) applyExplicitSkillCommand(
+	raw string,
+	agent *AgentInstance,
+	opts *processOptions,
+) (matched bool, handled bool, reply string) {
+	cmdName, ok := commands.CommandName(raw)
+	if !ok || cmdName != "use" {
+		return false, false, ""
+	}
+
+	if agent == nil || agent.ContextBuilder == nil {
+		return true, true, commandsUnavailableSkillMessage()
+	}
+
+	parts := strings.Fields(strings.TrimSpace(raw))
+	if len(parts) < 2 {
+		return true, true, buildUseCommandHelp(agent)
+	}
+
+	arg := strings.TrimSpace(parts[1])
+	if strings.EqualFold(arg, "clear") || strings.EqualFold(arg, "off") {
+		if opts != nil {
+			al.clearPendingSkills(opts.SessionKey)
 		}
-		switch args[0] {
-		case "models":
-			return "Available models: configured in config.json per agent", true
-		case "channels":
+		return true, true, "Cleared pending skill override."
+	}
+
+	skillName, ok := agent.ContextBuilder.ResolveSkillName(arg)
+	if !ok {
+		return true, true, fmt.Sprintf("Unknown skill: %s\nUse /list skills to see installed skills.", arg)
+	}
+
+	if len(parts) < 3 {
+		if opts == nil || strings.TrimSpace(opts.SessionKey) == "" {
+			return true, true, commandsUnavailableSkillMessage()
+		}
+		al.setPendingSkills(opts.SessionKey, []string{skillName})
+		return true, true, fmt.Sprintf(
+			"Skill %q is armed for your next message. Send your next prompt normally, or use /use clear to cancel.",
+			skillName,
+		)
+	}
+
+	message := strings.TrimSpace(strings.Join(parts[2:], " "))
+	if message == "" {
+		return true, true, buildUseCommandHelp(agent)
+	}
+
+	if opts != nil {
+		opts.ForcedSkills = append(opts.ForcedSkills, skillName)
+		opts.UserMessage = message
+	}
+
+	return true, false, ""
+}
+
+func (al *AgentLoop) buildCommandsRuntime(agent *AgentInstance, opts *processOptions) *commands.Runtime {
+	registry := al.GetRegistry()
+	cfg := al.GetConfig()
+	rt := &commands.Runtime{
+		Config:          cfg,
+		ListAgentIDs:    registry.ListAgentIDs,
+		ListDefinitions: al.cmdRegistry.Definitions,
+		GetEnabledChannels: func() []string {
 			if al.channelManager == nil {
-				return "Channel manager not initialized", true
+				return nil
 			}
-			channels := al.channelManager.GetEnabledChannels()
-			if len(channels) == 0 {
-				return "No channels enabled", true
+			return al.channelManager.GetEnabledChannels()
+		},
+		GetActiveTurn: func() any {
+			info := al.GetActiveTurn()
+			if info == nil {
+				return nil
 			}
-			return fmt.Sprintf("Enabled channels: %s", strings.Join(channels, ", ")), true
-		case "agents":
-			agentIDs := al.registry.ListAgentIDs()
-			return fmt.Sprintf("Registered agents: %s", strings.Join(agentIDs, ", ")), true
-		default:
-			return fmt.Sprintf("Unknown list target: %s", args[0]), true
-		}
-
-	case "/switch":
-		if len(args) < 3 || args[1] != "to" {
-			return "Usage: /switch [model|channel] to <name>", true
-		}
-		target := args[0]
-		value := args[2]
-
-		switch target {
-		case "model":
-			defaultAgent := al.registry.GetDefaultAgent()
-			if defaultAgent == nil {
-				return "No default agent configured", true
-			}
-			oldModel := defaultAgent.Model
-			defaultAgent.Model = value
-			return fmt.Sprintf("Switched model from %s to %s", oldModel, value), true
-		case "channel":
+			return info
+		},
+		SwitchChannel: func(value string) error {
 			if al.channelManager == nil {
-				return "Channel manager not initialized", true
+				return fmt.Errorf("channel manager not initialized")
 			}
 			if _, exists := al.channelManager.GetChannel(value); !exists && value != "cli" {
-				return fmt.Sprintf("Channel '%s' not found or not enabled", value), true
+				return fmt.Errorf("channel '%s' not found or not enabled", value)
 			}
-			return fmt.Sprintf("Switched target channel to %s", value), true
-		default:
-			return fmt.Sprintf("Unknown switch target: %s", target), true
+			return nil
+		},
+	}
+	if agent != nil && agent.ContextBuilder != nil {
+		rt.ListSkillNames = agent.ContextBuilder.ListSkillNames
+	}
+	rt.ReloadConfig = func() error {
+		if al.reloadFunc == nil {
+			return fmt.Errorf("reload not configured")
+		}
+		return al.reloadFunc()
+	}
+	if agent != nil {
+		if agent.ContextBuilder != nil {
+			rt.ListSkillNames = agent.ContextBuilder.ListSkillNames
+		}
+		rt.GetModelInfo = func() (string, string) {
+			return agent.Model, resolvedCandidateProvider(agent.Candidates, cfg.Agents.Defaults.Provider)
+		}
+		rt.SwitchModel = func(value string) (string, error) {
+			value = strings.TrimSpace(value)
+			modelCfg, err := resolvedModelConfig(cfg, value, agent.Workspace)
+			if err != nil {
+				return "", err
+			}
+
+			nextProvider, _, err := providers.CreateProviderFromConfig(modelCfg)
+			if err != nil {
+				return "", fmt.Errorf("failed to initialize model %q: %w", value, err)
+			}
+
+			nextCandidates := resolveModelCandidates(cfg, cfg.Agents.Defaults.Provider, modelCfg.Model, agent.Fallbacks)
+			if len(nextCandidates) == 0 {
+				return "", fmt.Errorf("model %q did not resolve to any provider candidates", value)
+			}
+
+			oldModel := agent.Model
+			oldProvider := agent.Provider
+			agent.Model = value
+			agent.Provider = nextProvider
+			agent.Candidates = nextCandidates
+			agent.ThinkingLevel = parseThinkingLevel(modelCfg.ThinkingLevel)
+
+			if oldProvider != nil && oldProvider != nextProvider {
+				if stateful, ok := oldProvider.(providers.StatefulProvider); ok {
+					stateful.Close()
+				}
+			}
+			return oldModel, nil
+		}
+
+		rt.ClearHistory = func() error {
+			if opts == nil {
+				return fmt.Errorf("process options not available")
+			}
+			if agent.Sessions == nil {
+				return fmt.Errorf("sessions not initialized for agent")
+			}
+
+			agent.Sessions.SetHistory(opts.SessionKey, make([]providers.Message, 0))
+			agent.Sessions.SetSummary(opts.SessionKey, "")
+			agent.Sessions.Save(opts.SessionKey)
+			return nil
 		}
 	}
+	return rt
+}
 
-	return "", false
+func commandsUnavailableSkillMessage() string {
+	return "Skill selection is unavailable in the current context."
+}
+
+func buildUseCommandHelp(agent *AgentInstance) string {
+	if agent == nil || agent.ContextBuilder == nil {
+		return "Usage: /use <skill> [message]"
+	}
+
+	names := agent.ContextBuilder.ListSkillNames()
+	if len(names) == 0 {
+		return "Usage: /use <skill> [message]\nNo installed skills found."
+	}
+
+	return fmt.Sprintf(
+		"Usage: /use <skill> [message]\n\nInstalled Skills:\n- %s\n\nUse /use <skill> to apply a skill to your next message, or /use <skill> <message> to force it immediately.",
+		strings.Join(names, "\n- "),
+	)
+}
+
+func (al *AgentLoop) setPendingSkills(sessionKey string, skillNames []string) {
+	sessionKey = strings.TrimSpace(sessionKey)
+	if sessionKey == "" || len(skillNames) == 0 {
+		return
+	}
+
+	filtered := make([]string, 0, len(skillNames))
+	for _, name := range skillNames {
+		name = strings.TrimSpace(name)
+		if name != "" {
+			filtered = append(filtered, name)
+		}
+	}
+	if len(filtered) == 0 {
+		return
+	}
+
+	al.pendingSkills.Store(sessionKey, filtered)
+}
+
+func (al *AgentLoop) takePendingSkills(sessionKey string) []string {
+	sessionKey = strings.TrimSpace(sessionKey)
+	if sessionKey == "" {
+		return nil
+	}
+
+	value, ok := al.pendingSkills.LoadAndDelete(sessionKey)
+	if !ok {
+		return nil
+	}
+
+	skills, ok := value.([]string)
+	if !ok {
+		return nil
+	}
+
+	return append([]string(nil), skills...)
+}
+
+func (al *AgentLoop) clearPendingSkills(sessionKey string) {
+	sessionKey = strings.TrimSpace(sessionKey)
+	if sessionKey == "" {
+		return
+	}
+	al.pendingSkills.Delete(sessionKey)
+}
+
+func mapCommandError(result commands.ExecuteResult) string {
+	if result.Command == "" {
+		return fmt.Sprintf("Failed to execute command: %v", result.Err)
+	}
+	return fmt.Sprintf("Failed to execute /%s: %v", result.Command, result.Err)
 }
 
 // extractPeer extracts the routing peer from the inbound message's structured Peer field.
@@ -1341,12 +3521,54 @@ func extractPeer(msg bus.InboundMessage) *routing.RoutePeer {
 	return &routing.RoutePeer{Kind: msg.Peer.Kind, ID: peerID}
 }
 
+func inboundMetadata(msg bus.InboundMessage, key string) string {
+	if msg.Metadata == nil {
+		return ""
+	}
+	return msg.Metadata[key]
+}
+
 // extractParentPeer extracts the parent peer (reply-to) from inbound message metadata.
 func extractParentPeer(msg bus.InboundMessage) *routing.RoutePeer {
-	parentKind := msg.Metadata["parent_peer_kind"]
-	parentID := msg.Metadata["parent_peer_id"]
+	parentKind := inboundMetadata(msg, metadataKeyParentPeerKind)
+	parentID := inboundMetadata(msg, metadataKeyParentPeerID)
 	if parentKind == "" || parentID == "" {
 		return nil
 	}
 	return &routing.RoutePeer{Kind: parentKind, ID: parentID}
 }
+
+// isNativeSearchProvider reports whether the given LLM provider implements
+// NativeSearchCapable and returns true for SupportsNativeSearch.
+func isNativeSearchProvider(p providers.LLMProvider) bool {
+	if ns, ok := p.(providers.NativeSearchCapable); ok {
+		return ns.SupportsNativeSearch()
+	}
+	return false
+}
+
+// filterClientWebSearch returns a copy of tools with the client-side
+// web_search tool removed. Used when native provider search is preferred.
+func filterClientWebSearch(tools []providers.ToolDefinition) []providers.ToolDefinition {
+	result := make([]providers.ToolDefinition, 0, len(tools))
+	for _, t := range tools {
+		if strings.EqualFold(t.Function.Name, "web_search") {
+			continue
+		}
+		result = append(result, t)
+	}
+	return result
+}
+
+// Helper to extract provider from registry for cleanup
+func extractProvider(registry *AgentRegistry) (providers.LLMProvider, bool) {
+	if registry == nil {
+		return nil, false
+	}
+	// Get any agent to access the provider
+	defaultAgent := registry.GetDefaultAgent()
+	if defaultAgent == nil {
+		return nil, false
+	}
+	return defaultAgent.Provider, true
+}
diff --git a/pkg/agent/loop_mcp.go b/pkg/agent/loop_mcp.go
new file mode 100644
index 000000000..97debbc33
--- /dev/null
+++ b/pkg/agent/loop_mcp.go
@@ -0,0 +1,223 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// Inspired by and based on nanobot: https://github.com/HKUDS/nanobot
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package agent
+
+import (
+	"context"
+	"fmt"
+	"sync"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/mcp"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+type mcpRuntime struct {
+	initOnce sync.Once
+	mu       sync.Mutex
+	manager  *mcp.Manager
+	initErr  error
+}
+
+func (r *mcpRuntime) setManager(manager *mcp.Manager) {
+	r.mu.Lock()
+	r.manager = manager
+	r.initErr = nil
+	r.mu.Unlock()
+}
+
+func (r *mcpRuntime) setInitErr(err error) {
+	r.mu.Lock()
+	r.initErr = err
+	r.mu.Unlock()
+}
+
+func (r *mcpRuntime) getInitErr() error {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.initErr
+}
+
+func (r *mcpRuntime) takeManager() *mcp.Manager {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	manager := r.manager
+	r.manager = nil
+	return manager
+}
+
+func (r *mcpRuntime) hasManager() bool {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	return r.manager != nil
+}
+
+// ensureMCPInitialized loads MCP servers/tools once so both Run() and direct
+// agent mode share the same initialization path.
+func (al *AgentLoop) ensureMCPInitialized(ctx context.Context) error {
+	if !al.cfg.Tools.IsToolEnabled("mcp") {
+		return nil
+	}
+
+	if al.cfg.Tools.MCP.Servers == nil || len(al.cfg.Tools.MCP.Servers) == 0 {
+		logger.WarnCF("agent", "MCP is enabled but no servers are configured, skipping MCP initialization", nil)
+		return nil
+	}
+
+	findValidServer := false
+	for _, serverCfg := range al.cfg.Tools.MCP.Servers {
+		if serverCfg.Enabled {
+			findValidServer = true
+		}
+	}
+	if !findValidServer {
+		logger.WarnCF("agent", "MCP is enabled but no valid servers are configured, skipping MCP initialization", nil)
+		return nil
+	}
+
+	al.mcp.initOnce.Do(func() {
+		mcpManager := mcp.NewManager()
+
+		defaultAgent := al.registry.GetDefaultAgent()
+		workspacePath := al.cfg.WorkspacePath()
+		if defaultAgent != nil && defaultAgent.Workspace != "" {
+			workspacePath = defaultAgent.Workspace
+		}
+
+		if err := mcpManager.LoadFromMCPConfig(ctx, al.cfg.Tools.MCP, workspacePath); err != nil {
+			logger.WarnCF("agent", "Failed to load MCP servers, MCP tools will not be available",
+				map[string]any{
+					"error": err.Error(),
+				})
+			if closeErr := mcpManager.Close(); closeErr != nil {
+				logger.ErrorCF("agent", "Failed to close MCP manager",
+					map[string]any{
+						"error": closeErr.Error(),
+					})
+			}
+			return
+		}
+
+		// Register MCP tools for all agents
+		servers := mcpManager.GetServers()
+		uniqueTools := 0
+		totalRegistrations := 0
+		agentIDs := al.registry.ListAgentIDs()
+		agentCount := len(agentIDs)
+
+		for serverName, conn := range servers {
+			uniqueTools += len(conn.Tools)
+
+			// Determine whether this server's tools should be deferred (hidden).
+			// Per-server "deferred" field takes precedence over the global Discovery.Enabled.
+			serverCfg := al.cfg.Tools.MCP.Servers[serverName]
+			registerAsHidden := serverIsDeferred(al.cfg.Tools.MCP.Discovery.Enabled, serverCfg)
+
+			for _, tool := range conn.Tools {
+				for _, agentID := range agentIDs {
+					agent, ok := al.registry.GetAgent(agentID)
+					if !ok {
+						continue
+					}
+
+					mcpTool := tools.NewMCPTool(mcpManager, serverName, tool)
+
+					if registerAsHidden {
+						agent.Tools.RegisterHidden(mcpTool)
+					} else {
+						agent.Tools.Register(mcpTool)
+					}
+
+					totalRegistrations++
+					logger.DebugCF("agent", "Registered MCP tool",
+						map[string]any{
+							"agent_id": agentID,
+							"server":   serverName,
+							"tool":     tool.Name,
+							"name":     mcpTool.Name(),
+							"deferred": registerAsHidden,
+						})
+				}
+			}
+		}
+		logger.InfoCF("agent", "MCP tools registered successfully",
+			map[string]any{
+				"server_count":        len(servers),
+				"unique_tools":        uniqueTools,
+				"total_registrations": totalRegistrations,
+				"agent_count":         agentCount,
+			})
+
+		// Initializes Discovery Tools only if enabled by configuration
+		if al.cfg.Tools.MCP.Enabled && al.cfg.Tools.MCP.Discovery.Enabled {
+			useBM25 := al.cfg.Tools.MCP.Discovery.UseBM25
+			useRegex := al.cfg.Tools.MCP.Discovery.UseRegex
+
+			// Fail fast: If discovery is enabled but no search method is turned on
+			if !useBM25 && !useRegex {
+				al.mcp.setInitErr(fmt.Errorf(
+					"tool discovery is enabled but neither 'use_bm25' nor 'use_regex' is set to true in the configuration",
+				))
+				if closeErr := mcpManager.Close(); closeErr != nil {
+					logger.ErrorCF("agent", "Failed to close MCP manager",
+						map[string]any{
+							"error": closeErr.Error(),
+						})
+				}
+				return
+			}
+
+			ttl := al.cfg.Tools.MCP.Discovery.TTL
+			if ttl <= 0 {
+				ttl = 5 // Default value
+			}
+
+			maxSearchResults := al.cfg.Tools.MCP.Discovery.MaxSearchResults
+			if maxSearchResults <= 0 {
+				maxSearchResults = 5 // Default value
+			}
+
+			logger.InfoCF("agent", "Initializing tool discovery", map[string]any{
+				"bm25": useBM25, "regex": useRegex, "ttl": ttl, "max_results": maxSearchResults,
+			})
+
+			for _, agentID := range agentIDs {
+				agent, ok := al.registry.GetAgent(agentID)
+				if !ok {
+					continue
+				}
+
+				if useRegex {
+					agent.Tools.Register(tools.NewRegexSearchTool(agent.Tools, ttl, maxSearchResults))
+				}
+				if useBM25 {
+					agent.Tools.Register(tools.NewBM25SearchTool(agent.Tools, ttl, maxSearchResults))
+				}
+			}
+		}
+
+		al.mcp.setManager(mcpManager)
+	})
+
+	return al.mcp.getInitErr()
+}
+
+// serverIsDeferred reports whether an MCP server's tools should be registered
+// as hidden (deferred/discovery mode).
+//
+// The per-server Deferred field takes precedence over the global discoveryEnabled
+// default. When Deferred is nil, discoveryEnabled is used as the fallback.
+func serverIsDeferred(discoveryEnabled bool, serverCfg config.MCPServerConfig) bool {
+	if !discoveryEnabled {
+		return false
+	}
+	if serverCfg.Deferred != nil {
+		return *serverCfg.Deferred
+	}
+	return true
+}
diff --git a/pkg/agent/loop_mcp_test.go b/pkg/agent/loop_mcp_test.go
new file mode 100644
index 000000000..35c3e49c8
--- /dev/null
+++ b/pkg/agent/loop_mcp_test.go
@@ -0,0 +1,75 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// Inspired by and based on nanobot: https://github.com/HKUDS/nanobot
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package agent
+
+import (
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func boolPtr(b bool) *bool { return &b }
+
+func TestServerIsDeferred(t *testing.T) {
+	tests := []struct {
+		name             string
+		discoveryEnabled bool
+		serverDeferred   *bool
+		want             bool
+	}{
+		// --- global false always wins: per-server deferred is ignored ---
+		{
+			name:             "global false: per-server deferred=true is ignored",
+			discoveryEnabled: false,
+			serverDeferred:   boolPtr(true),
+			want:             false,
+		},
+		{
+			name:             "global false: per-server deferred=false stays false",
+			discoveryEnabled: false,
+			serverDeferred:   boolPtr(false),
+			want:             false,
+		},
+		// --- global true: per-server override applies ---
+		{
+			name:             "global true: per-server deferred=false opts out",
+			discoveryEnabled: true,
+			serverDeferred:   boolPtr(false),
+			want:             false,
+		},
+		{
+			name:             "global true: per-server deferred=true stays true",
+			discoveryEnabled: true,
+			serverDeferred:   boolPtr(true),
+			want:             true,
+		},
+		// --- no per-server override: fall back to global ---
+		{
+			name:             "no per-server field, global discovery enabled",
+			discoveryEnabled: true,
+			serverDeferred:   nil,
+			want:             true,
+		},
+		{
+			name:             "no per-server field, global discovery disabled",
+			discoveryEnabled: false,
+			serverDeferred:   nil,
+			want:             false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			serverCfg := config.MCPServerConfig{Deferred: tt.serverDeferred}
+			got := serverIsDeferred(tt.discoveryEnabled, serverCfg)
+			if got != tt.want {
+				t.Errorf("serverIsDeferred(discoveryEnabled=%v, deferred=%v) = %v, want %v",
+					tt.discoveryEnabled, tt.serverDeferred, got, tt.want)
+			}
+		})
+	}
+}
diff --git a/pkg/agent/loop_media.go b/pkg/agent/loop_media.go
new file mode 100644
index 000000000..e8314c10d
--- /dev/null
+++ b/pkg/agent/loop_media.go
@@ -0,0 +1,198 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// Inspired by and based on nanobot: https://github.com/HKUDS/nanobot
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package agent
+
+import (
+	"bytes"
+	"encoding/base64"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/h2non/filetype"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// resolveMediaRefs resolves media:// refs in messages.
+// Images are base64-encoded into the Media array for multimodal LLMs.
+// Non-image files (documents, audio, video) have their local path injected
+// into Content so the agent can access them via file tools like read_file.
+// Returns a new slice; original messages are not mutated.
+func resolveMediaRefs(messages []providers.Message, store media.MediaStore, maxSize int) []providers.Message {
+	if store == nil {
+		return messages
+	}
+
+	result := make([]providers.Message, len(messages))
+	copy(result, messages)
+
+	for i, m := range result {
+		if len(m.Media) == 0 {
+			continue
+		}
+
+		resolved := make([]string, 0, len(m.Media))
+		var pathTags []string
+
+		for _, ref := range m.Media {
+			if !strings.HasPrefix(ref, "media://") {
+				resolved = append(resolved, ref)
+				continue
+			}
+
+			localPath, meta, err := store.ResolveWithMeta(ref)
+			if err != nil {
+				logger.WarnCF("agent", "Failed to resolve media ref", map[string]any{
+					"ref":   ref,
+					"error": err.Error(),
+				})
+				continue
+			}
+
+			info, err := os.Stat(localPath)
+			if err != nil {
+				logger.WarnCF("agent", "Failed to stat media file", map[string]any{
+					"path":  localPath,
+					"error": err.Error(),
+				})
+				continue
+			}
+
+			mime := detectMIME(localPath, meta)
+
+			if strings.HasPrefix(mime, "image/") {
+				dataURL := encodeImageToDataURL(localPath, mime, info, maxSize)
+				if dataURL != "" {
+					resolved = append(resolved, dataURL)
+				}
+				continue
+			}
+
+			pathTags = append(pathTags, buildPathTag(mime, localPath))
+		}
+
+		result[i].Media = resolved
+		if len(pathTags) > 0 {
+			result[i].Content = injectPathTags(result[i].Content, pathTags)
+		}
+	}
+
+	return result
+}
+
+func buildArtifactTags(store media.MediaStore, refs []string) []string {
+	if store == nil || len(refs) == 0 {
+		return nil
+	}
+
+	tags := make([]string, 0, len(refs))
+	for _, ref := range refs {
+		localPath, meta, err := store.ResolveWithMeta(ref)
+		if err != nil {
+			continue
+		}
+		mime := detectMIME(localPath, meta)
+		tags = append(tags, buildPathTag(mime, localPath))
+	}
+
+	return tags
+}
+
+// detectMIME determines the MIME type from metadata or magic-bytes detection.
+// Returns empty string if detection fails.
+func detectMIME(localPath string, meta media.MediaMeta) string {
+	if meta.ContentType != "" {
+		return meta.ContentType
+	}
+	kind, err := filetype.MatchFile(localPath)
+	if err != nil || kind == filetype.Unknown {
+		return ""
+	}
+	return kind.MIME.Value
+}
+
+// encodeImageToDataURL base64-encodes an image file into a data URL.
+// Returns empty string if the file exceeds maxSize or encoding fails.
+func encodeImageToDataURL(localPath, mime string, info os.FileInfo, maxSize int) string {
+	if info.Size() > int64(maxSize) {
+		logger.WarnCF("agent", "Media file too large, skipping", map[string]any{
+			"path":     localPath,
+			"size":     info.Size(),
+			"max_size": maxSize,
+		})
+		return ""
+	}
+
+	f, err := os.Open(localPath)
+	if err != nil {
+		logger.WarnCF("agent", "Failed to open media file", map[string]any{
+			"path":  localPath,
+			"error": err.Error(),
+		})
+		return ""
+	}
+	defer f.Close()
+
+	prefix := "data:" + mime + ";base64,"
+	encodedLen := base64.StdEncoding.EncodedLen(int(info.Size()))
+	var buf bytes.Buffer
+	buf.Grow(len(prefix) + encodedLen)
+	buf.WriteString(prefix)
+
+	encoder := base64.NewEncoder(base64.StdEncoding, &buf)
+	if _, err := io.Copy(encoder, f); err != nil {
+		logger.WarnCF("agent", "Failed to encode media file", map[string]any{
+			"path":  localPath,
+			"error": err.Error(),
+		})
+		return ""
+	}
+	encoder.Close()
+
+	return buf.String()
+}
+
+// buildPathTag creates a structured tag exposing the local file path.
+// Tag type is derived from MIME: [audio:/path], [video:/path], or [file:/path].
+func buildPathTag(mime, localPath string) string {
+	switch {
+	case strings.HasPrefix(mime, "audio/"):
+		return "[audio:" + localPath + "]"
+	case strings.HasPrefix(mime, "video/"):
+		return "[video:" + localPath + "]"
+	default:
+		return "[file:" + localPath + "]"
+	}
+}
+
+// injectPathTags replaces generic media tags in content with path-bearing versions,
+// or appends if no matching generic tag is found.
+func injectPathTags(content string, tags []string) string {
+	for _, tag := range tags {
+		var generic string
+		switch {
+		case strings.HasPrefix(tag, "[audio:"):
+			generic = "[audio]"
+		case strings.HasPrefix(tag, "[video:"):
+			generic = "[video]"
+		case strings.HasPrefix(tag, "[file:"):
+			generic = "[file]"
+		}
+
+		if generic != "" && strings.Contains(content, generic) {
+			content = strings.Replace(content, generic, tag, 1)
+		} else if content == "" {
+			content = tag
+		} else {
+			content += " " + tag
+		}
+	}
+	return content
+}
diff --git a/pkg/agent/loop_test.go b/pkg/agent/loop_test.go
index 1034b06e8..e0a5dffb3 100644
--- a/pkg/agent/loop_test.go
+++ b/pkg/agent/loop_test.go
@@ -2,17 +2,23 @@ package agent
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
+	"net/http"
+	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"slices"
+	"strings"
 	"testing"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/channels"
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/routing"
 	"github.com/sipeed/picoclaw/pkg/tools"
 )
 
@@ -27,93 +33,408 @@ func (f *fakeChannel) IsAllowed(string) bool                                   {
 func (f *fakeChannel) IsAllowedSender(sender bus.SenderInfo) bool              { return true }
 func (f *fakeChannel) ReasoningChannelID() string                              { return f.id }
 
-func TestRecordLastChannel(t *testing.T) {
-	// Create temp workspace
+type fakeMediaChannel struct {
+	fakeChannel
+	sentMedia []bus.OutboundMediaMessage
+}
+
+func (f *fakeMediaChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	f.sentMedia = append(f.sentMedia, msg)
+	return nil
+}
+
+func newStartedTestChannelManager(
+	t *testing.T,
+	msgBus *bus.MessageBus,
+	store media.MediaStore,
+	name string,
+	ch channels.Channel,
+) *channels.Manager {
+	t.Helper()
+
+	cm, err := channels.NewManager(&config.Config{}, msgBus, store)
+	if err != nil {
+		t.Fatalf("NewManager() error = %v", err)
+	}
+	cm.RegisterChannel(name, ch)
+	if err := cm.StartAll(context.Background()); err != nil {
+		t.Fatalf("StartAll() error = %v", err)
+	}
+	t.Cleanup(func() {
+		if err := cm.StopAll(context.Background()); err != nil {
+			t.Fatalf("StopAll() error = %v", err)
+		}
+	})
+	return cm
+}
+
+type recordingProvider struct {
+	lastMessages []providers.Message
+}
+
+func (r *recordingProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	r.lastMessages = append([]providers.Message(nil), messages...)
+	return &providers.LLMResponse{
+		Content:   "Mock response",
+		ToolCalls: []providers.ToolCall{},
+	}, nil
+}
+
+func (r *recordingProvider) GetDefaultModel() string {
+	return "mock-model"
+}
+
+func newTestAgentLoop(
+	t *testing.T,
+) (al *AgentLoop, cfg *config.Config, msgBus *bus.MessageBus, provider *mockProvider, cleanup func()) {
+	t.Helper()
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	cfg = &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+	msgBus = bus.NewMessageBus()
+	provider = &mockProvider{}
+	al = NewAgentLoop(cfg, msgBus, provider)
+	return al, cfg, msgBus, provider, func() { os.RemoveAll(tmpDir) }
+}
+
+func TestProcessMessage_IncludesCurrentSenderInDynamicContext(t *testing.T) {
 	tmpDir, err := os.MkdirTemp("", "agent-test-*")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
 	}
 	defer os.RemoveAll(tmpDir)
 
-	// Create test config
 	cfg := &config.Config{
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
-				Model:             "test-model",
+				ModelName:         "test-model",
 				MaxTokens:         4096,
 				MaxToolIterations: 10,
 			},
 		},
 	}
 
-	// Create agent loop
 	msgBus := bus.NewMessageBus()
-	provider := &mockProvider{}
+	provider := &recordingProvider{}
 	al := NewAgentLoop(cfg, msgBus, provider)
 
-	// Test RecordLastChannel
-	testChannel := "test-channel"
-	err = al.RecordLastChannel(testChannel)
+	response, err := al.processMessage(context.Background(), bus.InboundMessage{
+		Channel:  "discord",
+		SenderID: "discord:123",
+		Sender: bus.SenderInfo{
+			DisplayName: "Alice",
+		},
+		ChatID:  "group-1",
+		Content: "hello",
+	})
 	if err != nil {
+		t.Fatalf("processMessage() error = %v", err)
+	}
+	if response != "Mock response" {
+		t.Fatalf("processMessage() response = %q, want %q", response, "Mock response")
+	}
+	if len(provider.lastMessages) == 0 {
+		t.Fatal("provider did not receive any messages")
+	}
+
+	systemPrompt := provider.lastMessages[0].Content
+	wantSender := "## Current Sender\nCurrent sender: Alice (ID: discord:123)"
+	if !strings.Contains(systemPrompt, wantSender) {
+		t.Fatalf("system prompt missing sender context %q:\n%s", wantSender, systemPrompt)
+	}
+
+	lastMessage := provider.lastMessages[len(provider.lastMessages)-1]
+	if lastMessage.Role != "user" || lastMessage.Content != "hello" {
+		t.Fatalf("last provider message = %+v, want unchanged user message", lastMessage)
+	}
+}
+
+func TestProcessMessage_UseCommandLoadsRequestedSkill(t *testing.T) {
+	tmpDir := t.TempDir()
+	skillDir := filepath.Join(tmpDir, "skills", "shell")
+	if err := os.MkdirAll(skillDir, 0o755); err != nil {
+		t.Fatalf("mkdir skill dir: %v", err)
+	}
+	if err := os.WriteFile(
+		filepath.Join(skillDir, "SKILL.md"),
+		[]byte("# shell\n\nPrefer concise shell commands and explain them briefly."),
+		0o644,
+	); err != nil {
+		t.Fatalf("write skill file: %v", err)
+	}
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+	msgBus := bus.NewMessageBus()
+	provider := &recordingProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	response, err := al.processMessage(context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "telegram:123",
+		ChatID:   "chat-1",
+		Content:  "/use shell explain how to list files",
+	})
+	if err != nil {
+		t.Fatalf("processMessage() error = %v", err)
+	}
+	if response != "Mock response" {
+		t.Fatalf("processMessage() response = %q, want %q", response, "Mock response")
+	}
+	if len(provider.lastMessages) == 0 {
+		t.Fatal("provider did not receive any messages")
+	}
+
+	systemPrompt := provider.lastMessages[0].Content
+	if !strings.Contains(systemPrompt, "# Active Skills") {
+		t.Fatalf("system prompt missing active skills section:\n%s", systemPrompt)
+	}
+	if !strings.Contains(systemPrompt, "### Skill: shell") {
+		t.Fatalf("system prompt missing requested skill content:\n%s", systemPrompt)
+	}
+
+	lastMessage := provider.lastMessages[len(provider.lastMessages)-1]
+	if lastMessage.Role != "user" || lastMessage.Content != "explain how to list files" {
+		t.Fatalf("last provider message = %+v, want rewritten user message", lastMessage)
+	}
+}
+
+func TestHandleCommand_UseCommandRejectsUnknownSkill(t *testing.T) {
+	tmpDir := t.TempDir()
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+	msgBus := bus.NewMessageBus()
+	provider := &recordingProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+	agent := al.GetRegistry().GetDefaultAgent()
+
+	opts := processOptions{}
+	reply, handled := al.handleCommand(context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "telegram:123",
+		ChatID:   "chat-1",
+		Content:  "/use missing explain how to list files",
+	}, agent, &opts)
+	if !handled {
+		t.Fatal("expected /use with unknown skill to be handled")
+	}
+	if !strings.Contains(reply, "Unknown skill: missing") {
+		t.Fatalf("reply = %q, want unknown skill error", reply)
+	}
+}
+
+func TestProcessMessage_UseCommandArmsSkillForNextMessage(t *testing.T) {
+	tmpDir := t.TempDir()
+	skillDir := filepath.Join(tmpDir, "skills", "shell")
+	if err := os.MkdirAll(skillDir, 0o755); err != nil {
+		t.Fatalf("mkdir skill dir: %v", err)
+	}
+	if err := os.WriteFile(
+		filepath.Join(skillDir, "SKILL.md"),
+		[]byte("# shell\n\nPrefer concise shell commands and explain them briefly."),
+		0o644,
+	); err != nil {
+		t.Fatalf("write skill file: %v", err)
+	}
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+	msgBus := bus.NewMessageBus()
+	provider := &recordingProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	response, err := al.processMessage(context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "telegram:123",
+		ChatID:   "chat-1",
+		Content:  "/use shell",
+	})
+	if err != nil {
+		t.Fatalf("processMessage() arm error = %v", err)
+	}
+	if !strings.Contains(response, `Skill "shell" is armed for your next message.`) {
+		t.Fatalf("arm response = %q, want armed confirmation", response)
+	}
+
+	response, err = al.processMessage(context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "telegram:123",
+		ChatID:   "chat-1",
+		Content:  "explain how to list files",
+	})
+	if err != nil {
+		t.Fatalf("processMessage() follow-up error = %v", err)
+	}
+	if response != "Mock response" {
+		t.Fatalf("follow-up response = %q, want %q", response, "Mock response")
+	}
+	if len(provider.lastMessages) == 0 {
+		t.Fatal("provider did not receive any messages")
+	}
+
+	systemPrompt := provider.lastMessages[0].Content
+	if !strings.Contains(systemPrompt, "### Skill: shell") {
+		t.Fatalf("system prompt missing pending skill content:\n%s", systemPrompt)
+	}
+	lastMessage := provider.lastMessages[len(provider.lastMessages)-1]
+	if lastMessage.Role != "user" || lastMessage.Content != "explain how to list files" {
+		t.Fatalf("last provider message = %+v, want unchanged follow-up user message", lastMessage)
+	}
+}
+
+func TestApplyExplicitSkillCommand_ArmsSkillForNextMessage(t *testing.T) {
+	al, cfg, _, _, cleanup := newTestAgentLoop(t)
+	defer cleanup()
+
+	if err := os.MkdirAll(filepath.Join(cfg.Agents.Defaults.Workspace, "skills", "finance-news"), 0o755); err != nil {
+		t.Fatalf("MkdirAll(skill) error = %v", err)
+	}
+	if err := os.WriteFile(
+		filepath.Join(cfg.Agents.Defaults.Workspace, "skills", "finance-news", "SKILL.md"),
+		[]byte("# Finance News\n\nUse web tools for current finance updates.\n"),
+		0o644,
+	); err != nil {
+		t.Fatalf("WriteFile(SKILL.md) error = %v", err)
+	}
+
+	agent := al.GetRegistry().GetDefaultAgent()
+	if agent == nil {
+		t.Fatal("expected default agent")
+	}
+
+	opts := &processOptions{SessionKey: "agent:main:test"}
+	matched, handled, reply := al.applyExplicitSkillCommand("/use finance-news", agent, opts)
+	if !matched {
+		t.Fatal("expected /use command to match")
+	}
+	if !handled {
+		t.Fatal("expected /use without inline message to be handled immediately")
+	}
+	if !strings.Contains(reply, `Skill "finance-news" is armed for your next message`) {
+		t.Fatalf("unexpected reply: %q", reply)
+	}
+
+	pending := al.takePendingSkills(opts.SessionKey)
+	if len(pending) != 1 || pending[0] != "finance-news" {
+		t.Fatalf("pending skills = %#v, want [finance-news]", pending)
+	}
+}
+
+func TestApplyExplicitSkillCommand_InlineMessageMutatesOptions(t *testing.T) {
+	al, cfg, _, _, cleanup := newTestAgentLoop(t)
+	defer cleanup()
+
+	if err := os.MkdirAll(filepath.Join(cfg.Agents.Defaults.Workspace, "skills", "finance-news"), 0o755); err != nil {
+		t.Fatalf("MkdirAll(skill) error = %v", err)
+	}
+	if err := os.WriteFile(
+		filepath.Join(cfg.Agents.Defaults.Workspace, "skills", "finance-news", "SKILL.md"),
+		[]byte("# Finance News\n\nUse web tools for current finance updates.\n"),
+		0o644,
+	); err != nil {
+		t.Fatalf("WriteFile(SKILL.md) error = %v", err)
+	}
+
+	agent := al.GetRegistry().GetDefaultAgent()
+	if agent == nil {
+		t.Fatal("expected default agent")
+	}
+
+	opts := &processOptions{
+		SessionKey:  "agent:main:test",
+		UserMessage: "/use finance-news dammi le ultime news",
+	}
+	matched, handled, reply := al.applyExplicitSkillCommand(opts.UserMessage, agent, opts)
+	if !matched {
+		t.Fatal("expected /use command to match")
+	}
+	if handled {
+		t.Fatal("expected /use with inline message to fall through into normal agent execution")
+	}
+	if reply != "" {
+		t.Fatalf("unexpected reply: %q", reply)
+	}
+	if opts.UserMessage != "dammi le ultime news" {
+		t.Fatalf("opts.UserMessage = %q, want %q", opts.UserMessage, "dammi le ultime news")
+	}
+	if len(opts.ForcedSkills) != 1 || opts.ForcedSkills[0] != "finance-news" {
+		t.Fatalf("opts.ForcedSkills = %#v, want [finance-news]", opts.ForcedSkills)
+	}
+}
+
+func TestRecordLastChannel(t *testing.T) {
+	al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t)
+	defer cleanup()
+
+	testChannel := "test-channel"
+	if err := al.RecordLastChannel(testChannel); err != nil {
 		t.Fatalf("RecordLastChannel failed: %v", err)
 	}
-
-	// Verify channel was saved
-	lastChannel := al.state.GetLastChannel()
-	if lastChannel != testChannel {
-		t.Errorf("Expected channel '%s', got '%s'", testChannel, lastChannel)
+	if got := al.state.GetLastChannel(); got != testChannel {
+		t.Errorf("Expected channel '%s', got '%s'", testChannel, got)
 	}
-
-	// Verify persistence by creating a new agent loop
 	al2 := NewAgentLoop(cfg, msgBus, provider)
-	if al2.state.GetLastChannel() != testChannel {
-		t.Errorf("Expected persistent channel '%s', got '%s'", testChannel, al2.state.GetLastChannel())
+	if got := al2.state.GetLastChannel(); got != testChannel {
+		t.Errorf("Expected persistent channel '%s', got '%s'", testChannel, got)
 	}
 }
 
 func TestRecordLastChatID(t *testing.T) {
-	// Create temp workspace
-	tmpDir, err := os.MkdirTemp("", "agent-test-*")
-	if err != nil {
-		t.Fatalf("Failed to create temp dir: %v", err)
-	}
-	defer os.RemoveAll(tmpDir)
+	al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t)
+	defer cleanup()
 
-	// Create test config
-	cfg := &config.Config{
-		Agents: config.AgentsConfig{
-			Defaults: config.AgentDefaults{
-				Workspace:         tmpDir,
-				Model:             "test-model",
-				MaxTokens:         4096,
-				MaxToolIterations: 10,
-			},
-		},
-	}
-
-	// Create agent loop
-	msgBus := bus.NewMessageBus()
-	provider := &mockProvider{}
-	al := NewAgentLoop(cfg, msgBus, provider)
-
-	// Test RecordLastChatID
 	testChatID := "test-chat-id-123"
-	err = al.RecordLastChatID(testChatID)
-	if err != nil {
+	if err := al.RecordLastChatID(testChatID); err != nil {
 		t.Fatalf("RecordLastChatID failed: %v", err)
 	}
-
-	// Verify chat ID was saved
-	lastChatID := al.state.GetLastChatID()
-	if lastChatID != testChatID {
-		t.Errorf("Expected chat ID '%s', got '%s'", testChatID, lastChatID)
+	if got := al.state.GetLastChatID(); got != testChatID {
+		t.Errorf("Expected chat ID '%s', got '%s'", testChatID, got)
 	}
-
-	// Verify persistence by creating a new agent loop
 	al2 := NewAgentLoop(cfg, msgBus, provider)
-	if al2.state.GetLastChatID() != testChatID {
-		t.Errorf("Expected persistent chat ID '%s', got '%s'", testChatID, al2.state.GetLastChatID())
+	if got := al2.state.GetLastChatID(); got != testChatID {
+		t.Errorf("Expected persistent chat ID '%s', got '%s'", testChatID, got)
 	}
 }
 
@@ -130,7 +451,7 @@ func TestNewAgentLoop_StateInitialized(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
-				Model:             "test-model",
+				ModelName:         "test-model",
 				MaxTokens:         4096,
 				MaxToolIterations: 10,
 			},
@@ -166,7 +487,7 @@ func TestToolRegistry_ToolRegistration(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
-				Model:             "test-model",
+				ModelName:         "test-model",
 				MaxTokens:         4096,
 				MaxToolIterations: 10,
 			},
@@ -194,35 +515,21 @@ func TestToolRegistry_ToolRegistration(t *testing.T) {
 	}
 }
 
-// TestToolContext_Updates verifies tool context is updated with channel/chatID
+// TestToolContext_Updates verifies tool context helpers work correctly
 func TestToolContext_Updates(t *testing.T) {
-	tmpDir, err := os.MkdirTemp("", "agent-test-*")
-	if err != nil {
-		t.Fatalf("Failed to create temp dir: %v", err)
-	}
-	defer os.RemoveAll(tmpDir)
+	ctx := tools.WithToolContext(context.Background(), "telegram", "chat-42")
 
-	cfg := &config.Config{
-		Agents: config.AgentsConfig{
-			Defaults: config.AgentDefaults{
-				Workspace:         tmpDir,
-				Model:             "test-model",
-				MaxTokens:         4096,
-				MaxToolIterations: 10,
-			},
-		},
+	if got := tools.ToolChannel(ctx); got != "telegram" {
+		t.Errorf("expected channel 'telegram', got %q", got)
+	}
+	if got := tools.ToolChatID(ctx); got != "chat-42" {
+		t.Errorf("expected chatID 'chat-42', got %q", got)
 	}
 
-	msgBus := bus.NewMessageBus()
-	provider := &simpleMockProvider{response: "OK"}
-	_ = NewAgentLoop(cfg, msgBus, provider)
-
-	// Verify that ContextualTool interface is defined and can be implemented
-	// This test validates the interface contract exists
-	ctxTool := &mockContextualTool{}
-
-	// Verify the tool implements the interface correctly
-	var _ tools.ContextualTool = ctxTool
+	// Empty context returns empty strings
+	if got := tools.ToolChannel(context.Background()); got != "" {
+		t.Errorf("expected empty channel from bare context, got %q", got)
+	}
 }
 
 // TestToolRegistry_GetDefinitions verifies tool definitions can be retrieved
@@ -237,7 +544,7 @@ func TestToolRegistry_GetDefinitions(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
-				Model:             "test-model",
+				ModelName:         "test-model",
 				MaxTokens:         4096,
 				MaxToolIterations: 10,
 			},
@@ -263,6 +570,217 @@ func TestToolRegistry_GetDefinitions(t *testing.T) {
 	}
 }
 
+func TestProcessMessage_MediaToolHandledSkipsFollowUpLLMAndFinalText(t *testing.T) {
+	tmpDir := t.TempDir()
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &handledMediaProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	store := media.NewFileMediaStore()
+	al.SetMediaStore(store)
+	telegramChannel := &fakeMediaChannel{fakeChannel: fakeChannel{id: "rid-telegram"}}
+	al.SetChannelManager(newStartedTestChannelManager(t, msgBus, store, "telegram", telegramChannel))
+
+	imagePath := filepath.Join(tmpDir, "screen.png")
+	if err := os.WriteFile(imagePath, []byte("fake screenshot"), 0o644); err != nil {
+		t.Fatalf("WriteFile(imagePath) error = %v", err)
+	}
+
+	al.RegisterTool(&handledMediaTool{
+		store: store,
+		path:  imagePath,
+	})
+
+	response, err := al.processMessage(context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		ChatID:   "chat1",
+		SenderID: "user1",
+		Content:  "take a screenshot of the screen and send it to me",
+	})
+	if err != nil {
+		t.Fatalf("processMessage() error = %v", err)
+	}
+	if response != "" {
+		t.Fatalf("expected no final response when media tool already handled delivery, got %q", response)
+	}
+	if provider.calls != 1 {
+		t.Fatalf("expected exactly 1 LLM call, got %d", provider.calls)
+	}
+	if len(provider.toolCounts) != 1 {
+		t.Fatalf("expected tool counts for 1 provider call, got %d", len(provider.toolCounts))
+	}
+	if provider.toolCounts[0] == 0 {
+		t.Fatal("expected tools to be available on the first LLM call")
+	}
+
+	if len(telegramChannel.sentMedia) != 1 {
+		t.Fatalf("expected exactly 1 synchronously sent media message, got %d", len(telegramChannel.sentMedia))
+	}
+	if telegramChannel.sentMedia[0].Channel != "telegram" || telegramChannel.sentMedia[0].ChatID != "chat1" {
+		t.Fatalf("unexpected sent media target: %+v", telegramChannel.sentMedia[0])
+	}
+	if len(telegramChannel.sentMedia[0].Parts) != 1 {
+		t.Fatalf("expected exactly 1 sent media part, got %d", len(telegramChannel.sentMedia[0].Parts))
+	}
+
+	select {
+	case extra := <-msgBus.OutboundMediaChan():
+		t.Fatalf("expected handled media to bypass async queue, got %+v", extra)
+	default:
+	}
+
+	defaultAgent := al.GetRegistry().GetDefaultAgent()
+	if defaultAgent == nil {
+		t.Fatal("expected default agent")
+	}
+	route, _, err := al.resolveMessageRoute(bus.InboundMessage{
+		Channel:  "telegram",
+		ChatID:   "chat1",
+		SenderID: "user1",
+		Content:  "take a screenshot of the screen and send it to me",
+	})
+	if err != nil {
+		t.Fatalf("resolveMessageRoute() error = %v", err)
+	}
+	sessionKey := resolveScopeKey(route, "")
+	history := defaultAgent.Sessions.GetHistory(sessionKey)
+	if len(history) == 0 {
+		t.Fatal("expected session history to be saved")
+	}
+	last := history[len(history)-1]
+	if last.Role != "assistant" || last.Content != "Requested output delivered via tool attachment." {
+		t.Fatalf("expected handled assistant summary in history, got %+v", last)
+	}
+}
+
+func TestProcessMessage_HandledToolProcessesQueuedSteeringBeforeReturning(t *testing.T) {
+	tmpDir := t.TempDir()
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &handledMediaWithSteeringProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	store := media.NewFileMediaStore()
+	al.SetMediaStore(store)
+	telegramChannel := &fakeMediaChannel{fakeChannel: fakeChannel{id: "rid-telegram"}}
+	al.SetChannelManager(newStartedTestChannelManager(t, msgBus, store, "telegram", telegramChannel))
+
+	imagePath := filepath.Join(tmpDir, "screen-steering.png")
+	if err := os.WriteFile(imagePath, []byte("fake screenshot"), 0o644); err != nil {
+		t.Fatalf("WriteFile(imagePath) error = %v", err)
+	}
+
+	al.RegisterTool(&handledMediaWithSteeringTool{
+		store: store,
+		path:  imagePath,
+		loop:  al,
+	})
+
+	response, err := al.processMessage(context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		ChatID:   "chat1",
+		SenderID: "user1",
+		Content:  "take a screenshot of the screen and send it to me",
+	})
+	if err != nil {
+		t.Fatalf("processMessage() error = %v", err)
+	}
+	if response != "Handled the queued steering message." {
+		t.Fatalf("response = %q, want queued steering response", response)
+	}
+	if provider.calls != 2 {
+		t.Fatalf("expected 2 LLM calls after queued steering, got %d", provider.calls)
+	}
+	if len(telegramChannel.sentMedia) != 1 {
+		t.Fatalf("expected exactly 1 synchronously sent media message, got %d", len(telegramChannel.sentMedia))
+	}
+}
+
+func TestProcessMessage_MediaArtifactCanBeForwardedBySendFile(t *testing.T) {
+	tmpDir := t.TempDir()
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.Workspace = tmpDir
+	cfg.Agents.Defaults.ModelName = "test-model"
+	cfg.Agents.Defaults.MaxTokens = 4096
+	cfg.Agents.Defaults.MaxToolIterations = 10
+
+	msgBus := bus.NewMessageBus()
+	provider := &artifactThenSendProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	store := media.NewFileMediaStore()
+	al.SetMediaStore(store)
+	telegramChannel := &fakeMediaChannel{fakeChannel: fakeChannel{id: "rid-telegram"}}
+	al.SetChannelManager(newStartedTestChannelManager(t, msgBus, store, "telegram", telegramChannel))
+
+	mediaDir := media.TempDir()
+	if err := os.MkdirAll(mediaDir, 0o700); err != nil {
+		t.Fatalf("MkdirAll(mediaDir) error = %v", err)
+	}
+	imagePath := filepath.Join(mediaDir, "artifact-screen.png")
+	if err := os.WriteFile(imagePath, []byte("fake screenshot"), 0o644); err != nil {
+		t.Fatalf("WriteFile(imagePath) error = %v", err)
+	}
+
+	al.RegisterTool(&mediaArtifactTool{
+		store: store,
+		path:  imagePath,
+	})
+
+	response, err := al.processMessage(context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		ChatID:   "chat1",
+		SenderID: "user1",
+		Content:  "take a screenshot of the screen and send it to me",
+	})
+	if err != nil {
+		t.Fatalf("processMessage() error = %v", err)
+	}
+	if response != "" {
+		t.Fatalf("expected no final response after send_file handled delivery, got %q", response)
+	}
+	if provider.calls != 2 {
+		t.Fatalf("expected 2 LLM calls (artifact + send_file), got %d", provider.calls)
+	}
+
+	if len(telegramChannel.sentMedia) != 1 {
+		t.Fatalf("expected exactly 1 synchronously sent media message, got %d", len(telegramChannel.sentMedia))
+	}
+	if telegramChannel.sentMedia[0].Channel != "telegram" || telegramChannel.sentMedia[0].ChatID != "chat1" {
+		t.Fatalf("unexpected sent media target: %+v", telegramChannel.sentMedia[0])
+	}
+	if len(telegramChannel.sentMedia[0].Parts) != 1 {
+		t.Fatalf("expected exactly 1 sent media part, got %d", len(telegramChannel.sentMedia[0].Parts))
+	}
+
+	select {
+	case extra := <-msgBus.OutboundMediaChan():
+		t.Fatalf("expected synchronous send_file delivery to bypass async queue, got %+v", extra)
+	default:
+	}
+}
+
 // TestAgentLoop_GetStartupInfo verifies startup info contains tools
 func TestAgentLoop_GetStartupInfo(t *testing.T) {
 	tmpDir, err := os.MkdirTemp("", "agent-test-*")
@@ -271,16 +789,11 @@ func TestAgentLoop_GetStartupInfo(t *testing.T) {
 	}
 	defer os.RemoveAll(tmpDir)
 
-	cfg := &config.Config{
-		Agents: config.AgentsConfig{
-			Defaults: config.AgentDefaults{
-				Workspace:         tmpDir,
-				Model:             "test-model",
-				MaxTokens:         4096,
-				MaxToolIterations: 10,
-			},
-		},
-	}
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.Workspace = tmpDir
+	cfg.Agents.Defaults.ModelName = "test-model"
+	cfg.Agents.Defaults.MaxTokens = 4096
+	cfg.Agents.Defaults.MaxToolIterations = 10
 
 	msgBus := bus.NewMessageBus()
 	provider := &mockProvider{}
@@ -322,7 +835,7 @@ func TestAgentLoop_Stop(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
-				Model:             "test-model",
+				ModelName:         "test-model",
 				MaxTokens:         4096,
 				MaxToolIterations: 10,
 			},
@@ -367,6 +880,167 @@ func (m *simpleMockProvider) GetDefaultModel() string {
 	return "mock-model"
 }
 
+type reasoningContentProvider struct {
+	response         string
+	reasoningContent string
+}
+
+func (m *reasoningContentProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	return &providers.LLMResponse{
+		Content:          m.response,
+		ReasoningContent: m.reasoningContent,
+		ToolCalls:        []providers.ToolCall{},
+	}, nil
+}
+
+func (m *reasoningContentProvider) GetDefaultModel() string {
+	return "reasoning-content-model"
+}
+
+type countingMockProvider struct {
+	response string
+	calls    int
+}
+
+func (m *countingMockProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	m.calls++
+	return &providers.LLMResponse{
+		Content:   m.response,
+		ToolCalls: []providers.ToolCall{},
+	}, nil
+}
+
+func (m *countingMockProvider) GetDefaultModel() string {
+	return "counting-mock-model"
+}
+
+type handledMediaProvider struct {
+	calls      int
+	toolCounts []int
+}
+
+func (m *handledMediaProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	m.calls++
+	m.toolCounts = append(m.toolCounts, len(tools))
+	if m.calls == 1 {
+		return &providers.LLMResponse{
+			Content: "Taking the screenshot now.",
+			ToolCalls: []providers.ToolCall{{
+				ID:        "call_handled_media",
+				Type:      "function",
+				Name:      "handled_media_tool",
+				Arguments: map[string]any{},
+			}},
+		}, nil
+	}
+	return &providers.LLMResponse{}, nil
+}
+
+func (m *handledMediaProvider) GetDefaultModel() string {
+	return "handled-media-model"
+}
+
+type artifactThenSendProvider struct {
+	calls int
+}
+
+func (m *artifactThenSendProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	m.calls++
+	if m.calls == 1 {
+		return &providers.LLMResponse{
+			Content: "Taking the screenshot now.",
+			ToolCalls: []providers.ToolCall{{
+				ID:        "call_artifact_media",
+				Type:      "function",
+				Name:      "media_artifact_tool",
+				Arguments: map[string]any{},
+			}},
+		}, nil
+	}
+
+	var artifactPath string
+	for i := len(messages) - 1; i >= 0; i-- {
+		if messages[i].Role != "tool" {
+			continue
+		}
+		start := strings.Index(messages[i].Content, "[file:")
+		if start < 0 {
+			continue
+		}
+		rest := messages[i].Content[start+len("[file:"):]
+		end := strings.Index(rest, "]")
+		if end < 0 {
+			continue
+		}
+		artifactPath = rest[:end]
+		break
+	}
+	if artifactPath == "" {
+		return nil, fmt.Errorf("provider did not receive artifact path in tool result")
+	}
+
+	return &providers.LLMResponse{
+		Content: "",
+		ToolCalls: []providers.ToolCall{{
+			ID:        "call_send_file",
+			Type:      "function",
+			Name:      "send_file",
+			Arguments: map[string]any{"path": artifactPath},
+		}},
+	}, nil
+}
+
+func (m *artifactThenSendProvider) GetDefaultModel() string {
+	return "artifact-then-send-model"
+}
+
+type toolLimitOnlyProvider struct{}
+
+func (m *toolLimitOnlyProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	return &providers.LLMResponse{
+		ToolCalls: []providers.ToolCall{{
+			ID:        "call_tool_limit_test",
+			Type:      "function",
+			Name:      "tool_limit_test_tool",
+			Arguments: map[string]any{"value": "x"},
+		}},
+	}, nil
+}
+
+func (m *toolLimitOnlyProvider) GetDefaultModel() string {
+	return "tool-limit-only-model"
+}
+
 // mockCustomTool is a simple mock tool for registration testing
 type mockCustomTool struct{}
 
@@ -380,8 +1054,9 @@ func (m *mockCustomTool) Description() string {
 
 func (m *mockCustomTool) Parameters() map[string]any {
 	return map[string]any{
-		"type":       "object",
-		"properties": map[string]any{},
+		"type":                 "object",
+		"properties":           map[string]any{},
+		"additionalProperties": true,
 	}
 }
 
@@ -389,34 +1064,156 @@ func (m *mockCustomTool) Execute(ctx context.Context, args map[string]any) *tool
 	return tools.SilentResult("Custom tool executed")
 }
 
-// mockContextualTool tracks context updates
-type mockContextualTool struct {
-	lastChannel string
-	lastChatID  string
+type handledMediaTool struct {
+	store media.MediaStore
+	path  string
 }
 
-func (m *mockContextualTool) Name() string {
-	return "mock_contextual"
+func (m *handledMediaTool) Name() string { return "handled_media_tool" }
+func (m *handledMediaTool) Description() string {
+	return "Returns a media attachment and fully handles the user response"
 }
 
-func (m *mockContextualTool) Description() string {
-	return "Mock contextual tool"
-}
-
-func (m *mockContextualTool) Parameters() map[string]any {
+func (m *handledMediaTool) Parameters() map[string]any {
 	return map[string]any{
 		"type":       "object",
 		"properties": map[string]any{},
 	}
 }
 
-func (m *mockContextualTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
-	return tools.SilentResult("Contextual tool executed")
+func (m *handledMediaTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+	ref, err := m.store.Store(m.path, media.MediaMeta{
+		Filename:    filepath.Base(m.path),
+		ContentType: "image/png",
+		Source:      "test:handled_media_tool",
+	}, "test:handled_media")
+	if err != nil {
+		return tools.ErrorResult(err.Error()).WithError(err)
+	}
+	return tools.MediaResult("Attachment delivered by tool.", []string{ref}).WithResponseHandled()
 }
 
-func (m *mockContextualTool) SetContext(channel, chatID string) {
-	m.lastChannel = channel
-	m.lastChatID = chatID
+type handledMediaWithSteeringProvider struct {
+	calls int
+}
+
+func (m *handledMediaWithSteeringProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	m.calls++
+	if m.calls == 1 {
+		return &providers.LLMResponse{
+			Content: "Taking the screenshot now.",
+			ToolCalls: []providers.ToolCall{{
+				ID:        "call_handled_media_steering",
+				Type:      "function",
+				Name:      "handled_media_with_steering_tool",
+				Arguments: map[string]any{},
+			}},
+		}, nil
+	}
+
+	for _, msg := range messages {
+		if msg.Role == "user" && msg.Content == "what about this instead?" {
+			return &providers.LLMResponse{Content: "Handled the queued steering message."}, nil
+		}
+	}
+
+	return nil, fmt.Errorf("provider did not receive queued steering message")
+}
+
+func (m *handledMediaWithSteeringProvider) GetDefaultModel() string {
+	return "handled-media-with-steering-model"
+}
+
+type handledMediaWithSteeringTool struct {
+	store media.MediaStore
+	path  string
+	loop  *AgentLoop
+}
+
+func (m *handledMediaWithSteeringTool) Name() string { return "handled_media_with_steering_tool" }
+func (m *handledMediaWithSteeringTool) Description() string {
+	return "Returns handled media and enqueues a steering message during execution"
+}
+
+func (m *handledMediaWithSteeringTool) Parameters() map[string]any {
+	return map[string]any{
+		"type":       "object",
+		"properties": map[string]any{},
+	}
+}
+
+func (m *handledMediaWithSteeringTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+	if err := m.loop.Steer(providers.Message{Role: "user", Content: "what about this instead?"}); err != nil {
+		return tools.ErrorResult(err.Error()).WithError(err)
+	}
+
+	ref, err := m.store.Store(m.path, media.MediaMeta{
+		Filename:    filepath.Base(m.path),
+		ContentType: "image/png",
+		Source:      "test:handled_media_with_steering_tool",
+	}, "test:handled_media_with_steering")
+	if err != nil {
+		return tools.ErrorResult(err.Error()).WithError(err)
+	}
+	return tools.MediaResult("Attachment delivered by tool.", []string{ref}).WithResponseHandled()
+}
+
+type mediaArtifactTool struct {
+	store media.MediaStore
+	path  string
+}
+
+func (m *mediaArtifactTool) Name() string { return "media_artifact_tool" }
+func (m *mediaArtifactTool) Description() string {
+	return "Returns a media artifact that the agent can forward or save later"
+}
+
+func (m *mediaArtifactTool) Parameters() map[string]any {
+	return map[string]any{
+		"type":       "object",
+		"properties": map[string]any{},
+	}
+}
+
+func (m *mediaArtifactTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+	ref, err := m.store.Store(m.path, media.MediaMeta{
+		Filename:    filepath.Base(m.path),
+		ContentType: "image/png",
+		Source:      "test:media_artifact_tool",
+	}, "test:media_artifact")
+	if err != nil {
+		return tools.ErrorResult(err.Error()).WithError(err)
+	}
+	return tools.MediaResult("Artifact created.", []string{ref})
+}
+
+type toolLimitTestTool struct{}
+
+func (m *toolLimitTestTool) Name() string {
+	return "tool_limit_test_tool"
+}
+
+func (m *toolLimitTestTool) Description() string {
+	return "Tool used to exhaust the iteration budget in tests"
+}
+
+func (m *toolLimitTestTool) Parameters() map[string]any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"value": map[string]any{"type": "string"},
+		},
+	}
+}
+
+func (m *toolLimitTestTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+	return tools.SilentResult("tool limit test result")
 }
 
 // testHelper executes a message and returns the response
@@ -424,6 +1221,46 @@ type testHelper struct {
 	al *AgentLoop
 }
 
+func newChatCompletionTestServer(
+	t *testing.T,
+	label string,
+	response string,
+	calls *int,
+	model *string,
+) *httptest.Server {
+	t.Helper()
+
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/chat/completions" {
+			t.Fatalf("%s server path = %q, want /chat/completions", label, r.URL.Path)
+		}
+		*calls = *calls + 1
+		defer r.Body.Close()
+
+		var req struct {
+			Model string `json:"model"`
+		}
+		decodeErr := json.NewDecoder(r.Body).Decode(&req)
+		if decodeErr != nil {
+			t.Fatalf("decode %s request: %v", label, decodeErr)
+		}
+		*model = req.Model
+
+		w.Header().Set("Content-Type", "application/json")
+		encodeErr := json.NewEncoder(w).Encode(map[string]any{
+			"choices": []map[string]any{
+				{
+					"message":       map[string]any{"content": response},
+					"finish_reason": "stop",
+				},
+			},
+		})
+		if encodeErr != nil {
+			t.Fatalf("encode %s response: %v", label, encodeErr)
+		}
+	}))
+}
+
 func (h testHelper) executeAndGetResponse(tb testing.TB, ctx context.Context, msg bus.InboundMessage) string {
 	// Use a short timeout to avoid hanging
 	timeoutCtx, cancel := context.WithTimeout(ctx, responseTimeout)
@@ -438,6 +1275,415 @@ func (h testHelper) executeAndGetResponse(tb testing.TB, ctx context.Context, ms
 
 const responseTimeout = 3 * time.Second
 
+func TestProcessMessage_UsesRouteSessionKey(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &simpleMockProvider{response: "ok"}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	msg := bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "hello",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	}
+
+	route := al.registry.ResolveRoute(routing.RouteInput{
+		Channel: msg.Channel,
+		Peer:    extractPeer(msg),
+	})
+	sessionKey := route.SessionKey
+
+	defaultAgent := al.registry.GetDefaultAgent()
+	if defaultAgent == nil {
+		t.Fatal("No default agent found")
+	}
+
+	helper := testHelper{al: al}
+	_ = helper.executeAndGetResponse(t, context.Background(), msg)
+
+	history := defaultAgent.Sessions.GetHistory(sessionKey)
+	if len(history) != 2 {
+		t.Fatalf("expected session history len=2, got %d", len(history))
+	}
+	if history[0].Role != "user" || history[0].Content != "hello" {
+		t.Fatalf("unexpected first message in session: %+v", history[0])
+	}
+}
+
+func TestProcessMessage_CommandOutcomes(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+		Session: config.SessionConfig{
+			DMScope: "per-channel-peer",
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &countingMockProvider{response: "LLM reply"}
+	al := NewAgentLoop(cfg, msgBus, provider)
+	helper := testHelper{al: al}
+
+	baseMsg := bus.InboundMessage{
+		Channel:  "whatsapp",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	}
+
+	showResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+		Channel:  baseMsg.Channel,
+		SenderID: baseMsg.SenderID,
+		ChatID:   baseMsg.ChatID,
+		Content:  "/show channel",
+		Peer:     baseMsg.Peer,
+	})
+	if showResp != "Current Channel: whatsapp" {
+		t.Fatalf("unexpected /show reply: %q", showResp)
+	}
+	if provider.calls != 0 {
+		t.Fatalf("LLM should not be called for handled command, calls=%d", provider.calls)
+	}
+
+	fooResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+		Channel:  baseMsg.Channel,
+		SenderID: baseMsg.SenderID,
+		ChatID:   baseMsg.ChatID,
+		Content:  "/foo",
+		Peer:     baseMsg.Peer,
+	})
+	if fooResp != "LLM reply" {
+		t.Fatalf("unexpected /foo reply: %q", fooResp)
+	}
+	if provider.calls != 1 {
+		t.Fatalf("LLM should be called exactly once after /foo passthrough, calls=%d", provider.calls)
+	}
+
+	newResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+		Channel:  baseMsg.Channel,
+		SenderID: baseMsg.SenderID,
+		ChatID:   baseMsg.ChatID,
+		Content:  "/new",
+		Peer:     baseMsg.Peer,
+	})
+	if newResp != "LLM reply" {
+		t.Fatalf("unexpected /new reply: %q", newResp)
+	}
+	if provider.calls != 2 {
+		t.Fatalf("LLM should be called for passthrough /new command, calls=%d", provider.calls)
+	}
+}
+
+func TestProcessMessage_SwitchModelShowModelConsistency(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				Provider:          "openai",
+				ModelName:         "local",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{
+				ModelName: "local",
+				Model:     "openai/local-model",
+				APIBase:   "https://local.example.invalid/v1",
+			},
+			{
+				ModelName: "deepseek",
+				Model:     "openrouter/deepseek/deepseek-v3.2",
+				APIBase:   "https://openrouter.ai/api/v1",
+			},
+		},
+	}
+	cfg.WithSecurity(&config.SecurityConfig{
+		ModelList: map[string]config.ModelSecurityEntry{
+			"local": {
+				APIKeys: []string{"test-key"},
+			},
+			"deepseek": {
+				APIKeys: []string{"test-key"},
+			},
+		},
+	})
+
+	msgBus := bus.NewMessageBus()
+	provider := &countingMockProvider{response: "LLM reply"}
+	al := NewAgentLoop(cfg, msgBus, provider)
+	helper := testHelper{al: al}
+
+	switchResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "/switch model to deepseek",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	})
+	if !strings.Contains(switchResp, "Switched model from local to deepseek") {
+		t.Fatalf("unexpected /switch reply: %q", switchResp)
+	}
+
+	showResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "/show model",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	})
+	if !strings.Contains(showResp, "Current Model: deepseek (Provider: openrouter)") {
+		t.Fatalf("unexpected /show model reply after switch: %q", showResp)
+	}
+
+	if provider.calls != 0 {
+		t.Fatalf("LLM should not be called for /switch and /show, calls=%d", provider.calls)
+	}
+}
+
+func TestProcessMessage_SwitchModelRejectsUnknownAlias(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				Provider:          "openai",
+				ModelName:         "local",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{
+				ModelName: "local",
+				Model:     "openai/local-model",
+				APIBase:   "https://local.example.invalid/v1",
+			},
+		},
+	}
+	cfg.WithSecurity(&config.SecurityConfig{
+		ModelList: map[string]config.ModelSecurityEntry{
+			"local": {
+				APIKeys: []string{"test-key"},
+			},
+		},
+	})
+
+	msgBus := bus.NewMessageBus()
+	provider := &countingMockProvider{response: "LLM reply"}
+	al := NewAgentLoop(cfg, msgBus, provider)
+	helper := testHelper{al: al}
+
+	switchResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "/switch model to missing",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	})
+	if switchResp != `model "missing" not found in model_list or providers` {
+		t.Fatalf("unexpected /switch error reply: %q", switchResp)
+	}
+
+	showResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "/show model",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	})
+	if !strings.Contains(showResp, "Current Model: local (Provider: openai)") {
+		t.Fatalf("unexpected /show model reply after rejected switch: %q", showResp)
+	}
+
+	if provider.calls != 0 {
+		t.Fatalf("LLM should not be called for rejected /switch and /show, calls=%d", provider.calls)
+	}
+}
+
+func TestProcessMessage_SwitchModelRoutesSubsequentRequestsToSelectedProvider(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	localCalls := 0
+	localModel := ""
+	localServer := newChatCompletionTestServer(t, "local", "local reply", &localCalls, &localModel)
+	defer localServer.Close()
+
+	remoteCalls := 0
+	remoteModel := ""
+	remoteServer := newChatCompletionTestServer(t, "remote", "remote reply", &remoteCalls, &remoteModel)
+	defer remoteServer.Close()
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				Provider:          "openai",
+				ModelName:         "local",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+		ModelList: []*config.ModelConfig{
+			{
+				ModelName: "local",
+				Model:     "openai/Qwen3.5-35B-A3B",
+				APIBase:   localServer.URL,
+			},
+			{
+				ModelName: "deepseek",
+				Model:     "openrouter/deepseek/deepseek-v3.2",
+				APIBase:   remoteServer.URL,
+			},
+		},
+	}
+	cfg.WithSecurity(&config.SecurityConfig{
+		ModelList: map[string]config.ModelSecurityEntry{
+			"local": {
+				APIKeys: []string{"local-key"},
+			},
+			"deepseek": {
+				APIKeys: []string{"remote-key"},
+			},
+		},
+	})
+
+	msgBus := bus.NewMessageBus()
+	provider, _, err := providers.CreateProvider(cfg)
+	if err != nil {
+		t.Fatalf("CreateProvider() error = %v", err)
+	}
+	al := NewAgentLoop(cfg, msgBus, provider)
+	helper := testHelper{al: al}
+
+	firstResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "hello before switch",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	})
+	if firstResp != "local reply" {
+		t.Fatalf("unexpected response before switch: %q", firstResp)
+	}
+	if localCalls != 1 {
+		t.Fatalf("local calls before switch = %d, want 1", localCalls)
+	}
+	if remoteCalls != 0 {
+		t.Fatalf("remote calls before switch = %d, want 0", remoteCalls)
+	}
+	if localModel != "Qwen3.5-35B-A3B" {
+		t.Fatalf("local model before switch = %q, want %q", localModel, "Qwen3.5-35B-A3B")
+	}
+
+	switchResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "/switch model to deepseek",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	})
+	if !strings.Contains(switchResp, "Switched model from local to deepseek") {
+		t.Fatalf("unexpected /switch reply: %q", switchResp)
+	}
+
+	secondResp := helper.executeAndGetResponse(t, context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "hello after switch",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	})
+	if secondResp != "remote reply" {
+		t.Fatalf("unexpected response after switch: %q", secondResp)
+	}
+	if localCalls != 1 {
+		t.Fatalf("local calls after switch = %d, want 1", localCalls)
+	}
+	if remoteCalls != 1 {
+		t.Fatalf("remote calls after switch = %d, want 1", remoteCalls)
+	}
+	if remoteModel != "deepseek-v3.2" {
+		t.Fatalf(
+			"remote model after switch = %q, want %q",
+			remoteModel,
+			"deepseek-v3.2",
+		)
+	}
+}
+
 // TestToolResult_SilentToolDoesNotSendUserMessage verifies silent tools don't trigger outbound
 func TestToolResult_SilentToolDoesNotSendUserMessage(t *testing.T) {
 	tmpDir, err := os.MkdirTemp("", "agent-test-*")
@@ -450,7 +1696,7 @@ func TestToolResult_SilentToolDoesNotSendUserMessage(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
-				Model:             "test-model",
+				ModelName:         "test-model",
 				MaxTokens:         4096,
 				MaxToolIterations: 10,
 			},
@@ -492,7 +1738,7 @@ func TestToolResult_UserFacingToolDoesSendMessage(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
-				Model:             "test-model",
+				ModelName:         "test-model",
 				MaxTokens:         4096,
 				MaxToolIterations: 10,
 			},
@@ -563,7 +1809,7 @@ func TestAgentLoop_ContextExhaustionRetry(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
-				Model:             "test-model",
+				ModelName:         "test-model",
 				MaxTokens:         4096,
 				MaxToolIterations: 10,
 			},
@@ -582,11 +1828,11 @@ func TestAgentLoop_ContextExhaustionRetry(t *testing.T) {
 
 	al := NewAgentLoop(cfg, msgBus, provider)
 
-	// Inject some history to simulate a full context
+	// Inject some history to simulate a full context.
+	// Session history only stores user/assistant/tool messages — the system
+	// prompt is built dynamically by BuildMessages and is NOT stored here.
 	sessionKey := "test-session-context"
-	// Create dummy history
 	history := []providers.Message{
-		{Role: "system", Content: "System prompt"},
 		{Role: "user", Content: "Old message 1"},
 		{Role: "assistant", Content: "Old response 1"},
 		{Role: "user", Content: "Old message 2"},
@@ -624,12 +1870,151 @@ func TestAgentLoop_ContextExhaustionRetry(t *testing.T) {
 	// Check final history length
 	finalHistory := defaultAgent.Sessions.GetHistory(sessionKey)
 	// We verify that the history has been modified (compressed)
-	// Original length: 6
-	// Expected behavior: compression drops ~50% of history (mid slice)
-	// We can assert that the length is NOT what it would be without compression.
-	// Without compression: 6 + 1 (new user msg) + 1 (assistant msg) = 8
-	if len(finalHistory) >= 8 {
-		t.Errorf("Expected history to be compressed (len < 8), got %d", len(finalHistory))
+	// Original length: 5
+	// Expected behavior: compression drops ~50% of Turns
+	// Without compression: 5 + 1 (new user msg) + 1 (assistant msg) = 7
+	if len(finalHistory) >= 7 {
+		t.Errorf("Expected history to be compressed (len < 7), got %d", len(finalHistory))
+	}
+}
+
+func TestAgentLoop_EmptyModelResponseUsesAccurateFallback(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 3,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &simpleMockProvider{response: ""}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	response, err := al.ProcessDirectWithChannel(context.Background(), "hello", "empty-response", "test", "chat1")
+	if err != nil {
+		t.Fatalf("ProcessDirectWithChannel failed: %v", err)
+	}
+	if response != defaultResponse {
+		t.Fatalf("response = %q, want %q", response, defaultResponse)
+	}
+}
+
+func TestAgentLoop_ToolLimitUsesDedicatedFallback(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 1,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &toolLimitOnlyProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+	al.RegisterTool(&toolLimitTestTool{})
+
+	response, err := al.ProcessDirectWithChannel(context.Background(), "hello", "tool-limit", "test", "chat1")
+	if err != nil {
+		t.Fatalf("ProcessDirectWithChannel failed: %v", err)
+	}
+	if response != toolLimitResponse {
+		t.Fatalf("response = %q, want %q", response, toolLimitResponse)
+	}
+
+	defaultAgent := al.registry.GetDefaultAgent()
+	if defaultAgent == nil {
+		t.Fatal("No default agent found")
+	}
+	route := al.registry.ResolveRoute(routing.RouteInput{
+		Channel: "test",
+		Peer: &routing.RoutePeer{
+			Kind: "direct",
+			ID:   "cron",
+		},
+	})
+	history := defaultAgent.Sessions.GetHistory(route.SessionKey)
+	if len(history) != 4 {
+		t.Fatalf("history len = %d, want 4", len(history))
+	}
+	assertRoles(t, history, "user", "assistant", "tool", "assistant")
+	if history[3].Content != toolLimitResponse {
+		t.Fatalf("final assistant content = %q, want %q", history[3].Content, toolLimitResponse)
+	}
+}
+
+// TestProcessDirectWithChannel_TriggersMCPInitialization verifies that
+// ProcessDirectWithChannel triggers MCP initialization when MCP is enabled.
+// Note: Manager is only initialized when at least one MCP server is configured
+// and successfully connected.
+func TestProcessDirectWithChannel_TriggersMCPInitialization(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	// Test with MCP enabled but no servers - should not initialize manager
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+		Tools: config.ToolsConfig{
+			MCP: config.MCPConfig{
+				ToolConfig: config.ToolConfig{
+					Enabled: true,
+				},
+				// No servers configured - manager should not be initialized
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &mockProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+	defer al.Close()
+
+	if al.mcp.hasManager() {
+		t.Fatal("expected MCP manager to be nil before first direct processing")
+	}
+
+	_, err = al.ProcessDirectWithChannel(
+		context.Background(),
+		"hello",
+		"session-1",
+		"cli",
+		"direct",
+	)
+	if err != nil {
+		t.Fatalf("ProcessDirectWithChannel failed: %v", err)
+	}
+
+	// Manager should not be initialized when no servers are configured
+	if al.mcp.hasManager() {
+		t.Fatal("expected MCP manager to be nil when no servers are configured")
 	}
 }
 
@@ -644,7 +2029,7 @@ func TestTargetReasoningChannelID_AllChannels(t *testing.T) {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         tmpDir,
-				Model:             "test-model",
+				ModelName:         "test-model",
 				MaxTokens:         4096,
 				MaxToolIterations: 10,
 			},
@@ -657,18 +2042,17 @@ func TestTargetReasoningChannelID_AllChannels(t *testing.T) {
 		t.Fatalf("Failed to create channel manager: %v", err)
 	}
 	for name, id := range map[string]string{
-		"whatsapp":  "rid-whatsapp",
-		"telegram":  "rid-telegram",
-		"feishu":    "rid-feishu",
-		"discord":   "rid-discord",
-		"maixcam":   "rid-maixcam",
-		"qq":        "rid-qq",
-		"dingtalk":  "rid-dingtalk",
-		"slack":     "rid-slack",
-		"line":      "rid-line",
-		"onebot":    "rid-onebot",
-		"wecom":     "rid-wecom",
-		"wecom_app": "rid-wecom-app",
+		"whatsapp": "rid-whatsapp",
+		"telegram": "rid-telegram",
+		"feishu":   "rid-feishu",
+		"discord":  "rid-discord",
+		"maixcam":  "rid-maixcam",
+		"qq":       "rid-qq",
+		"dingtalk": "rid-dingtalk",
+		"slack":    "rid-slack",
+		"line":     "rid-line",
+		"onebot":   "rid-onebot",
+		"wecom":    "rid-wecom",
 	} {
 		chManager.RegisterChannel(name, &fakeChannel{id: id})
 	}
@@ -688,7 +2072,6 @@ func TestTargetReasoningChannelID_AllChannels(t *testing.T) {
 		{channel: "line", wantID: "rid-line"},
 		{channel: "onebot", wantID: "rid-onebot"},
 		{channel: "wecom", wantID: "rid-wecom"},
-		{channel: "wecom_app", wantID: "rid-wecom-app"},
 		{channel: "unknown", wantID: ""},
 	}
 
@@ -714,7 +2097,7 @@ func TestHandleReasoning(t *testing.T) {
 			Agents: config.AgentsConfig{
 				Defaults: config.AgentDefaults{
 					Workspace:         tmpDir,
-					Model:             "test-model",
+					ModelName:         "test-model",
 					MaxTokens:         4096,
 					MaxToolIterations: 10,
 				},
@@ -728,10 +2111,25 @@ func TestHandleReasoning(t *testing.T) {
 		al, msgBus := newLoop(t)
 		al.handleReasoning(context.Background(), "reasoning", "telegram", "")
 
-		ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+		ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
 		defer cancel()
-		if msg, ok := msgBus.SubscribeOutbound(ctx); ok {
-			t.Fatalf("expected no outbound message, got %+v", msg)
+		for {
+			select {
+			case msg, ok := <-msgBus.OutboundChan():
+				if !ok {
+					t.Fatalf("expected no outbound message, got %+v", msg)
+				}
+				if msg.Content == "reasoning" {
+					t.Fatalf("expected no message for empty chatID, got %+v", msg)
+				}
+				return
+			case <-ctx.Done():
+				t.Log("expected an outbound message, got none within timeout")
+				return
+			default:
+				// Continue to check for message
+				time.Sleep(5 * time.Millisecond) // Avoid busy loop
+			}
 		}
 	})
 
@@ -739,9 +2137,7 @@ func TestHandleReasoning(t *testing.T) {
 		al, msgBus := newLoop(t)
 		al.handleReasoning(context.Background(), "hello reasoning", "slack", "channel-1")
 
-		ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
-		defer cancel()
-		msg, ok := msgBus.SubscribeOutbound(ctx)
+		msg, ok := <-msgBus.OutboundChan()
 		if !ok {
 			t.Fatal("expected an outbound message")
 		}
@@ -755,35 +2151,52 @@ func TestHandleReasoning(t *testing.T) {
 		reasoning := "hello telegram reasoning"
 		al.handleReasoning(context.Background(), reasoning, "telegram", "tg-chat")
 
-		ctx, cancel := context.WithTimeout(context.Background(), 200*time.Millisecond)
+		ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
 		defer cancel()
-		msg, ok := msgBus.SubscribeOutbound(ctx)
-		if !ok {
-			t.Fatal("expected outbound message")
-		}
+		for {
+			select {
+			case <-ctx.Done():
+				t.Fatal("expected an outbound message, got none within timeout")
+				return
+			case msg, ok := <-msgBus.OutboundChan():
+				if !ok {
+					t.Fatal("expected outbound message")
+				}
 
-		if msg.Channel != "telegram" {
-			t.Fatalf("expected telegram channel message, got %+v", msg)
-		}
-		if msg.ChatID != "tg-chat" {
-			t.Fatalf("expected chatID tg-chat, got %+v", msg)
-		}
-		if msg.Content != reasoning {
-			t.Fatalf("content mismatch: got %q want %q", msg.Content, reasoning)
+				if msg.Channel != "telegram" {
+					t.Fatalf("expected telegram channel message, got %+v", msg)
+				}
+				if msg.ChatID != "tg-chat" {
+					t.Fatalf("expected chatID tg-chat, got %+v", msg)
+				}
+				if msg.Content != reasoning {
+					t.Fatalf("content mismatch: got %q want %q", msg.Content, reasoning)
+				}
+				return
+			}
 		}
 	})
 	t.Run("expired ctx", func(t *testing.T) {
 		al, msgBus := newLoop(t)
 		reasoning := "hello telegram reasoning"
-		ctx, cancel := context.WithCancel(context.Background())
-		cancel()
-		al.handleReasoning(ctx, reasoning, "telegram", "tg-chat")
 
-		ctx, cancel = context.WithTimeout(context.Background(), 200*time.Millisecond)
-		defer cancel()
-		msg, ok := msgBus.SubscribeOutbound(ctx)
-		if ok {
-			t.Fatalf("expected no outbound message, got %+v", msg)
+		al.handleReasoning(context.Background(), reasoning, "telegram", "tg-chat")
+
+		consumeCtx, consumeCancel := context.WithTimeout(context.Background(), 2*time.Second)
+		defer consumeCancel()
+
+		for {
+			select {
+			case msg, ok := <-msgBus.OutboundChan():
+				if !ok {
+					t.Fatalf("expected no outbound message, but received: %+v", msg)
+				}
+				t.Logf("Received unexpected outbound message: %+v", msg)
+				return
+			case <-consumeCtx.Done():
+				t.Fatalf("failed: no message received within timeout")
+				return
+			}
 		}
 	})
 
@@ -823,20 +2236,444 @@ func TestHandleReasoning(t *testing.T) {
 
 		// Drain the bus and verify the reasoning message was NOT published
 		// (it should have been dropped due to timeout).
-		drainCtx, drainCancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
-		defer drainCancel()
-		foundReasoning := false
+		timeer := time.After(1 * time.Second)
 		for {
-			msg, ok := msgBus.SubscribeOutbound(drainCtx)
-			if !ok {
-				break
+			select {
+			case <-timeer:
+				t.Logf(
+					"no reasoning message received after draining bus for 1s, as expected,length=%d",
+					len(msgBus.OutboundChan()),
+				)
+				return
+			case msg, ok := <-msgBus.OutboundChan():
+				if !ok {
+					break
+				}
+				if msg.Content == "should timeout" {
+					t.Fatal("expected reasoning message to be dropped when bus is full, but it was published")
+				}
 			}
-			if msg.Content == "should timeout" {
-				foundReasoning = true
-			}
-		}
-		if foundReasoning {
-			t.Fatal("expected reasoning message to be dropped when bus is full, but it was published")
 		}
 	})
 }
+
+func TestProcessMessage_PublishesReasoningContentToReasoningChannel(t *testing.T) {
+	tmpDir := t.TempDir()
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &reasoningContentProvider{
+		response:         "final answer",
+		reasoningContent: "thinking trace",
+	}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	chManager, err := channels.NewManager(&config.Config{}, msgBus, nil)
+	if err != nil {
+		t.Fatalf("Failed to create channel manager: %v", err)
+	}
+	chManager.RegisterChannel("telegram", &fakeChannel{id: "reason-chat"})
+	al.SetChannelManager(chManager)
+
+	response, err := al.processMessage(context.Background(), bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "hello",
+	})
+	if err != nil {
+		t.Fatalf("processMessage() error = %v", err)
+	}
+	if response != "final answer" {
+		t.Fatalf("processMessage() response = %q, want %q", response, "final answer")
+	}
+
+	select {
+	case outbound := <-msgBus.OutboundChan():
+		if outbound.Channel != "telegram" {
+			t.Fatalf("reasoning channel = %q, want %q", outbound.Channel, "telegram")
+		}
+		if outbound.ChatID != "reason-chat" {
+			t.Fatalf("reasoning chatID = %q, want %q", outbound.ChatID, "reason-chat")
+		}
+		if outbound.Content != "thinking trace" {
+			t.Fatalf("reasoning content = %q, want %q", outbound.Content, "thinking trace")
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("expected reasoning content to be published to reasoning channel")
+	}
+}
+
+func TestResolveMediaRefs_ResolvesToBase64(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	// Create a minimal valid PNG (8-byte header is enough for filetype detection)
+	pngPath := filepath.Join(dir, "test.png")
+	// PNG magic: 0x89 P N G \r \n 0x1A \n + minimal IHDR
+	pngHeader := []byte{
+		0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, // PNG signature
+		0x00, 0x00, 0x00, 0x0D, // IHDR length
+		0x49, 0x48, 0x44, 0x52, // "IHDR"
+		0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x02, // 1x1 RGB
+		0x00, 0x00, 0x00, // no interlace
+		0x90, 0x77, 0x53, 0xDE, // CRC
+	}
+	if err := os.WriteFile(pngPath, pngHeader, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	ref, err := store.Store(pngPath, media.MediaMeta{}, "test")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	messages := []providers.Message{
+		{Role: "user", Content: "describe this", Media: []string{ref}},
+	}
+	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
+
+	if len(result[0].Media) != 1 {
+		t.Fatalf("expected 1 resolved media, got %d", len(result[0].Media))
+	}
+	if !strings.HasPrefix(result[0].Media[0], "data:image/png;base64,") {
+		t.Fatalf("expected data:image/png;base64, prefix, got %q", result[0].Media[0][:40])
+	}
+}
+
+func TestResolveMediaRefs_SkipsOversizedFile(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	bigPath := filepath.Join(dir, "big.png")
+	// Write PNG header + padding to exceed limit
+	data := make([]byte, 1024+1) // 1KB + 1 byte
+	copy(data, []byte{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A})
+	if err := os.WriteFile(bigPath, data, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	ref, _ := store.Store(bigPath, media.MediaMeta{}, "test")
+
+	messages := []providers.Message{
+		{Role: "user", Content: "hi", Media: []string{ref}},
+	}
+	// Use a tiny limit (1KB) so the file is oversized
+	result := resolveMediaRefs(messages, store, 1024)
+
+	if len(result[0].Media) != 0 {
+		t.Fatalf("expected 0 media (oversized), got %d", len(result[0].Media))
+	}
+}
+
+func TestResolveMediaRefs_UnknownTypeInjectsPath(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	txtPath := filepath.Join(dir, "readme.txt")
+	if err := os.WriteFile(txtPath, []byte("hello world"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	ref, _ := store.Store(txtPath, media.MediaMeta{}, "test")
+
+	messages := []providers.Message{
+		{Role: "user", Content: "hi", Media: []string{ref}},
+	}
+	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
+
+	if len(result[0].Media) != 0 {
+		t.Fatalf("expected 0 media entries, got %d", len(result[0].Media))
+	}
+	expected := "hi [file:" + txtPath + "]"
+	if result[0].Content != expected {
+		t.Fatalf("expected content %q, got %q", expected, result[0].Content)
+	}
+}
+
+func TestResolveMediaRefs_PassesThroughNonMediaRefs(t *testing.T) {
+	messages := []providers.Message{
+		{Role: "user", Content: "hi", Media: []string{"https://example.com/img.png"}},
+	}
+	result := resolveMediaRefs(messages, nil, config.DefaultMaxMediaSize)
+
+	if len(result[0].Media) != 1 || result[0].Media[0] != "https://example.com/img.png" {
+		t.Fatalf("expected passthrough of non-media:// URL, got %v", result[0].Media)
+	}
+}
+
+func TestResolveMediaRefs_DoesNotMutateOriginal(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+	pngPath := filepath.Join(dir, "test.png")
+	pngHeader := []byte{
+		0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A,
+		0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52,
+		0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x02,
+		0x00, 0x00, 0x00, 0x90, 0x77, 0x53, 0xDE,
+	}
+	os.WriteFile(pngPath, pngHeader, 0o644)
+	ref, _ := store.Store(pngPath, media.MediaMeta{}, "test")
+
+	original := []providers.Message{
+		{Role: "user", Content: "hi", Media: []string{ref}},
+	}
+	originalRef := original[0].Media[0]
+
+	resolveMediaRefs(original, store, config.DefaultMaxMediaSize)
+
+	if original[0].Media[0] != originalRef {
+		t.Fatal("resolveMediaRefs mutated original message slice")
+	}
+}
+
+func TestResolveMediaRefs_UsesMetaContentType(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	// File with JPEG content but stored with explicit content type
+	jpegPath := filepath.Join(dir, "photo")
+	jpegHeader := []byte{0xFF, 0xD8, 0xFF, 0xE0} // JPEG magic bytes
+	os.WriteFile(jpegPath, jpegHeader, 0o644)
+	ref, _ := store.Store(jpegPath, media.MediaMeta{ContentType: "image/jpeg"}, "test")
+
+	messages := []providers.Message{
+		{Role: "user", Content: "hi", Media: []string{ref}},
+	}
+	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
+
+	if len(result[0].Media) != 1 {
+		t.Fatalf("expected 1 media, got %d", len(result[0].Media))
+	}
+	if !strings.HasPrefix(result[0].Media[0], "data:image/jpeg;base64,") {
+		t.Fatalf("expected jpeg prefix, got %q", result[0].Media[0][:30])
+	}
+}
+
+func TestResolveMediaRefs_PDFInjectsFilePath(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	pdfPath := filepath.Join(dir, "report.pdf")
+	// PDF magic bytes
+	os.WriteFile(pdfPath, []byte("%PDF-1.4 test content"), 0o644)
+	ref, _ := store.Store(pdfPath, media.MediaMeta{ContentType: "application/pdf"}, "test")
+
+	messages := []providers.Message{
+		{Role: "user", Content: "report.pdf [file]", Media: []string{ref}},
+	}
+	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
+
+	if len(result[0].Media) != 0 {
+		t.Fatalf("expected 0 media (non-image), got %d", len(result[0].Media))
+	}
+	expected := "report.pdf [file:" + pdfPath + "]"
+	if result[0].Content != expected {
+		t.Fatalf("expected content %q, got %q", expected, result[0].Content)
+	}
+}
+
+func TestResolveMediaRefs_AudioInjectsAudioPath(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	oggPath := filepath.Join(dir, "voice.ogg")
+	os.WriteFile(oggPath, []byte("fake audio"), 0o644)
+	ref, _ := store.Store(oggPath, media.MediaMeta{ContentType: "audio/ogg"}, "test")
+
+	messages := []providers.Message{
+		{Role: "user", Content: "voice.ogg [audio]", Media: []string{ref}},
+	}
+	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
+
+	if len(result[0].Media) != 0 {
+		t.Fatalf("expected 0 media, got %d", len(result[0].Media))
+	}
+	expected := "voice.ogg [audio:" + oggPath + "]"
+	if result[0].Content != expected {
+		t.Fatalf("expected content %q, got %q", expected, result[0].Content)
+	}
+}
+
+func TestResolveMediaRefs_VideoInjectsVideoPath(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	mp4Path := filepath.Join(dir, "clip.mp4")
+	os.WriteFile(mp4Path, []byte("fake video"), 0o644)
+	ref, _ := store.Store(mp4Path, media.MediaMeta{ContentType: "video/mp4"}, "test")
+
+	messages := []providers.Message{
+		{Role: "user", Content: "clip.mp4 [video]", Media: []string{ref}},
+	}
+	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
+
+	if len(result[0].Media) != 0 {
+		t.Fatalf("expected 0 media, got %d", len(result[0].Media))
+	}
+	expected := "clip.mp4 [video:" + mp4Path + "]"
+	if result[0].Content != expected {
+		t.Fatalf("expected content %q, got %q", expected, result[0].Content)
+	}
+}
+
+func TestResolveMediaRefs_NoGenericTagAppendsPath(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	csvPath := filepath.Join(dir, "data.csv")
+	os.WriteFile(csvPath, []byte("a,b,c"), 0o644)
+	ref, _ := store.Store(csvPath, media.MediaMeta{ContentType: "text/csv"}, "test")
+
+	messages := []providers.Message{
+		{Role: "user", Content: "here is my data", Media: []string{ref}},
+	}
+	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
+
+	expected := "here is my data [file:" + csvPath + "]"
+	if result[0].Content != expected {
+		t.Fatalf("expected content %q, got %q", expected, result[0].Content)
+	}
+}
+
+func TestResolveMediaRefs_EmptyContentGetsPathTag(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	docPath := filepath.Join(dir, "doc.docx")
+	os.WriteFile(docPath, []byte("fake docx"), 0o644)
+	docxMIME := "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+	ref, _ := store.Store(docPath, media.MediaMeta{ContentType: docxMIME}, "test")
+
+	messages := []providers.Message{
+		{Role: "user", Content: "", Media: []string{ref}},
+	}
+	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
+
+	expected := "[file:" + docPath + "]"
+	if result[0].Content != expected {
+		t.Fatalf("expected content %q, got %q", expected, result[0].Content)
+	}
+}
+
+func TestResolveMediaRefs_MixedImageAndFile(t *testing.T) {
+	store := media.NewFileMediaStore()
+	dir := t.TempDir()
+
+	pngPath := filepath.Join(dir, "photo.png")
+	pngHeader := []byte{
+		0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A,
+		0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52,
+		0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x02,
+		0x00, 0x00, 0x00, 0x90, 0x77, 0x53, 0xDE,
+	}
+	os.WriteFile(pngPath, pngHeader, 0o644)
+	imgRef, _ := store.Store(pngPath, media.MediaMeta{}, "test")
+
+	pdfPath := filepath.Join(dir, "report.pdf")
+	os.WriteFile(pdfPath, []byte("%PDF-1.4 test"), 0o644)
+	fileRef, _ := store.Store(pdfPath, media.MediaMeta{ContentType: "application/pdf"}, "test")
+
+	messages := []providers.Message{
+		{Role: "user", Content: "check these [file]", Media: []string{imgRef, fileRef}},
+	}
+	result := resolveMediaRefs(messages, store, config.DefaultMaxMediaSize)
+
+	if len(result[0].Media) != 1 {
+		t.Fatalf("expected 1 media (image only), got %d", len(result[0].Media))
+	}
+	if !strings.HasPrefix(result[0].Media[0], "data:image/png;base64,") {
+		t.Fatal("expected image to be base64 encoded")
+	}
+	expectedContent := "check these [file:" + pdfPath + "]"
+	if result[0].Content != expectedContent {
+		t.Fatalf("expected content %q, got %q", expectedContent, result[0].Content)
+	}
+}
+
+// --- Native search helper tests ---
+
+type nativeSearchProvider struct {
+	supported bool
+}
+
+func (p *nativeSearchProvider) Chat(
+	ctx context.Context, msgs []providers.Message, tools []providers.ToolDefinition,
+	model string, opts map[string]any,
+) (*providers.LLMResponse, error) {
+	return &providers.LLMResponse{Content: "ok"}, nil
+}
+
+func (p *nativeSearchProvider) GetDefaultModel() string { return "test-model" }
+
+func (p *nativeSearchProvider) SupportsNativeSearch() bool { return p.supported }
+
+type plainProvider struct{}
+
+func (p *plainProvider) Chat(
+	ctx context.Context, msgs []providers.Message, tools []providers.ToolDefinition,
+	model string, opts map[string]any,
+) (*providers.LLMResponse, error) {
+	return &providers.LLMResponse{Content: "ok"}, nil
+}
+
+func (p *plainProvider) GetDefaultModel() string { return "test-model" }
+
+func TestIsNativeSearchProvider_Supported(t *testing.T) {
+	if !isNativeSearchProvider(&nativeSearchProvider{supported: true}) {
+		t.Fatal("expected true for provider that supports native search")
+	}
+}
+
+func TestIsNativeSearchProvider_NotSupported(t *testing.T) {
+	if isNativeSearchProvider(&nativeSearchProvider{supported: false}) {
+		t.Fatal("expected false for provider that does not support native search")
+	}
+}
+
+func TestIsNativeSearchProvider_NoInterface(t *testing.T) {
+	if isNativeSearchProvider(&plainProvider{}) {
+		t.Fatal("expected false for provider that does not implement NativeSearchCapable")
+	}
+}
+
+func TestFilterClientWebSearch_RemovesWebSearch(t *testing.T) {
+	defs := []providers.ToolDefinition{
+		{Type: "function", Function: providers.ToolFunctionDefinition{Name: "web_search"}},
+		{Type: "function", Function: providers.ToolFunctionDefinition{Name: "read_file"}},
+		{Type: "function", Function: providers.ToolFunctionDefinition{Name: "exec"}},
+	}
+	result := filterClientWebSearch(defs)
+	if len(result) != 2 {
+		t.Fatalf("len(result) = %d, want 2", len(result))
+	}
+	for _, td := range result {
+		if td.Function.Name == "web_search" {
+			t.Fatal("web_search should be filtered out")
+		}
+	}
+}
+
+func TestFilterClientWebSearch_NoWebSearch(t *testing.T) {
+	defs := []providers.ToolDefinition{
+		{Type: "function", Function: providers.ToolFunctionDefinition{Name: "read_file"}},
+		{Type: "function", Function: providers.ToolFunctionDefinition{Name: "exec"}},
+	}
+	result := filterClientWebSearch(defs)
+	if len(result) != 2 {
+		t.Fatalf("len(result) = %d, want 2", len(result))
+	}
+}
+
+func TestFilterClientWebSearch_EmptyInput(t *testing.T) {
+	result := filterClientWebSearch(nil)
+	if len(result) != 0 {
+		t.Fatalf("len(result) = %d, want 0", len(result))
+	}
+}
diff --git a/pkg/agent/model_resolution.go b/pkg/agent/model_resolution.go
new file mode 100644
index 000000000..140cff718
--- /dev/null
+++ b/pkg/agent/model_resolution.go
@@ -0,0 +1,97 @@
+package agent
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func buildModelListResolver(cfg *config.Config) func(raw string) (string, bool) {
+	ensureProtocol := func(model string) string {
+		model = strings.TrimSpace(model)
+		if model == "" {
+			return ""
+		}
+		if strings.Contains(model, "/") {
+			return model
+		}
+		return "openai/" + model
+	}
+
+	return func(raw string) (string, bool) {
+		raw = strings.TrimSpace(raw)
+		if raw == "" || cfg == nil {
+			return "", false
+		}
+
+		if mc, err := cfg.GetModelConfig(raw); err == nil && mc != nil && strings.TrimSpace(mc.Model) != "" {
+			return ensureProtocol(mc.Model), true
+		}
+
+		for i := range cfg.ModelList {
+			fullModel := strings.TrimSpace(cfg.ModelList[i].Model)
+			if fullModel == "" {
+				continue
+			}
+			if fullModel == raw {
+				return ensureProtocol(fullModel), true
+			}
+			_, modelID := providers.ExtractProtocol(fullModel)
+			if modelID == raw {
+				return ensureProtocol(fullModel), true
+			}
+		}
+
+		return "", false
+	}
+}
+
+func resolveModelCandidates(
+	cfg *config.Config,
+	defaultProvider string,
+	primary string,
+	fallbacks []string,
+) []providers.FallbackCandidate {
+	return providers.ResolveCandidatesWithLookup(
+		providers.ModelConfig{
+			Primary:   primary,
+			Fallbacks: fallbacks,
+		},
+		defaultProvider,
+		buildModelListResolver(cfg),
+	)
+}
+
+func resolvedCandidateModel(candidates []providers.FallbackCandidate, fallback string) string {
+	if len(candidates) > 0 && strings.TrimSpace(candidates[0].Model) != "" {
+		return candidates[0].Model
+	}
+	return fallback
+}
+
+func resolvedCandidateProvider(candidates []providers.FallbackCandidate, fallback string) string {
+	if len(candidates) > 0 && strings.TrimSpace(candidates[0].Provider) != "" {
+		return candidates[0].Provider
+	}
+	return fallback
+}
+
+func resolvedModelConfig(cfg *config.Config, modelName, workspace string) (*config.ModelConfig, error) {
+	if cfg == nil {
+		return nil, fmt.Errorf("config is nil")
+	}
+
+	modelCfg, err := cfg.GetModelConfig(strings.TrimSpace(modelName))
+	if err != nil {
+		return nil, err
+	}
+
+	clone := *modelCfg
+	if clone.Workspace == "" {
+		clone.Workspace = workspace
+	}
+
+	return &clone, nil
+}
diff --git a/pkg/agent/registry.go b/pkg/agent/registry.go
index 77b846832..58b7ce440 100644
--- a/pkg/agent/registry.go
+++ b/pkg/agent/registry.go
@@ -7,6 +7,7 @@ import (
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
 	"github.com/sipeed/picoclaw/pkg/routing"
+	"github.com/sipeed/picoclaw/pkg/tools"
 )
 
 // AgentRegistry manages multiple agent instances and routes messages to them.
@@ -100,6 +101,31 @@ func (r *AgentRegistry) CanSpawnSubagent(parentAgentID, targetAgentID string) bo
 	return false
 }
 
+// ForEachTool calls fn for every tool registered under the given name
+// across all agents. This is useful for propagating dependencies (e.g.
+// MediaStore) to tools after registry construction.
+func (r *AgentRegistry) ForEachTool(name string, fn func(tools.Tool)) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	for _, agent := range r.agents {
+		if t, ok := agent.Tools.Get(name); ok {
+			fn(t)
+		}
+	}
+}
+
+// Close releases resources held by all registered agents.
+func (r *AgentRegistry) Close() {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	for _, agent := range r.agents {
+		if err := agent.Close(); err != nil {
+			logger.WarnCF("agent", "Failed to close agent",
+				map[string]any{"agent_id": agent.ID, "error": err.Error()})
+		}
+	}
+}
+
 // GetDefaultAgent returns the default agent instance.
 func (r *AgentRegistry) GetDefaultAgent() *AgentInstance {
 	r.mu.RLock()
diff --git a/pkg/agent/registry_test.go b/pkg/agent/registry_test.go
index 518bb441f..b173ef967 100644
--- a/pkg/agent/registry_test.go
+++ b/pkg/agent/registry_test.go
@@ -29,7 +29,7 @@ func testCfg(agents []config.AgentConfig) *config.Config {
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace:         "/tmp/picoclaw-test-registry",
-				Model:             "gpt-4",
+				ModelName:         "gpt-4",
 				MaxTokens:         8192,
 				MaxToolIterations: 10,
 			},
diff --git a/pkg/agent/steering.go b/pkg/agent/steering.go
new file mode 100644
index 000000000..ad6613e8c
--- /dev/null
+++ b/pkg/agent/steering.go
@@ -0,0 +1,503 @@
+package agent
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/routing"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+// SteeringMode controls how queued steering messages are dequeued.
+type SteeringMode string
+
+const (
+	// SteeringOneAtATime dequeues only the first queued message per poll.
+	SteeringOneAtATime SteeringMode = "one-at-a-time"
+	// SteeringAll drains the entire queue in a single poll.
+	SteeringAll SteeringMode = "all"
+	// MaxQueueSize number of possible messages in the Steering Queue
+	MaxQueueSize = 10
+	// manualSteeringScope is the legacy fallback queue used when no active
+	// turn/session scope is available.
+	manualSteeringScope = "__manual__"
+)
+
+// parseSteeringMode normalizes a config string into a SteeringMode.
+func parseSteeringMode(s string) SteeringMode {
+	switch s {
+	case "all":
+		return SteeringAll
+	default:
+		return SteeringOneAtATime
+	}
+}
+
+// steeringQueue is a thread-safe queue of user messages that can be injected
+// into a running agent loop to interrupt it between tool calls.
+type steeringQueue struct {
+	mu     sync.Mutex
+	queues map[string][]providers.Message
+	mode   SteeringMode
+}
+
+func newSteeringQueue(mode SteeringMode) *steeringQueue {
+	return &steeringQueue{
+		queues: make(map[string][]providers.Message),
+		mode:   mode,
+	}
+}
+
+func normalizeSteeringScope(scope string) string {
+	scope = strings.TrimSpace(scope)
+	if scope == "" {
+		return manualSteeringScope
+	}
+	return scope
+}
+
+// push enqueues a steering message in the legacy fallback scope.
+func (sq *steeringQueue) push(msg providers.Message) error {
+	return sq.pushScope(manualSteeringScope, msg)
+}
+
+// pushScope enqueues a steering message for the provided scope.
+func (sq *steeringQueue) pushScope(scope string, msg providers.Message) error {
+	sq.mu.Lock()
+	defer sq.mu.Unlock()
+
+	scope = normalizeSteeringScope(scope)
+	queue := sq.queues[scope]
+	if len(queue) >= MaxQueueSize {
+		return fmt.Errorf("steering queue is full")
+	}
+	sq.queues[scope] = append(queue, msg)
+	return nil
+}
+
+// dequeue removes and returns pending steering messages from the legacy
+// fallback scope according to the configured mode.
+func (sq *steeringQueue) dequeue() []providers.Message {
+	return sq.dequeueScope(manualSteeringScope)
+}
+
+// dequeueScope removes and returns pending steering messages for the provided
+// scope according to the configured mode.
+func (sq *steeringQueue) dequeueScope(scope string) []providers.Message {
+	sq.mu.Lock()
+	defer sq.mu.Unlock()
+
+	return sq.dequeueLocked(normalizeSteeringScope(scope))
+}
+
+// dequeueScopeWithFallback drains the scoped queue first and falls back to the
+// legacy manual scope for backwards compatibility.
+func (sq *steeringQueue) dequeueScopeWithFallback(scope string) []providers.Message {
+	sq.mu.Lock()
+	defer sq.mu.Unlock()
+
+	scope = strings.TrimSpace(scope)
+	if scope != "" {
+		if msgs := sq.dequeueLocked(scope); len(msgs) > 0 {
+			return msgs
+		}
+	}
+
+	return sq.dequeueLocked(manualSteeringScope)
+}
+
+func (sq *steeringQueue) dequeueLocked(scope string) []providers.Message {
+	queue := sq.queues[scope]
+	if len(queue) == 0 {
+		return nil
+	}
+
+	switch sq.mode {
+	case SteeringAll:
+		msgs := append([]providers.Message(nil), queue...)
+		delete(sq.queues, scope)
+		return msgs
+	default:
+		msg := queue[0]
+		queue[0] = providers.Message{} // Clear reference for GC
+		queue = queue[1:]
+		if len(queue) == 0 {
+			delete(sq.queues, scope)
+		} else {
+			sq.queues[scope] = queue
+		}
+		return []providers.Message{msg}
+	}
+}
+
+// len returns the number of queued messages across all scopes.
+func (sq *steeringQueue) len() int {
+	sq.mu.Lock()
+	defer sq.mu.Unlock()
+
+	total := 0
+	for _, queue := range sq.queues {
+		total += len(queue)
+	}
+	return total
+}
+
+// lenScope returns the number of queued messages for a specific scope.
+func (sq *steeringQueue) lenScope(scope string) int {
+	sq.mu.Lock()
+	defer sq.mu.Unlock()
+	return len(sq.queues[normalizeSteeringScope(scope)])
+}
+
+// setMode updates the steering mode.
+func (sq *steeringQueue) setMode(mode SteeringMode) {
+	sq.mu.Lock()
+	defer sq.mu.Unlock()
+	sq.mode = mode
+}
+
+// getMode returns the current steering mode.
+func (sq *steeringQueue) getMode() SteeringMode {
+	sq.mu.Lock()
+	defer sq.mu.Unlock()
+	return sq.mode
+}
+
+// Steer enqueues a user message to be injected into the currently running
+// agent loop. The message will be picked up after the current tool finishes
+// executing, causing any remaining tool calls in the batch to be skipped.
+func (al *AgentLoop) Steer(msg providers.Message) error {
+	scope := ""
+	agentID := ""
+	if ts := al.getAnyActiveTurnState(); ts != nil {
+		scope = ts.sessionKey
+		agentID = ts.agentID
+	}
+	return al.enqueueSteeringMessage(scope, agentID, msg)
+}
+
+func (al *AgentLoop) enqueueSteeringMessage(scope, agentID string, msg providers.Message) error {
+	if al.steering == nil {
+		return fmt.Errorf("steering queue is not initialized")
+	}
+
+	if err := al.steering.pushScope(scope, msg); err != nil {
+		logger.WarnCF("agent", "Failed to enqueue steering message", map[string]any{
+			"error": err.Error(),
+			"role":  msg.Role,
+			"scope": normalizeSteeringScope(scope),
+		})
+		return err
+	}
+
+	queueDepth := al.steering.lenScope(scope)
+	logger.DebugCF("agent", "Steering message enqueued", map[string]any{
+		"role":        msg.Role,
+		"content_len": len(msg.Content),
+		"media_count": len(msg.Media),
+		"queue_len":   queueDepth,
+		"scope":       normalizeSteeringScope(scope),
+	})
+
+	meta := EventMeta{
+		Source:    "Steer",
+		TracePath: "turn.interrupt.received",
+	}
+	if ts := al.getAnyActiveTurnState(); ts != nil {
+		meta = ts.eventMeta("Steer", "turn.interrupt.received")
+	} else {
+		if strings.TrimSpace(agentID) != "" {
+			meta.AgentID = agentID
+		}
+		normalizedScope := normalizeSteeringScope(scope)
+		if normalizedScope != manualSteeringScope {
+			meta.SessionKey = normalizedScope
+		}
+		if meta.AgentID == "" {
+			if registry := al.GetRegistry(); registry != nil {
+				if agent := registry.GetDefaultAgent(); agent != nil {
+					meta.AgentID = agent.ID
+				}
+			}
+		}
+	}
+
+	al.emitEvent(
+		EventKindInterruptReceived,
+		meta,
+		InterruptReceivedPayload{
+			Kind:       InterruptKindSteering,
+			Role:       msg.Role,
+			ContentLen: len(msg.Content),
+			QueueDepth: queueDepth,
+		},
+	)
+
+	return nil
+}
+
+// SteeringMode returns the current steering mode.
+func (al *AgentLoop) SteeringMode() SteeringMode {
+	if al.steering == nil {
+		return SteeringOneAtATime
+	}
+	return al.steering.getMode()
+}
+
+// SetSteeringMode updates the steering mode.
+func (al *AgentLoop) SetSteeringMode(mode SteeringMode) {
+	if al.steering == nil {
+		return
+	}
+	al.steering.setMode(mode)
+}
+
+// dequeueSteeringMessages is the internal method called by the agent loop
+// to poll for steering messages in the legacy fallback scope.
+func (al *AgentLoop) dequeueSteeringMessages() []providers.Message {
+	if al.steering == nil {
+		return nil
+	}
+	return al.steering.dequeue()
+}
+
+func (al *AgentLoop) dequeueSteeringMessagesForScope(scope string) []providers.Message {
+	if al.steering == nil {
+		return nil
+	}
+	return al.steering.dequeueScope(scope)
+}
+
+func (al *AgentLoop) dequeueSteeringMessagesForScopeWithFallback(scope string) []providers.Message {
+	if al.steering == nil {
+		return nil
+	}
+	return al.steering.dequeueScopeWithFallback(scope)
+}
+
+func (al *AgentLoop) pendingSteeringCountForScope(scope string) int {
+	if al.steering == nil {
+		return 0
+	}
+	return al.steering.lenScope(scope)
+}
+
+func (al *AgentLoop) continueWithSteeringMessages(
+	ctx context.Context,
+	agent *AgentInstance,
+	sessionKey, channel, chatID string,
+	steeringMsgs []providers.Message,
+) (string, error) {
+	return al.runAgentLoop(ctx, agent, processOptions{
+		SessionKey:              sessionKey,
+		Channel:                 channel,
+		ChatID:                  chatID,
+		DefaultResponse:         defaultResponse,
+		EnableSummary:           true,
+		SendResponse:            false,
+		InitialSteeringMessages: steeringMsgs,
+		SkipInitialSteeringPoll: true,
+	})
+}
+
+func (al *AgentLoop) agentForSession(sessionKey string) *AgentInstance {
+	registry := al.GetRegistry()
+	if registry == nil {
+		return nil
+	}
+
+	if parsed := routing.ParseAgentSessionKey(sessionKey); parsed != nil {
+		if agent, ok := registry.GetAgent(parsed.AgentID); ok {
+			return agent
+		}
+	}
+
+	return registry.GetDefaultAgent()
+}
+
+// Continue resumes an idle agent by dequeuing any pending steering messages
+// and running them through the agent loop. This is used when the agent's last
+// message was from the assistant (i.e., it has stopped processing) and the
+// user has since enqueued steering messages.
+//
+// If no steering messages are pending, it returns an empty string.
+func (al *AgentLoop) Continue(ctx context.Context, sessionKey, channel, chatID string) (string, error) {
+	if active := al.GetActiveTurn(); active != nil {
+		return "", fmt.Errorf("turn %s is still active", active.TurnID)
+	}
+	if err := al.ensureHooksInitialized(ctx); err != nil {
+		return "", err
+	}
+	if err := al.ensureMCPInitialized(ctx); err != nil {
+		return "", err
+	}
+
+	steeringMsgs := al.dequeueSteeringMessagesForScopeWithFallback(sessionKey)
+	if len(steeringMsgs) == 0 {
+		return "", nil
+	}
+
+	agent := al.agentForSession(sessionKey)
+	if agent == nil {
+		return "", fmt.Errorf("no agent available for session %q", sessionKey)
+	}
+
+	if tool, ok := agent.Tools.Get("message"); ok {
+		if resetter, ok := tool.(interface{ ResetSentInRound() }); ok {
+			resetter.ResetSentInRound()
+		}
+	}
+
+	return al.continueWithSteeringMessages(ctx, agent, sessionKey, channel, chatID, steeringMsgs)
+}
+
+func (al *AgentLoop) InterruptGraceful(hint string) error {
+	ts := al.getAnyActiveTurnState()
+	if ts == nil {
+		return fmt.Errorf("no active turn")
+	}
+	if !ts.requestGracefulInterrupt(hint) {
+		return fmt.Errorf("turn %s cannot accept graceful interrupt", ts.turnID)
+	}
+
+	al.emitEvent(
+		EventKindInterruptReceived,
+		ts.eventMeta("InterruptGraceful", "turn.interrupt.received"),
+		InterruptReceivedPayload{
+			Kind:    InterruptKindGraceful,
+			HintLen: len(hint),
+		},
+	)
+
+	return nil
+}
+
+func (al *AgentLoop) InterruptHard() error {
+	ts := al.getAnyActiveTurnState()
+	if ts == nil {
+		return fmt.Errorf("no active turn")
+	}
+	if !ts.requestHardAbort() {
+		return fmt.Errorf("turn %s is already aborting", ts.turnID)
+	}
+
+	al.emitEvent(
+		EventKindInterruptReceived,
+		ts.eventMeta("InterruptHard", "turn.interrupt.received"),
+		InterruptReceivedPayload{
+			Kind: InterruptKindHard,
+		},
+	)
+
+	return nil
+}
+
+// ====================== SubTurn Result Polling ======================
+
+// dequeuePendingSubTurnResults polls the SubTurn result channel for the given
+// session and returns all available results without blocking.
+// Returns nil if no active turn state exists for this session.
+func (al *AgentLoop) dequeuePendingSubTurnResults(sessionKey string) []*tools.ToolResult {
+	tsInterface, ok := al.activeTurnStates.Load(sessionKey)
+	if !ok {
+		return nil
+	}
+	ts, ok := tsInterface.(*turnState)
+	if !ok {
+		return nil
+	}
+
+	var results []*tools.ToolResult
+	for {
+		select {
+		case result, ok := <-ts.pendingResults:
+			if !ok {
+				return results
+			}
+			if result != nil {
+				results = append(results, result)
+			}
+		default:
+			return results
+		}
+	}
+}
+
+// ====================== Hard Abort ======================
+
+// HardAbort immediately cancels the running agent loop for the given session,
+// cascading the cancellation to all child SubTurns. This is a destructive operation
+// that terminates execution without waiting for graceful cleanup.
+//
+// Use this when the user explicitly requests immediate termination (e.g., "stop now", "abort").
+// For graceful interruption that allows the agent to finish the current tool and summarize,
+// use Steer() instead.
+func (al *AgentLoop) HardAbort(sessionKey string) error {
+	tsInterface, ok := al.activeTurnStates.Load(sessionKey)
+	if !ok {
+		return fmt.Errorf("no active turn state found for session %s", sessionKey)
+	}
+
+	ts, ok := tsInterface.(*turnState)
+	if !ok {
+		return fmt.Errorf("invalid turn state type for session %s", sessionKey)
+	}
+
+	logger.InfoCF("agent", "Hard abort triggered", map[string]any{
+		"session_key":            sessionKey,
+		"turn_id":                ts.turnID,
+		"depth":                  ts.depth,
+		"initial_history_length": ts.initialHistoryLength,
+	})
+
+	// IMPORTANT: Trigger cascading cancellation FIRST to stop all child SubTurns
+	// from adding more messages to the session. This prevents race conditions
+	// where rollback happens while children are still writing.
+	// Use isHardAbort=true for hard abort to immediately cancel all children.
+	ts.Finish(true)
+
+	// Roll back session history to the state before the turn started.
+	if ts.session != nil {
+		history := ts.session.GetHistory(sessionKey)
+		if ts.initialHistoryLength < len(history) {
+			ts.session.SetHistory(sessionKey, history[:ts.initialHistoryLength])
+		}
+	}
+
+	return nil
+}
+
+// ====================== Follow-Up Injection ======================
+
+// InjectFollowUp enqueues a message to be automatically processed after the current
+// turn completes. Unlike Steer(), which interrupts the current execution, InjectFollowUp
+// waits for the current turn to finish naturally before processing the message.
+//
+// This is useful for:
+// - Automated workflows that need to chain multiple turns
+// - Background tasks that should run after the main task completes
+// - Scheduled follow-up actions
+//
+// The message will be processed via Continue() when the agent becomes idle.
+func (al *AgentLoop) InjectFollowUp(msg providers.Message) error {
+	// InjectFollowUp uses the same steering queue mechanism as Steer(),
+	// but the semantic difference is in when it's called:
+	// - Steer() is called during active execution to interrupt
+	// - InjectFollowUp() is called when planning future work
+	//
+	// Both end up in the same queue and are processed by Continue()
+	// when the agent is idle.
+	return al.Steer(msg)
+}
+
+// ====================== API Aliases for Design Document Compatibility ======================
+
+// InjectSteering is an alias for Steer() to match the design document naming.
+// It injects a steering message into the currently running agent loop.
+func (al *AgentLoop) InjectSteering(msg providers.Message) error {
+	return al.Steer(msg)
+}
diff --git a/pkg/agent/steering_test.go b/pkg/agent/steering_test.go
new file mode 100644
index 000000000..75ba9861d
--- /dev/null
+++ b/pkg/agent/steering_test.go
@@ -0,0 +1,1591 @@
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/media"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/routing"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+// --- steeringQueue unit tests ---
+
+func TestSteeringQueue_PushDequeue_OneAtATime(t *testing.T) {
+	sq := newSteeringQueue(SteeringOneAtATime)
+
+	sq.push(providers.Message{Role: "user", Content: "msg1"})
+	sq.push(providers.Message{Role: "user", Content: "msg2"})
+	sq.push(providers.Message{Role: "user", Content: "msg3"})
+
+	if sq.len() != 3 {
+		t.Fatalf("expected 3 messages, got %d", sq.len())
+	}
+
+	msgs := sq.dequeue()
+	if len(msgs) != 1 {
+		t.Fatalf("expected 1 message in one-at-a-time mode, got %d", len(msgs))
+	}
+	if msgs[0].Content != "msg1" {
+		t.Fatalf("expected 'msg1', got %q", msgs[0].Content)
+	}
+	if sq.len() != 2 {
+		t.Fatalf("expected 2 remaining, got %d", sq.len())
+	}
+
+	msgs = sq.dequeue()
+	if len(msgs) != 1 || msgs[0].Content != "msg2" {
+		t.Fatalf("expected 'msg2', got %v", msgs)
+	}
+
+	msgs = sq.dequeue()
+	if len(msgs) != 1 || msgs[0].Content != "msg3" {
+		t.Fatalf("expected 'msg3', got %v", msgs)
+	}
+
+	msgs = sq.dequeue()
+	if msgs != nil {
+		t.Fatalf("expected nil from empty queue, got %v", msgs)
+	}
+}
+
+func TestSteeringQueue_PushDequeue_All(t *testing.T) {
+	sq := newSteeringQueue(SteeringAll)
+
+	sq.push(providers.Message{Role: "user", Content: "msg1"})
+	sq.push(providers.Message{Role: "user", Content: "msg2"})
+	sq.push(providers.Message{Role: "user", Content: "msg3"})
+
+	msgs := sq.dequeue()
+	if len(msgs) != 3 {
+		t.Fatalf("expected 3 messages in all mode, got %d", len(msgs))
+	}
+	if msgs[0].Content != "msg1" || msgs[1].Content != "msg2" || msgs[2].Content != "msg3" {
+		t.Fatalf("unexpected messages: %v", msgs)
+	}
+
+	if sq.len() != 0 {
+		t.Fatalf("expected 0 remaining, got %d", sq.len())
+	}
+
+	msgs = sq.dequeue()
+	if msgs != nil {
+		t.Fatalf("expected nil from empty queue, got %v", msgs)
+	}
+}
+
+func TestSteeringQueue_EmptyDequeue(t *testing.T) {
+	sq := newSteeringQueue(SteeringOneAtATime)
+	if msgs := sq.dequeue(); msgs != nil {
+		t.Fatalf("expected nil, got %v", msgs)
+	}
+}
+
+func TestSteeringQueue_SetMode(t *testing.T) {
+	sq := newSteeringQueue(SteeringOneAtATime)
+	if sq.getMode() != SteeringOneAtATime {
+		t.Fatalf("expected one-at-a-time, got %v", sq.getMode())
+	}
+
+	sq.setMode(SteeringAll)
+	if sq.getMode() != SteeringAll {
+		t.Fatalf("expected all, got %v", sq.getMode())
+	}
+
+	// Push two messages and verify all-mode drains them
+	sq.push(providers.Message{Role: "user", Content: "a"})
+	sq.push(providers.Message{Role: "user", Content: "b"})
+
+	msgs := sq.dequeue()
+	if len(msgs) != 2 {
+		t.Fatalf("expected 2 messages after mode switch, got %d", len(msgs))
+	}
+}
+
+func TestSteeringQueue_ConcurrentAccess(t *testing.T) {
+	sq := newSteeringQueue(SteeringOneAtATime)
+
+	var wg sync.WaitGroup
+	const n = MaxQueueSize
+
+	// Push from multiple goroutines
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func(i int) {
+			defer wg.Done()
+			sq.push(providers.Message{Role: "user", Content: fmt.Sprintf("msg%d", i)})
+		}(i)
+	}
+	wg.Wait()
+
+	if sq.len() != n {
+		t.Fatalf("expected %d messages, got %d", n, sq.len())
+	}
+
+	// Drain from multiple goroutines
+	var drained int
+	var mu sync.Mutex
+	for i := 0; i < n; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			if msgs := sq.dequeue(); len(msgs) > 0 {
+				mu.Lock()
+				drained += len(msgs)
+				mu.Unlock()
+			}
+		}()
+	}
+	wg.Wait()
+
+	if drained != n {
+		t.Fatalf("expected to drain %d messages, got %d", n, drained)
+	}
+}
+
+func TestSteeringQueue_Overflow(t *testing.T) {
+	sq := newSteeringQueue(SteeringOneAtATime)
+
+	// Fill the queue up to its maximum capacity
+	for i := 0; i < MaxQueueSize; i++ {
+		err := sq.push(providers.Message{Role: "user", Content: fmt.Sprintf("msg%d", i)})
+		if err != nil {
+			t.Fatalf("unexpected error pushing message %d: %v", i, err)
+		}
+	}
+
+	// Sanity check: ensure the queue is actually full
+	if sq.len() != MaxQueueSize {
+		t.Fatalf("expected queue length %d, got %d", MaxQueueSize, sq.len())
+	}
+
+	// Attempt to push one more message, which MUST fail
+	err := sq.push(providers.Message{Role: "user", Content: "overflow_msg"})
+
+	// Assert the error happened and is the exact one we expect
+	if err == nil {
+		t.Fatal("expected an error when pushing to a full queue, but got nil")
+	}
+
+	expectedErr := "steering queue is full"
+	if err.Error() != expectedErr {
+		t.Errorf("expected error message %q, got %q", expectedErr, err.Error())
+	}
+}
+
+func TestParseSteeringMode(t *testing.T) {
+	tests := []struct {
+		input    string
+		expected SteeringMode
+	}{
+		{"", SteeringOneAtATime},
+		{"one-at-a-time", SteeringOneAtATime},
+		{"all", SteeringAll},
+		{"unknown", SteeringOneAtATime},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			if got := parseSteeringMode(tt.input); got != tt.expected {
+				t.Fatalf("parseSteeringMode(%q) = %v, want %v", tt.input, got, tt.expected)
+			}
+		})
+	}
+}
+
+// --- AgentLoop steering integration tests ---
+
+func TestAgentLoop_Steer_Enqueues(t *testing.T) {
+	al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t)
+	defer cleanup()
+
+	if cfg == nil {
+		t.Fatal("expected config to be initialized")
+	}
+	if msgBus == nil {
+		t.Fatal("expected message bus to be initialized")
+	}
+	if provider == nil {
+		t.Fatal("expected provider to be initialized")
+	}
+
+	al.Steer(providers.Message{Role: "user", Content: "interrupt me"})
+
+	if al.steering.len() != 1 {
+		t.Fatalf("expected 1 steering message, got %d", al.steering.len())
+	}
+
+	msgs := al.dequeueSteeringMessages()
+	if len(msgs) != 1 || msgs[0].Content != "interrupt me" {
+		t.Fatalf("unexpected dequeued message: %v", msgs)
+	}
+}
+
+func TestAgentLoop_SteeringMode_GetSet(t *testing.T) {
+	al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t)
+	defer cleanup()
+
+	if cfg == nil {
+		t.Fatal("expected config to be initialized")
+	}
+	if msgBus == nil {
+		t.Fatal("expected message bus to be initialized")
+	}
+	if provider == nil {
+		t.Fatal("expected provider to be initialized")
+	}
+
+	if al.SteeringMode() != SteeringOneAtATime {
+		t.Fatalf("expected default mode one-at-a-time, got %v", al.SteeringMode())
+	}
+
+	al.SetSteeringMode(SteeringAll)
+	if al.SteeringMode() != SteeringAll {
+		t.Fatalf("expected all mode, got %v", al.SteeringMode())
+	}
+}
+
+func TestAgentLoop_SteeringMode_ConfiguredFromConfig(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+				SteeringMode:      "all",
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &mockProvider{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	if al.SteeringMode() != SteeringAll {
+		t.Fatalf("expected 'all' mode from config, got %v", al.SteeringMode())
+	}
+}
+
+func TestAgentLoop_Continue_NoMessages(t *testing.T) {
+	al, cfg, msgBus, provider, cleanup := newTestAgentLoop(t)
+	defer cleanup()
+
+	if cfg == nil {
+		t.Fatal("expected config to be initialized")
+	}
+	if msgBus == nil {
+		t.Fatal("expected message bus to be initialized")
+	}
+	if provider == nil {
+		t.Fatal("expected provider to be initialized")
+	}
+
+	resp, err := al.Continue(context.Background(), "test-session", "test", "chat1")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if resp != "" {
+		t.Fatalf("expected empty response for no steering messages, got %q", resp)
+	}
+}
+
+func TestAgentLoop_Continue_WithMessages(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &simpleMockProvider{response: "continued response"}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	al.Steer(providers.Message{Role: "user", Content: "new direction"})
+
+	resp, err := al.Continue(context.Background(), "test-session", "test", "chat1")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if resp != "continued response" {
+		t.Fatalf("expected 'continued response', got %q", resp)
+	}
+}
+
+func TestDrainBusToSteering_RequeuesDifferentScopeMessage(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+		Session: config.SessionConfig{
+			DMScope: "per-peer",
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	al := NewAgentLoop(cfg, msgBus, &mockProvider{})
+
+	activeMsg := bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "active turn",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	}
+	activeScope, activeAgentID, ok := al.resolveSteeringTarget(activeMsg)
+	if !ok {
+		t.Fatal("expected active message to resolve to a steering scope")
+	}
+
+	otherMsg := bus.InboundMessage{
+		Channel:  "telegram",
+		SenderID: "user2",
+		ChatID:   "chat2",
+		Content:  "other session",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user2",
+		},
+	}
+	otherScope, _, ok := al.resolveSteeringTarget(otherMsg)
+	if !ok {
+		t.Fatal("expected other message to resolve to a steering scope")
+	}
+	if otherScope == activeScope {
+		t.Fatalf("expected different steering scopes, got same scope %q", activeScope)
+	}
+
+	if err := msgBus.PublishInbound(context.Background(), otherMsg); err != nil {
+		t.Fatalf("PublishInbound failed: %v", err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+
+	done := make(chan struct{})
+	go func() {
+		al.drainBusToSteering(ctx, activeScope, activeAgentID)
+		close(done)
+	}()
+
+	select {
+	case <-done:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timeout waiting for drainBusToSteering to stop")
+	}
+
+	if msgs := al.dequeueSteeringMessagesForScope(activeScope); len(msgs) != 0 {
+		t.Fatalf("expected no steering messages for active scope, got %v", msgs)
+	}
+
+	select {
+	case <-ctx.Done():
+		t.Fatalf("timeout waiting for requeued message on outbound bus")
+	case requeued := <-msgBus.OutboundChan():
+		if requeued.Channel != otherMsg.Channel || requeued.ChatID != otherMsg.ChatID ||
+			requeued.Content != otherMsg.Content {
+			t.Fatalf("requeued message mismatch: got %+v want %+v", requeued, otherMsg)
+		}
+	}
+}
+
+// slowTool simulates a tool that takes some time to execute.
+type slowTool struct {
+	name     string
+	duration time.Duration
+	execCh   chan struct{} // closed when Execute starts
+}
+
+func (t *slowTool) Name() string        { return t.name }
+func (t *slowTool) Description() string { return "slow tool for testing" }
+func (t *slowTool) Parameters() map[string]any {
+	return map[string]any{
+		"type":       "object",
+		"properties": map[string]any{},
+	}
+}
+
+func (t *slowTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+	if t.execCh != nil {
+		close(t.execCh)
+	}
+	time.Sleep(t.duration)
+	return tools.SilentResult(fmt.Sprintf("executed %s", t.name))
+}
+
+// toolCallProvider returns an LLM response with tool calls on the first call,
+// then a direct response on subsequent calls.
+type toolCallProvider struct {
+	mu        sync.Mutex
+	calls     int
+	toolCalls []providers.ToolCall
+	finalResp string
+}
+
+func (m *toolCallProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.calls++
+
+	if m.calls == 1 && len(m.toolCalls) > 0 {
+		return &providers.LLMResponse{
+			Content:   "",
+			ToolCalls: m.toolCalls,
+		}, nil
+	}
+
+	return &providers.LLMResponse{
+		Content:   m.finalResp,
+		ToolCalls: []providers.ToolCall{},
+	}, nil
+}
+
+func (m *toolCallProvider) GetDefaultModel() string {
+	return "tool-call-mock"
+}
+
+type gracefulCaptureProvider struct {
+	mu                 sync.Mutex
+	calls              int
+	toolCalls          []providers.ToolCall
+	finalResp          string
+	terminalMessages   []providers.Message
+	terminalToolsCount int
+}
+
+func (p *gracefulCaptureProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	p.calls++
+
+	if p.calls == 1 {
+		return &providers.LLMResponse{
+			ToolCalls: p.toolCalls,
+		}, nil
+	}
+
+	p.terminalMessages = append([]providers.Message(nil), messages...)
+	p.terminalToolsCount = len(tools)
+	return &providers.LLMResponse{
+		Content: p.finalResp,
+	}, nil
+}
+
+func (p *gracefulCaptureProvider) GetDefaultModel() string {
+	return "graceful-capture-mock"
+}
+
+type lateSteeringProvider struct {
+	mu                 sync.Mutex
+	calls              int
+	firstCallStarted   chan struct{}
+	releaseFirstCall   chan struct{}
+	firstStartOnce     sync.Once
+	secondCallMessages []providers.Message
+}
+
+func (p *lateSteeringProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	p.mu.Lock()
+	p.calls++
+	call := p.calls
+	p.mu.Unlock()
+
+	if call == 1 {
+		p.firstStartOnce.Do(func() { close(p.firstCallStarted) })
+		<-p.releaseFirstCall
+		return &providers.LLMResponse{Content: "first response"}, nil
+	}
+
+	p.mu.Lock()
+	p.secondCallMessages = append([]providers.Message(nil), messages...)
+	p.mu.Unlock()
+	return &providers.LLMResponse{Content: "continued response"}, nil
+}
+
+func (p *lateSteeringProvider) GetDefaultModel() string {
+	return "late-steering-mock"
+}
+
+type blockingDirectProvider struct {
+	mu           sync.Mutex
+	calls        int
+	firstStarted chan struct{}
+	releaseFirst chan struct{}
+	firstResp    string
+	finalResp    string
+}
+
+func (p *blockingDirectProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	p.mu.Lock()
+	p.calls++
+	call := p.calls
+	firstStarted := p.firstStarted
+	releaseFirst := p.releaseFirst
+	firstResp := p.firstResp
+	finalResp := p.finalResp
+	if call == 1 && p.firstStarted != nil {
+		close(p.firstStarted)
+		p.firstStarted = nil
+	}
+	p.mu.Unlock()
+
+	if call == 1 {
+		select {
+		case <-releaseFirst:
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		}
+		return &providers.LLMResponse{Content: firstResp}, nil
+	}
+
+	_ = firstStarted
+	return &providers.LLMResponse{Content: finalResp}, nil
+}
+
+func (p *blockingDirectProvider) GetDefaultModel() string {
+	return "blocking-direct-mock"
+}
+
+type interruptibleTool struct {
+	name    string
+	started chan struct{}
+	once    sync.Once
+}
+
+func (t *interruptibleTool) Name() string        { return t.name }
+func (t *interruptibleTool) Description() string { return "interruptible tool for testing" }
+func (t *interruptibleTool) Parameters() map[string]any {
+	return map[string]any{
+		"type":       "object",
+		"properties": map[string]any{},
+	}
+}
+
+func (t *interruptibleTool) Execute(ctx context.Context, args map[string]any) *tools.ToolResult {
+	if t.started != nil {
+		t.once.Do(func() { close(t.started) })
+	}
+	<-ctx.Done()
+	return tools.ErrorResult(ctx.Err().Error()).WithError(ctx.Err())
+}
+
+func TestAgentLoop_Steering_SkipsRemainingTools(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	tool1ExecCh := make(chan struct{})
+	tool1 := &slowTool{name: "tool_one", duration: 50 * time.Millisecond, execCh: tool1ExecCh}
+	tool2 := &slowTool{name: "tool_two", duration: 50 * time.Millisecond}
+
+	provider := &toolCallProvider{
+		toolCalls: []providers.ToolCall{
+			{
+				ID:   "call_1",
+				Type: "function",
+				Name: "tool_one",
+				Function: &providers.FunctionCall{
+					Name:      "tool_one",
+					Arguments: "{}",
+				},
+				Arguments: map[string]any{},
+			},
+			{
+				ID:   "call_2",
+				Type: "function",
+				Name: "tool_two",
+				Function: &providers.FunctionCall{
+					Name:      "tool_two",
+					Arguments: "{}",
+				},
+				Arguments: map[string]any{},
+			},
+		},
+		finalResp: "steered response",
+	}
+
+	msgBus := bus.NewMessageBus()
+	al := NewAgentLoop(cfg, msgBus, provider)
+	al.RegisterTool(tool1)
+	al.RegisterTool(tool2)
+
+	// Start processing in a goroutine
+	type result struct {
+		resp string
+		err  error
+	}
+	resultCh := make(chan result, 1)
+
+	go func() {
+		resp, err := al.ProcessDirectWithChannel(
+			context.Background(),
+			"do something",
+			"test-session",
+			"test",
+			"chat1",
+		)
+		resultCh <- result{resp, err}
+	}()
+
+	// Wait for tool_one to start executing, then enqueue a steering message
+	select {
+	case <-tool1ExecCh:
+		// tool_one has started executing
+	case <-time.After(2 * time.Second):
+		t.Fatal("timeout waiting for tool_one to start")
+	}
+
+	al.Steer(providers.Message{Role: "user", Content: "change course"})
+
+	// Get the result
+	select {
+	case r := <-resultCh:
+		if r.err != nil {
+			t.Fatalf("unexpected error: %v", r.err)
+		}
+		if r.resp != "steered response" {
+			t.Fatalf("expected 'steered response', got %q", r.resp)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("timeout waiting for agent loop to complete")
+	}
+
+	// The provider should have been called twice:
+	// 1. first call returned tool calls
+	// 2. second call (after steering) returned the final response
+	provider.mu.Lock()
+	calls := provider.calls
+	provider.mu.Unlock()
+	if calls != 2 {
+		t.Fatalf("expected 2 provider calls, got %d", calls)
+	}
+}
+
+func TestAgentLoop_Steering_InitialPoll(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	// Provider that captures messages it receives
+	var capturedMessages []providers.Message
+	var capMu sync.Mutex
+	provider := &capturingMockProvider{
+		response: "ack",
+		captureFn: func(msgs []providers.Message) {
+			capMu.Lock()
+			capturedMessages = make([]providers.Message, len(msgs))
+			copy(capturedMessages, msgs)
+			capMu.Unlock()
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	// Enqueue a steering message before processing starts
+	al.Steer(providers.Message{Role: "user", Content: "pre-enqueued steering"})
+
+	// Process a normal message - the initial steering poll should inject the steering message
+	_, err = al.ProcessDirectWithChannel(
+		context.Background(),
+		"initial message",
+		"test-session",
+		"test",
+		"chat1",
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// The steering message should have been injected into the conversation
+	capMu.Lock()
+	msgs := capturedMessages
+	capMu.Unlock()
+
+	// Look for the steering message in the captured messages
+	found := false
+	for _, m := range msgs {
+		if m.Content == "pre-enqueued steering" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatal("expected steering message to be injected into conversation context")
+	}
+}
+
+func TestAgentLoop_Run_AutoContinuesLateSteeringMessage(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &lateSteeringProvider{
+		firstCallStarted: make(chan struct{}),
+		releaseFirstCall: make(chan struct{}),
+	}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	runCtx, cancelRun := context.WithCancel(context.Background())
+	defer cancelRun()
+
+	runErrCh := make(chan error, 1)
+	go func() {
+		runErrCh <- al.Run(runCtx)
+	}()
+
+	first := bus.InboundMessage{
+		Channel:  "test",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "first message",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	}
+	late := bus.InboundMessage{
+		Channel:  "test",
+		SenderID: "user1",
+		ChatID:   "chat1",
+		Content:  "late append",
+		Peer: bus.Peer{
+			Kind: "direct",
+			ID:   "user1",
+		},
+	}
+
+	pubCtx, pubCancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer pubCancel()
+	if err := msgBus.PublishInbound(pubCtx, first); err != nil {
+		t.Fatalf("publish first inbound: %v", err)
+	}
+
+	select {
+	case <-provider.firstCallStarted:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timeout waiting for first provider call to start")
+	}
+
+	if err := msgBus.PublishInbound(pubCtx, late); err != nil {
+		t.Fatalf("publish late inbound: %v", err)
+	}
+
+	close(provider.releaseFirstCall)
+
+	subCtx, subCancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer subCancel()
+
+	var out1 bus.OutboundMessage
+	select {
+	case out1 = <-msgBus.OutboundChan():
+	case <-subCtx.Done():
+		t.Fatal("expected outbound response")
+	}
+	if out1.Content != "continued response" {
+		t.Fatalf("expected continued response, got %q", out1.Content)
+	}
+
+	noExtraCtx, cancelNoExtra := context.WithTimeout(context.Background(), 200*time.Millisecond)
+	defer cancelNoExtra()
+	select {
+	case out2 := <-msgBus.OutboundChan():
+		t.Fatalf("expected stale direct response to be suppressed, got extra outbound %q", out2.Content)
+	case <-noExtraCtx.Done():
+	}
+
+	cancelRun()
+	select {
+	case err := <-runErrCh:
+		if err != nil {
+			t.Fatalf("Run returned error: %v", err)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("timeout waiting for Run to stop")
+	}
+
+	provider.mu.Lock()
+	calls := provider.calls
+	secondMessages := append([]providers.Message(nil), provider.secondCallMessages...)
+	provider.mu.Unlock()
+
+	if calls != 2 {
+		t.Fatalf("expected 2 provider calls, got %d", calls)
+	}
+
+	foundLateMessage := false
+	for _, msg := range secondMessages {
+		if msg.Role == "user" && msg.Content == "late append" {
+			foundLateMessage = true
+			break
+		}
+	}
+	if !foundLateMessage {
+		t.Fatal("expected queued late message to be processed in an automatic follow-up turn")
+	}
+}
+
+func TestAgentLoop_Steering_DirectResponseContinuesWithQueuedMessage(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	sessionKey := routing.BuildAgentMainSessionKey(routing.DefaultAgentID)
+	provider := &blockingDirectProvider{
+		firstStarted: make(chan struct{}),
+		releaseFirst: make(chan struct{}),
+		firstResp:    "stale direct response",
+		finalResp:    "fresh response after steering",
+	}
+
+	msgBus := bus.NewMessageBus()
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	resultCh := make(chan struct {
+		resp string
+		err  error
+	}, 1)
+	go func() {
+		resp, err := al.ProcessDirectWithChannel(
+			context.Background(),
+			"initial request",
+			sessionKey,
+			"test",
+			"chat1",
+		)
+		resultCh <- struct {
+			resp string
+			err  error
+		}{resp: resp, err: err}
+	}()
+
+	select {
+	case <-provider.firstStarted:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timeout waiting for first LLM call to start")
+	}
+
+	if err := al.Steer(providers.Message{Role: "user", Content: "follow-up instruction"}); err != nil {
+		t.Fatalf("Steer failed: %v", err)
+	}
+	close(provider.releaseFirst)
+
+	select {
+	case result := <-resultCh:
+		if result.err != nil {
+			t.Fatalf("unexpected error: %v", result.err)
+		}
+		if result.resp != "fresh response after steering" {
+			t.Fatalf("expected refreshed response, got %q", result.resp)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("timeout waiting for ProcessDirectWithChannel")
+	}
+
+	provider.mu.Lock()
+	calls := provider.calls
+	provider.mu.Unlock()
+	if calls != 2 {
+		t.Fatalf("expected 2 provider calls, got %d", calls)
+	}
+
+	if msgs := al.dequeueSteeringMessagesForScope(sessionKey); len(msgs) != 0 {
+		t.Fatalf("expected steering queue to be empty after continuation, got %v", msgs)
+	}
+}
+
+func TestAgentLoop_Continue_PreservesSteeringMedia(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	store := media.NewFileMediaStore()
+	pngPath := filepath.Join(tmpDir, "steer.png")
+	pngHeader := []byte{
+		0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A,
+		0x00, 0x00, 0x00, 0x0D,
+		0x49, 0x48, 0x44, 0x52,
+		0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x08, 0x02,
+		0x00, 0x00, 0x00,
+		0x90, 0x77, 0x53, 0xDE,
+	}
+	if err = os.WriteFile(pngPath, pngHeader, 0o644); err != nil {
+		t.Fatalf("WriteFile failed: %v", err)
+	}
+	ref, err := store.Store(pngPath, media.MediaMeta{Filename: "steer.png", ContentType: "image/png"}, "test")
+	if err != nil {
+		t.Fatalf("Store failed: %v", err)
+	}
+
+	var capturedMessages []providers.Message
+	var capMu sync.Mutex
+	provider := &capturingMockProvider{
+		response: "ack",
+		captureFn: func(msgs []providers.Message) {
+			capMu.Lock()
+			defer capMu.Unlock()
+			capturedMessages = append([]providers.Message(nil), msgs...)
+		},
+	}
+
+	sessionKey := routing.BuildAgentMainSessionKey(routing.DefaultAgentID)
+	msgBus := bus.NewMessageBus()
+	al := NewAgentLoop(cfg, msgBus, provider)
+	al.SetMediaStore(store)
+
+	if err = al.Steer(providers.Message{
+		Role:    "user",
+		Content: "describe this image",
+		Media:   []string{ref},
+	}); err != nil {
+		t.Fatalf("Steer failed: %v", err)
+	}
+
+	resp, err := al.Continue(context.Background(), sessionKey, "test", "chat1")
+	if err != nil {
+		t.Fatalf("Continue failed: %v", err)
+	}
+	if resp != "ack" {
+		t.Fatalf("expected ack, got %q", resp)
+	}
+
+	capMu.Lock()
+	msgs := append([]providers.Message(nil), capturedMessages...)
+	capMu.Unlock()
+
+	foundResolvedMedia := false
+	for _, msg := range msgs {
+		if msg.Role != "user" || msg.Content != "describe this image" || len(msg.Media) != 1 {
+			continue
+		}
+		if strings.HasPrefix(msg.Media[0], "data:image/png;base64,") {
+			foundResolvedMedia = true
+			break
+		}
+	}
+	if !foundResolvedMedia {
+		t.Fatal("expected continue path to inject steering media into the provider request")
+	}
+
+	defaultAgent := al.registry.GetDefaultAgent()
+	if defaultAgent == nil {
+		t.Fatal("expected default agent")
+	}
+	history := defaultAgent.Sessions.GetHistory(sessionKey)
+	foundOriginalRef := false
+	for _, msg := range history {
+		if msg.Role == "user" && len(msg.Media) == 1 && msg.Media[0] == ref {
+			foundOriginalRef = true
+			break
+		}
+	}
+	if !foundOriginalRef {
+		t.Fatal("expected original steering media ref to be preserved in session history")
+	}
+}
+
+func TestAgentLoop_InterruptGraceful_UsesTerminalNoToolCall(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	tool1ExecCh := make(chan struct{})
+	tool1 := &slowTool{name: "tool_one", duration: 50 * time.Millisecond, execCh: tool1ExecCh}
+	tool2 := &slowTool{name: "tool_two", duration: 50 * time.Millisecond}
+
+	provider := &gracefulCaptureProvider{
+		toolCalls: []providers.ToolCall{
+			{
+				ID:   "call_1",
+				Type: "function",
+				Name: "tool_one",
+				Function: &providers.FunctionCall{
+					Name:      "tool_one",
+					Arguments: "{}",
+				},
+				Arguments: map[string]any{},
+			},
+			{
+				ID:   "call_2",
+				Type: "function",
+				Name: "tool_two",
+				Function: &providers.FunctionCall{
+					Name:      "tool_two",
+					Arguments: "{}",
+				},
+				Arguments: map[string]any{},
+			},
+		},
+		finalResp: "graceful summary",
+	}
+
+	msgBus := bus.NewMessageBus()
+	al := NewAgentLoop(cfg, msgBus, provider)
+	al.RegisterTool(tool1)
+	al.RegisterTool(tool2)
+	sessionKey := routing.BuildAgentMainSessionKey(routing.DefaultAgentID)
+
+	sub := al.SubscribeEvents(32)
+	defer al.UnsubscribeEvents(sub.ID)
+
+	type result struct {
+		resp string
+		err  error
+	}
+	resultCh := make(chan result, 1)
+	go func() {
+		resp, err := al.ProcessDirectWithChannel(
+			context.Background(),
+			"do something",
+			sessionKey,
+			"test",
+			"chat1",
+		)
+		resultCh <- result{resp: resp, err: err}
+	}()
+
+	select {
+	case <-tool1ExecCh:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timeout waiting for tool_one to start")
+	}
+
+	active := al.GetActiveTurn()
+	if active == nil {
+		t.Fatal("expected active turn while tool is running")
+	}
+	if active.SessionKey != sessionKey {
+		t.Fatalf("expected active session %q, got %q", sessionKey, active.SessionKey)
+	}
+	if active.Channel != "test" || active.ChatID != "chat1" {
+		t.Fatalf("unexpected active turn target: %#v", active)
+	}
+
+	if err := al.InterruptGraceful("wrap it up"); err != nil {
+		t.Fatalf("InterruptGraceful failed: %v", err)
+	}
+
+	select {
+	case r := <-resultCh:
+		if r.err != nil {
+			t.Fatalf("unexpected error: %v", r.err)
+		}
+		if r.resp != "graceful summary" {
+			t.Fatalf("expected graceful summary, got %q", r.resp)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("timeout waiting for graceful interrupt result")
+	}
+
+	if active := al.GetActiveTurn(); active != nil {
+		t.Fatalf("expected no active turn after completion, got %#v", active)
+	}
+
+	provider.mu.Lock()
+	terminalMessages := append([]providers.Message(nil), provider.terminalMessages...)
+	terminalToolsCount := provider.terminalToolsCount
+	calls := provider.calls
+	provider.mu.Unlock()
+
+	if calls != 2 {
+		t.Fatalf("expected 2 provider calls, got %d", calls)
+	}
+	if terminalToolsCount != 0 {
+		t.Fatalf("expected graceful terminal call to disable tools, got %d tool defs", terminalToolsCount)
+	}
+
+	foundHint := false
+	foundSkipped := false
+	expectedHint := "Interrupt requested. Stop scheduling tools and provide a short final summary.\n\n" +
+		"Interrupt hint: wrap it up"
+	for _, msg := range terminalMessages {
+		if msg.Role == "user" && msg.Content == expectedHint {
+			foundHint = true
+		}
+		if msg.Role == "tool" && msg.ToolCallID == "call_2" && msg.Content == "Skipped due to graceful interrupt." {
+			foundSkipped = true
+		}
+	}
+	if !foundHint {
+		t.Fatal("expected graceful terminal call to include interrupt hint message")
+	}
+	if !foundSkipped {
+		t.Fatal("expected remaining tool to be marked as skipped after graceful interrupt")
+	}
+
+	events := collectEventStream(sub.C)
+	interruptEvt, ok := findEvent(events, EventKindInterruptReceived)
+	if !ok {
+		t.Fatal("expected interrupt received event")
+	}
+	interruptPayload, ok := interruptEvt.Payload.(InterruptReceivedPayload)
+	if !ok {
+		t.Fatalf("expected InterruptReceivedPayload, got %T", interruptEvt.Payload)
+	}
+	if interruptPayload.Kind != InterruptKindGraceful {
+		t.Fatalf("expected graceful interrupt payload, got %q", interruptPayload.Kind)
+	}
+
+	turnEndEvt, ok := findEvent(events, EventKindTurnEnd)
+	if !ok {
+		t.Fatal("expected turn end event")
+	}
+	turnEndPayload, ok := turnEndEvt.Payload.(TurnEndPayload)
+	if !ok {
+		t.Fatalf("expected TurnEndPayload, got %T", turnEndEvt.Payload)
+	}
+	if turnEndPayload.Status != TurnEndStatusCompleted {
+		t.Fatalf("expected completed turn after graceful interrupt, got %q", turnEndPayload.Status)
+	}
+}
+
+func TestAgentLoop_InterruptHard_RestoresSession(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	provider := &toolCallProvider{
+		toolCalls: []providers.ToolCall{
+			{
+				ID:   "call_1",
+				Type: "function",
+				Name: "cancel_tool",
+				Function: &providers.FunctionCall{
+					Name:      "cancel_tool",
+					Arguments: "{}",
+				},
+				Arguments: map[string]any{},
+			},
+		},
+		finalResp: "should not happen",
+	}
+
+	al := NewAgentLoop(cfg, msgBus, provider)
+	started := make(chan struct{})
+	al.RegisterTool(&interruptibleTool{name: "cancel_tool", started: started})
+	sessionKey := routing.BuildAgentMainSessionKey(routing.DefaultAgentID)
+
+	defaultAgent := al.registry.GetDefaultAgent()
+	if defaultAgent == nil {
+		t.Fatal("expected default agent")
+	}
+
+	originalHistory := []providers.Message{
+		{Role: "user", Content: "before"},
+		{Role: "assistant", Content: "after"},
+	}
+	defaultAgent.Sessions.SetHistory(sessionKey, originalHistory)
+
+	sub := al.SubscribeEvents(16)
+	defer al.UnsubscribeEvents(sub.ID)
+
+	type result struct {
+		resp string
+		err  error
+	}
+	resultCh := make(chan result, 1)
+	go func() {
+		resp, err := al.ProcessDirectWithChannel(
+			context.Background(),
+			"do work",
+			sessionKey,
+			"test",
+			"chat1",
+		)
+		resultCh <- result{resp: resp, err: err}
+	}()
+
+	select {
+	case <-started:
+	case <-time.After(2 * time.Second):
+		t.Fatal("timeout waiting for interruptible tool to start")
+	}
+
+	if active := al.GetActiveTurn(); active == nil {
+		t.Fatal("expected active turn before hard abort")
+	}
+
+	if err := al.InterruptHard(); err != nil {
+		t.Fatalf("InterruptHard failed: %v", err)
+	}
+
+	select {
+	case r := <-resultCh:
+		if r.err != nil {
+			t.Fatalf("unexpected error: %v", r.err)
+		}
+		if r.resp != "" {
+			t.Fatalf("expected no final response after hard abort, got %q", r.resp)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("timeout waiting for hard abort result")
+	}
+
+	if active := al.GetActiveTurn(); active != nil {
+		t.Fatalf("expected no active turn after hard abort, got %#v", active)
+	}
+
+	finalHistory := defaultAgent.Sessions.GetHistory(sessionKey)
+	if !reflect.DeepEqual(finalHistory, originalHistory) {
+		t.Fatalf("expected history rollback after hard abort, got %#v", finalHistory)
+	}
+
+	events := collectEventStream(sub.C)
+	interruptEvt, ok := findEvent(events, EventKindInterruptReceived)
+	if !ok {
+		t.Fatal("expected interrupt received event")
+	}
+	interruptPayload, ok := interruptEvt.Payload.(InterruptReceivedPayload)
+	if !ok {
+		t.Fatalf("expected InterruptReceivedPayload, got %T", interruptEvt.Payload)
+	}
+	if interruptPayload.Kind != InterruptKindHard {
+		t.Fatalf("expected hard interrupt payload, got %q", interruptPayload.Kind)
+	}
+
+	turnEndEvt, ok := findEvent(events, EventKindTurnEnd)
+	if !ok {
+		t.Fatal("expected turn end event")
+	}
+	turnEndPayload, ok := turnEndEvt.Payload.(TurnEndPayload)
+	if !ok {
+		t.Fatalf("expected TurnEndPayload, got %T", turnEndEvt.Payload)
+	}
+	if turnEndPayload.Status != TurnEndStatusAborted {
+		t.Fatalf("expected aborted turn, got %q", turnEndPayload.Status)
+	}
+}
+
+// capturingMockProvider captures messages sent to Chat for inspection.
+type capturingMockProvider struct {
+	response  string
+	calls     int
+	captureFn func([]providers.Message)
+}
+
+func (m *capturingMockProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	m.calls++
+	if m.captureFn != nil {
+		m.captureFn(messages)
+	}
+	return &providers.LLMResponse{
+		Content:   m.response,
+		ToolCalls: []providers.ToolCall{},
+	}, nil
+}
+
+func (m *capturingMockProvider) GetDefaultModel() string {
+	return "capturing-mock"
+}
+
+func TestAgentLoop_Steering_SkippedToolsHaveErrorResults(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "agent-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         tmpDir,
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+
+	execCh := make(chan struct{})
+	tool1 := &slowTool{name: "slow_tool", duration: 50 * time.Millisecond, execCh: execCh}
+	tool2 := &slowTool{name: "skipped_tool", duration: 50 * time.Millisecond}
+
+	// Provider that captures messages on the second call (after tools)
+	var secondCallMessages []providers.Message
+	var capMu sync.Mutex
+	callCount := 0
+
+	provider := &toolCallProvider{
+		toolCalls: []providers.ToolCall{
+			{
+				ID:   "call_1",
+				Type: "function",
+				Name: "slow_tool",
+				Function: &providers.FunctionCall{
+					Name:      "slow_tool",
+					Arguments: "{}",
+				},
+				Arguments: map[string]any{},
+			},
+			{
+				ID:   "call_2",
+				Type: "function",
+				Name: "skipped_tool",
+				Function: &providers.FunctionCall{
+					Name:      "skipped_tool",
+					Arguments: "{}",
+				},
+				Arguments: map[string]any{},
+			},
+		},
+		finalResp: "done",
+	}
+
+	// Wrap provider to capture messages on second call
+	wrappedProvider := &wrappingProvider{
+		inner: provider,
+		onChat: func(msgs []providers.Message) {
+			capMu.Lock()
+			callCount++
+			if callCount >= 2 {
+				secondCallMessages = make([]providers.Message, len(msgs))
+				copy(secondCallMessages, msgs)
+			}
+			capMu.Unlock()
+		},
+	}
+
+	msgBus := bus.NewMessageBus()
+	al := NewAgentLoop(cfg, msgBus, wrappedProvider)
+	al.RegisterTool(tool1)
+	al.RegisterTool(tool2)
+
+	resultCh := make(chan string, 1)
+	go func() {
+		resp, _ := al.ProcessDirectWithChannel(
+			context.Background(), "go", "test-session", "test", "chat1",
+		)
+		resultCh <- resp
+	}()
+
+	<-execCh
+	al.Steer(providers.Message{Role: "user", Content: "interrupt!"})
+
+	select {
+	case <-resultCh:
+	case <-time.After(5 * time.Second):
+		t.Fatal("timeout")
+	}
+
+	// Check that the skipped tool result message is in the conversation
+	capMu.Lock()
+	msgs := secondCallMessages
+	capMu.Unlock()
+
+	foundSkipped := false
+	for _, m := range msgs {
+		if m.Role == "tool" && m.ToolCallID == "call_2" && m.Content == "Skipped due to queued user message." {
+			foundSkipped = true
+			break
+		}
+	}
+	if !foundSkipped {
+		// Log what we actually got
+		for i, m := range msgs {
+			t.Logf("msg[%d]: role=%s toolCallID=%s content=%s", i, m.Role, m.ToolCallID, truncate(m.Content, 80))
+		}
+		t.Fatal("expected skipped tool result for call_2")
+	}
+}
+
+func truncate(s string, n int) string {
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "..."
+}
+
+// wrappingProvider wraps another provider to hook into Chat calls.
+type wrappingProvider struct {
+	inner  providers.LLMProvider
+	onChat func([]providers.Message)
+}
+
+func (w *wrappingProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	if w.onChat != nil {
+		w.onChat(messages)
+	}
+	return w.inner.Chat(ctx, messages, tools, model, opts)
+}
+
+func (w *wrappingProvider) GetDefaultModel() string {
+	return w.inner.GetDefaultModel()
+}
+
+// Ensure NormalizeToolCall handles our test tool calls.
+func init() {
+	// This is a no-op init; we just need the tool call tests to work
+	// with the proper argument serialization.
+	_ = json.Marshal
+}
diff --git a/pkg/agent/subturn.go b/pkg/agent/subturn.go
new file mode 100644
index 000000000..f5ba412ab
--- /dev/null
+++ b/pkg/agent/subturn.go
@@ -0,0 +1,671 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+// ====================== Config & Constants ======================
+const (
+	// Default values for SubTurn configuration (used when config is not set or is zero)
+	defaultMaxSubTurnDepth       = 3
+	defaultMaxConcurrentSubTurns = 5
+	defaultConcurrencyTimeout    = 30 * time.Second
+	defaultSubTurnTimeout        = 5 * time.Minute
+	// maxEphemeralHistorySize limits the number of messages stored in ephemeral sessions.
+	// This prevents memory accumulation in long-running sub-turns.
+	maxEphemeralHistorySize = 50
+)
+
+var (
+	ErrDepthLimitExceeded   = errors.New("sub-turn depth limit exceeded")
+	ErrInvalidSubTurnConfig = errors.New("invalid sub-turn config")
+	ErrConcurrencyTimeout   = errors.New("timeout waiting for concurrency slot")
+)
+
+// getSubTurnConfig returns the effective SubTurn configuration with defaults applied.
+func (al *AgentLoop) getSubTurnConfig() subTurnRuntimeConfig {
+	cfg := al.cfg.Agents.Defaults.SubTurn
+
+	maxDepth := cfg.MaxDepth
+	if maxDepth <= 0 {
+		maxDepth = defaultMaxSubTurnDepth
+	}
+
+	maxConcurrent := cfg.MaxConcurrent
+	if maxConcurrent <= 0 {
+		maxConcurrent = defaultMaxConcurrentSubTurns
+	}
+
+	concurrencyTimeout := time.Duration(cfg.ConcurrencyTimeoutSec) * time.Second
+	if concurrencyTimeout <= 0 {
+		concurrencyTimeout = defaultConcurrencyTimeout
+	}
+
+	defaultTimeout := time.Duration(cfg.DefaultTimeoutMinutes) * time.Minute
+	if defaultTimeout <= 0 {
+		defaultTimeout = defaultSubTurnTimeout
+	}
+
+	return subTurnRuntimeConfig{
+		maxDepth:           maxDepth,
+		maxConcurrent:      maxConcurrent,
+		concurrencyTimeout: concurrencyTimeout,
+		defaultTimeout:     defaultTimeout,
+		defaultTokenBudget: cfg.DefaultTokenBudget,
+	}
+}
+
+// subTurnRuntimeConfig holds the effective runtime configuration for SubTurn execution.
+type subTurnRuntimeConfig struct {
+	maxDepth           int
+	maxConcurrent      int
+	concurrencyTimeout time.Duration
+	defaultTimeout     time.Duration
+	defaultTokenBudget int
+}
+
+// ====================== SubTurn Config ======================
+
+// SubTurnConfig configures the execution of a child sub-turn.
+//
+// Usage Examples:
+//
+// Synchronous sub-turn (Async=false):
+//
+//	cfg := SubTurnConfig{
+//	    Model: "gpt-4o-mini",
+//	    SystemPrompt: "Analyze this code",
+//	    Async: false,  // Result returned immediately
+//	}
+//	result, err := SpawnSubTurn(ctx, cfg)
+//	// Use result directly here
+//	processResult(result)
+//
+// Asynchronous sub-turn (Async=true):
+//
+//	cfg := SubTurnConfig{
+//	    Model: "gpt-4o-mini",
+//	    SystemPrompt: "Background analysis",
+//	    Async: true,  // Result delivered to channel
+//	}
+//	result, err := SpawnSubTurn(ctx, cfg)
+//	// Result also available in parent's pendingResults channel
+//	// Parent turn will poll and process it in a later iteration
+type SubTurnConfig struct {
+	Model        string
+	Tools        []tools.Tool
+	SystemPrompt string
+	MaxTokens    int
+
+	// Async controls the result delivery mechanism:
+	//
+	// When Async = false (synchronous sub-turn):
+	//   - The caller blocks until the sub-turn completes
+	//   - The result is ONLY returned via the function return value
+	//   - The result is NOT delivered to the parent's pendingResults channel
+	//   - This prevents double delivery: caller gets result immediately, no need for channel
+	//   - Use case: When the caller needs the result immediately to continue execution
+	//   - Example: A tool that needs to process the sub-turn result before returning
+	//
+	// When Async = true (asynchronous sub-turn):
+	//   - The sub-turn runs in the background (still blocks the caller, but semantically async)
+	//   - The result is delivered to the parent's pendingResults channel
+	//   - The result is ALSO returned via the function return value (for consistency)
+	//   - The parent turn can poll pendingResults in later iterations to process results
+	//   - Use case: Fire-and-forget operations, or when results are processed in batches
+	//   - Example: Spawning multiple sub-turns in parallel and collecting results later
+	//
+	// IMPORTANT: The Async flag does NOT make the call non-blocking. It only controls
+	// whether the result is delivered via the channel. For true non-blocking execution,
+	// the caller must spawn the sub-turn in a separate goroutine.
+	Async bool
+
+	// Critical indicates this SubTurn's result is important and should continue
+	// running even after the parent turn finishes gracefully.
+	//
+	// When parent finishes gracefully (Finish(false)):
+	//   - Critical=true: SubTurn continues running, delivers result as orphan
+	//   - Critical=false: SubTurn exits gracefully without error
+	//
+	// When parent finishes with hard abort (Finish(true)):
+	//   - All SubTurns are canceled regardless of Critical flag
+	Critical bool
+
+	// Timeout is the maximum duration for this SubTurn.
+	// If the SubTurn runs longer than this, it will be canceled.
+	// Default is 5 minutes (defaultSubTurnTimeout) if not specified.
+	Timeout time.Duration
+
+	// MaxContextRunes limits the context size (in runes) passed to the SubTurn.
+	// This prevents context window overflow by truncating message history before LLM calls.
+	//
+	// Values:
+	//   0  = Auto-calculate based on model's ContextWindow * 0.75 (default, recommended)
+	//   -1 = No limit (disable soft truncation, rely only on hard context errors)
+	//   >0 = Use specified rune limit
+	//
+	// The soft limit acts as a first line of defense before hitting the provider's
+	// hard context window limit. When exceeded, older messages are intelligently
+	// truncated while preserving system messages and recent context.
+	MaxContextRunes int
+
+	// ActualSystemPrompt is injected as the true 'system' role message for the childAgent.
+	// The legacy SystemPrompt field is actually used as the first 'user' message (task description).
+	ActualSystemPrompt string
+
+	// InitialMessages preloads the ephemeral session history before the agent loop starts.
+	// Used by evaluator-optimizer patterns to pass the full worker context across multiple iterations.
+	InitialMessages []providers.Message
+
+	// InitialTokenBudget is a shared atomic counter for tracking remaining tokens.
+	// If set, the SubTurn will inherit this budget and deduct tokens after each LLM call.
+	// If nil, the SubTurn will inherit the parent's tokenBudget (if any).
+	// Used by team tool to enforce token limits across all team members.
+	InitialTokenBudget *atomic.Int64
+
+	// Can be extended with temperature, topP, etc.
+}
+
+// ====================== Context Keys ======================
+type agentLoopKeyType struct{}
+
+var agentLoopKey = agentLoopKeyType{}
+
+// WithAgentLoop injects AgentLoop into context for tool access
+func WithAgentLoop(ctx context.Context, al *AgentLoop) context.Context {
+	return context.WithValue(ctx, agentLoopKey, al)
+}
+
+// AgentLoopFromContext retrieves AgentLoop from context
+func AgentLoopFromContext(ctx context.Context) *AgentLoop {
+	al, _ := ctx.Value(agentLoopKey).(*AgentLoop)
+	return al
+}
+
+// ====================== Helper Functions ======================
+
+func (al *AgentLoop) generateSubTurnID() string {
+	return fmt.Sprintf("subturn-%d", al.subTurnCounter.Add(1))
+}
+
+// ====================== Core Function: spawnSubTurn ======================
+
+// AgentLoopSpawner implements tools.SubTurnSpawner interface.
+// This allows tools to spawn sub-turns without circular dependency.
+type AgentLoopSpawner struct {
+	al *AgentLoop
+}
+
+// SpawnSubTurn implements tools.SubTurnSpawner interface.
+func (s *AgentLoopSpawner) SpawnSubTurn(
+	ctx context.Context,
+	cfg tools.SubTurnConfig,
+) (*tools.ToolResult, error) {
+	parentTS := turnStateFromContext(ctx)
+	if parentTS == nil {
+		return nil, errors.New(
+			"parent turnState not found in context - cannot spawn sub-turn outside of a turn",
+		)
+	}
+
+	// Convert tools.SubTurnConfig to agent.SubTurnConfig
+	agentCfg := SubTurnConfig{
+		Model:              cfg.Model,
+		Tools:              cfg.Tools,
+		SystemPrompt:       cfg.SystemPrompt,
+		ActualSystemPrompt: cfg.ActualSystemPrompt,
+		InitialMessages:    cfg.InitialMessages,
+		InitialTokenBudget: cfg.InitialTokenBudget,
+		MaxTokens:          cfg.MaxTokens,
+		Async:              cfg.Async,
+		Critical:           cfg.Critical,
+		Timeout:            cfg.Timeout,
+		MaxContextRunes:    cfg.MaxContextRunes,
+	}
+
+	return spawnSubTurn(ctx, s.al, parentTS, agentCfg)
+}
+
+// NewSubTurnSpawner creates a SubTurnSpawner for the given AgentLoop.
+func NewSubTurnSpawner(al *AgentLoop) *AgentLoopSpawner {
+	return &AgentLoopSpawner{al: al}
+}
+
+// SpawnSubTurn is the exported entry point for tools to spawn sub-turns.
+// It retrieves AgentLoop and parent turnState from context and delegates to spawnSubTurn.
+func SpawnSubTurn(ctx context.Context, cfg SubTurnConfig) (*tools.ToolResult, error) {
+	al := AgentLoopFromContext(ctx)
+	if al == nil {
+		return nil, errors.New(
+			"AgentLoop not found in context - ensure context is properly initialized",
+		)
+	}
+
+	parentTS := turnStateFromContext(ctx)
+	if parentTS == nil {
+		return nil, errors.New(
+			"parent turnState not found in context - cannot spawn sub-turn outside of a turn",
+		)
+	}
+
+	return spawnSubTurn(ctx, al, parentTS, cfg)
+}
+
+func spawnSubTurn(
+	ctx context.Context,
+	al *AgentLoop,
+	parentTS *turnState,
+	cfg SubTurnConfig,
+) (result *tools.ToolResult, err error) {
+	// Get effective SubTurn configuration
+	rtCfg := al.getSubTurnConfig()
+
+	// 0. Acquire concurrency semaphore FIRST to ensure it's released even if early validation fails.
+	// Blocks if parent already has maxConcurrentSubTurns running, with a timeout to prevent indefinite blocking.
+	// Also respects context cancellation so we don't block forever if parent is aborted.
+	// NOTE: The semaphore is released immediately after runTurn completes (not in a defer) to
+	// ensure it is freed before the cleanup phase (async result delivery), which may block on
+	// a full pendingResults channel. Holding the semaphore through cleanup would allow the
+	// parent's goroutine to be blocked waiting for a semaphore slot while child turns are
+	// blocked delivering results — a deadlock.
+	var semAcquired bool
+	if parentTS.concurrencySem != nil {
+		// Create a timeout context for semaphore acquisition
+		timeoutCtx, cancel := context.WithTimeout(ctx, rtCfg.concurrencyTimeout)
+		defer cancel()
+
+		select {
+		case parentTS.concurrencySem <- struct{}{}:
+			semAcquired = true
+			defer func() {
+				if semAcquired {
+					<-parentTS.concurrencySem
+				}
+			}()
+		case <-timeoutCtx.Done():
+			// Check parent context first - if it was canceled, propagate that error
+			if ctx.Err() != nil {
+				return nil, ctx.Err()
+			}
+			// Otherwise it's our timeout
+			return nil, fmt.Errorf("%w: all %d slots occupied for %v",
+				ErrConcurrencyTimeout, rtCfg.maxConcurrent, rtCfg.concurrencyTimeout)
+		}
+	}
+
+	// 1. Depth limit check
+	if parentTS.depth >= rtCfg.maxDepth {
+		logger.WarnCF("subturn", "Depth limit exceeded", map[string]any{
+			"parent_id": parentTS.turnID,
+			"depth":     parentTS.depth,
+			"max_depth": rtCfg.maxDepth,
+		})
+		return nil, ErrDepthLimitExceeded
+	}
+
+	// 2. Config validation
+	if cfg.Model == "" {
+		return nil, ErrInvalidSubTurnConfig
+	}
+
+	// 3. Determine timeout for child SubTurn
+	timeout := cfg.Timeout
+	if timeout <= 0 {
+		timeout = rtCfg.defaultTimeout
+	}
+
+	// 4. Create INDEPENDENT child context (not derived from parent ctx).
+	// This allows the child to continue running after parent finishes gracefully.
+	// The child has its own timeout for self-protection.
+	childCtx, cancel := context.WithTimeout(context.Background(), timeout)
+	defer cancel()
+
+	childID := al.generateSubTurnID()
+
+	// Get the agent instance from parent, falling back to the default agent.
+	// Wrap it in a shallow copy that uses an ephemeral (in-memory only) session store
+	// so that child turns never pollute or persist to the parent's session history.
+	baseAgent := parentTS.agent
+	if baseAgent == nil {
+		baseAgent = al.registry.GetDefaultAgent()
+	}
+	if baseAgent == nil {
+		return nil, errors.New("parent turnState has no agent instance")
+	}
+	ephemeralStore := newEphemeralSession(nil)
+	agent := *baseAgent // shallow copy
+	agent.Sessions = ephemeralStore
+	// Clone the tool registry so child turn's tool registrations
+	// don't pollute the parent's registry.
+	if baseAgent.Tools != nil {
+		agent.Tools = baseAgent.Tools.Clone()
+	}
+
+	// Create processOptions for the child turn
+	opts := processOptions{
+		SessionKey:              childID,
+		Channel:                 parentTS.channel,
+		ChatID:                  parentTS.chatID,
+		SenderID:                parentTS.opts.SenderID,
+		SenderDisplayName:       parentTS.opts.SenderDisplayName,
+		UserMessage:             cfg.SystemPrompt, // Task description becomes the first user message
+		SystemPromptOverride:    cfg.ActualSystemPrompt,
+		Media:                   nil,
+		InitialSteeringMessages: cfg.InitialMessages,
+		DefaultResponse:         "",
+		EnableSummary:           false,
+		SendResponse:            false,
+		NoHistory:               true, // SubTurns don't use session history
+		SkipInitialSteeringPoll: true,
+	}
+
+	// Create event scope for the child turn
+	scope := al.newTurnEventScope(agent.ID, childID)
+
+	// Create child turnState using the new API
+	childTS := newTurnState(&agent, opts, scope)
+
+	// Set SubTurn-specific fields
+	childTS.cancelFunc = cancel
+	childTS.critical = cfg.Critical
+	childTS.depth = parentTS.depth + 1
+	childTS.parentTurnID = parentTS.turnID
+	childTS.parentTurnState = parentTS
+	childTS.pendingResults = make(chan *tools.ToolResult, 16)
+	childTS.concurrencySem = make(chan struct{}, rtCfg.maxConcurrent)
+	childTS.al = al                  // back-ref for hard abort cascade
+	childTS.session = ephemeralStore // same store as agent.Sessions
+
+	// Token budget initialization/inheritance
+	// If InitialTokenBudget is explicitly provided (e.g., by team tool), use it.
+	// Otherwise, inherit from parent's tokenBudget (for nested SubTurns).
+	if cfg.InitialTokenBudget != nil {
+		childTS.tokenBudget = cfg.InitialTokenBudget
+	} else if parentTS.tokenBudget != nil {
+		childTS.tokenBudget = parentTS.tokenBudget
+	} else if rtCfg.defaultTokenBudget > 0 {
+		// Apply default token budget from config if no budget is set
+		budget := &atomic.Int64{}
+		budget.Store(int64(rtCfg.defaultTokenBudget))
+		childTS.tokenBudget = budget
+	}
+
+	// IMPORTANT: Put childTS into childCtx so that code inside runTurn can retrieve it
+	childCtx = withTurnState(childCtx, childTS)
+	childCtx = WithAgentLoop(childCtx, al) // Propagate AgentLoop to child turn
+
+	childTS.ctx = childCtx
+
+	// Register child turn state so GetAllActiveTurns/Subagents can find it
+	al.activeTurnStates.Store(childID, childTS)
+	defer al.activeTurnStates.Delete(childID)
+
+	// 5. Establish parent-child relationship (thread-safe)
+	parentTS.mu.Lock()
+	parentTS.childTurnIDs = append(parentTS.childTurnIDs, childID)
+	parentTS.mu.Unlock()
+
+	// 6. Emit Spawn event
+	al.emitEvent(EventKindSubTurnSpawn,
+		childTS.eventMeta("spawnSubTurn", "subturn.spawn"),
+		SubTurnSpawnPayload{
+			AgentID:      childTS.agentID,
+			Label:        childID,
+			ParentTurnID: parentTS.turnID,
+		},
+	)
+
+	// 7. Defer cleanup: deliver result (for async), emit End event, and recover from panics
+	defer func() {
+		if r := recover(); r != nil {
+			err = fmt.Errorf("subturn panicked: %v", r)
+			result = nil
+			logger.ErrorCF("subturn", "SubTurn panicked", map[string]any{
+				"child_id":  childID,
+				"parent_id": parentTS.turnID,
+				"panic":     r,
+			})
+		}
+
+		// Result Delivery Strategy (Async vs Sync)
+		if cfg.Async {
+			deliverSubTurnResult(al, parentTS, childID, result)
+		}
+
+		status := "completed"
+		if err != nil {
+			status = "error"
+		}
+		al.emitEvent(EventKindSubTurnEnd,
+			childTS.eventMeta("spawnSubTurn", "subturn.end"),
+			SubTurnEndPayload{
+				AgentID: childTS.agentID,
+				Status:  status,
+			},
+		)
+	}()
+
+	// 8. Execute sub-turn via the real agent loop.
+	turnRes, turnErr := al.runTurn(childCtx, childTS)
+
+	// Release the concurrency semaphore immediately after runTurn completes,
+	// before the cleanup defer runs. This prevents a deadlock where:
+	// - All semaphore slots are held by sub-turns in their cleanup phase
+	// - Cleanup blocks on a full pendingResults channel
+	// - The parent goroutine is blocked waiting for a semaphore slot
+	// - The parent cannot consume pendingResults because it is blocked on the semaphore
+	if semAcquired {
+		<-parentTS.concurrencySem
+		semAcquired = false // prevent the defer from double-releasing
+	}
+
+	// Convert turnResult to tools.ToolResult
+	if turnErr != nil {
+		err = turnErr
+		result = &tools.ToolResult{
+			Err:    turnErr,
+			ForLLM: fmt.Sprintf("SubTurn failed: %v", turnErr),
+		}
+	} else {
+		result = &tools.ToolResult{
+			ForLLM:  turnRes.finalContent,
+			ForUser: turnRes.finalContent,
+		}
+	}
+
+	return result, err
+}
+
+// ====================== Result Delivery ======================
+
+// deliverSubTurnResult delivers a sub-turn result to the parent turn's pendingResults channel.
+//
+// IMPORTANT: This function is ONLY called for asynchronous sub-turns (Async=true).
+// For synchronous sub-turns (Async=false), results are returned directly via the function
+// return value to avoid double delivery.
+//
+// Delivery behavior:
+//   - If parent turn is still running: attempts to deliver to pendingResults channel
+//   - If channel is full: emits SubTurnOrphanResultEvent (result is lost from channel but tracked)
+//   - If parent turn has finished: emits SubTurnOrphanResultEvent (late arrival)
+//
+// Thread safety:
+//   - Reads parent state under lock, then releases lock before channel send
+//   - Small race window exists but is acceptable (worst case: result becomes orphan)
+//
+// Event emissions:
+//   - SubTurnResultDeliveredEvent: successful delivery to channel
+//   - SubTurnOrphanResultEvent: delivery failed (parent finished or channel full)
+func deliverSubTurnResult(al *AgentLoop, parentTS *turnState, childID string, result *tools.ToolResult) {
+	// Let GC clean up the pendingResults channel; parent Finish will no longer close it.
+	// We use defer/recover to catch any unlikely channel panics if it were ever closed.
+	defer func() {
+		if r := recover(); r != nil {
+			logger.WarnCF("subturn", "recovered panic sending to pendingResults", map[string]any{
+				"parent_id": parentTS.turnID,
+				"child_id":  childID,
+				"recover":   r,
+			})
+			if result != nil && al != nil {
+				al.emitEvent(EventKindSubTurnOrphan,
+					parentTS.eventMeta("deliverSubTurnResult", "subturn.orphan"),
+					SubTurnOrphanPayload{ParentTurnID: parentTS.turnID, ChildTurnID: childID, Reason: "panic"},
+				)
+			}
+		}
+	}()
+	parentTS.mu.Lock()
+	isFinished := parentTS.isFinished.Load()
+	resultChan := parentTS.pendingResults
+	parentTS.mu.Unlock()
+
+	// If parent turn has already finished, treat this as an orphan result
+	if isFinished || resultChan == nil {
+		if result != nil && al != nil {
+			al.emitEvent(EventKindSubTurnOrphan,
+				parentTS.eventMeta("deliverSubTurnResult", "subturn.orphan"),
+				SubTurnOrphanPayload{ParentTurnID: parentTS.turnID, ChildTurnID: childID, Reason: "parent_finished"},
+			)
+		}
+		return
+	}
+
+	// Parent Turn is still running → attempt to deliver result
+	// We use a select statement with parentTS.Finished() to ensure that if the
+	// parent turn finishes while we are waiting to send the result (e.g. channel
+	// is full), we don't leak this goroutine by blocking forever.
+	select {
+	case resultChan <- result:
+		// Successfully delivered
+		if al != nil {
+			al.emitEvent(EventKindSubTurnResultDelivered,
+				parentTS.eventMeta("deliverSubTurnResult", "subturn.result_delivered"),
+				SubTurnResultDeliveredPayload{ContentLen: len(result.ForLLM)},
+			)
+		}
+	case <-parentTS.Finished():
+		// Parent finished while we were waiting to deliver.
+		// The result cannot be delivered to the LLM, so it becomes an orphan.
+		logger.WarnCF("subturn", "parent finished before result could be delivered", map[string]any{
+			"parent_id": parentTS.turnID,
+			"child_id":  childID,
+		})
+		if result != nil && al != nil {
+			al.emitEvent(
+				EventKindSubTurnOrphan,
+				parentTS.eventMeta("deliverSubTurnResult", "subturn.orphan"),
+				SubTurnOrphanPayload{
+					ParentTurnID: parentTS.turnID,
+					ChildTurnID:  childID,
+					Reason:       "parent_finished_waiting",
+				},
+			)
+		}
+	}
+}
+
+// ====================== Other Types ======================
+
+// ephemeralSessionStore is an in-memory session.SessionStore used by SubTurns.
+// It does not persist to disk and auto-truncates history to maxEphemeralHistorySize.
+type ephemeralSessionStore struct {
+	mu      sync.Mutex
+	history []providers.Message
+	summary string
+}
+
+func newEphemeralSession(initial []providers.Message) ephemeralSessionStoreIface {
+	s := &ephemeralSessionStore{}
+	if len(initial) > 0 {
+		s.history = append(s.history, initial...)
+	}
+	return s
+}
+
+// ephemeralSessionStoreIface is satisfied by *ephemeralSessionStore.
+// Declared so newEphemeralSession can return a typed interface.
+type ephemeralSessionStoreIface interface {
+	AddMessage(sessionKey, role, content string)
+	AddFullMessage(sessionKey string, msg providers.Message)
+	GetHistory(key string) []providers.Message
+	GetSummary(key string) string
+	SetSummary(key, summary string)
+	SetHistory(key string, history []providers.Message)
+	TruncateHistory(key string, keepLast int)
+	Save(key string) error
+	Close() error
+}
+
+func (e *ephemeralSessionStore) AddMessage(_, role, content string) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	e.history = append(e.history, providers.Message{Role: role, Content: content})
+	e.truncateLocked()
+}
+
+func (e *ephemeralSessionStore) AddFullMessage(_ string, msg providers.Message) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	e.history = append(e.history, msg)
+	e.truncateLocked()
+}
+
+func (e *ephemeralSessionStore) GetHistory(_ string) []providers.Message {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	out := make([]providers.Message, len(e.history))
+	copy(out, e.history)
+	return out
+}
+
+func (e *ephemeralSessionStore) GetSummary(_ string) string {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	return e.summary
+}
+
+func (e *ephemeralSessionStore) SetSummary(_, summary string) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	e.summary = summary
+}
+
+func (e *ephemeralSessionStore) SetHistory(_ string, history []providers.Message) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	e.history = make([]providers.Message, len(history))
+	copy(e.history, history)
+	e.truncateLocked()
+}
+
+func (e *ephemeralSessionStore) TruncateHistory(_ string, keepLast int) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	if keepLast <= 0 {
+		e.history = nil
+		return
+	}
+
+	if keepLast >= len(e.history) {
+		return
+	}
+	e.history = e.history[len(e.history)-keepLast:]
+}
+
+func (e *ephemeralSessionStore) Save(_ string) error { return nil }
+func (e *ephemeralSessionStore) Close() error        { return nil }
+
+func (e *ephemeralSessionStore) truncateLocked() {
+	if len(e.history) > maxEphemeralHistorySize {
+		e.history = e.history[len(e.history)-maxEphemeralHistorySize:]
+	}
+}
diff --git a/pkg/agent/subturn_test.go b/pkg/agent/subturn_test.go
new file mode 100644
index 000000000..6a2ba835d
--- /dev/null
+++ b/pkg/agent/subturn_test.go
@@ -0,0 +1,2067 @@
+package agent
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+// Test constants (use defaults from subturn.go)
+const (
+	testMaxConcurrentSubTurns = defaultMaxConcurrentSubTurns
+)
+
+// ====================== Test Helper: Event Collector ======================
+type eventCollector struct {
+	mu     sync.Mutex
+	events []Event
+}
+
+func newEventCollector(t *testing.T, al *AgentLoop) (*eventCollector, func()) {
+	t.Helper()
+	c := &eventCollector{}
+	sub := al.SubscribeEvents(16)
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		for evt := range sub.C {
+			c.mu.Lock()
+			c.events = append(c.events, evt)
+			c.mu.Unlock()
+		}
+	}()
+	cleanup := func() {
+		al.UnsubscribeEvents(sub.ID)
+		<-done
+	}
+	return c, cleanup
+}
+
+func (c *eventCollector) hasEventOfKind(kind EventKind) bool {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	for _, e := range c.events {
+		if e.Kind == kind {
+			return true
+		}
+	}
+	return false
+}
+
+// ====================== Main Test Function ======================
+func TestSpawnSubTurn(t *testing.T) {
+	tests := []struct {
+		name          string
+		parentDepth   int
+		config        SubTurnConfig
+		wantErr       error
+		wantSpawn     bool
+		wantEnd       bool
+		wantDepthFail bool
+	}{
+		{
+			name:        "Basic success path - Single layer sub-turn",
+			parentDepth: 0,
+			config: SubTurnConfig{
+				Model: "gpt-4o-mini",
+				Tools: []tools.Tool{}, // At least one tool
+			},
+			wantErr:   nil,
+			wantSpawn: true,
+			wantEnd:   true,
+		},
+		{
+			name:        "Nested 2 layers - Normal",
+			parentDepth: 1,
+			config: SubTurnConfig{
+				Model: "gpt-4o-mini",
+				Tools: []tools.Tool{},
+			},
+			wantErr:   nil,
+			wantSpawn: true,
+			wantEnd:   true,
+		},
+		{
+			name:        "Depth limit triggered - 4th layer fails",
+			parentDepth: 3,
+			config: SubTurnConfig{
+				Model: "gpt-4o-mini",
+				Tools: []tools.Tool{},
+			},
+			wantErr:       ErrDepthLimitExceeded,
+			wantSpawn:     false,
+			wantEnd:       false,
+			wantDepthFail: true,
+		},
+		{
+			name:        "Invalid config - Empty Model",
+			parentDepth: 0,
+			config: SubTurnConfig{
+				Model: "",
+				Tools: []tools.Tool{},
+			},
+			wantErr:   ErrInvalidSubTurnConfig,
+			wantSpawn: false,
+			wantEnd:   false,
+		},
+	}
+
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Prepare parent Turn
+			parent := &turnState{
+				ctx:            context.Background(),
+				turnID:         "parent-1",
+				depth:          tt.parentDepth,
+				childTurnIDs:   []string{},
+				pendingResults: make(chan *tools.ToolResult, 10),
+				session:        &ephemeralSessionStore{},
+				agent:          al.registry.GetDefaultAgent(),
+			}
+
+			// Subscribe to real EventBus to capture events
+			collector, collectCleanup := newEventCollector(t, al)
+			defer collectCleanup()
+
+			// Execute spawnSubTurn
+			result, err := spawnSubTurn(context.Background(), al, parent, tt.config)
+
+			// Assert errors
+			if tt.wantErr != nil {
+				if err == nil || err != tt.wantErr {
+					t.Errorf("expected error %v, got %v", tt.wantErr, err)
+				}
+				return
+			}
+			if err != nil {
+				t.Errorf("unexpected error: %v", err)
+				return
+			}
+
+			// Verify result
+			if result == nil {
+				t.Error("expected non-nil result")
+			}
+
+			// Verify event emission
+			time.Sleep(10 * time.Millisecond) // let event goroutine flush
+			if tt.wantSpawn {
+				if !collector.hasEventOfKind(EventKindSubTurnSpawn) {
+					t.Error("SubTurnSpawnEvent not emitted")
+				}
+			}
+			if tt.wantEnd {
+				if !collector.hasEventOfKind(EventKindSubTurnEnd) {
+					t.Error("SubTurnEndEvent not emitted")
+				}
+			}
+
+			// Verify turn tree
+			if len(parent.childTurnIDs) == 0 && !tt.wantDepthFail {
+				t.Error("child Turn not added to parent.childTurnIDs")
+			}
+
+			// For synchronous calls (Async=false, the default), result is returned directly
+			// and should NOT be in pendingResults. The result was already verified above.
+			// Only async calls (Async=true) would place results in pendingResults.
+		})
+	}
+}
+
+// ====================== Extra Independent Test: Ephemeral Session Isolation ======================
+func TestSpawnSubTurn_EphemeralSessionIsolation(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	// Parent uses its own ephemeral store pre-seeded with one message
+	parentSession := &ephemeralSessionStore{}
+	parentSession.AddMessage("", "user", "parent msg")
+	parent := &turnState{
+		ctx:            context.Background(),
+		turnID:         "parent-1",
+		depth:          0,
+		pendingResults: make(chan *tools.ToolResult, 4),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+		session:        parentSession,
+	}
+
+	cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}}
+
+	originalParentLen := len(parentSession.GetHistory(""))
+
+	_, _ = spawnSubTurn(context.Background(), al, parent, cfg)
+
+	// Parent session must be untouched — child used its own store
+	if got := len(parentSession.GetHistory("")); got != originalParentLen {
+		t.Errorf("parent session polluted: expected %d messages, got %d", originalParentLen, got)
+	}
+
+	// The child's agent.Sessions must NOT be the same pointer as the parent's session.
+	// We verify this indirectly: spawnSubTurn stores childTS in activeTurnStates during
+	// execution (deleted on return), so we can't easily grab childTS after the call.
+	// Instead, confirm that the child session is a distinct ephemeralSessionStore by
+	// checking the parent session key is only used by the parent store.
+	// If isolation is correct, parent.session.GetHistory(childID) is always empty
+	// (the child never wrote to the parent store).
+	al.activeTurnStates.Range(func(k, v any) bool {
+		// No active turns should remain after spawnSubTurn returns
+		t.Errorf("unexpected active turn state left after spawnSubTurn: key=%v", k)
+		return true
+	})
+}
+
+// ====================== Extra Independent Test: Result Delivery Path (Async) ======================
+func TestSpawnSubTurn_ResultDelivery(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	parent := &turnState{
+		ctx:            context.Background(),
+		turnID:         "parent-1",
+		depth:          0,
+		pendingResults: make(chan *tools.ToolResult, 1),
+		session:        &ephemeralSessionStore{},
+	}
+
+	// Set Async=true to test async result delivery via pendingResults channel
+	cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}, Async: true}
+
+	_, _ = spawnSubTurn(context.Background(), al, parent, cfg)
+
+	// Check if pendingResults received the result (only for async calls)
+	select {
+	case res := <-parent.pendingResults:
+		if res == nil {
+			t.Error("received nil result in pendingResults")
+		}
+	default:
+		t.Error("result did not enter pendingResults for async call")
+	}
+}
+
+// ====================== Extra Independent Test: Result Delivery Path (Sync) ======================
+func TestSpawnSubTurn_ResultDeliverySync(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	parent := &turnState{
+		ctx:            context.Background(),
+		turnID:         "parent-sync-1",
+		depth:          0,
+		pendingResults: make(chan *tools.ToolResult, 1),
+		session:        &ephemeralSessionStore{},
+	}
+
+	// Sync call (Async=false, the default) - result should be returned directly
+	cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}, Async: false}
+
+	result, err := spawnSubTurn(context.Background(), al, parent, cfg)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Result should be returned directly
+	if result == nil {
+		t.Error("expected non-nil result from sync call")
+	}
+
+	// pendingResults should NOT contain the result (no double delivery)
+	select {
+	case <-parent.pendingResults:
+		t.Error("sync call should not place result in pendingResults (double delivery)")
+	default:
+		// Expected - channel should be empty
+	}
+}
+
+// ====================== Extra Independent Test: Orphan Result Routing ======================
+func TestSpawnSubTurn_OrphanResultRouting(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	collector, collectCleanup := newEventCollector(t, al)
+	defer collectCleanup()
+
+	parentCtx, cancelParent := context.WithCancel(context.Background())
+	parent := &turnState{
+		ctx:            parentCtx,
+		cancelFunc:     cancelParent,
+		turnID:         "parent-1",
+		depth:          0,
+		pendingResults: make(chan *tools.ToolResult, 1),
+		session:        &ephemeralSessionStore{},
+	}
+
+	// Simulate parent finishing before child delivers result
+	parent.Finish(false)
+
+	// Call deliverSubTurnResult directly to simulate a delayed child
+	deliverSubTurnResult(al, parent, "delayed-child", &tools.ToolResult{ForLLM: "late result"})
+
+	time.Sleep(10 * time.Millisecond) // let event goroutine flush
+	// Verify Orphan event is emitted
+	if !collector.hasEventOfKind(EventKindSubTurnOrphan) {
+		t.Error("SubTurnOrphanResultEvent not emitted for finished parent")
+	}
+
+	// Verify history is NOT polluted
+	if len(parent.session.GetHistory("")) != 0 {
+		t.Error("Parent history was polluted by orphan result")
+	}
+}
+
+// ====================== Extra Independent Test: Result Channel Registration ======================
+func TestSubTurnResultChannelRegistration(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	parent := &turnState{
+		ctx:            context.Background(),
+		turnID:         "parent-reg-1",
+		depth:          0,
+		pendingResults: make(chan *tools.ToolResult, 4),
+		session:        &ephemeralSessionStore{},
+	}
+
+	cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}}
+
+	// Before spawn: channel should not be registered
+	if results := al.dequeuePendingSubTurnResults(parent.turnID); results != nil {
+		t.Error("expected no channel before spawnSubTurn")
+	}
+
+	_, _ = spawnSubTurn(context.Background(), al, parent, cfg)
+}
+
+// ====================== Extra Independent Test: Dequeue Pending SubTurn Results ======================
+func TestDequeuePendingSubTurnResults(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	sessionKey := "test-session-dequeue"
+
+	// Empty (no turnState registered) returns nil
+	if results := al.dequeuePendingSubTurnResults(sessionKey); len(results) != 0 {
+		t.Errorf("expected empty results, got %d", len(results))
+	}
+
+	// Register a turnState so dequeuePendingSubTurnResults can find it
+	ts := &turnState{
+		ctx:            context.Background(),
+		turnID:         sessionKey,
+		depth:          0,
+		session:        &ephemeralSessionStore{},
+		pendingResults: make(chan *tools.ToolResult, 4),
+	}
+	al.activeTurnStates.Store(sessionKey, ts)
+	defer al.activeTurnStates.Delete(sessionKey)
+
+	// Put 3 results in
+	ts.pendingResults <- &tools.ToolResult{ForLLM: "result-1"}
+	ts.pendingResults <- &tools.ToolResult{ForLLM: "result-2"}
+	ts.pendingResults <- &tools.ToolResult{ForLLM: "result-3"}
+
+	results := al.dequeuePendingSubTurnResults(sessionKey)
+	if len(results) != 3 {
+		t.Errorf("expected 3 results, got %d", len(results))
+	}
+	if results[0].ForLLM != "result-1" || results[2].ForLLM != "result-3" {
+		t.Error("results order or content mismatch")
+	}
+
+	// Channel should be drained now
+	if results := al.dequeuePendingSubTurnResults(sessionKey); len(results) != 0 {
+		t.Errorf("expected empty after drain, got %d", len(results))
+	}
+
+	// After removing from activeTurnStates, returns nil
+	al.activeTurnStates.Delete(sessionKey)
+	if results := al.dequeuePendingSubTurnResults(sessionKey); results != nil {
+		t.Error("expected nil for unregistered session")
+	}
+}
+
+// ====================== Extra Independent Test: Concurrency Semaphore ======================
+func TestSubTurnConcurrencySemaphore(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	parent := &turnState{
+		ctx:            context.Background(),
+		turnID:         "parent-concurrency",
+		depth:          0,
+		pendingResults: make(chan *tools.ToolResult, 10),
+		session:        &ephemeralSessionStore{},
+		concurrencySem: make(chan struct{}, 2), // Only allow 2 concurrent children
+	}
+
+	cfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}}
+
+	// Spawn 2 children — should succeed immediately
+	done := make(chan bool, 3)
+	for i := 0; i < 2; i++ {
+		go func() {
+			_, _ = spawnSubTurn(context.Background(), al, parent, cfg)
+			done <- true
+		}()
+	}
+
+	// Wait a bit to ensure the first 2 are running
+	// (In real scenario they'd be blocked in runTurn, but mockProvider returns immediately)
+	// So we just verify the semaphore doesn't block when under limit
+	<-done
+	<-done
+
+	// Verify semaphore is now full (2/2 slots used, but they already released)
+	// Since mockProvider returns immediately, semaphore is already released
+	// So we can't easily test blocking without a real long-running operation
+
+	// Instead, verify that semaphore exists and has correct capacity
+	if cap(parent.concurrencySem) != 2 {
+		t.Errorf("expected semaphore capacity 2, got %d", cap(parent.concurrencySem))
+	}
+}
+
+// ====================== Extra Independent Test: Hard Abort Cascading ======================
+func TestHardAbortCascading(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	sessionKey := "test-session-abort"
+
+	// Root turn with its own independent context (not derived from child)
+	rootCtx, rootCancel := context.WithCancel(context.Background())
+	rootTS := &turnState{
+		ctx:            rootCtx,
+		cancelFunc:     rootCancel,
+		turnID:         sessionKey,
+		depth:          0,
+		session:        &ephemeralSessionStore{},
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, 5),
+		al:             al,
+	}
+	al.activeTurnStates.Store(sessionKey, rootTS)
+	defer al.activeTurnStates.Delete(sessionKey)
+
+	// Child turn with an INDEPENDENT context (simulates spawnSubTurn behavior:
+	// context.WithTimeout(context.Background(), ...) — NOT derived from parent).
+	// Cascade must therefore happen via childTurnIDs traversal, not Go context tree.
+	childCtx, childCancel := context.WithCancel(context.Background())
+	childID := "child-independent"
+	childTS := &turnState{
+		ctx:            childCtx,
+		cancelFunc:     childCancel,
+		turnID:         childID,
+		pendingResults: make(chan *tools.ToolResult, 4),
+		al:             al,
+	}
+	al.activeTurnStates.Store(childID, childTS)
+	defer al.activeTurnStates.Delete(childID)
+
+	// Wire child into root's childTurnIDs (as spawnSubTurn would do)
+	rootTS.childTurnIDs = append(rootTS.childTurnIDs, childID)
+
+	// Verify neither context is canceled yet
+	select {
+	case <-rootTS.ctx.Done():
+		t.Fatal("root context should not be canceled yet")
+	default:
+	}
+	select {
+	case <-childTS.ctx.Done():
+		t.Fatal("child context should not be canceled yet (independent context)")
+	default:
+	}
+
+	// Trigger Hard Abort via al.HardAbort (goes through steering.go → Finish(true))
+	err := al.HardAbort(sessionKey)
+	if err != nil {
+		t.Fatalf("HardAbort failed: %v", err)
+	}
+
+	// Root context must be canceled
+	select {
+	case <-rootTS.ctx.Done():
+	default:
+		t.Error("root context should be canceled after HardAbort")
+	}
+
+	// Child context must be canceled via childTurnIDs cascade, NOT via Go context tree
+	select {
+	case <-childTS.ctx.Done():
+	default:
+		t.Error("child context should be canceled via childTurnIDs cascade")
+	}
+
+	// HardAbort on non-existent session should return an error
+	if err := al.HardAbort("non-existent-session"); err == nil {
+		t.Error("expected error for non-existent session")
+	}
+}
+
+// TestHardAbortSessionRollback verifies that HardAbort rolls back session history
+// to the state before the turn started, discarding all messages added during the turn.
+func TestHardAbortSessionRollback(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	// Create a session with initial history
+	sess := &ephemeralSessionStore{
+		history: []providers.Message{
+			{Role: "user", Content: "initial message 1"},
+			{Role: "assistant", Content: "initial response 1"},
+		},
+	}
+
+	// Create a root turnState with initialHistoryLength = 2
+	rootTS := &turnState{
+		ctx:                  context.Background(),
+		turnID:               "test-session",
+		depth:                0,
+		session:              sess,
+		initialHistoryLength: 2, // Snapshot: 2 messages
+		pendingResults:       make(chan *tools.ToolResult, 16),
+		concurrencySem:       make(chan struct{}, 5),
+	}
+
+	// Register the turn state
+	al.activeTurnStates.Store("test-session", rootTS)
+
+	// Simulate adding messages during the turn (e.g., user input + assistant response)
+	sess.AddMessage("", "user", "new user message")
+	sess.AddMessage("", "assistant", "new assistant response")
+
+	// Verify history grew to 4 messages
+	if len(sess.GetHistory("")) != 4 {
+		t.Fatalf("expected 4 messages before abort, got %d", len(sess.GetHistory("")))
+	}
+
+	// Trigger HardAbort
+	err := al.HardAbort("test-session")
+	if err != nil {
+		t.Fatalf("HardAbort failed: %v", err)
+	}
+
+	// Verify history rolled back to initial 2 messages
+	finalHistory := sess.GetHistory("")
+	if len(finalHistory) != 2 {
+		t.Errorf("expected history to rollback to 2 messages, got %d", len(finalHistory))
+	}
+
+	// Verify the content matches the initial state
+	if finalHistory[0].Content != "initial message 1" || finalHistory[1].Content != "initial response 1" {
+		t.Error("history content does not match initial state after rollback")
+	}
+}
+
+// TestNestedSubTurnHierarchy verifies that nested SubTurns maintain correct
+// parent-child relationships and depth tracking when recursively calling runAgentLoop.
+func TestNestedSubTurnHierarchy(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	// Track spawned turns and their depths
+	type turnInfo struct {
+		parentID string
+		childID  string
+	}
+	var spawnedTurns []turnInfo
+	var mu sync.Mutex
+
+	// Subscribe to real EventBus to capture spawn events
+	sub := al.SubscribeEvents(16)
+	defer al.UnsubscribeEvents(sub.ID)
+	go func() {
+		for evt := range sub.C {
+			if evt.Kind == EventKindSubTurnSpawn {
+				p, _ := evt.Payload.(SubTurnSpawnPayload)
+				mu.Lock()
+				spawnedTurns = append(spawnedTurns, turnInfo{
+					parentID: p.ParentTurnID,
+					childID:  p.Label,
+				})
+				mu.Unlock()
+			}
+		}
+	}()
+
+	// Create a root turn
+	rootSession := &ephemeralSessionStore{}
+	rootTS := &turnState{
+		ctx:            context.Background(),
+		turnID:         "root-turn",
+		depth:          0,
+		session:        rootSession,
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, 5),
+	}
+
+	// Spawn a child (depth 1)
+	childCfg := SubTurnConfig{Model: "gpt-4o-mini"}
+	_, err := spawnSubTurn(context.Background(), al, rootTS, childCfg)
+	if err != nil {
+		t.Fatalf("failed to spawn child: %v", err)
+	}
+
+	time.Sleep(10 * time.Millisecond) // let event goroutine flush
+
+	// Verify we captured the spawn event
+	mu.Lock()
+	if len(spawnedTurns) != 1 {
+		t.Fatalf("expected 1 spawn event, got %d", len(spawnedTurns))
+	}
+	if spawnedTurns[0].parentID != "root-turn" {
+		t.Errorf("expected parent ID 'root-turn', got %s", spawnedTurns[0].parentID)
+	}
+	mu.Unlock()
+
+	// Verify root turn has the child in its childTurnIDs
+	rootTS.mu.Lock()
+	if len(rootTS.childTurnIDs) != 1 {
+		t.Errorf("expected root to have 1 child, got %d", len(rootTS.childTurnIDs))
+	}
+	rootTS.mu.Unlock()
+}
+
+// TestDeliverSubTurnResultNoDeadlock verifies that deliverSubTurnResult doesn't
+// deadlock when multiple goroutines are accessing the parent turnState concurrently.
+func TestDeliverSubTurnResultNoDeadlock(t *testing.T) {
+	parent := &turnState{
+		ctx:            context.Background(),
+		turnID:         "parent-deadlock-test",
+		depth:          0,
+		pendingResults: make(chan *tools.ToolResult, 2), // Small buffer to test blocking
+	}
+
+	// Simulate multiple child turns delivering results concurrently
+	var wg sync.WaitGroup
+	numChildren := 10
+
+	for i := 0; i < numChildren; i++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			result := &tools.ToolResult{ForLLM: fmt.Sprintf("result-%d", id)}
+			deliverSubTurnResult(nil, parent, fmt.Sprintf("child-%d", id), result)
+		}(i)
+	}
+
+	// Concurrently read from the channel to prevent blocking
+	// and to actually retrieve the matched number of results
+	go func() {
+		for i := 0; i < numChildren; i++ {
+			select {
+			case <-parent.pendingResults:
+			case <-time.After(5 * time.Second):
+				t.Error("timeout waiting for result")
+				return
+			}
+		}
+	}()
+
+	// Wait for all deliveries to complete (with timeout)
+	done := make(chan struct{})
+	go func() {
+		wg.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// Success - no deadlock
+	case <-time.After(3 * time.Second):
+		t.Fatal("deadlock detected: deliverSubTurnResult blocked")
+	}
+}
+
+// TestHardAbortOrderOfOperations verifies that HardAbort calls Finish() before
+// rolling back session history, minimizing the race window where new messages
+// could be added after rollback.
+func TestHardAbortOrderOfOperations(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	sess := &ephemeralSessionStore{
+		history: []providers.Message{
+			{Role: "user", Content: "initial message"},
+			{Role: "assistant", Content: "response 1"},
+			{Role: "user", Content: "follow-up"},
+		},
+	}
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	rootTS := &turnState{
+		ctx:                  ctx,
+		cancelFunc:           cancel,
+		turnID:               "test-session-order",
+		depth:                0,
+		session:              sess,
+		initialHistoryLength: 1, // Snapshot: 1 message
+		pendingResults:       make(chan *tools.ToolResult, 16),
+		concurrencySem:       make(chan struct{}, 5),
+	}
+
+	al.activeTurnStates.Store("test-session-order", rootTS)
+
+	// Trigger HardAbort
+	err := al.HardAbort("test-session-order")
+	if err != nil {
+		t.Fatalf("HardAbort failed: %v", err)
+	}
+
+	// Verify context was canceled (Finish() was called)
+	select {
+	case <-rootTS.ctx.Done():
+		// Good - context was canceled
+	default:
+		t.Error("expected context to be canceled after HardAbort")
+	}
+
+	// Verify history was rolled back
+	finalHistory := sess.GetHistory("")
+	if len(finalHistory) != 1 {
+		t.Errorf("expected history to rollback to 1 message, got %d", len(finalHistory))
+	}
+
+	if finalHistory[0].Content != "initial message" {
+		t.Error("history content does not match initial state after rollback")
+	}
+}
+
+// TestFinishedChannelClosedState verifies that Finish() closes the Finished() channel
+// so that child turns can safely abort waiting.
+func TestFinishedChannelClosedState(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	ts := &turnState{
+		ctx:            ctx,
+		cancelFunc:     cancel,
+		turnID:         "test-finished-channel",
+		depth:          0,
+		pendingResults: make(chan *tools.ToolResult, 2),
+	}
+
+	// Verify Finished channel is blocking initially
+	select {
+	case <-ts.Finished():
+		t.Fatal("finished channel should block initially")
+	default:
+		// Good
+	}
+
+	// Call Finish() with graceful finish
+	ts.Finish(false)
+
+	// Verify Finished channel is closed
+	select {
+	case _, ok := <-ts.Finished():
+		if ok {
+			t.Error("expected Finished() channel to be closed after Finish()")
+		}
+	default:
+		t.Fatal("expected <-ts.Finished() to not block")
+	}
+
+	// Verify Finish() is idempotent
+	ts.Finish(false) // Should not panic
+
+	// Verify deliverSubTurnResult correctly uses Finished() channel and treats as orphan
+	result := &tools.ToolResult{ForLLM: "late result"}
+	deliverSubTurnResult(nil, ts, "child-1", result) // Will emit orphan due to <-ts.Finished() case
+}
+
+// TestFinalPollCapturesLateResults verifies that the final poll before Finish()
+// captures results that arrive after the last iteration poll.
+func TestFinalPollCapturesLateResults(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	sessionKey := "test-session-final-poll"
+
+	// Register a turnState
+	ts := &turnState{
+		ctx:            context.Background(),
+		turnID:         sessionKey,
+		depth:          0,
+		session:        &ephemeralSessionStore{},
+		pendingResults: make(chan *tools.ToolResult, 4),
+	}
+	al.activeTurnStates.Store(sessionKey, ts)
+	defer al.activeTurnStates.Delete(sessionKey)
+
+	// Simulate results arriving after last iteration poll
+	ts.pendingResults <- &tools.ToolResult{ForLLM: "result 1"}
+	ts.pendingResults <- &tools.ToolResult{ForLLM: "result 2"}
+
+	// Dequeue should capture both results
+	results := al.dequeuePendingSubTurnResults(sessionKey)
+
+	if len(results) != 2 {
+		t.Errorf("expected 2 results, got %d", len(results))
+	}
+
+	// Verify channel is now empty
+	results = al.dequeuePendingSubTurnResults(sessionKey)
+	if len(results) != 0 {
+		t.Errorf("expected 0 results on second poll, got %d", len(results))
+	}
+}
+
+// TestSpawnSubTurn_PanicRecovery verifies that even if runTurn panics,
+// the result is still delivered for async calls and SubTurnEndEvent is emitted.
+func TestSpawnSubTurn_PanicRecovery(t *testing.T) {
+	// Create a panic provider
+	panicProvider := &panicMockProvider{}
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Workspace:         t.TempDir(),
+				ModelName:         "test-model",
+				MaxTokens:         4096,
+				MaxToolIterations: 10,
+			},
+		},
+	}
+	al := NewAgentLoop(cfg, bus.NewMessageBus(), panicProvider)
+
+	parent := &turnState{
+		ctx:            context.Background(),
+		turnID:         "parent-panic",
+		depth:          0,
+		pendingResults: make(chan *tools.ToolResult, 1),
+		session:        &ephemeralSessionStore{},
+	}
+
+	collector, collectCleanup := newEventCollector(t, al)
+	defer collectCleanup()
+
+	// Test async call - result should still be delivered via channel
+	asyncCfg := SubTurnConfig{Model: "gpt-4o-mini", Tools: []tools.Tool{}, Async: true}
+	result, err := spawnSubTurn(context.Background(), al, parent, asyncCfg)
+
+	// Should return error from panic recovery
+	if err == nil {
+		t.Error("expected error from panic recovery")
+	}
+
+	// Result should be nil because panic occurred before runTurn could return
+	if result != nil {
+		t.Error("expected nil result after panic")
+	}
+
+	time.Sleep(10 * time.Millisecond) // let event goroutine flush
+	// SubTurnEndEvent should still be emitted
+	if !collector.hasEventOfKind(EventKindSubTurnEnd) {
+		t.Error("SubTurnEndEvent not emitted after panic")
+	}
+
+	// For async call, result should still be delivered to channel (even if nil)
+	select {
+	case res := <-parent.pendingResults:
+		// Result was delivered (nil due to panic)
+		_ = res
+	default:
+		t.Error("async result should be delivered to channel even after panic")
+	}
+}
+
+// panicMockProvider is a mock provider that always panics
+type panicMockProvider struct{}
+
+func (m *panicMockProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	opts map[string]any,
+) (*providers.LLMResponse, error) {
+	panic("intentional panic for testing")
+}
+
+func (m *panicMockProvider) GetDefaultModel() string {
+	return "panic-model"
+}
+
+// ====================== Public API Tests ======================
+
+// simpleMockProviderAPI for testing public APIs
+type simpleMockProviderAPI struct {
+	response string
+}
+
+func (m *simpleMockProviderAPI) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	toolDefs []providers.ToolDefinition,
+	model string,
+	options map[string]any,
+) (*providers.LLMResponse, error) {
+	return &providers.LLMResponse{
+		Content: m.response,
+	}, nil
+}
+
+func (m *simpleMockProviderAPI) GetDefaultModel() string {
+	return "gpt-4o-mini"
+}
+
+// TestGetActiveTurn verifies that GetActiveTurn returns correct turn information
+func TestGetActiveTurn(t *testing.T) {
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "gpt-4o-mini",
+				Provider:  "mock",
+			},
+		},
+	}
+	al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"})
+
+	// Create a root turn state
+	rootCtx := context.Background()
+	rootTS := &turnState{
+		ctx:            rootCtx,
+		turnID:         "root-turn",
+		parentTurnID:   "",
+		depth:          0,
+		childTurnIDs:   []string{},
+		session:        newEphemeralSession(nil),
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+
+	sessionKey := "test-session"
+	al.activeTurnStates.Store(sessionKey, rootTS)
+	defer al.activeTurnStates.Delete(sessionKey)
+
+	// Test: GetActiveTurn should return turn info
+	info := al.GetActiveTurnBySession(sessionKey)
+	if info == nil {
+		t.Fatal("GetActiveTurn returned nil for active session")
+	}
+
+	if info.TurnID != "root-turn" {
+		t.Errorf("Expected TurnID 'root-turn', got %q", info.TurnID)
+	}
+
+	if info.Depth != 0 {
+		t.Errorf("Expected Depth 0, got %d", info.Depth)
+	}
+
+	if info.ParentTurnID != "" {
+		t.Errorf("Expected empty ParentTurnID, got %q", info.ParentTurnID)
+	}
+
+	if len(info.ChildTurnIDs) != 0 {
+		t.Errorf("Expected 0 child turns, got %d", len(info.ChildTurnIDs))
+	}
+
+	// Test: GetActiveTurn should return nil for non-existent session
+	nonExistentInfo := al.GetActiveTurnBySession("non-existent-session")
+	if nonExistentInfo != nil {
+		t.Error("GetActiveTurn should return nil for non-existent session")
+	}
+}
+
+// TestGetActiveTurn_WithChildren verifies that child turn IDs are correctly reported
+func TestGetActiveTurn_WithChildren(t *testing.T) {
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "gpt-4o-mini",
+				Provider:  "mock",
+			},
+		},
+	}
+	al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"})
+
+	rootCtx := context.Background()
+	rootTS := &turnState{
+		ctx:            rootCtx,
+		turnID:         "root-turn",
+		parentTurnID:   "",
+		depth:          0,
+		childTurnIDs:   []string{"child-1", "child-2"},
+		session:        newEphemeralSession(nil),
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+
+	sessionKey := "test-session-with-children"
+	al.activeTurnStates.Store(sessionKey, rootTS)
+	defer al.activeTurnStates.Delete(sessionKey)
+
+	info := al.GetActiveTurnBySession(sessionKey)
+	if info == nil {
+		t.Fatal("GetActiveTurn returned nil")
+	}
+
+	if len(info.ChildTurnIDs) != 2 {
+		t.Fatalf("Expected 2 child turns, got %d", len(info.ChildTurnIDs))
+	}
+
+	if info.ChildTurnIDs[0] != "child-1" || info.ChildTurnIDs[1] != "child-2" {
+		t.Errorf("Child turn IDs mismatch: got %v", info.ChildTurnIDs)
+	}
+}
+
+// TestTurnStateInfo_ThreadSafety verifies that Info() is thread-safe
+func TestTurnStateInfo_ThreadSafety(t *testing.T) {
+	rootCtx := context.Background()
+	ts := &turnState{
+		ctx:            rootCtx,
+		turnID:         "test-turn",
+		parentTurnID:   "parent",
+		depth:          1,
+		childTurnIDs:   []string{},
+		session:        newEphemeralSession(nil),
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+
+	// Concurrently read Info() and modify childTurnIDs
+	done := make(chan bool)
+	go func() {
+		for i := 0; i < 100; i++ {
+			ts.mu.Lock()
+			ts.childTurnIDs = append(ts.childTurnIDs, "child")
+			ts.mu.Unlock()
+		}
+		done <- true
+	}()
+
+	go func() {
+		for i := 0; i < 100; i++ {
+			info := ts.snapshot()
+			if info.TurnID == "" {
+				t.Error("snapshot() returned empty TurnID")
+			}
+		}
+		done <- true
+	}()
+
+	<-done
+	<-done
+}
+
+// TestInjectFollowUp verifies that InjectFollowUp enqueues messages
+func TestInjectFollowUp(t *testing.T) {
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "gpt-4o-mini",
+				Provider:  "mock",
+			},
+		},
+	}
+
+	al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"})
+
+	msg := providers.Message{
+		Role:    "user",
+		Content: "Follow-up task",
+	}
+
+	err := al.InjectFollowUp(msg)
+	if err != nil {
+		t.Fatalf("InjectFollowUp failed: %v", err)
+	}
+
+	// Verify message was enqueued
+	if al.steering.len() != 1 {
+		t.Errorf("Expected 1 message in queue, got %d", al.steering.len())
+	}
+}
+
+// TestAPIAliases verifies that API aliases work correctly
+func TestAPIAliases(t *testing.T) {
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "gpt-4o-mini",
+				Provider:  "mock",
+			},
+		},
+	}
+
+	al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"})
+
+	msg := providers.Message{
+		Role:    "user",
+		Content: "Test message",
+	}
+
+	// Test InterruptGraceful: requires active turn, so error is expected here
+	_ = al.InterruptGraceful(msg.Content)
+
+	// Test InjectSteering (enqueues a steering message)
+	err := al.InjectSteering(msg)
+	if err != nil {
+		t.Errorf("InjectSteering failed: %v", err)
+	}
+
+	// Also enqueue via Steer to verify second message
+	err = al.Steer(msg)
+	if err != nil {
+		t.Errorf("Steer failed: %v", err)
+	}
+
+	// Verify both messages were enqueued
+	if al.steering.len() != 2 {
+		t.Errorf("Expected 2 messages in queue, got %d", al.steering.len())
+	}
+}
+
+// TestInterruptHard_Alias verifies that InterruptHard is an alias for HardAbort
+func TestInterruptHard_Alias(t *testing.T) {
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				ModelName: "gpt-4o-mini",
+				Provider:  "mock",
+			},
+		},
+	}
+	al := NewAgentLoop(cfg, nil, &simpleMockProviderAPI{response: "ok"})
+
+	rootCtx := context.Background()
+	rootTS := &turnState{
+		ctx:                  rootCtx,
+		turnID:               "test-turn",
+		depth:                0,
+		session:              newEphemeralSession(nil),
+		initialHistoryLength: 0,
+		pendingResults:       make(chan *tools.ToolResult, 16),
+		concurrencySem:       make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+
+	sessionKey := "test-session-interrupt"
+	al.activeTurnStates.Store(sessionKey, rootTS)
+
+	// Test InterruptHard (alias for HardAbort)
+	err := al.InterruptHard()
+	if err != nil {
+		t.Errorf("InterruptHard failed: %v", err)
+	}
+
+	// Verify turn was finished (removed from activeTurnStates)
+	info := al.GetActiveTurnBySession(sessionKey)
+	_ = info // turn may still be in map briefly; hard abort sets isFinished on the state
+}
+
+// TestFinish_ConcurrentCalls verifies that calling Finish() concurrently from multiple
+// goroutines is safe and doesn't cause panics or double-close errors.
+func TestFinish_ConcurrentCalls(t *testing.T) {
+	ctx := context.Background()
+	parentTS := &turnState{
+		ctx:            ctx,
+		turnID:         "parent-concurrent-finish",
+		depth:          0,
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+	parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+	// Launch multiple goroutines that all call Finish() concurrently
+	const numGoroutines = 10
+	var wg sync.WaitGroup
+	wg.Add(numGoroutines)
+
+	for i := 0; i < numGoroutines; i++ {
+		go func() {
+			defer wg.Done()
+			// This should not panic, even when called concurrently
+			parentTS.Finish(false)
+		}()
+	}
+
+	wg.Wait()
+
+	// Verify the Finished() channel is closed
+	select {
+	case _, ok := <-parentTS.Finished():
+		if ok {
+			t.Error("Expected Finished() channel to be closed")
+		}
+	default:
+		t.Error("Expected Finished() channel to be closed and readable without blocking")
+	}
+
+	// Verify isFinished is set
+	parentTS.mu.Lock()
+	if !parentTS.isFinished.Load() {
+		t.Error("Expected isFinished to be true")
+	}
+	parentTS.mu.Unlock()
+}
+
+// TestDeliverSubTurnResult_RaceWithFinish verifies that deliverSubTurnResult handles
+// the race condition where Finish() is called while results are being delivered.
+func TestDeliverSubTurnResult_RaceWithFinish(t *testing.T) {
+	al, _, _, _, cleanup := newTestAgentLoop(t) //nolint:dogsled
+	defer cleanup()
+
+	// Collect events via real EventBus
+	var mu sync.Mutex
+	var deliveredCount, orphanCount int
+	sub := al.SubscribeEvents(64)
+	defer al.UnsubscribeEvents(sub.ID)
+	go func() {
+		for evt := range sub.C {
+			mu.Lock()
+			switch evt.Kind {
+			case EventKindSubTurnResultDelivered:
+				deliveredCount++
+			case EventKindSubTurnOrphan:
+				orphanCount++
+			}
+			mu.Unlock()
+		}
+	}()
+
+	ctx := context.Background()
+	parentTS := &turnState{
+		ctx:            ctx,
+		turnID:         "parent-race-test",
+		depth:          0,
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+	parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+	// Launch goroutines that deliver results while another goroutine calls Finish()
+	const numResults = 20
+	var wg sync.WaitGroup
+	wg.Add(numResults + 1)
+
+	// Goroutine that calls Finish() after a short delay
+	go func() {
+		defer wg.Done()
+		time.Sleep(5 * time.Millisecond)
+		parentTS.Finish(false)
+	}()
+
+	// Goroutines that deliver results
+	for i := 0; i < numResults; i++ {
+		go func(id int) {
+			defer wg.Done()
+			result := &tools.ToolResult{
+				ForLLM: fmt.Sprintf("result-%d", id),
+			}
+			// This should not panic, even if Finish() is called concurrently
+			deliverSubTurnResult(al, parentTS, fmt.Sprintf("child-%d", id), result)
+		}(i)
+	}
+
+	wg.Wait()
+	time.Sleep(20 * time.Millisecond) // let event goroutine flush
+
+	// Get final counts
+	mu.Lock()
+	finalDelivered := deliveredCount
+	finalOrphan := orphanCount
+	mu.Unlock()
+
+	t.Logf("Delivered: %d, Orphan: %d, Total: %d", finalDelivered, finalOrphan, finalDelivered+finalOrphan)
+
+	// With the new drainPendingResults behavior, the total events may be >= numResults
+	// because Finish() drains remaining results from the channel and emits them as orphans.
+	// So we expect:
+	// - Some results were delivered successfully (before Finish())
+	// - Some results became orphans (after Finish() or channel full)
+	// - Some results were in the channel when Finish() was called and got drained as orphans
+	// The total should be at least numResults (could be more due to drain)
+	if finalDelivered+finalOrphan < numResults {
+		t.Errorf("Expected at least %d total events, got %d delivered + %d orphan = %d",
+			numResults, finalDelivered, finalOrphan, finalDelivered+finalOrphan)
+	}
+
+	// Should have at least some orphan results (those that arrived after Finish() or were drained)
+	if finalOrphan == 0 {
+		t.Error("Expected at least some orphan results after Finish()")
+	}
+}
+
+// TestConcurrencySemaphore_Timeout verifies that spawning sub-turns times out
+// when all concurrency slots are occupied for too long.
+// Note: This test uses a shorter timeout by temporarily modifying the constant.
+func TestConcurrencySemaphore_Timeout(t *testing.T) {
+	// This test would take 30 seconds with the default timeout.
+	// Instead, we'll test the mechanism by verifying the timeout context is created correctly.
+	// A full integration test with actual timeout would be too slow for unit tests.
+
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Provider: "mock",
+			},
+		},
+	}
+	msgBus := bus.NewMessageBus()
+	provider := &simpleMockProviderAPI{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	ctx := context.Background()
+	parentTS := &turnState{
+		ctx:            ctx,
+		turnID:         "parent-timeout-test",
+		depth:          0,
+		session:        newEphemeralSession(nil),
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+	parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+	defer parentTS.Finish(false)
+
+	// Fill all concurrency slots
+	for i := 0; i < testMaxConcurrentSubTurns; i++ {
+		parentTS.concurrencySem <- struct{}{}
+	}
+
+	// Create a context with a very short timeout for testing
+	testCtx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
+	defer cancel()
+
+	// Now try to spawn a sub-turn with the short timeout context
+	subTurnCfg := SubTurnConfig{
+		Model: "gpt-4o-mini",
+		Async: false,
+	}
+
+	start := time.Now()
+	_, err := spawnSubTurn(testCtx, al, parentTS, subTurnCfg)
+	elapsed := time.Since(start)
+
+	// Should get a timeout error (either from our timeout context or the internal one)
+	if err == nil {
+		t.Error("Expected timeout error, got nil")
+	}
+
+	// The error should be related to context cancellation or timeout
+	if !errors.Is(err, context.DeadlineExceeded) && !errors.Is(err, ErrConcurrencyTimeout) {
+		t.Logf("Got error: %v (type: %T)", err, err)
+		// This is acceptable - the error might be wrapped
+	}
+
+	// Should timeout quickly (within a reasonable margin)
+	if elapsed > 2*time.Second {
+		t.Errorf("Timeout took too long: %v", elapsed)
+	}
+
+	t.Logf("Timeout occurred after %v with error: %v", elapsed, err)
+
+	// Clean up - drain the semaphore
+	for i := 0; i < testMaxConcurrentSubTurns; i++ {
+		<-parentTS.concurrencySem
+	}
+}
+
+// TestEphemeralSession_AutoTruncate verifies that ephemeral sessions automatically
+// truncate their history to prevent memory accumulation.
+func TestEphemeralSession_AutoTruncate(t *testing.T) {
+	store := newEphemeralSession(nil).(*ephemeralSessionStore)
+
+	// Add more messages than the limit
+	for i := 0; i < maxEphemeralHistorySize+20; i++ {
+		store.AddMessage("test", "user", fmt.Sprintf("message-%d", i))
+	}
+
+	// Verify history is truncated to the limit
+	history := store.GetHistory("test")
+	if len(history) != maxEphemeralHistorySize {
+		t.Errorf("Expected history length %d, got %d", maxEphemeralHistorySize, len(history))
+	}
+
+	// Verify we kept the most recent messages
+	lastMsg := history[len(history)-1]
+	expectedContent := fmt.Sprintf("message-%d", maxEphemeralHistorySize+20-1)
+	if lastMsg.Content != expectedContent {
+		t.Errorf("Expected last message to be %q, got %q", expectedContent, lastMsg.Content)
+	}
+
+	// Verify the oldest messages were discarded
+	firstMsg := history[0]
+	expectedFirstContent := fmt.Sprintf("message-%d", 20) // First 20 were discarded
+	if firstMsg.Content != expectedFirstContent {
+		t.Errorf("Expected first message to be %q, got %q", expectedFirstContent, firstMsg.Content)
+	}
+}
+
+// TestContextWrapping_SingleLayer verifies that we only create one context layer
+// in spawnSubTurn, not multiple redundant layers.
+func TestContextWrapping_SingleLayer(t *testing.T) {
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Provider: "mock",
+			},
+		},
+	}
+	msgBus := bus.NewMessageBus()
+	provider := &simpleMockProviderAPI{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	ctx := context.Background()
+	parentTS := &turnState{
+		ctx:            ctx,
+		turnID:         "parent-context-test",
+		depth:          0,
+		session:        newEphemeralSession(nil),
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+	parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+	defer parentTS.Finish(false)
+
+	// Spawn a sub-turn
+	subTurnCfg := SubTurnConfig{
+		Model: "gpt-4o-mini",
+		Async: false,
+	}
+
+	result, err := spawnSubTurn(ctx, al, parentTS, subTurnCfg)
+	if err != nil {
+		t.Fatalf("spawnSubTurn failed: %v", err)
+	}
+
+	if result == nil {
+		t.Error("Expected non-nil result")
+	}
+
+	// Verify the child turn was created with a cancel function
+	// (This is implicit - if the test passes without hanging, the context management is correct)
+	t.Log("Context wrapping test passed - no redundant layers detected")
+}
+
+// TestSyncSubTurn_NoChannelDelivery verifies that synchronous sub-turns
+// do NOT deliver results to the pendingResults channel (only return directly).
+func TestSyncSubTurn_NoChannelDelivery(t *testing.T) {
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Provider: "mock",
+			},
+		},
+	}
+	msgBus := bus.NewMessageBus()
+	provider := &simpleMockProviderAPI{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	ctx := context.Background()
+	parentTS := &turnState{
+		ctx:            ctx,
+		turnID:         "parent-sync-test",
+		depth:          0,
+		session:        newEphemeralSession(nil),
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+	parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+	defer parentTS.Finish(false)
+
+	// Spawn a SYNCHRONOUS sub-turn (Async=false)
+	subTurnCfg := SubTurnConfig{
+		Model: "gpt-4o-mini",
+		Async: false, // Synchronous - should NOT deliver to channel
+	}
+
+	result, err := spawnSubTurn(ctx, al, parentTS, subTurnCfg)
+	if err != nil {
+		t.Fatalf("spawnSubTurn failed: %v", err)
+	}
+
+	if result == nil {
+		t.Error("Expected non-nil result from synchronous sub-turn")
+	}
+
+	// Verify the pendingResults channel is EMPTY
+	// (synchronous sub-turns should not deliver to channel)
+	select {
+	case r := <-parentTS.pendingResults:
+		t.Errorf("Expected empty channel for sync sub-turn, but got result: %v", r)
+	default:
+		// Expected: channel is empty
+		t.Log("Verified: synchronous sub-turn did not deliver to channel")
+	}
+
+	// Verify channel length is 0
+	if len(parentTS.pendingResults) != 0 {
+		t.Errorf("Expected channel length 0, got %d", len(parentTS.pendingResults))
+	}
+}
+
+// TestAsyncSubTurn_ChannelDelivery verifies that asynchronous sub-turns
+// DO deliver results to the pendingResults channel.
+func TestAsyncSubTurn_ChannelDelivery(t *testing.T) {
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Provider: "mock",
+			},
+		},
+	}
+	msgBus := bus.NewMessageBus()
+	provider := &simpleMockProviderAPI{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	ctx := context.Background()
+	parentTS := &turnState{
+		ctx:            ctx,
+		turnID:         "parent-async-test",
+		depth:          0,
+		session:        newEphemeralSession(nil),
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+	parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+	defer parentTS.Finish(false)
+
+	// Spawn an ASYNCHRONOUS sub-turn (Async=true)
+	subTurnCfg := SubTurnConfig{
+		Model: "gpt-4o-mini",
+		Async: true, // Asynchronous - SHOULD deliver to channel
+	}
+
+	result, err := spawnSubTurn(ctx, al, parentTS, subTurnCfg)
+	if err != nil {
+		t.Fatalf("spawnSubTurn failed: %v", err)
+	}
+
+	if result == nil {
+		t.Error("Expected non-nil result from asynchronous sub-turn")
+	}
+
+	// Verify the pendingResults channel has the result
+	select {
+	case r := <-parentTS.pendingResults:
+		if r == nil {
+			t.Error("Expected non-nil result from channel")
+		}
+		t.Log("Verified: asynchronous sub-turn delivered to channel")
+	case <-time.After(100 * time.Millisecond):
+		t.Error("Expected result in channel for async sub-turn, but channel was empty")
+	}
+}
+
+// TestGrandchildAbort_CascadingCancellation verifies that when a grandparent turn
+// is hard aborted, the cancellation cascades down to grandchild turns.
+func TestGrandchildAbort_CascadingCancellation(t *testing.T) {
+	al, _, _, provider, cleanup := newTestAgentLoop(t)
+	_ = provider
+	defer cleanup()
+
+	// Three independent contexts — none derived from another.
+	// Cascade must happen exclusively through childTurnIDs traversal in Finish(true).
+	gpCtx, gpCancel := context.WithCancel(context.Background())
+	parentCtx, parentCancel := context.WithCancel(context.Background())
+	childCtx, childCancel := context.WithCancel(context.Background())
+
+	childTS := &turnState{
+		ctx:        childCtx,
+		cancelFunc: childCancel,
+		turnID:     "grandchild",
+		al:         al,
+	}
+	parentTS := &turnState{
+		ctx:          parentCtx,
+		cancelFunc:   parentCancel,
+		turnID:       "parent",
+		childTurnIDs: []string{"grandchild"},
+		al:           al,
+	}
+	grandparentTS := &turnState{
+		ctx:            gpCtx,
+		cancelFunc:     gpCancel,
+		turnID:         "grandparent",
+		depth:          0,
+		session:        newEphemeralSession(nil),
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+		childTurnIDs:   []string{"parent"},
+		al:             al,
+	}
+
+	al.activeTurnStates.Store("grandparent", grandparentTS)
+	al.activeTurnStates.Store("parent", parentTS)
+	al.activeTurnStates.Store("grandchild", childTS)
+	defer al.activeTurnStates.Delete("grandparent")
+	defer al.activeTurnStates.Delete("parent")
+	defer al.activeTurnStates.Delete("grandchild")
+
+	// All contexts must be active before the abort
+	for _, ctx := range []context.Context{gpCtx, parentCtx, childCtx} {
+		select {
+		case <-ctx.Done():
+			t.Fatal("context should not be canceled yet")
+		default:
+		}
+	}
+
+	// Hard abort the grandparent — should cascade to parent and grandchild
+	grandparentTS.Finish(true)
+
+	time.Sleep(10 * time.Millisecond)
+
+	select {
+	case <-gpCtx.Done():
+		t.Log("Grandparent context canceled (expected)")
+	default:
+		t.Error("Grandparent context should be canceled")
+	}
+	select {
+	case <-parentCtx.Done():
+		t.Log("Parent context canceled via cascade (expected)")
+	default:
+		t.Error("Parent context should be canceled via childTurnIDs cascade")
+	}
+	select {
+	case <-childCtx.Done():
+		t.Log("Grandchild context canceled via cascade (expected)")
+	default:
+		t.Error("Grandchild context should be canceled via childTurnIDs cascade")
+	}
+}
+
+// TestSpawnDuringAbort_RaceCondition verifies behavior when trying to spawn
+// a sub-turn while the parent is being aborted.
+func TestSpawnDuringAbort_RaceCondition(t *testing.T) {
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Provider: "mock",
+			},
+		},
+	}
+	msgBus := bus.NewMessageBus()
+	provider := &simpleMockProviderAPI{}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	ctx := context.Background()
+	parentTS := &turnState{
+		ctx:            ctx,
+		turnID:         "parent-abort-race",
+		depth:          0,
+		session:        newEphemeralSession(nil),
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+	parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+	var wg sync.WaitGroup
+	wg.Add(2)
+
+	var spawnErr error
+
+	// Goroutine 1: Try to spawn a sub-turn
+	go func() {
+		defer wg.Done()
+		subTurnCfg := SubTurnConfig{
+			Model: "gpt-4o-mini",
+			Async: false,
+		}
+		_, err := spawnSubTurn(parentTS.ctx, al, parentTS, subTurnCfg)
+		spawnErr = err
+	}()
+
+	// Goroutine 2: Abort the parent almost immediately
+	go func() {
+		defer wg.Done()
+		time.Sleep(1 * time.Millisecond)
+		parentTS.Finish(false)
+	}()
+
+	wg.Wait()
+
+	// The spawn should either succeed (if it started before abort)
+	// or fail with context canceled error (if abort happened first)
+	if spawnErr != nil {
+		if errors.Is(spawnErr, context.Canceled) {
+			t.Logf("Spawn failed with expected context cancellation: %v", spawnErr)
+		} else {
+			t.Logf("Spawn failed with error: %v", spawnErr)
+		}
+	} else {
+		t.Log("Spawn succeeded before abort")
+	}
+
+	// The important thing is that it doesn't panic or deadlock
+	t.Log("Race condition handled gracefully - no panic or deadlock")
+}
+
+// ====================== Slow SubTurn Cancellation Test ======================
+
+// slowMockProvider simulates a slow LLM call that takes a long time to complete.
+// This is used to test the scenario where a parent turn finishes before the child SubTurn.
+type slowMockProvider struct {
+	delay time.Duration
+}
+
+func (m *slowMockProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	toolDefs []providers.ToolDefinition,
+	model string,
+	options map[string]any,
+) (*providers.LLMResponse, error) {
+	select {
+	case <-time.After(m.delay):
+		// Completed normally after delay
+		return &providers.LLMResponse{
+			Content: "slow response completed",
+		}, nil
+	case <-ctx.Done():
+		// Context was canceled while waiting
+		return nil, ctx.Err()
+	}
+}
+
+func (m *slowMockProvider) GetDefaultModel() string {
+	return "slow-model"
+}
+
+// TestAsyncSubTurn_ParentFinishesEarly simulates the scenario where:
+// 1. Parent spawns an async SubTurn that takes a long time
+// 2. Parent finishes quickly
+// 3. SubTurn should be canceled with context canceled error
+func TestAsyncSubTurn_ParentFinishesEarly(t *testing.T) {
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Provider: "mock",
+			},
+		},
+	}
+	msgBus := bus.NewMessageBus()
+	provider := &slowMockProvider{delay: 5 * time.Second} // SubTurn takes 5 seconds
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	// Capture events via real EventBus
+	var mu sync.Mutex
+	var events []Event
+	sub := al.SubscribeEvents(32)
+	defer al.UnsubscribeEvents(sub.ID)
+	go func() {
+		for evt := range sub.C {
+			mu.Lock()
+			events = append(events, evt)
+			mu.Unlock()
+		}
+	}()
+
+	ctx := context.Background()
+	parentTS := &turnState{
+		ctx:            ctx,
+		turnID:         "parent-fast",
+		depth:          0,
+		session:        newEphemeralSession(nil),
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+	parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+	var subTurnErr error
+	var subTurnResult *tools.ToolResult
+	var wg sync.WaitGroup
+
+	// Spawn async SubTurn in a goroutine (it will be slow)
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		subTurnCfg := SubTurnConfig{
+			Model: "slow-model",
+			Async: true, // Asynchronous SubTurn
+		}
+		subTurnResult, subTurnErr = spawnSubTurn(parentTS.ctx, al, parentTS, subTurnCfg)
+	}()
+
+	// Parent finishes quickly (after 100ms), while SubTurn is still running
+	time.Sleep(100 * time.Millisecond)
+	t.Log("Parent finishing early...")
+	parentTS.Finish(false)
+
+	// Wait for SubTurn to complete (or be canceled)
+	wg.Wait()
+
+	// Check the result
+	t.Logf("SubTurn error: %v", subTurnErr)
+	t.Logf("SubTurn result: %v", subTurnResult)
+
+	if subTurnErr != nil {
+		if errors.Is(subTurnErr, context.Canceled) {
+			t.Log("✓ SubTurn was canceled as expected (context canceled)")
+		} else {
+			t.Logf("SubTurn failed with other error: %v", subTurnErr)
+		}
+	} else {
+		t.Log("SubTurn completed before parent finished (unlikely but possible)")
+	}
+
+	// Log captured events
+	mu.Lock()
+	t.Logf("Captured %d events:", len(events))
+	for i, e := range events {
+		t.Logf("  Event %d: %s", i+1, e.Kind)
+	}
+	mu.Unlock()
+}
+
+// TestAsyncSubTurn_ParentWaitsForChild simulates the scenario where:
+// 1. Parent spawns an async SubTurn that takes some time
+// 2. Parent WAITS for SubTurn to complete before finishing
+// 3. Both should complete successfully
+func TestAsyncSubTurn_ParentWaitsForChild(t *testing.T) {
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Provider: "mock",
+			},
+		},
+	}
+	msgBus := bus.NewMessageBus()
+	provider := &slowMockProvider{delay: 200 * time.Millisecond} // SubTurn takes 200ms
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	ctx := context.Background()
+	parentTS := &turnState{
+		ctx:            ctx,
+		turnID:         "parent-wait",
+		depth:          0,
+		session:        newEphemeralSession(nil),
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+	parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+	var subTurnErr error
+	var subTurnResult *tools.ToolResult
+	var wg sync.WaitGroup
+
+	// Spawn async SubTurn in a goroutine
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		subTurnCfg := SubTurnConfig{
+			Model: "slow-model",
+			Async: true,
+		}
+		subTurnResult, subTurnErr = spawnSubTurn(parentTS.ctx, al, parentTS, subTurnCfg)
+	}()
+
+	// Parent WAITS for SubTurn to complete
+	t.Log("Parent waiting for SubTurn...")
+	wg.Wait()
+	t.Log("SubTurn completed, parent now finishing")
+
+	// Now parent can finish safely
+	parentTS.Finish(false)
+
+	// Check the result
+	if subTurnErr != nil {
+		if errors.Is(subTurnErr, context.Canceled) {
+			t.Errorf("SubTurn should NOT have been canceled: %v", subTurnErr)
+		} else {
+			t.Logf("SubTurn failed with error: %v", subTurnErr)
+		}
+	} else {
+		t.Log("✓ SubTurn completed successfully")
+		if subTurnResult != nil {
+			t.Logf("SubTurn result: %s", subTurnResult.ForLLM)
+		}
+	}
+
+	// Check channel delivery
+	select {
+	case r := <-parentTS.pendingResults:
+		if r != nil {
+			t.Logf("✓ Result delivered to channel: %s", r.ForLLM)
+		}
+	case <-time.After(100 * time.Millisecond):
+		t.Log("No result in channel (expected since we waited)")
+	}
+}
+
+// ====================== Graceful vs Hard Finish Tests ======================
+
+// TestFinish_GracefulVsHard verifies the behavior difference between:
+// - Finish(false): graceful finish, signals parentEnded but doesn't cancel children
+// - Finish(true): hard abort, immediately cancels all children
+func TestFinish_GracefulVsHard(t *testing.T) {
+	// Test 1: Graceful finish should set parentEnded but not cancel context
+	t.Run("Graceful_SetsParentEnded", func(t *testing.T) {
+		ctx, cancel := context.WithCancel(context.Background())
+		defer cancel()
+
+		ts := &turnState{
+			ctx:            ctx,
+			turnID:         "graceful-test",
+			depth:          0,
+			pendingResults: make(chan *tools.ToolResult, 16),
+		}
+		ts.ctx, ts.cancelFunc = context.WithCancel(ctx)
+
+		// Finish gracefully
+		ts.Finish(false)
+
+		// Verify parentEnded is set
+		if !ts.parentEnded.Load() {
+			t.Error("parentEnded should be true after graceful finish")
+		}
+
+		// Verify context is NOT canceled (for graceful finish, children continue)
+		// Note: In graceful mode, we don't call cancelFunc()
+		// But since we're using WithCancel on the same ctx, it might be canceled
+		// Let's check that the context is still valid for a moment
+		time.Sleep(10 * time.Millisecond)
+		// Context might be canceled by the deferred cancel() in test, which is fine
+	})
+
+	// Test 2: Hard abort should cancel context immediately
+	t.Run("Hard_CancelsContext", func(t *testing.T) {
+		ctx := context.Background()
+
+		ts := &turnState{
+			ctx:            ctx,
+			turnID:         "hard-test",
+			depth:          0,
+			pendingResults: make(chan *tools.ToolResult, 16),
+		}
+		ts.ctx, ts.cancelFunc = context.WithCancel(ctx)
+
+		// Finish with hard abort
+		ts.Finish(true)
+
+		// Verify context is canceled
+		select {
+		case <-ts.ctx.Done():
+			t.Log("✓ Context canceled after hard abort")
+		default:
+			t.Error("Context should be canceled after hard abort")
+		}
+	})
+
+	// Test 3: IsParentEnded returns correct value
+	t.Run("IsParentEnded", func(t *testing.T) {
+		ctx := context.Background()
+
+		parentTS := &turnState{
+			ctx:            ctx,
+			turnID:         "parent-isended-test",
+			depth:          0,
+			pendingResults: make(chan *tools.ToolResult, 16),
+		}
+		parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+		childTS := &turnState{
+			ctx:             ctx,
+			turnID:          "child-isended-test",
+			depth:           1,
+			parentTurnState: parentTS,
+			pendingResults:  make(chan *tools.ToolResult, 16),
+		}
+
+		// Before parent finishes
+		if childTS.IsParentEnded() {
+			t.Error("IsParentEnded should be false before parent finishes")
+		}
+
+		// Finish parent gracefully
+		parentTS.Finish(false)
+
+		// After parent finishes
+		if !childTS.IsParentEnded() {
+			t.Error("IsParentEnded should be true after parent finishes gracefully")
+		}
+	})
+}
+
+// TestSubTurn_IndependentContext verifies that SubTurns use independent contexts
+// that don't get canceled when the parent finishes gracefully.
+func TestSubTurn_IndependentContext(t *testing.T) {
+	cfg := &config.Config{
+		Agents: config.AgentsConfig{
+			Defaults: config.AgentDefaults{
+				Provider: "mock",
+			},
+		},
+	}
+	msgBus := bus.NewMessageBus()
+	provider := &slowMockProvider{delay: 500 * time.Millisecond}
+	al := NewAgentLoop(cfg, msgBus, provider)
+
+	ctx := context.Background()
+	parentTS := &turnState{
+		ctx:            ctx,
+		turnID:         "parent-independent",
+		depth:          0,
+		session:        newEphemeralSession(nil),
+		pendingResults: make(chan *tools.ToolResult, 16),
+		concurrencySem: make(chan struct{}, testMaxConcurrentSubTurns),
+	}
+	parentTS.ctx, parentTS.cancelFunc = context.WithCancel(ctx)
+
+	var subTurnErr error
+	var wg sync.WaitGroup
+
+	// Spawn SubTurn with Critical=true (should continue after parent finishes)
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		subTurnCfg := SubTurnConfig{
+			Model:    "slow-model",
+			Async:    true,
+			Critical: true, // Critical SubTurn should continue
+		}
+		_, subTurnErr = spawnSubTurn(parentTS.ctx, al, parentTS, subTurnCfg)
+	}()
+
+	// Let SubTurn start
+	time.Sleep(50 * time.Millisecond)
+
+	// Parent finishes gracefully (should NOT cancel SubTurn)
+	parentTS.Finish(false)
+	t.Log("Parent finished gracefully, SubTurn should continue")
+
+	// Wait for SubTurn to complete
+	wg.Wait()
+
+	// SubTurn should complete without context canceled error
+	// (because it uses independent context now)
+	if subTurnErr != nil {
+		t.Logf("SubTurn error: %v", subTurnErr)
+		// The error might be context.DeadlineExceeded if timeout is too short
+		// but should NOT be context.Canceled from parent
+		if errors.Is(subTurnErr, context.Canceled) {
+			t.Error("SubTurn should not be canceled by parent's graceful finish")
+		}
+	} else {
+		t.Log("✓ SubTurn completed successfully (independent context)")
+	}
+}
diff --git a/pkg/agent/thinking.go b/pkg/agent/thinking.go
new file mode 100644
index 000000000..015b69282
--- /dev/null
+++ b/pkg/agent/thinking.go
@@ -0,0 +1,39 @@
+package agent
+
+import "strings"
+
+// ThinkingLevel controls how the provider sends thinking parameters.
+//
+//   - "adaptive": sends {thinking: {type: "adaptive"}} + output_config.effort (Claude 4.6+)
+//   - "low"/"medium"/"high"/"xhigh": sends {thinking: {type: "enabled", budget_tokens: N}} (all models)
+//   - "off": disables thinking
+type ThinkingLevel string
+
+const (
+	ThinkingOff      ThinkingLevel = "off"
+	ThinkingLow      ThinkingLevel = "low"
+	ThinkingMedium   ThinkingLevel = "medium"
+	ThinkingHigh     ThinkingLevel = "high"
+	ThinkingXHigh    ThinkingLevel = "xhigh"
+	ThinkingAdaptive ThinkingLevel = "adaptive"
+)
+
+// parseThinkingLevel normalizes a config string to a ThinkingLevel.
+// Case-insensitive and whitespace-tolerant for user-facing config values.
+// Returns ThinkingOff for unknown or empty values.
+func parseThinkingLevel(level string) ThinkingLevel {
+	switch strings.ToLower(strings.TrimSpace(level)) {
+	case "adaptive":
+		return ThinkingAdaptive
+	case "low":
+		return ThinkingLow
+	case "medium":
+		return ThinkingMedium
+	case "high":
+		return ThinkingHigh
+	case "xhigh":
+		return ThinkingXHigh
+	default:
+		return ThinkingOff
+	}
+}
diff --git a/pkg/agent/thinking_test.go b/pkg/agent/thinking_test.go
new file mode 100644
index 000000000..be3a68c33
--- /dev/null
+++ b/pkg/agent/thinking_test.go
@@ -0,0 +1,35 @@
+package agent
+
+import "testing"
+
+func TestParseThinkingLevel(t *testing.T) {
+	tests := []struct {
+		name  string
+		input string
+		want  ThinkingLevel
+	}{
+		{"off", "off", ThinkingOff},
+		{"empty", "", ThinkingOff},
+		{"low", "low", ThinkingLow},
+		{"medium", "medium", ThinkingMedium},
+		{"high", "high", ThinkingHigh},
+		{"xhigh", "xhigh", ThinkingXHigh},
+		{"adaptive", "adaptive", ThinkingAdaptive},
+		{"unknown", "unknown", ThinkingOff},
+		// Case-insensitive and whitespace-tolerant
+		{"upper_Medium", "Medium", ThinkingMedium},
+		{"upper_HIGH", "HIGH", ThinkingHigh},
+		{"mixed_Adaptive", "Adaptive", ThinkingAdaptive},
+		{"leading_space", " high", ThinkingHigh},
+		{"trailing_space", "low ", ThinkingLow},
+		{"both_spaces", " medium ", ThinkingMedium},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := parseThinkingLevel(tt.input); got != tt.want {
+				t.Errorf("parseThinkingLevel(%q) = %q, want %q", tt.input, got, tt.want)
+			}
+		})
+	}
+}
diff --git a/pkg/agent/turn.go b/pkg/agent/turn.go
new file mode 100644
index 000000000..e4970c519
--- /dev/null
+++ b/pkg/agent/turn.go
@@ -0,0 +1,481 @@
+package agent
+
+import (
+	"context"
+	"reflect"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/session"
+	"github.com/sipeed/picoclaw/pkg/tools"
+)
+
+type TurnPhase string
+
+const (
+	TurnPhaseSetup      TurnPhase = "setup"
+	TurnPhaseRunning    TurnPhase = "running"
+	TurnPhaseTools      TurnPhase = "tools"
+	TurnPhaseFinalizing TurnPhase = "finalizing"
+	TurnPhaseCompleted  TurnPhase = "completed"
+	TurnPhaseAborted    TurnPhase = "aborted"
+)
+
+type ActiveTurnInfo struct {
+	TurnID       string
+	AgentID      string
+	SessionKey   string
+	Channel      string
+	ChatID       string
+	UserMessage  string
+	Phase        TurnPhase
+	Iteration    int
+	StartedAt    time.Time
+	Depth        int
+	ParentTurnID string
+	ChildTurnIDs []string
+}
+
+type turnResult struct {
+	finalContent string
+	status       TurnEndStatus
+	followUps    []bus.InboundMessage
+}
+
+type turnState struct {
+	mu sync.RWMutex
+
+	agent *AgentInstance
+	opts  processOptions
+	scope turnEventScope
+
+	turnID     string
+	agentID    string
+	sessionKey string
+
+	channel     string
+	chatID      string
+	userMessage string
+	media       []string
+
+	phase        TurnPhase
+	iteration    int
+	startedAt    time.Time
+	finalContent string
+
+	followUps []bus.InboundMessage
+
+	gracefulInterrupt     bool
+	gracefulInterruptHint string
+	gracefulTerminalUsed  bool
+	hardAbort             bool
+	providerCancel        context.CancelFunc
+	turnCancel            context.CancelFunc
+
+	restorePointHistory []providers.Message
+	restorePointSummary string
+	persistedMessages   []providers.Message
+
+	// SubTurn support (from HEAD)
+	depth                int                    // SubTurn depth (0 for root turn)
+	parentTurnID         string                 // Parent turn ID (empty for root turn)
+	childTurnIDs         []string               // Child turn IDs
+	pendingResults       chan *tools.ToolResult // Channel for SubTurn results
+	concurrencySem       chan struct{}          // Semaphore for limiting concurrent SubTurns
+	isFinished           atomic.Bool            // Whether this turn has finished
+	session              session.SessionStore   // Session store reference
+	initialHistoryLength int                    // Snapshot of history length at turn start
+
+	// Additional SubTurn fields
+	ctx             context.Context    // Context for this turn
+	cancelFunc      context.CancelFunc // Cancel function for this turn's context
+	critical        bool               // Whether this SubTurn should continue after parent ends
+	parentTurnState *turnState         // Reference to parent turnState
+	parentEnded     atomic.Bool        // Whether parent has ended
+	closeOnce       sync.Once          // Ensures pendingResults channel is closed once
+	finishedChan    chan struct{}      // Closed when turn finishes
+
+	// Token budget tracking
+	tokenBudget      *atomic.Int64        // Shared token budget counter
+	lastFinishReason string               // Last LLM finish_reason
+	lastUsage        *providers.UsageInfo // Last LLM usage info
+
+	// Back-reference to the owning AgentLoop (set for SubTurns only, used for hard abort cascade)
+	al *AgentLoop
+}
+
+func newTurnState(agent *AgentInstance, opts processOptions, scope turnEventScope) *turnState {
+	ts := &turnState{
+		agent:       agent,
+		opts:        opts,
+		scope:       scope,
+		turnID:      scope.turnID,
+		agentID:     agent.ID,
+		sessionKey:  opts.SessionKey,
+		channel:     opts.Channel,
+		chatID:      opts.ChatID,
+		userMessage: opts.UserMessage,
+		media:       append([]string(nil), opts.Media...),
+		phase:       TurnPhaseSetup,
+		startedAt:   time.Now(),
+	}
+
+	// Bind session store and capture initial history length for rollback logic
+	if agent != nil && agent.Sessions != nil {
+		ts.session = agent.Sessions
+		ts.initialHistoryLength = len(agent.Sessions.GetHistory(opts.SessionKey))
+	}
+
+	return ts
+}
+
+func (al *AgentLoop) registerActiveTurn(ts *turnState) {
+	al.activeTurnStates.Store(ts.sessionKey, ts)
+}
+
+func (al *AgentLoop) clearActiveTurn(ts *turnState) {
+	al.activeTurnStates.Delete(ts.sessionKey)
+}
+
+func (al *AgentLoop) getActiveTurnState(sessionKey string) *turnState {
+	if val, ok := al.activeTurnStates.Load(sessionKey); ok {
+		return val.(*turnState)
+	}
+	return nil
+}
+
+// getAnyActiveTurnState returns any active turn state (for backward compatibility)
+func (al *AgentLoop) getAnyActiveTurnState() *turnState {
+	var firstTS *turnState
+	al.activeTurnStates.Range(func(key, value any) bool {
+		firstTS = value.(*turnState)
+		return false // stop after first
+	})
+	return firstTS
+}
+
+func (al *AgentLoop) GetActiveTurn() *ActiveTurnInfo {
+	// For backward compatibility, return the first active turn found
+	// In the new architecture, there can be multiple concurrent turns
+	var firstTS *turnState
+	al.activeTurnStates.Range(func(key, value any) bool {
+		firstTS = value.(*turnState)
+		return false // stop after first
+	})
+	if firstTS == nil {
+		return nil
+	}
+	info := firstTS.snapshot()
+	return &info
+}
+
+func (al *AgentLoop) GetActiveTurnBySession(sessionKey string) *ActiveTurnInfo {
+	ts := al.getActiveTurnState(sessionKey)
+	if ts == nil {
+		return nil
+	}
+	info := ts.snapshot()
+	return &info
+}
+
+func (ts *turnState) snapshot() ActiveTurnInfo {
+	ts.mu.RLock()
+	defer ts.mu.RUnlock()
+
+	return ActiveTurnInfo{
+		TurnID:       ts.turnID,
+		AgentID:      ts.agentID,
+		SessionKey:   ts.sessionKey,
+		Channel:      ts.channel,
+		ChatID:       ts.chatID,
+		UserMessage:  ts.userMessage,
+		Phase:        ts.phase,
+		Iteration:    ts.iteration,
+		StartedAt:    ts.startedAt,
+		Depth:        ts.depth,
+		ParentTurnID: ts.parentTurnID,
+		ChildTurnIDs: append([]string(nil), ts.childTurnIDs...),
+	}
+}
+
+func (ts *turnState) setPhase(phase TurnPhase) {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	ts.phase = phase
+}
+
+func (ts *turnState) setIteration(iteration int) {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	ts.iteration = iteration
+}
+
+func (ts *turnState) currentIteration() int {
+	ts.mu.RLock()
+	defer ts.mu.RUnlock()
+	return ts.iteration
+}
+
+func (ts *turnState) setFinalContent(content string) {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	ts.finalContent = content
+}
+
+func (ts *turnState) finalContentLen() int {
+	ts.mu.RLock()
+	defer ts.mu.RUnlock()
+	return len(ts.finalContent)
+}
+
+func (ts *turnState) setTurnCancel(cancel context.CancelFunc) {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	ts.turnCancel = cancel
+}
+
+func (ts *turnState) setProviderCancel(cancel context.CancelFunc) {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	ts.providerCancel = cancel
+}
+
+func (ts *turnState) clearProviderCancel(_ context.CancelFunc) {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	ts.providerCancel = nil
+}
+
+func (ts *turnState) requestGracefulInterrupt(hint string) bool {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	if ts.hardAbort {
+		return false
+	}
+	ts.gracefulInterrupt = true
+	ts.gracefulInterruptHint = hint
+	return true
+}
+
+func (ts *turnState) gracefulInterruptRequested() (bool, string) {
+	ts.mu.RLock()
+	defer ts.mu.RUnlock()
+	return ts.gracefulInterrupt && !ts.gracefulTerminalUsed, ts.gracefulInterruptHint
+}
+
+func (ts *turnState) markGracefulTerminalUsed() {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	ts.gracefulTerminalUsed = true
+}
+
+func (ts *turnState) requestHardAbort() bool {
+	ts.mu.Lock()
+	if ts.hardAbort {
+		ts.mu.Unlock()
+		return false
+	}
+	ts.hardAbort = true
+	turnCancel := ts.turnCancel
+	providerCancel := ts.providerCancel
+	ts.mu.Unlock()
+
+	if providerCancel != nil {
+		providerCancel()
+	}
+	if turnCancel != nil {
+		turnCancel()
+	}
+	return true
+}
+
+func (ts *turnState) hardAbortRequested() bool {
+	ts.mu.RLock()
+	defer ts.mu.RUnlock()
+	return ts.hardAbort
+}
+
+func (ts *turnState) eventMeta(source, tracePath string) EventMeta {
+	snap := ts.snapshot()
+	return EventMeta{
+		AgentID:    snap.AgentID,
+		TurnID:     snap.TurnID,
+		SessionKey: snap.SessionKey,
+		Iteration:  snap.Iteration,
+		Source:     source,
+		TracePath:  tracePath,
+	}
+}
+
+func (ts *turnState) captureRestorePoint(history []providers.Message, summary string) {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	ts.restorePointHistory = append([]providers.Message(nil), history...)
+	ts.restorePointSummary = summary
+}
+
+func (ts *turnState) recordPersistedMessage(msg providers.Message) {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	ts.persistedMessages = append(ts.persistedMessages, msg)
+}
+
+func (ts *turnState) refreshRestorePointFromSession(agent *AgentInstance) {
+	history := agent.Sessions.GetHistory(ts.sessionKey)
+	summary := agent.Sessions.GetSummary(ts.sessionKey)
+
+	ts.mu.RLock()
+	persisted := append([]providers.Message(nil), ts.persistedMessages...)
+	ts.mu.RUnlock()
+
+	if matched := matchingTurnMessageTail(history, persisted); matched > 0 {
+		history = append([]providers.Message(nil), history[:len(history)-matched]...)
+	}
+
+	ts.captureRestorePoint(history, summary)
+}
+
+func (ts *turnState) restoreSession(agent *AgentInstance) error {
+	ts.mu.RLock()
+	history := append([]providers.Message(nil), ts.restorePointHistory...)
+	summary := ts.restorePointSummary
+	ts.mu.RUnlock()
+
+	agent.Sessions.SetHistory(ts.sessionKey, history)
+	agent.Sessions.SetSummary(ts.sessionKey, summary)
+	return agent.Sessions.Save(ts.sessionKey)
+}
+
+func matchingTurnMessageTail(history, persisted []providers.Message) int {
+	maxMatch := min(len(history), len(persisted))
+	for size := maxMatch; size > 0; size-- {
+		if reflect.DeepEqual(history[len(history)-size:], persisted[len(persisted)-size:]) {
+			return size
+		}
+	}
+	return 0
+}
+
+func (ts *turnState) interruptHintMessage() providers.Message {
+	_, hint := ts.gracefulInterruptRequested()
+	content := "Interrupt requested. Stop scheduling tools and provide a short final summary."
+	if hint != "" {
+		content += "\n\nInterrupt hint: " + hint
+	}
+	return providers.Message{
+		Role:    "user",
+		Content: content,
+	}
+}
+
+// SubTurn-related methods
+
+// Finish marks the turn as finished and closes the pendingResults channel
+func (ts *turnState) Finish(isHardAbort bool) {
+	ts.isFinished.Store(true)
+
+	// Close pendingResults channel exactly once
+	ts.closeOnce.Do(func() {
+		if ts.pendingResults != nil {
+			close(ts.pendingResults)
+		}
+		ts.mu.Lock()
+		if ts.finishedChan == nil {
+			ts.finishedChan = make(chan struct{})
+		}
+		close(ts.finishedChan)
+		ts.mu.Unlock()
+	})
+
+	// If this is a graceful finish (not hard abort), signal to children
+	if !isHardAbort && ts.parentTurnState == nil {
+		// This is a root turn finishing gracefully
+		ts.parentEnded.Store(true)
+	}
+
+	// Cancel the turn context
+	if ts.cancelFunc != nil {
+		ts.cancelFunc()
+	}
+
+	// Hard abort cascades to all child turns
+	if isHardAbort && ts.al != nil {
+		ts.mu.RLock()
+		children := append([]string(nil), ts.childTurnIDs...)
+		ts.mu.RUnlock()
+		for _, childID := range children {
+			if val, ok := ts.al.activeTurnStates.Load(childID); ok {
+				val.(*turnState).Finish(true)
+			}
+		}
+	}
+}
+
+// Finished returns whether the turn has finished
+func (ts *turnState) Finished() chan struct{} {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	if ts.finishedChan == nil {
+		ts.finishedChan = make(chan struct{})
+	}
+	return ts.finishedChan
+}
+
+// IsParentEnded checks if the parent turn has ended
+func (ts *turnState) IsParentEnded() bool {
+	if ts.parentTurnState == nil {
+		return false
+	}
+	return ts.parentTurnState.parentEnded.Load()
+}
+
+// GetLastFinishReason returns the last LLM finish_reason
+func (ts *turnState) GetLastFinishReason() string {
+	ts.mu.RLock()
+	defer ts.mu.RUnlock()
+	return ts.lastFinishReason
+}
+
+// SetLastFinishReason sets the last LLM finish_reason
+func (ts *turnState) SetLastFinishReason(reason string) {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	ts.lastFinishReason = reason
+}
+
+// GetLastUsage returns the last LLM usage info
+func (ts *turnState) GetLastUsage() *providers.UsageInfo {
+	ts.mu.RLock()
+	defer ts.mu.RUnlock()
+	return ts.lastUsage
+}
+
+// SetLastUsage sets the last LLM usage info
+func (ts *turnState) SetLastUsage(usage *providers.UsageInfo) {
+	ts.mu.Lock()
+	defer ts.mu.Unlock()
+	ts.lastUsage = usage
+}
+
+// Context helper functions for SubTurn
+
+type turnStateKeyType struct{}
+
+var turnStateKey = turnStateKeyType{}
+
+func withTurnState(ctx context.Context, ts *turnState) context.Context {
+	return context.WithValue(ctx, turnStateKey, ts)
+}
+
+func turnStateFromContext(ctx context.Context) *turnState {
+	ts, _ := ctx.Value(turnStateKey).(*turnState)
+	return ts
+}
+
+// TurnStateFromContext retrieves turnState from context (exported for tools)
+func TurnStateFromContext(ctx context.Context) *turnState {
+	return turnStateFromContext(ctx)
+}
diff --git a/pkg/auth/anthropic_usage.go b/pkg/auth/anthropic_usage.go
new file mode 100644
index 000000000..716b2908e
--- /dev/null
+++ b/pkg/auth/anthropic_usage.go
@@ -0,0 +1,71 @@
+package auth
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"time"
+)
+
+const (
+	anthropicBetaHeader = "oauth-2025-04-20"
+	anthropicAPIVersion = "2023-06-01"
+)
+
+// anthropicUsageURL is the endpoint for fetching OAuth usage stats.
+// It is a var (not const) to allow overriding in tests.
+var anthropicUsageURL = "https://api.anthropic.com/api/oauth/usage"
+
+func setAnthropicUsageURL(url string) { anthropicUsageURL = url }
+
+type AnthropicUsage struct {
+	FiveHourUtilization float64
+	SevenDayUtilization float64
+}
+
+func FetchAnthropicUsage(token string) (*AnthropicUsage, error) {
+	req, err := http.NewRequest("GET", anthropicUsageURL, nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+token)
+	req.Header.Set("Anthropic-Version", anthropicAPIVersion)
+	req.Header.Set("Anthropic-Beta", anthropicBetaHeader)
+
+	client := &http.Client{Timeout: 10 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("reading usage response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		if resp.StatusCode == http.StatusForbidden {
+			return nil, fmt.Errorf("insufficient scope: usage endpoint requires oauth scope")
+		}
+		return nil, fmt.Errorf("usage request failed (%d): %s", resp.StatusCode, string(body))
+	}
+
+	var result struct {
+		FiveHour struct {
+			Utilization float64 `json:"utilization"`
+		} `json:"five_hour"`
+		SevenDay struct {
+			Utilization float64 `json:"utilization"`
+		} `json:"seven_day"`
+	}
+	if err := json.Unmarshal(body, &result); err != nil {
+		return nil, fmt.Errorf("parsing usage response: %w", err)
+	}
+
+	return &AnthropicUsage{
+		FiveHourUtilization: result.FiveHour.Utilization,
+		SevenDayUtilization: result.SevenDay.Utilization,
+	}, nil
+}
diff --git a/pkg/auth/anthropic_usage_test.go b/pkg/auth/anthropic_usage_test.go
new file mode 100644
index 000000000..ef4a35364
--- /dev/null
+++ b/pkg/auth/anthropic_usage_test.go
@@ -0,0 +1,98 @@
+package auth
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestFetchAnthropicUsage_Success(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if got := r.Header.Get("Authorization"); got != "Bearer test-token" {
+			t.Errorf("Authorization = %q, want %q", got, "Bearer test-token")
+		}
+		if got := r.Header.Get("Anthropic-Beta"); got != anthropicBetaHeader {
+			t.Errorf("Anthropic-Beta = %q, want %q", got, anthropicBetaHeader)
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`{"five_hour":{"utilization":0.42},"seven_day":{"utilization":0.85}}`))
+	}))
+	defer srv.Close()
+
+	// Temporarily override the URL by using the test server
+	origURL := anthropicUsageURL
+	defer func() { setAnthropicUsageURL(origURL) }()
+	setAnthropicUsageURL(srv.URL)
+
+	usage, err := FetchAnthropicUsage("test-token")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if usage.FiveHourUtilization != 0.42 {
+		t.Errorf("FiveHourUtilization = %v, want 0.42", usage.FiveHourUtilization)
+	}
+	if usage.SevenDayUtilization != 0.85 {
+		t.Errorf("SevenDayUtilization = %v, want 0.85", usage.SevenDayUtilization)
+	}
+}
+
+func TestFetchAnthropicUsage_Forbidden(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusForbidden)
+		w.Write([]byte(`{"error":"forbidden"}`))
+	}))
+	defer srv.Close()
+
+	origURL := anthropicUsageURL
+	defer func() { setAnthropicUsageURL(origURL) }()
+	setAnthropicUsageURL(srv.URL)
+
+	_, err := FetchAnthropicUsage("test-token")
+	if err == nil {
+		t.Fatal("expected error for 403, got nil")
+	}
+	if !strings.Contains(err.Error(), "insufficient scope") {
+		t.Errorf("expected 'insufficient scope' error, got %q", err.Error())
+	}
+}
+
+func TestFetchAnthropicUsage_ServerError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+		w.Write([]byte(`internal error`))
+	}))
+	defer srv.Close()
+
+	origURL := anthropicUsageURL
+	defer func() { setAnthropicUsageURL(origURL) }()
+	setAnthropicUsageURL(srv.URL)
+
+	_, err := FetchAnthropicUsage("test-token")
+	if err == nil {
+		t.Fatal("expected error for 500, got nil")
+	}
+	if !strings.Contains(err.Error(), "500") {
+		t.Errorf("expected error containing '500', got %q", err.Error())
+	}
+}
+
+func TestFetchAnthropicUsage_MalformedJSON(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(`not json`))
+	}))
+	defer srv.Close()
+
+	origURL := anthropicUsageURL
+	defer func() { setAnthropicUsageURL(origURL) }()
+	setAnthropicUsageURL(srv.URL)
+
+	_, err := FetchAnthropicUsage("test-token")
+	if err == nil {
+		t.Fatal("expected error for malformed JSON, got nil")
+	}
+	if !strings.Contains(err.Error(), "parsing usage response") {
+		t.Errorf("expected 'parsing usage response' error, got %q", err.Error())
+	}
+}
diff --git a/pkg/auth/oauth.go b/pkg/auth/oauth.go
index 91c9e25c5..4667e3d81 100644
--- a/pkg/auth/oauth.go
+++ b/pkg/auth/oauth.go
@@ -212,7 +212,10 @@ func RequestDeviceCode(cfg OAuthProviderConfig) (*DeviceCodeInfo, error) {
 	}
 	defer resp.Body.Close()
 
-	body, _ := io.ReadAll(resp.Body)
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("reading device code response: %w", err)
+	}
 	if resp.StatusCode != http.StatusOK {
 		return nil, fmt.Errorf("device code request failed: %s", string(body))
 	}
@@ -300,7 +303,10 @@ func LoginDeviceCode(cfg OAuthProviderConfig) (*AuthCredential, error) {
 	}
 	defer resp.Body.Close()
 
-	body, _ := io.ReadAll(resp.Body)
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("reading device code response: %w", err)
+	}
 	if resp.StatusCode != http.StatusOK {
 		return nil, fmt.Errorf("device code request failed: %s", string(body))
 	}
@@ -360,7 +366,10 @@ func pollDeviceCode(cfg OAuthProviderConfig, deviceAuthID, userCode string) (*Au
 		return nil, fmt.Errorf("pending")
 	}
 
-	body, _ := io.ReadAll(resp.Body)
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("reading device token response: %w", err)
+	}
 
 	var tokenResp struct {
 		AuthorizationCode string `json:"authorization_code"`
@@ -401,7 +410,10 @@ func RefreshAccessToken(cred *AuthCredential, cfg OAuthProviderConfig) (*AuthCre
 	}
 	defer resp.Body.Close()
 
-	body, _ := io.ReadAll(resp.Body)
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("reading token refresh response: %w", err)
+	}
 	if resp.StatusCode != http.StatusOK {
 		return nil, fmt.Errorf("token refresh failed: %s", string(body))
 	}
@@ -494,7 +506,10 @@ func ExchangeCodeForTokens(cfg OAuthProviderConfig, code, codeVerifier, redirect
 	}
 	defer resp.Body.Close()
 
-	body, _ := io.ReadAll(resp.Body)
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("reading token exchange response: %w", err)
+	}
 	if resp.StatusCode != http.StatusOK {
 		return nil, fmt.Errorf("token exchange failed: %s", string(body))
 	}
diff --git a/pkg/auth/store.go b/pkg/auth/store.go
index 283dc6977..8a878d553 100644
--- a/pkg/auth/store.go
+++ b/pkg/auth/store.go
@@ -6,6 +6,8 @@ import (
 	"path/filepath"
 	"time"
 
+	"github.com/sipeed/picoclaw/pkg"
+	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/fileutil"
 )
 
@@ -39,8 +41,11 @@ func (c *AuthCredential) NeedsRefresh() bool {
 }
 
 func authFilePath() string {
+	if home := os.Getenv(config.EnvHome); home != "" {
+		return filepath.Join(home, "auth.json")
+	}
 	home, _ := os.UserHomeDir()
-	return filepath.Join(home, ".picoclaw", "auth.json")
+	return filepath.Join(home, pkg.DefaultPicoClawHome, "auth.json")
 }
 
 func LoadStore() (*AuthStore, error) {
diff --git a/pkg/auth/token.go b/pkg/auth/token.go
index a5a13ff03..0e69e60ac 100644
--- a/pkg/auth/token.go
+++ b/pkg/auth/token.go
@@ -31,6 +31,35 @@ func LoginPasteToken(provider string, r io.Reader) (*AuthCredential, error) {
 	}, nil
 }
 
+func LoginSetupToken(r io.Reader) (*AuthCredential, error) {
+	fmt.Println("Paste your setup token from `claude setup-token`:")
+	fmt.Print("> ")
+
+	scanner := bufio.NewScanner(r)
+	if !scanner.Scan() {
+		if err := scanner.Err(); err != nil {
+			return nil, fmt.Errorf("reading token: %w", err)
+		}
+		return nil, fmt.Errorf("no input received")
+	}
+
+	token := strings.TrimSpace(scanner.Text())
+
+	if !strings.HasPrefix(token, "sk-ant-oat01-") {
+		return nil, fmt.Errorf("invalid setup token: expected prefix sk-ant-oat01-")
+	}
+
+	if len(token) < 80 {
+		return nil, fmt.Errorf("invalid setup token: too short (expected at least 80 characters)")
+	}
+
+	return &AuthCredential{
+		AccessToken: token,
+		Provider:    "anthropic",
+		AuthMethod:  "oauth",
+	}, nil
+}
+
 func providerDisplayName(provider string) string {
 	switch provider {
 	case "anthropic":
diff --git a/pkg/auth/token_test.go b/pkg/auth/token_test.go
new file mode 100644
index 000000000..673cd9d5d
--- /dev/null
+++ b/pkg/auth/token_test.go
@@ -0,0 +1,61 @@
+package auth
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestLoginSetupToken(t *testing.T) {
+	// A valid token: correct prefix + at least 80 chars
+	validToken := "sk-ant-oat01-" + strings.Repeat("a", 80)
+
+	tests := []struct {
+		name    string
+		input   string
+		wantErr string
+	}{
+		{"valid token", validToken, ""},
+		{"empty input", "", "expected prefix sk-ant-oat01-"},
+		{"wrong prefix", "sk-ant-api-" + strings.Repeat("a", 80), "expected prefix sk-ant-oat01-"},
+		{"too short", "sk-ant-oat01-short", "too short"},
+		{"whitespace only", "   ", "expected prefix sk-ant-oat01-"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			r := strings.NewReader(tt.input + "\n")
+			cred, err := LoginSetupToken(r)
+
+			if tt.wantErr != "" {
+				if err == nil {
+					t.Fatalf("expected error containing %q, got nil", tt.wantErr)
+				}
+				if !strings.Contains(err.Error(), tt.wantErr) {
+					t.Fatalf("expected error containing %q, got %q", tt.wantErr, err.Error())
+				}
+				return
+			}
+
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if cred.AccessToken != validToken {
+				t.Errorf("AccessToken = %q, want %q", cred.AccessToken, validToken)
+			}
+			if cred.Provider != "anthropic" {
+				t.Errorf("Provider = %q, want %q", cred.Provider, "anthropic")
+			}
+			if cred.AuthMethod != "oauth" {
+				t.Errorf("AuthMethod = %q, want %q", cred.AuthMethod, "oauth")
+			}
+		})
+	}
+}
+
+func TestLoginSetupToken_EmptyReader(t *testing.T) {
+	r := strings.NewReader("")
+	_, err := LoginSetupToken(r)
+	if err == nil {
+		t.Fatal("expected error for empty reader, got nil")
+	}
+}
diff --git a/pkg/bus/bus.go b/pkg/bus/bus.go
index f5ff9587d..37fcb74c5 100644
--- a/pkg/bus/bus.go
+++ b/pkg/bus/bus.go
@@ -3,6 +3,7 @@ package bus
 import (
 	"context"
 	"errors"
+	"sync"
 	"sync/atomic"
 
 	"github.com/sipeed/picoclaw/pkg/logger"
@@ -13,12 +14,32 @@ var ErrBusClosed = errors.New("message bus closed")
 
 const defaultBusBufferSize = 64
 
+// StreamDelegate is implemented by the channel Manager to provide streaming
+// capabilities to the agent loop without tight coupling.
+type StreamDelegate interface {
+	// GetStreamer returns a Streamer for the given channel+chatID if the channel
+	// supports streaming. Returns nil, false if streaming is unavailable.
+	GetStreamer(ctx context.Context, channel, chatID string) (Streamer, bool)
+}
+
+// Streamer pushes incremental content to a streaming-capable channel.
+// Defined here so the agent loop can use it without importing pkg/channels.
+type Streamer interface {
+	Update(ctx context.Context, content string) error
+	Finalize(ctx context.Context, content string) error
+	Cancel(ctx context.Context)
+}
+
 type MessageBus struct {
 	inbound       chan InboundMessage
 	outbound      chan OutboundMessage
 	outboundMedia chan OutboundMediaMessage
-	done          chan struct{}
-	closed        atomic.Bool
+
+	closeOnce      sync.Once
+	done           chan struct{}
+	closed         atomic.Bool
+	wg             sync.WaitGroup
+	streamDelegate atomic.Value // stores StreamDelegate
 }
 
 func NewMessageBus() *MessageBus {
@@ -30,128 +51,104 @@ func NewMessageBus() *MessageBus {
 	}
 }
 
-func (mb *MessageBus) PublishInbound(ctx context.Context, msg InboundMessage) error {
+func publish[T any](ctx context.Context, mb *MessageBus, ch chan T, msg T) error {
+	// check bus closed before acquiring wg, to avoid unnecessary wg.Add and potential deadlock
 	if mb.closed.Load() {
 		return ErrBusClosed
 	}
-	if err := ctx.Err(); err != nil {
-		return err
-	}
+
+	// check again,before sending message, to avoid sending to closed channel
 	select {
-	case mb.inbound <- msg:
-		return nil
-	case <-mb.done:
-		return ErrBusClosed
 	case <-ctx.Done():
 		return ctx.Err()
+	case <-mb.done:
+		return ErrBusClosed
+	default:
+	}
+
+	mb.wg.Add(1)
+	defer mb.wg.Done()
+
+	select {
+	case ch <- msg:
+		return nil
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-mb.done:
+		return ErrBusClosed
 	}
 }
 
-func (mb *MessageBus) ConsumeInbound(ctx context.Context) (InboundMessage, bool) {
-	select {
-	case msg, ok := <-mb.inbound:
-		return msg, ok
-	case <-mb.done:
-		return InboundMessage{}, false
-	case <-ctx.Done():
-		return InboundMessage{}, false
-	}
+func (mb *MessageBus) PublishInbound(ctx context.Context, msg InboundMessage) error {
+	return publish(ctx, mb, mb.inbound, msg)
+}
+
+func (mb *MessageBus) InboundChan() <-chan InboundMessage {
+	return mb.inbound
 }
 
 func (mb *MessageBus) PublishOutbound(ctx context.Context, msg OutboundMessage) error {
-	if mb.closed.Load() {
-		return ErrBusClosed
-	}
-	if err := ctx.Err(); err != nil {
-		return err
-	}
-	select {
-	case mb.outbound <- msg:
-		return nil
-	case <-mb.done:
-		return ErrBusClosed
-	case <-ctx.Done():
-		return ctx.Err()
-	}
+	return publish(ctx, mb, mb.outbound, msg)
 }
 
-func (mb *MessageBus) SubscribeOutbound(ctx context.Context) (OutboundMessage, bool) {
-	select {
-	case msg, ok := <-mb.outbound:
-		return msg, ok
-	case <-mb.done:
-		return OutboundMessage{}, false
-	case <-ctx.Done():
-		return OutboundMessage{}, false
-	}
+func (mb *MessageBus) OutboundChan() <-chan OutboundMessage {
+	return mb.outbound
 }
 
 func (mb *MessageBus) PublishOutboundMedia(ctx context.Context, msg OutboundMediaMessage) error {
-	if mb.closed.Load() {
-		return ErrBusClosed
-	}
-	if err := ctx.Err(); err != nil {
-		return err
-	}
-	select {
-	case mb.outboundMedia <- msg:
-		return nil
-	case <-mb.done:
-		return ErrBusClosed
-	case <-ctx.Done():
-		return ctx.Err()
-	}
+	return publish(ctx, mb, mb.outboundMedia, msg)
 }
 
-func (mb *MessageBus) SubscribeOutboundMedia(ctx context.Context) (OutboundMediaMessage, bool) {
-	select {
-	case msg, ok := <-mb.outboundMedia:
-		return msg, ok
-	case <-mb.done:
-		return OutboundMediaMessage{}, false
-	case <-ctx.Done():
-		return OutboundMediaMessage{}, false
+func (mb *MessageBus) OutboundMediaChan() <-chan OutboundMediaMessage {
+	return mb.outboundMedia
+}
+
+// SetStreamDelegate registers a StreamDelegate (typically the channel Manager).
+func (mb *MessageBus) SetStreamDelegate(d StreamDelegate) {
+	mb.streamDelegate.Store(d)
+}
+
+// GetStreamer returns a Streamer for the given channel+chatID via the delegate.
+func (mb *MessageBus) GetStreamer(ctx context.Context, channel, chatID string) (Streamer, bool) {
+	if d, ok := mb.streamDelegate.Load().(StreamDelegate); ok && d != nil {
+		return d.GetStreamer(ctx, channel, chatID)
 	}
+	return nil, false
 }
 
 func (mb *MessageBus) Close() {
-	if mb.closed.CompareAndSwap(false, true) {
+	mb.closeOnce.Do(func() {
+		// notify all blocked publishers to exit
 		close(mb.done)
 
-		// Drain buffered channels so messages aren't silently lost.
-		// Channels are NOT closed to avoid send-on-closed panics from concurrent publishers.
+		// because every publisher will check mb.closed before acquiring wg
+		// so we can be sure that new publishers will not be added new messages after this point
+		mb.closed.Store(true)
+
+		// wait for all ongoing Publish calls to finish, ensuring all messages have been sent to channels or exited
+		mb.wg.Wait()
+
+		// close channels safely
+		close(mb.inbound)
+		close(mb.outbound)
+		close(mb.outboundMedia)
+
+		// clean up any remaining messages in channels
 		drained := 0
-		for {
-			select {
-			case <-mb.inbound:
-				drained++
-			default:
-				goto doneInbound
-			}
+		for range mb.inbound {
+			drained++
 		}
-	doneInbound:
-		for {
-			select {
-			case <-mb.outbound:
-				drained++
-			default:
-				goto doneOutbound
-			}
+		for range mb.outbound {
+			drained++
 		}
-	doneOutbound:
-		for {
-			select {
-			case <-mb.outboundMedia:
-				drained++
-			default:
-				goto doneMedia
-			}
+		for range mb.outboundMedia {
+			drained++
 		}
-	doneMedia:
+
 		if drained > 0 {
 			logger.DebugCF("bus", "Drained buffered messages during close", map[string]any{
 				"count": drained,
 			})
 		}
-	}
+	})
 }
diff --git a/pkg/bus/bus_test.go b/pkg/bus/bus_test.go
index e07b8c7fe..9b6324ca6 100644
--- a/pkg/bus/bus_test.go
+++ b/pkg/bus/bus_test.go
@@ -24,7 +24,7 @@ func TestPublishConsume(t *testing.T) {
 		t.Fatalf("PublishInbound failed: %v", err)
 	}
 
-	got, ok := mb.ConsumeInbound(ctx)
+	got, ok := <-mb.InboundChan()
 	if !ok {
 		t.Fatal("ConsumeInbound returned ok=false")
 	}
@@ -52,7 +52,7 @@ func TestPublishOutboundSubscribe(t *testing.T) {
 		t.Fatalf("PublishOutbound failed: %v", err)
 	}
 
-	got, ok := mb.SubscribeOutbound(ctx)
+	got, ok := <-mb.OutboundChan()
 	if !ok {
 		t.Fatal("SubscribeOutbound returned ok=false")
 	}
@@ -108,27 +108,48 @@ func TestPublishOutbound_BusClosed(t *testing.T) {
 
 func TestConsumeInbound_ContextCancel(t *testing.T) {
 	mb := NewMessageBus()
+
 	defer mb.Close()
 
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
+	for i := range defaultBusBufferSize {
+		if err := mb.PublishInbound(context.Background(), InboundMessage{Content: "fill"}); err != nil {
+			t.Fatalf("fill failed at %d: %v", i, err)
+		}
+	}
 
-	_, ok := mb.ConsumeInbound(ctx)
-	if ok {
-		t.Fatal("expected ok=false when context is canceled")
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+	mb.PublishInbound(ctx, InboundMessage{Content: "ContextCancel"})
+
+	select {
+	case <-ctx.Done():
+		t.Log("context canceled, as expected")
+
+	case msg, ok := <-mb.InboundChan():
+		if !ok {
+			t.Fatal("expected ok=false when context is canceled")
+		}
+		if msg.Content == "ContextCancel" {
+			t.Fatalf("expected content 'ContextCancel', got %q", msg.Content)
+		}
 	}
 }
 
 func TestConsumeInbound_BusClosed(t *testing.T) {
 	mb := NewMessageBus()
-	mb.Close()
 
-	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
-	defer cancel()
+	timer := time.AfterFunc(100*time.Millisecond, func() {
+		mb.Close()
+	})
 
-	_, ok := mb.ConsumeInbound(ctx)
-	if ok {
-		t.Fatal("expected ok=false when bus is closed")
+	select {
+	case <-timer.C:
+		t.Log("context canceled, as expected")
+
+	case _, ok := <-mb.InboundChan():
+		if ok {
+			t.Fatal("expected ok=false when context is canceled")
+		}
 	}
 }
 
@@ -136,10 +157,7 @@ func TestSubscribeOutbound_BusClosed(t *testing.T) {
 	mb := NewMessageBus()
 	mb.Close()
 
-	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
-	defer cancel()
-
-	_, ok := mb.SubscribeOutbound(ctx)
+	_, ok := <-mb.OutboundChan()
 	if ok {
 		t.Fatal("expected ok=false when bus is closed")
 	}
diff --git a/pkg/bus/types.go b/pkg/bus/types.go
index 7ad8f0417..12da3f1dd 100644
--- a/pkg/bus/types.go
+++ b/pkg/bus/types.go
@@ -30,9 +30,10 @@ type InboundMessage struct {
 }
 
 type OutboundMessage struct {
-	Channel string `json:"channel"`
-	ChatID  string `json:"chat_id"`
-	Content string `json:"content"`
+	Channel          string `json:"channel"`
+	ChatID           string `json:"chat_id"`
+	Content          string `json:"content"`
+	ReplyToMessageID string `json:"reply_to_message_id,omitempty"`
 }
 
 // MediaPart describes a single media attachment to send.
diff --git a/pkg/channels/README.md b/pkg/channels/README.md
index b7c56660b..7f238ece5 100644
--- a/pkg/channels/README.md
+++ b/pkg/channels/README.md
@@ -1255,8 +1255,7 @@ make test                                       # Full test suite
 | `pkg/channels/onebot/` | `"onebot"` | ReactionCapable, MediaSender |
 | `pkg/channels/dingtalk/` | `"dingtalk"` | — |
 | `pkg/channels/feishu/` | `"feishu"` | — (architecture-specific build tags: `feishu_32.go` / `feishu_64.go`) |
-| `pkg/channels/wecom/` | `"wecom"` | WebhookHandler, HealthChecker |
-| `pkg/channels/wecom/` | `"wecom_app"` | MediaSender, WebhookHandler, HealthChecker |
+| `pkg/channels/wecom/` | `"wecom"` | MediaSender |
 | `pkg/channels/qq/` | `"qq"` | — |
 | `pkg/channels/whatsapp/` | `"whatsapp"` | — (Bridge mode) |
 | `pkg/channels/whatsapp_native/` | `"whatsapp_native"` | — (Native whatsmeow mode) |
@@ -1371,7 +1370,7 @@ agentLoop.Stop()               // Stop Agent
 
 2. **Feishu architecture-specific compilation**: The Feishu channel uses build tags to distinguish 32-bit and 64-bit architectures (`feishu_32.go` / `feishu_64.go`). Feishu uses the SDK's WebSocket mode (not HTTP webhook), so it does not implement `WebhookHandler`.
 
-3. **WeCom has two factories**: `"wecom"` (Bot mode, webhook only) and `"wecom_app"` (App mode, supports MediaSender) are registered separately. Both implement `WebhookHandler` and `HealthChecker`.
+3. **WeCom is now a single channel**: `"wecom"` is implemented as a WebSocket-based AI Bot channel with route persistence. Access control uses the shared channel allowlist mechanism. It no longer exposes the legacy webhook/app split.
 
 4. **Pico Protocol**: `pkg/channels/pico/` implements a custom PicoClaw native protocol channel that receives messages via WebSocket webhook (`/pico/ws`).
 
@@ -1381,4 +1380,4 @@ agentLoop.Stop()               // Stop Agent
 
 7. **PlaceholderConfig vs implementation**: `PlaceholderConfig` appears in 6 channel configs (Telegram, Discord, Slack, LINE, OneBot, Pico), but only channels that implement both `PlaceholderCapable` + `MessageEditor` (Telegram, Discord, Pico) can actually use placeholder message editing. The rest are reserved fields.
 
-8. **ReasoningChannelID**: Most channel configs include a `reasoning_channel_id` field to route LLM reasoning/thinking output to a designated channel (WhatsApp, Telegram, Feishu, Discord, MaixCam, QQ, DingTalk, Slack, LINE, OneBot, WeCom, WeComApp). Note: `PicoConfig` does not currently expose this field. `BaseChannel` exposes this via the `WithReasoningChannelID` option and `ReasoningChannelID()` method.
\ No newline at end of file
+8. **ReasoningChannelID**: Most channel configs include a `reasoning_channel_id` field to route LLM reasoning/thinking output to a designated channel (WhatsApp, Telegram, Feishu, Discord, MaixCam, QQ, DingTalk, Slack, LINE, OneBot, WeCom). Note: `PicoConfig` does not currently expose this field. `BaseChannel` exposes this via the `WithReasoningChannelID` option and `ReasoningChannelID()` method.
diff --git a/pkg/channels/README.zh.md b/pkg/channels/README.zh.md
index 2c5e7356e..8bc8c8dbc 100644
--- a/pkg/channels/README.zh.md
+++ b/pkg/channels/README.zh.md
@@ -1254,8 +1254,7 @@ make test                                       # 全量测试
 | `pkg/channels/onebot/` | `"onebot"` | ReactionCapable, MediaSender |
 | `pkg/channels/dingtalk/` | `"dingtalk"` | — |
 | `pkg/channels/feishu/` | `"feishu"` | — (架构特定 build tags: `feishu_32.go` / `feishu_64.go`) |
-| `pkg/channels/wecom/` | `"wecom"` | WebhookHandler, HealthChecker |
-| `pkg/channels/wecom/` | `"wecom_app"` | MediaSender, WebhookHandler, HealthChecker |
+| `pkg/channels/wecom/` | `"wecom"` | MediaSender |
 | `pkg/channels/qq/` | `"qq"` | — |
 | `pkg/channels/whatsapp/` | `"whatsapp"` | — (Bridge 模式) |
 | `pkg/channels/whatsapp_native/` | `"whatsapp_native"` | — (原生 whatsmeow 模式) |
@@ -1370,7 +1369,7 @@ agentLoop.Stop()               // 停止 Agent
 
 2. **Feishu 架构特定编译**：Feishu channel 使用 build tags 区分 32 位和 64 位架构（`feishu_32.go` / `feishu_64.go`）。Feishu 使用 SDK 的 WebSocket 模式（非 HTTP webhook），因此不实现 `WebhookHandler`。
 
-3. **WeCom 有两个工厂**：`"wecom"`（Bot 模式，纯 webhook）和 `"wecom_app"`（应用模式，支持 MediaSender）分别注册。两者都实现了 `WebhookHandler` 和 `HealthChecker`。
+3. **WeCom 现在只有一个 channel**：`"wecom"` 采用 WebSocket AI Bot 实现，带路由持久化；访问控制走统一的 channel 白名单机制，不再保留旧的 webhook/app 双分支。
 
 4. **Pico Protocol**：`pkg/channels/pico/` 实现了一个自定义的 PicoClaw 原生协议 channel，通过 WebSocket webhook (`/pico/ws`) 接收消息。
 
@@ -1380,4 +1379,4 @@ agentLoop.Stop()               // 停止 Agent
 
 7. **PlaceholderConfig 的配置与实现**：`PlaceholderConfig` 出现在 6 个 channel config 中（Telegram、Discord、Slack、LINE、OneBot、Pico），但只有实现了 `PlaceholderCapable` + `MessageEditor` 的 channel（Telegram、Discord、Pico）能真正使用占位消息编辑功能。其余 channel 的 `PlaceholderConfig` 为预留字段。
 
-8. **ReasoningChannelID**：大多数 channel config 都包含 `reasoning_channel_id` 字段，用于将 LLM 的思维链（reasoning/thinking）路由到指定 channel（WhatsApp、Telegram、Feishu、Discord、MaixCam、QQ、DingTalk、Slack、LINE、OneBot、WeCom、WeComApp）。注意：`PicoConfig` 目前不包含该字段。`BaseChannel` 通过 `WithReasoningChannelID` 选项和 `ReasoningChannelID()` 方法暴露此配置。
\ No newline at end of file
+8. **ReasoningChannelID**：大多数 channel config 都包含 `reasoning_channel_id` 字段，用于将 LLM 的思维链（reasoning/thinking）路由到指定 channel（WhatsApp、Telegram、Feishu、Discord、MaixCam、QQ、DingTalk、Slack、LINE、OneBot、WeCom）。注意：`PicoConfig` 目前不包含该字段。`BaseChannel` 通过 `WithReasoningChannelID` 选项和 `ReasoningChannelID()` 方法暴露此配置。
diff --git a/pkg/channels/base.go b/pkg/channels/base.go
index 063a66523..882e72d08 100644
--- a/pkg/channels/base.go
+++ b/pkg/channels/base.go
@@ -5,6 +5,7 @@ import (
 	"crypto/rand"
 	"encoding/binary"
 	"encoding/hex"
+	"regexp"
 	"strconv"
 	"strings"
 	"sync/atomic"
@@ -32,6 +33,9 @@ func init() {
 	uniqueIDPrefix = hex.EncodeToString(b[:])
 }
 
+// audioAnnotationRe matches audio/voice annotations injected by channels (e.g. [voice], [audio: file.ogg]).
+var audioAnnotationRe = regexp.MustCompile(`\[(voice|audio)(?::[^\]]*)?\]`)
+
 // uniqueID generates a process-unique ID using a random prefix and an atomic counter.
 // This ID is intended for internal correlation (e.g. media scope keys) and is NOT
 // cryptographically secure — it must not be used in contexts where unpredictability matters.
@@ -271,23 +275,32 @@ func (c *BaseChannel) HandleMessage(
 
 	// Auto-trigger typing indicator, message reaction, and placeholder before publishing.
 	// Each capability is independent — all three may fire for the same message.
+	// Note: even when streaming is available, we still show typing + placeholder on inbound.
+	// If streaming actually activates, preSend will skip the placeholder edit (streamActive map)
+	// and the typing stop will still be called. This avoids the problem of compile-time interface
+	// checks incorrectly skipping indicators when streaming may not work at runtime.
 	if c.owner != nil && c.placeholderRecorder != nil {
-		// Typing — independent pipeline
+		// Typing
 		if tc, ok := c.owner.(TypingCapable); ok {
 			if stop, err := tc.StartTyping(ctx, chatID); err == nil {
 				c.placeholderRecorder.RecordTypingStop(c.name, chatID, stop)
 			}
 		}
-		// Reaction — independent pipeline
+		// Reaction
 		if rc, ok := c.owner.(ReactionCapable); ok && messageID != "" {
 			if undo, err := rc.ReactToMessage(ctx, chatID, messageID); err == nil {
 				c.placeholderRecorder.RecordReactionUndo(c.name, chatID, undo)
 			}
 		}
-		// Placeholder — independent pipeline
-		if pc, ok := c.owner.(PlaceholderCapable); ok {
-			if phID, err := pc.SendPlaceholder(ctx, chatID); err == nil && phID != "" {
-				c.placeholderRecorder.RecordPlaceholder(c.name, chatID, phID)
+		// Placeholder — independent pipeline.
+		// Skip when the message contains audio: the agent will send the
+		// placeholder after transcription completes, so the user sees
+		// "Thinking…" only once the voice has been processed.
+		if !audioAnnotationRe.MatchString(content) {
+			if pc, ok := c.owner.(PlaceholderCapable); ok {
+				if phID, err := pc.SendPlaceholder(ctx, chatID); err == nil && phID != "" {
+					c.placeholderRecorder.RecordPlaceholder(c.name, chatID, phID)
+				}
 			}
 		}
 	}
diff --git a/pkg/channels/dingtalk/dingtalk.go b/pkg/channels/dingtalk/dingtalk.go
index 8642ad362..7ac2c073f 100644
--- a/pkg/channels/dingtalk/dingtalk.go
+++ b/pkg/channels/dingtalk/dingtalk.go
@@ -10,6 +10,7 @@ import (
 
 	"github.com/open-dingtalk/dingtalk-stream-sdk-go/chatbot"
 	"github.com/open-dingtalk/dingtalk-stream-sdk-go/client"
+	dinglog "github.com/open-dingtalk/dingtalk-stream-sdk-go/logger"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/channels"
@@ -35,10 +36,13 @@ type DingTalkChannel struct {
 
 // NewDingTalkChannel creates a new DingTalk channel instance
 func NewDingTalkChannel(cfg config.DingTalkConfig, messageBus *bus.MessageBus) (*DingTalkChannel, error) {
-	if cfg.ClientID == "" || cfg.ClientSecret == "" {
+	if cfg.ClientID == "" || cfg.ClientSecret() == "" {
 		return nil, fmt.Errorf("dingtalk client_id and client_secret are required")
 	}
 
+	// Set the logger for the Stream SDK
+	dinglog.SetLogger(logger.NewLogger("dingtalk"))
+
 	base := channels.NewBaseChannel("dingtalk", cfg, messageBus, cfg.AllowFrom,
 		channels.WithMaxMessageLength(20000),
 		channels.WithGroupTrigger(cfg.GroupTrigger),
@@ -49,7 +53,7 @@ func NewDingTalkChannel(cfg config.DingTalkConfig, messageBus *bus.MessageBus) (
 		BaseChannel:  base,
 		config:       cfg,
 		clientID:     cfg.ClientID,
-		clientSecret: cfg.ClientSecret,
+		clientSecret: cfg.ClientSecret(),
 	}, nil
 }
 
diff --git a/pkg/channels/discord/discord.go b/pkg/channels/discord/discord.go
index cd6a2560f..3b5b4f8bb 100644
--- a/pkg/channels/discord/discord.go
+++ b/pkg/channels/discord/discord.go
@@ -3,12 +3,16 @@ package discord
 import (
 	"context"
 	"fmt"
+	"net/http"
+	"net/url"
 	"os"
+	"regexp"
 	"strings"
 	"sync"
 	"time"
 
 	"github.com/bwmarrin/discordgo"
+	"github.com/gorilla/websocket"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/channels"
@@ -23,6 +27,12 @@ const (
 	sendTimeout = 10 * time.Second
 )
 
+var (
+	// Pre-compiled regexes for resolveDiscordRefs (avoid re-compiling per call)
+	channelRefRe = regexp.MustCompile(`<#(\d+)>`)
+	msgLinkRe    = regexp.MustCompile(`https://(?:discord\.com|discordapp\.com)/channels/(\d+)/(\d+)/(\d+)`)
+)
+
 type DiscordChannel struct {
 	*channels.BaseChannel
 	session    *discordgo.Session
@@ -35,11 +45,22 @@ type DiscordChannel struct {
 }
 
 func NewDiscordChannel(cfg config.DiscordConfig, bus *bus.MessageBus) (*DiscordChannel, error) {
-	session, err := discordgo.New("Bot " + cfg.Token)
+	discordgo.Logger = logger.NewLogger("discord").
+		WithLevels(map[int]logger.LogLevel{
+			discordgo.LogError:         logger.ERROR,
+			discordgo.LogWarning:       logger.WARN,
+			discordgo.LogInformational: logger.INFO,
+			discordgo.LogDebug:         logger.DEBUG,
+		}).Log
+
+	session, err := discordgo.New("Bot " + cfg.Token())
 	if err != nil {
 		return nil, fmt.Errorf("failed to create discord session: %w", err)
 	}
 
+	if err := applyDiscordProxy(session, cfg.Proxy); err != nil {
+		return nil, err
+	}
 	base := channels.NewBaseChannel("discord", cfg, bus, cfg.AllowFrom,
 		channels.WithMaxMessageLength(2000),
 		channels.WithGroupTrigger(cfg.GroupTrigger),
@@ -121,7 +142,7 @@ func (c *DiscordChannel) Send(ctx context.Context, msg bus.OutboundMessage) erro
 		return nil
 	}
 
-	return c.sendChunk(ctx, channelID, msg.Content)
+	return c.sendChunk(ctx, channelID, msg.Content, msg.ReplyToMessageID)
 }
 
 // SendMedia implements the channels.MediaSender interface.
@@ -246,14 +267,29 @@ func (c *DiscordChannel) SendPlaceholder(ctx context.Context, chatID string) (st
 	return msg.ID, nil
 }
 
-func (c *DiscordChannel) sendChunk(ctx context.Context, channelID, content string) error {
+func (c *DiscordChannel) sendChunk(ctx context.Context, channelID, content, replyToID string) error {
 	// Use the passed ctx for timeout control
 	sendCtx, cancel := context.WithTimeout(ctx, sendTimeout)
 	defer cancel()
 
 	done := make(chan error, 1)
 	go func() {
-		_, err := c.session.ChannelMessageSend(channelID, content)
+		var err error
+
+		// If we have an ID, we send the message as "Reply"
+		if replyToID != "" {
+			_, err = c.session.ChannelMessageSendComplex(channelID, &discordgo.MessageSend{
+				Content: content,
+				Reference: &discordgo.MessageReference{
+					MessageID: replyToID,
+					ChannelID: channelID,
+				},
+			})
+		} else {
+			// Otherwise, we send a normal message
+			_, err = c.session.ChannelMessageSend(channelID, content)
+		}
+
 		done <- err
 	}()
 
@@ -332,6 +368,24 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 		content = c.stripBotMention(content)
 	}
 
+	// Resolve Discord refs in main content before concatenation to avoid
+	// double-expanding links that appear in the referenced message.
+	content = c.resolveDiscordRefs(s, content, m.GuildID)
+
+	// Prepend referenced (quoted) message content if this is a reply
+	if m.MessageReference != nil && m.ReferencedMessage != nil {
+		refContent := m.ReferencedMessage.Content
+		if refContent != "" {
+			refAuthor := "unknown"
+			if m.ReferencedMessage.Author != nil {
+				refAuthor = m.ReferencedMessage.Author.Username
+			}
+			refContent = c.resolveDiscordRefs(s, refContent, m.GuildID)
+			content = fmt.Sprintf("[quoted message from %s]: %s\n\n%s",
+				refAuthor, refContent, content)
+		}
+	}
+
 	senderID := m.Author.ID
 
 	mediaPaths := make([]string, 0, len(m.Attachments))
@@ -342,8 +396,9 @@ func (c *DiscordChannel) handleMessage(s *discordgo.Session, m *discordgo.Messag
 	storeMedia := func(localPath, filename string) string {
 		if store := c.GetMediaStore(); store != nil {
 			ref, err := store.Store(localPath, media.MediaMeta{
-				Filename: filename,
-				Source:   "discord",
+				Filename:      filename,
+				Source:        "discord",
+				CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
 			}, scope)
 			if err == nil {
 				return ref
@@ -465,9 +520,88 @@ func (c *DiscordChannel) StartTyping(ctx context.Context, chatID string) (func()
 func (c *DiscordChannel) downloadAttachment(url, filename string) string {
 	return utils.DownloadFile(url, filename, utils.DownloadOptions{
 		LoggerPrefix: "discord",
+		ProxyURL:     c.config.Proxy,
 	})
 }
 
+func applyDiscordProxy(session *discordgo.Session, proxyAddr string) error {
+	var proxyFunc func(*http.Request) (*url.URL, error)
+	if proxyAddr != "" {
+		proxyURL, err := url.Parse(proxyAddr)
+		if err != nil {
+			return fmt.Errorf("invalid discord proxy URL %q: %w", proxyAddr, err)
+		}
+		proxyFunc = http.ProxyURL(proxyURL)
+	} else if os.Getenv("HTTP_PROXY") != "" || os.Getenv("HTTPS_PROXY") != "" {
+		proxyFunc = http.ProxyFromEnvironment
+	}
+
+	if proxyFunc == nil {
+		return nil
+	}
+
+	transport := &http.Transport{Proxy: proxyFunc}
+	session.Client = &http.Client{
+		Timeout:   sendTimeout,
+		Transport: transport,
+	}
+
+	if session.Dialer != nil {
+		dialerCopy := *session.Dialer
+		dialerCopy.Proxy = proxyFunc
+		session.Dialer = &dialerCopy
+	} else {
+		session.Dialer = &websocket.Dialer{Proxy: proxyFunc}
+	}
+
+	return nil
+}
+
+// resolveDiscordRefs resolves channel references (<#id> → #channel-name) and
+// expands Discord message links to show the linked message content.
+// Only links pointing to the same guild are expanded to prevent cross-guild leakage.
+func (c *DiscordChannel) resolveDiscordRefs(s *discordgo.Session, text string, guildID string) string {
+	// 1. Resolve channel references: <#id> → #channel-name
+	text = channelRefRe.ReplaceAllStringFunc(text, func(match string) string {
+		parts := channelRefRe.FindStringSubmatch(match)
+		if len(parts) < 2 {
+			return match
+		}
+		// Prefer session state cache to avoid API calls
+		if ch, err := s.State.Channel(parts[1]); err == nil {
+			return "#" + ch.Name
+		}
+		if ch, err := s.Channel(parts[1]); err == nil {
+			return "#" + ch.Name
+		}
+		return match
+	})
+
+	// 2. Expand Discord message links (max 3, same guild only)
+	matches := msgLinkRe.FindAllStringSubmatch(text, 3)
+	for _, m := range matches {
+		if len(m) < 4 {
+			continue
+		}
+		linkGuildID, channelID, messageID := m[1], m[2], m[3]
+		// Security: only expand links from the same guild
+		if linkGuildID != guildID {
+			continue
+		}
+		msg, err := s.ChannelMessage(channelID, messageID)
+		if err != nil || msg == nil || msg.Content == "" {
+			continue
+		}
+		author := "unknown"
+		if msg.Author != nil {
+			author = msg.Author.Username
+		}
+		text += fmt.Sprintf("\n[linked message from %s]: %s", author, msg.Content)
+	}
+
+	return text
+}
+
 // stripBotMention removes the bot mention from the message content.
 // Discord mentions have the format <@USER_ID> or <@!USER_ID> (with nickname).
 func (c *DiscordChannel) stripBotMention(text string) string {
diff --git a/pkg/channels/discord/discord_resolve_test.go b/pkg/channels/discord/discord_resolve_test.go
new file mode 100644
index 000000000..4bc65cc18
--- /dev/null
+++ b/pkg/channels/discord/discord_resolve_test.go
@@ -0,0 +1,98 @@
+package discord
+
+import (
+	"testing"
+)
+
+func TestChannelRefRegex(t *testing.T) {
+	tests := []struct {
+		name   string
+		input  string
+		wantID string
+		wantOK bool
+	}{
+		{"basic channel ref", "<#123456789>", "123456789", true},
+		{"long id", "<#9876543210123456>", "9876543210123456", true},
+		{"no match plain text", "hello world", "", false},
+		{"no match partial", "<#>", "", false},
+		{"no match letters", "<#abc>", "", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			matches := channelRefRe.FindStringSubmatch(tt.input)
+			if tt.wantOK {
+				if len(matches) < 2 || matches[1] != tt.wantID {
+					t.Errorf("channelRefRe(%q) = %v, want ID %q", tt.input, matches, tt.wantID)
+				}
+			} else {
+				if len(matches) >= 2 {
+					t.Errorf("channelRefRe(%q) should not match, got %v", tt.input, matches)
+				}
+			}
+		})
+	}
+}
+
+func TestMsgLinkRegex(t *testing.T) {
+	tests := []struct {
+		name      string
+		input     string
+		wantGuild string
+		wantChan  string
+		wantMsg   string
+		wantOK    bool
+	}{
+		{
+			"discord.com link",
+			"https://discord.com/channels/111/222/333",
+			"111", "222", "333", true,
+		},
+		{
+			"discordapp.com link",
+			"https://discordapp.com/channels/111/222/333",
+			"111", "222", "333", true,
+		},
+		{
+			"real world ids",
+			"check this https://discord.com/channels/9000000000000001/9000000000000002/9000000000000003 please",
+			"9000000000000001", "9000000000000002", "9000000000000003", true,
+		},
+		{"no match http", "http://discord.com/channels/1/2/3", "", "", "", false},
+		{"no match missing segment", "https://discord.com/channels/1/2", "", "", "", false},
+		{"no match plain text", "hello world", "", "", "", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			matches := msgLinkRe.FindStringSubmatch(tt.input)
+			if tt.wantOK {
+				if len(matches) < 4 {
+					t.Fatalf("msgLinkRe(%q) didn't match, want guild=%s chan=%s msg=%s",
+						tt.input, tt.wantGuild, tt.wantChan, tt.wantMsg)
+				}
+				if matches[1] != tt.wantGuild || matches[2] != tt.wantChan || matches[3] != tt.wantMsg {
+					t.Errorf("msgLinkRe(%q) = guild=%s chan=%s msg=%s, want %s/%s/%s",
+						tt.input, matches[1], matches[2], matches[3],
+						tt.wantGuild, tt.wantChan, tt.wantMsg)
+				}
+			} else {
+				if len(matches) >= 4 {
+					t.Errorf("msgLinkRe(%q) should not match, got %v", tt.input, matches)
+				}
+			}
+		})
+	}
+}
+
+func TestMsgLinkRegex_MultipleMatches(t *testing.T) {
+	input := "see https://discord.com/channels/1/2/3 and https://discord.com/channels/4/5/6 and https://discord.com/channels/7/8/9 and https://discord.com/channels/10/11/12"
+	matches := msgLinkRe.FindAllStringSubmatch(input, 3)
+	if len(matches) != 3 {
+		t.Fatalf("expected 3 matches (capped), got %d", len(matches))
+	}
+	// Verify the 3rd match is 7/8/9 (not 10/11/12)
+	if matches[2][1] != "7" || matches[2][2] != "8" || matches[2][3] != "9" {
+		t.Errorf("3rd match = %v, want guild=7 chan=8 msg=9", matches[2])
+	}
+}
diff --git a/pkg/channels/discord/discord_test.go b/pkg/channels/discord/discord_test.go
new file mode 100644
index 000000000..0cd5328f4
--- /dev/null
+++ b/pkg/channels/discord/discord_test.go
@@ -0,0 +1,91 @@
+package discord
+
+import (
+	"net/http"
+	"net/url"
+	"testing"
+
+	"github.com/bwmarrin/discordgo"
+)
+
+func TestApplyDiscordProxy_CustomProxy(t *testing.T) {
+	session, err := discordgo.New("Bot test-token")
+	if err != nil {
+		t.Fatalf("discordgo.New() error: %v", err)
+	}
+
+	if err = applyDiscordProxy(session, "http://127.0.0.1:7890"); err != nil {
+		t.Fatalf("applyDiscordProxy() error: %v", err)
+	}
+
+	req, err := http.NewRequest("GET", "https://discord.com/api/v10/gateway", nil)
+	if err != nil {
+		t.Fatalf("http.NewRequest() error: %v", err)
+	}
+
+	restProxy := session.Client.Transport.(*http.Transport).Proxy
+	restProxyURL, err := restProxy(req)
+	if err != nil {
+		t.Fatalf("rest proxy func error: %v", err)
+	}
+	if got, want := restProxyURL.String(), "http://127.0.0.1:7890"; got != want {
+		t.Fatalf("REST proxy = %q, want %q", got, want)
+	}
+
+	wsProxyURL, err := session.Dialer.Proxy(req)
+	if err != nil {
+		t.Fatalf("ws proxy func error: %v", err)
+	}
+	if got, want := wsProxyURL.String(), "http://127.0.0.1:7890"; got != want {
+		t.Fatalf("WS proxy = %q, want %q", got, want)
+	}
+}
+
+func TestApplyDiscordProxy_FromEnvironment(t *testing.T) {
+	t.Setenv("HTTP_PROXY", "http://127.0.0.1:8888")
+	t.Setenv("http_proxy", "http://127.0.0.1:8888")
+	t.Setenv("HTTPS_PROXY", "http://127.0.0.1:8888")
+	t.Setenv("https_proxy", "http://127.0.0.1:8888")
+	t.Setenv("ALL_PROXY", "")
+	t.Setenv("all_proxy", "")
+	t.Setenv("NO_PROXY", "")
+	t.Setenv("no_proxy", "")
+
+	session, err := discordgo.New("Bot test-token")
+	if err != nil {
+		t.Fatalf("discordgo.New() error: %v", err)
+	}
+
+	if err = applyDiscordProxy(session, ""); err != nil {
+		t.Fatalf("applyDiscordProxy() error: %v", err)
+	}
+
+	req, err := http.NewRequest("GET", "https://discord.com/api/v10/gateway", nil)
+	if err != nil {
+		t.Fatalf("http.NewRequest() error: %v", err)
+	}
+
+	gotURL, err := session.Dialer.Proxy(req)
+	if err != nil {
+		t.Fatalf("ws proxy func error: %v", err)
+	}
+
+	wantURL, err := url.Parse("http://127.0.0.1:8888")
+	if err != nil {
+		t.Fatalf("url.Parse() error: %v", err)
+	}
+	if gotURL.String() != wantURL.String() {
+		t.Fatalf("WS proxy = %q, want %q", gotURL.String(), wantURL.String())
+	}
+}
+
+func TestApplyDiscordProxy_InvalidProxyURL(t *testing.T) {
+	session, err := discordgo.New("Bot test-token")
+	if err != nil {
+		t.Fatalf("discordgo.New() error: %v", err)
+	}
+
+	if err = applyDiscordProxy(session, "://bad-proxy"); err == nil {
+		t.Fatal("applyDiscordProxy() expected error for invalid proxy URL, got nil")
+	}
+}
diff --git a/pkg/channels/feishu/common.go b/pkg/channels/feishu/common.go
index e8a057741..4952394b7 100644
--- a/pkg/channels/feishu/common.go
+++ b/pkg/channels/feishu/common.go
@@ -1,5 +1,16 @@
 package feishu
 
+import (
+	"encoding/json"
+	"regexp"
+	"strings"
+
+	larkim "github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
+)
+
+// mentionPlaceholderRegex matches @_user_N placeholders inserted by Feishu for mentions.
+var mentionPlaceholderRegex = regexp.MustCompile(`@_user_\d+`)
+
 // stringValue safely dereferences a *string pointer.
 func stringValue(v *string) string {
 	if v == nil {
@@ -7,3 +18,130 @@ func stringValue(v *string) string {
 	}
 	return *v
 }
+
+// buildMarkdownCard builds a Feishu Interactive Card JSON 2.0 string with markdown content.
+// JSON 2.0 cards support full CommonMark standard markdown syntax.
+func buildMarkdownCard(content string) (string, error) {
+	card := map[string]any{
+		"schema": "2.0",
+		"body": map[string]any{
+			"elements": []map[string]any{
+				{
+					"tag":     "markdown",
+					"content": content,
+				},
+			},
+		},
+	}
+	data, err := json.Marshal(card)
+	if err != nil {
+		return "", err
+	}
+	return string(data), nil
+}
+
+// extractJSONStringField unmarshals content as JSON and returns the value of the given string field.
+// Returns "" if the content is invalid JSON or the field is missing/empty.
+func extractJSONStringField(content, field string) string {
+	var m map[string]json.RawMessage
+	if err := json.Unmarshal([]byte(content), &m); err != nil {
+		return ""
+	}
+	raw, ok := m[field]
+	if !ok {
+		return ""
+	}
+	var s string
+	if err := json.Unmarshal(raw, &s); err != nil {
+		return ""
+	}
+	return s
+}
+
+// extractImageKey extracts the image_key from a Feishu image message content JSON.
+// Format: {"image_key": "img_xxx"}
+func extractImageKey(content string) string { return extractJSONStringField(content, "image_key") }
+
+// extractFileKey extracts the file_key from a Feishu file/audio message content JSON.
+// Format: {"file_key": "file_xxx", "file_name": "...", ...}
+func extractFileKey(content string) string { return extractJSONStringField(content, "file_key") }
+
+// extractFileName extracts the file_name from a Feishu file message content JSON.
+func extractFileName(content string) string { return extractJSONStringField(content, "file_name") }
+
+// stripMentionPlaceholders removes @_user_N placeholders from the text content.
+// These are inserted by Feishu when users @mention someone in a message.
+func stripMentionPlaceholders(content string, mentions []*larkim.MentionEvent) string {
+	if len(mentions) == 0 {
+		return content
+	}
+	for _, m := range mentions {
+		if m.Key != nil && *m.Key != "" {
+			content = strings.ReplaceAll(content, *m.Key, "")
+		}
+	}
+	// Also clean up any remaining @_user_N patterns
+	content = mentionPlaceholderRegex.ReplaceAllString(content, "")
+	return strings.TrimSpace(content)
+}
+
+// extractCardImageKeys recursively extracts all image keys from a Feishu interactive card.
+// Image keys are used to download images from Feishu API.
+// Returns two slices: Feishu-hosted keys and external URLs.
+func extractCardImageKeys(rawContent string) (feishuKeys []string, externalURLs []string) {
+	if rawContent == "" {
+		return nil, nil
+	}
+
+	var card map[string]any
+	if err := json.Unmarshal([]byte(rawContent), &card); err != nil {
+		return nil, nil
+	}
+
+	extractImageKeysRecursive(card, &feishuKeys, &externalURLs)
+	return feishuKeys, externalURLs
+}
+
+// isExternalURL returns true if the string is an external HTTP/HTTPS URL.
+func isExternalURL(s string) bool {
+	return strings.HasPrefix(s, "http://") || strings.HasPrefix(s, "https://")
+}
+
+// extractImageKeysRecursive traverses card structure to find all image keys.
+// Collects both Feishu-hosted keys and external URLs separately.
+func extractImageKeysRecursive(v any, feishuKeys, externalURLs *[]string) {
+	switch val := v.(type) {
+	case map[string]any:
+		// Check if this is an img element
+		if tag, ok := val["tag"].(string); ok {
+			switch tag {
+			case "img":
+				// Try img_key first (always Feishu-hosted)
+				if imgKey, ok := val["img_key"].(string); ok && imgKey != "" {
+					*feishuKeys = append(*feishuKeys, imgKey)
+				}
+				// Check src - could be Feishu key or external URL
+				if src, ok := val["src"].(string); ok && src != "" {
+					if isExternalURL(src) {
+						*externalURLs = append(*externalURLs, src)
+					} else {
+						*feishuKeys = append(*feishuKeys, src)
+					}
+				}
+			case "icon":
+				// Icon elements use icon_key
+				if iconKey, ok := val["icon_key"].(string); ok && iconKey != "" {
+					*feishuKeys = append(*feishuKeys, iconKey)
+				}
+			}
+		}
+		// Recurse into all nested structures
+		for _, child := range val {
+			extractImageKeysRecursive(child, feishuKeys, externalURLs)
+		}
+	case []any:
+		for _, item := range val {
+			extractImageKeysRecursive(item, feishuKeys, externalURLs)
+		}
+	}
+}
diff --git a/pkg/channels/feishu/common_test.go b/pkg/channels/feishu/common_test.go
new file mode 100644
index 000000000..ff4af0148
--- /dev/null
+++ b/pkg/channels/feishu/common_test.go
@@ -0,0 +1,408 @@
+package feishu
+
+import (
+	"encoding/json"
+	"testing"
+
+	larkim "github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
+)
+
+func TestExtractJSONStringField(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		field   string
+		want    string
+	}{
+		{
+			name:    "valid field",
+			content: `{"image_key": "img_v2_xxx"}`,
+			field:   "image_key",
+			want:    "img_v2_xxx",
+		},
+		{
+			name:    "missing field",
+			content: `{"image_key": "img_v2_xxx"}`,
+			field:   "file_key",
+			want:    "",
+		},
+		{
+			name:    "invalid JSON",
+			content: `not json at all`,
+			field:   "image_key",
+			want:    "",
+		},
+		{
+			name:    "empty content",
+			content: "",
+			field:   "image_key",
+			want:    "",
+		},
+		{
+			name:    "non-string field value",
+			content: `{"count": 42}`,
+			field:   "count",
+			want:    "",
+		},
+		{
+			name:    "empty string value",
+			content: `{"image_key": ""}`,
+			field:   "image_key",
+			want:    "",
+		},
+		{
+			name:    "multiple fields",
+			content: `{"file_key": "file_xxx", "file_name": "test.pdf"}`,
+			field:   "file_name",
+			want:    "test.pdf",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := extractJSONStringField(tt.content, tt.field)
+			if got != tt.want {
+				t.Errorf("extractJSONStringField(%q, %q) = %q, want %q", tt.content, tt.field, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestExtractImageKey(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		want    string
+	}{
+		{
+			name:    "normal",
+			content: `{"image_key": "img_v2_abc123"}`,
+			want:    "img_v2_abc123",
+		},
+		{
+			name:    "missing key",
+			content: `{"file_key": "file_xxx"}`,
+			want:    "",
+		},
+		{
+			name:    "malformed JSON",
+			content: `{broken`,
+			want:    "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := extractImageKey(tt.content)
+			if got != tt.want {
+				t.Errorf("extractImageKey(%q) = %q, want %q", tt.content, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestExtractFileKey(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		want    string
+	}{
+		{
+			name:    "normal",
+			content: `{"file_key": "file_v2_abc123", "file_name": "test.doc"}`,
+			want:    "file_v2_abc123",
+		},
+		{
+			name:    "missing key",
+			content: `{"image_key": "img_xxx"}`,
+			want:    "",
+		},
+		{
+			name:    "malformed JSON",
+			content: `not json`,
+			want:    "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := extractFileKey(tt.content)
+			if got != tt.want {
+				t.Errorf("extractFileKey(%q) = %q, want %q", tt.content, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestExtractFileName(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		want    string
+	}{
+		{
+			name:    "normal",
+			content: `{"file_key": "file_xxx", "file_name": "report.pdf"}`,
+			want:    "report.pdf",
+		},
+		{
+			name:    "missing name",
+			content: `{"file_key": "file_xxx"}`,
+			want:    "",
+		},
+		{
+			name:    "malformed JSON",
+			content: `{bad`,
+			want:    "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := extractFileName(tt.content)
+			if got != tt.want {
+				t.Errorf("extractFileName(%q) = %q, want %q", tt.content, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestBuildMarkdownCard(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+	}{
+		{
+			name:    "normal content",
+			content: "Hello **world**",
+		},
+		{
+			name:    "empty content",
+			content: "",
+		},
+		{
+			name:    "special characters",
+			content: `Code: "foo" & <bar> 'baz'`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result, err := buildMarkdownCard(tt.content)
+			if err != nil {
+				t.Fatalf("buildMarkdownCard(%q) unexpected error: %v", tt.content, err)
+			}
+
+			// Verify valid JSON
+			var parsed map[string]any
+			if err := json.Unmarshal([]byte(result), &parsed); err != nil {
+				t.Fatalf("buildMarkdownCard(%q) produced invalid JSON: %v", tt.content, err)
+			}
+
+			// Verify schema
+			if parsed["schema"] != "2.0" {
+				t.Errorf("schema = %v, want %q", parsed["schema"], "2.0")
+			}
+
+			// Verify body.elements[0].content == input
+			body, ok := parsed["body"].(map[string]any)
+			if !ok {
+				t.Fatal("missing body in card JSON")
+			}
+			elements, ok := body["elements"].([]any)
+			if !ok || len(elements) == 0 {
+				t.Fatal("missing or empty elements in card JSON")
+			}
+			elem, ok := elements[0].(map[string]any)
+			if !ok {
+				t.Fatal("first element is not an object")
+			}
+			if elem["tag"] != "markdown" {
+				t.Errorf("tag = %v, want %q", elem["tag"], "markdown")
+			}
+			if elem["content"] != tt.content {
+				t.Errorf("content = %v, want %q", elem["content"], tt.content)
+			}
+		})
+	}
+}
+
+func TestStripMentionPlaceholders(t *testing.T) {
+	strPtr := func(s string) *string { return &s }
+
+	tests := []struct {
+		name     string
+		content  string
+		mentions []*larkim.MentionEvent
+		want     string
+	}{
+		{
+			name:     "no mentions",
+			content:  "Hello world",
+			mentions: nil,
+			want:     "Hello world",
+		},
+		{
+			name:    "single mention",
+			content: "@_user_1 hello",
+			mentions: []*larkim.MentionEvent{
+				{Key: strPtr("@_user_1")},
+			},
+			want: "hello",
+		},
+		{
+			name:    "multiple mentions",
+			content: "@_user_1 @_user_2 hey",
+			mentions: []*larkim.MentionEvent{
+				{Key: strPtr("@_user_1")},
+				{Key: strPtr("@_user_2")},
+			},
+			want: "hey",
+		},
+		{
+			name:     "empty content",
+			content:  "",
+			mentions: []*larkim.MentionEvent{{Key: strPtr("@_user_1")}},
+			want:     "",
+		},
+		{
+			name:     "empty mentions slice",
+			content:  "@_user_1 test",
+			mentions: []*larkim.MentionEvent{},
+			want:     "@_user_1 test",
+		},
+		{
+			name:    "mention with nil key",
+			content: "@_user_1 test",
+			mentions: []*larkim.MentionEvent{
+				{Key: nil},
+			},
+			want: "test",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := stripMentionPlaceholders(tt.content, tt.mentions)
+			if got != tt.want {
+				t.Errorf("stripMentionPlaceholders(%q, ...) = %q, want %q", tt.content, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestExtractCardImageKeys(t *testing.T) {
+	tests := []struct {
+		name             string
+		content          string
+		wantFeishuKeys   []string
+		wantExternalURLs []string
+	}{
+		{
+			name:             "empty content",
+			content:          "",
+			wantFeishuKeys:   nil,
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "invalid JSON",
+			content:          "not json",
+			wantFeishuKeys:   nil,
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "card with no images",
+			content:          `{"schema":"2.0","body":{"elements":[{"tag":"markdown","content":"text"}]}}`,
+			wantFeishuKeys:   nil,
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "single image with img_key",
+			content:          `{"elements":[{"tag":"img","img_key":"img_abc123"}]}`,
+			wantFeishuKeys:   []string{"img_abc123"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "single image with src as Feishu key",
+			content:          `{"elements":[{"tag":"img","src":"img_xyz789"}]}`,
+			wantFeishuKeys:   []string{"img_xyz789"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "multiple images",
+			content:          `{"elements":[{"tag":"img","img_key":"img_1"},{"tag":"div","text":{"content":"text"}},{"tag":"img","img_key":"img_2"}]}`,
+			wantFeishuKeys:   []string{"img_1", "img_2"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "nested image in columns",
+			content:          `{"elements":[{"tag":"div","columns":[{"tag":"img","img_key":"img_col1"},{"tag":"img","img_key":"img_col2"}]}]}`,
+			wantFeishuKeys:   []string{"img_col1", "img_col2"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "image in action",
+			content:          `{"elements":[{"tag":"action","actions":[{"tag":"img","img_key":"img_action"}]}]}`,
+			wantFeishuKeys:   []string{"img_action"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "icon element",
+			content:          `{"elements":[{"tag":"icon","icon_key":"icon_123"}]}`,
+			wantFeishuKeys:   []string{"icon_123"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "complex card with text and images",
+			content:          `{"header":{"title":{"content":"Title"}},"elements":[{"tag":"div","text":{"content":"Description"}},{"tag":"img","img_key":"img_main"}]}`,
+			wantFeishuKeys:   []string{"img_main"},
+			wantExternalURLs: nil,
+		},
+		{
+			name:             "external URL in src",
+			content:          `{"elements":[{"tag":"img","src":"https://example.com/image.png"}]}`,
+			wantFeishuKeys:   nil,
+			wantExternalURLs: []string{"https://example.com/image.png"},
+		},
+		{
+			name:             "mixed Feishu keys and external URLs",
+			content:          `{"elements":[{"tag":"img","img_key":"img_feishu"},{"tag":"img","src":"https://cdn.example.com/external.jpg"},{"tag":"img","src":"img_another"}]}`,
+			wantFeishuKeys:   []string{"img_feishu", "img_another"},
+			wantExternalURLs: []string{"https://cdn.example.com/external.jpg"},
+		},
+		{
+			name:             "multiple external URLs",
+			content:          `{"elements":[{"tag":"img","src":"https://a.com/1.png"},{"tag":"img","src":"http://b.com/2.jpg"}]}`,
+			wantFeishuKeys:   nil,
+			wantExternalURLs: []string{"https://a.com/1.png", "http://b.com/2.jpg"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gotFeishuKeys, gotExternalURLs := extractCardImageKeys(tt.content)
+
+			// Compare Feishu keys
+			if len(gotFeishuKeys) != len(tt.wantFeishuKeys) {
+				t.Errorf("extractCardImageKeys() feishuKeys = %v, want %v", gotFeishuKeys, tt.wantFeishuKeys)
+				return
+			}
+			for i, v := range gotFeishuKeys {
+				if v != tt.wantFeishuKeys[i] {
+					t.Errorf("extractCardImageKeys() feishuKeys[%d] = %q, want %q", i, v, tt.wantFeishuKeys[i])
+				}
+			}
+
+			// Compare external URLs
+			if len(gotExternalURLs) != len(tt.wantExternalURLs) {
+				t.Errorf("extractCardImageKeys() externalURLs = %v, want %v", gotExternalURLs, tt.wantExternalURLs)
+				return
+			}
+			for i, v := range gotExternalURLs {
+				if v != tt.wantExternalURLs[i] {
+					t.Errorf("extractCardImageKeys() externalURLs[%d] = %q, want %q", i, v, tt.wantExternalURLs[i])
+				}
+			}
+		})
+	}
+}
diff --git a/pkg/channels/feishu/feishu_32.go b/pkg/channels/feishu/feishu_32.go
index d0ec758c6..f5e3aa224 100644
--- a/pkg/channels/feishu/feishu_32.go
+++ b/pkg/channels/feishu/feishu_32.go
@@ -16,6 +16,8 @@ type FeishuChannel struct {
 	*channels.BaseChannel
 }
 
+var errUnsupported = errors.New("feishu channel is not supported on 32-bit architectures")
+
 // NewFeishuChannel returns an error on 32-bit architectures where the Feishu SDK is not supported
 func NewFeishuChannel(cfg config.FeishuConfig, bus *bus.MessageBus) (*FeishuChannel, error) {
 	return nil, errors.New(
@@ -25,15 +27,35 @@ func NewFeishuChannel(cfg config.FeishuConfig, bus *bus.MessageBus) (*FeishuChan
 
 // Start is a stub method to satisfy the Channel interface
 func (c *FeishuChannel) Start(ctx context.Context) error {
-	return nil
+	return errUnsupported
 }
 
 // Stop is a stub method to satisfy the Channel interface
 func (c *FeishuChannel) Stop(ctx context.Context) error {
-	return nil
+	return errUnsupported
 }
 
 // Send is a stub method to satisfy the Channel interface
 func (c *FeishuChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
-	return errors.New("feishu channel is not supported on 32-bit architectures")
+	return errUnsupported
+}
+
+// EditMessage is a stub method to satisfy MessageEditor
+func (c *FeishuChannel) EditMessage(ctx context.Context, chatID, messageID, content string) error {
+	return errUnsupported
+}
+
+// SendPlaceholder is a stub method to satisfy PlaceholderCapable
+func (c *FeishuChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) {
+	return "", errUnsupported
+}
+
+// ReactToMessage is a stub method to satisfy ReactionCapable
+func (c *FeishuChannel) ReactToMessage(ctx context.Context, chatID, messageID string) (func(), error) {
+	return func() {}, errUnsupported
+}
+
+// SendMedia is a stub method to satisfy MediaSender
+func (c *FeishuChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	return errUnsupported
 }
diff --git a/pkg/channels/feishu/feishu_64.go b/pkg/channels/feishu/feishu_64.go
index 1db1bf669..0ab70649f 100644
--- a/pkg/channels/feishu/feishu_64.go
+++ b/pkg/channels/feishu/feishu_64.go
@@ -6,10 +6,17 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"io"
+	"math/rand"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
 	"sync"
-	"time"
+	"sync/atomic"
 
 	lark "github.com/larksuite/oapi-sdk-go/v3"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
 	larkdispatcher "github.com/larksuite/oapi-sdk-go/v3/event/dispatcher"
 	larkim "github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
 	larkws "github.com/larksuite/oapi-sdk-go/v3/ws"
@@ -19,14 +26,23 @@ import (
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/identity"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
+// errCodeTenantTokenInvalid is the Feishu API error code for an expired/revoked
+// tenant_access_token. The Lark SDK's built-in retry does not clear its cache
+// on this error, so we do it ourselves.
+const errCodeTenantTokenInvalid = 99991663
+
 type FeishuChannel struct {
 	*channels.BaseChannel
-	config   config.FeishuConfig
-	client   *lark.Client
-	wsClient *larkws.Client
+	config     config.FeishuConfig
+	client     *lark.Client
+	wsClient   *larkws.Client
+	tokenCache *tokenCache // custom cache that supports invalidation
+
+	botOpenID atomic.Value // stores string; populated lazily for @mention detection
 
 	mu     sync.Mutex
 	cancel context.CancelFunc
@@ -38,29 +54,49 @@ func NewFeishuChannel(cfg config.FeishuConfig, bus *bus.MessageBus) (*FeishuChan
 		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
 	)
 
-	return &FeishuChannel{
+	tc := newTokenCache()
+	opts := []lark.ClientOptionFunc{lark.WithTokenCache(tc)}
+	if cfg.IsLark {
+		opts = append(opts, lark.WithOpenBaseUrl(lark.LarkBaseUrl))
+	}
+	ch := &FeishuChannel{
 		BaseChannel: base,
 		config:      cfg,
-		client:      lark.NewClient(cfg.AppID, cfg.AppSecret),
-	}, nil
+		tokenCache:  tc,
+		client:      lark.NewClient(cfg.AppID, cfg.AppSecret(), opts...),
+	}
+	ch.SetOwner(ch)
+	return ch, nil
 }
 
 func (c *FeishuChannel) Start(ctx context.Context) error {
-	if c.config.AppID == "" || c.config.AppSecret == "" {
+	if c.config.AppID == "" || c.config.AppSecret() == "" {
 		return fmt.Errorf("feishu app_id or app_secret is empty")
 	}
 
-	dispatcher := larkdispatcher.NewEventDispatcher(c.config.VerificationToken, c.config.EncryptKey).
+	// Fetch bot open_id via API for reliable @mention detection.
+	if err := c.fetchBotOpenID(ctx); err != nil {
+		logger.ErrorCF("feishu", "Failed to fetch bot open_id, @mention detection may not work", map[string]any{
+			"error": err.Error(),
+		})
+	}
+
+	dispatcher := larkdispatcher.NewEventDispatcher(c.config.VerificationToken(), c.config.EncryptKey()).
 		OnP2MessageReceiveV1(c.handleMessageReceive)
 
 	runCtx, cancel := context.WithCancel(ctx)
 
 	c.mu.Lock()
 	c.cancel = cancel
+	domain := lark.FeishuBaseUrl
+	if c.config.IsLark {
+		domain = lark.LarkBaseUrl
+	}
 	c.wsClient = larkws.NewClient(
 		c.config.AppID,
-		c.config.AppSecret,
+		c.config.AppSecret(),
 		larkws.WithEventHandler(dispatcher),
+		larkws.WithDomain(domain),
 	)
 	wsClient := c.wsClient
 	c.mu.Unlock()
@@ -93,46 +129,259 @@ func (c *FeishuChannel) Stop(ctx context.Context) error {
 	return nil
 }
 
+// Send sends a message using Interactive Card format for markdown rendering.
+// Falls back to plain text message if card sending fails (e.g., table limit exceeded).
 func (c *FeishuChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
 		return channels.ErrNotRunning
 	}
 
 	if msg.ChatID == "" {
-		return fmt.Errorf("chat ID is empty")
+		return fmt.Errorf("chat ID is empty: %w", channels.ErrSendFailed)
 	}
 
-	payload, err := json.Marshal(map[string]string{"text": msg.Content})
+	// Build interactive card with markdown content
+	cardContent, err := buildMarkdownCard(msg.Content)
 	if err != nil {
-		return fmt.Errorf("failed to marshal feishu content: %w", err)
+		// If card build fails, fall back to plain text
+		return c.sendText(ctx, msg.ChatID, msg.Content)
+	}
+
+	// First attempt: try sending as interactive card
+	err = c.sendCard(ctx, msg.ChatID, cardContent)
+	if err == nil {
+		return nil
+	}
+
+	// Check if error is due to card table limit (error code 11310)
+	// See: https://open.feishu.cn/document/server-docs/im-api/message-content-description/create_json
+	errMsg := err.Error()
+	isCardLimitError := strings.Contains(errMsg, "11310")
+
+	if isCardLimitError {
+		logger.WarnCF("feishu", "Card send failed (table limit), falling back to text message", map[string]any{
+			"chat_id": msg.ChatID,
+			"error":   errMsg,
+		})
+
+		// Second attempt: fall back to plain text message
+		textErr := c.sendText(ctx, msg.ChatID, msg.Content)
+		if textErr == nil {
+			return nil
+		}
+		// If text also fails, return the text error
+		return textErr
+	}
+
+	// For other errors, return the original card error
+	return err
+}
+
+// EditMessage implements channels.MessageEditor.
+// Uses Message.Patch to update an interactive card message.
+func (c *FeishuChannel) EditMessage(ctx context.Context, chatID, messageID, content string) error {
+	cardContent, err := buildMarkdownCard(content)
+	if err != nil {
+		return fmt.Errorf("feishu edit: card build failed: %w", err)
+	}
+
+	req := larkim.NewPatchMessageReqBuilder().
+		MessageId(messageID).
+		Body(larkim.NewPatchMessageReqBodyBuilder().Content(cardContent).Build()).
+		Build()
+
+	resp, err := c.client.Im.V1.Message.Patch(ctx, req)
+	if err != nil {
+		return fmt.Errorf("feishu edit: %w", err)
+	}
+	if !resp.Success() {
+		c.invalidateTokenOnAuthError(resp.Code)
+		return fmt.Errorf("feishu edit api error (code=%d msg=%s)", resp.Code, resp.Msg)
+	}
+	return nil
+}
+
+// SendPlaceholder implements channels.PlaceholderCapable.
+// Sends an interactive card with placeholder text and returns its message ID.
+func (c *FeishuChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) {
+	if !c.config.Placeholder.Enabled {
+		logger.DebugCF("feishu", "Placeholder disabled, skipping", map[string]any{
+			"chat_id": chatID,
+		})
+		return "", nil
+	}
+
+	text := c.config.Placeholder.Text
+	if text == "" {
+		text = "Thinking..."
+	}
+
+	cardContent, err := buildMarkdownCard(text)
+	if err != nil {
+		return "", fmt.Errorf("feishu placeholder: card build failed: %w", err)
 	}
 
 	req := larkim.NewCreateMessageReqBuilder().
 		ReceiveIdType(larkim.ReceiveIdTypeChatId).
 		Body(larkim.NewCreateMessageReqBodyBuilder().
-			ReceiveId(msg.ChatID).
-			MsgType(larkim.MsgTypeText).
-			Content(string(payload)).
-			Uuid(fmt.Sprintf("picoclaw-%d", time.Now().UnixNano())).
+			ReceiveId(chatID).
+			MsgType(larkim.MsgTypeInteractive).
+			Content(cardContent).
 			Build()).
 		Build()
 
 	resp, err := c.client.Im.V1.Message.Create(ctx, req)
 	if err != nil {
-		return fmt.Errorf("feishu send: %w", channels.ErrTemporary)
+		return "", fmt.Errorf("feishu placeholder send: %w", err)
 	}
-
 	if !resp.Success() {
-		return fmt.Errorf("feishu api error (code=%d msg=%s): %w", resp.Code, resp.Msg, channels.ErrTemporary)
+		c.invalidateTokenOnAuthError(resp.Code)
+		return "", fmt.Errorf("feishu placeholder api error (code=%d msg=%s)", resp.Code, resp.Msg)
 	}
 
-	logger.DebugCF("feishu", "Feishu message sent", map[string]any{
-		"chat_id": msg.ChatID,
-	})
+	if resp.Data != nil && resp.Data.MessageId != nil {
+		return *resp.Data.MessageId, nil
+	}
+	return "", nil
+}
+
+// ReactToMessage implements channels.ReactionCapable.
+// Adds a reaction (randomly chosen from config) and returns an undo function to remove it.
+func (c *FeishuChannel) ReactToMessage(ctx context.Context, chatID, messageID string) (func(), error) {
+	// Get emoji list from config
+	emojiList := c.config.RandomReactionEmoji
+	var chosenEmoji string
+	if len(emojiList) == 0 {
+		// Default to "Pin" if no config
+		chosenEmoji = "Pin"
+	} else {
+		idx := rand.Intn(len(emojiList))
+		chosenEmoji = emojiList[idx]
+	}
+
+	req := larkim.NewCreateMessageReactionReqBuilder().
+		MessageId(messageID).
+		Body(larkim.NewCreateMessageReactionReqBodyBuilder().
+			ReactionType(larkim.NewEmojiBuilder().EmojiType(chosenEmoji).Build()).
+			Build()).
+		Build()
+
+	resp, err := c.client.Im.V1.MessageReaction.Create(ctx, req)
+	if err != nil {
+		logger.ErrorCF("feishu", "Failed to add reaction", map[string]any{
+			"emoji":      chosenEmoji,
+			"message_id": messageID,
+			"error":      err.Error(),
+		})
+		return func() {}, fmt.Errorf("feishu react: %w", err)
+	}
+	if !resp.Success() {
+		c.invalidateTokenOnAuthError(resp.Code)
+		logger.ErrorCF("feishu", "Reaction API error", map[string]any{
+			"emoji":      chosenEmoji,
+			"message_id": messageID,
+			"code":       resp.Code,
+			"msg":        resp.Msg,
+		})
+		return func() {}, fmt.Errorf("feishu react api error (code=%d msg=%s)", resp.Code, resp.Msg)
+	}
+
+	var reactionID string
+	if resp.Data != nil && resp.Data.ReactionId != nil {
+		reactionID = *resp.Data.ReactionId
+	}
+	if reactionID == "" {
+		return func() {}, nil
+	}
+
+	var undone atomic.Bool
+	undo := func() {
+		if !undone.CompareAndSwap(false, true) {
+			return
+		}
+		delReq := larkim.NewDeleteMessageReactionReqBuilder().
+			MessageId(messageID).
+			ReactionId(reactionID).
+			Build()
+		_, _ = c.client.Im.V1.MessageReaction.Delete(context.Background(), delReq)
+	}
+	return undo, nil
+}
+
+// SendMedia implements channels.MediaSender.
+// Uploads images/files via Feishu API then sends as messages.
+func (c *FeishuChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	if msg.ChatID == "" {
+		return fmt.Errorf("chat ID is empty: %w", channels.ErrSendFailed)
+	}
+
+	store := c.GetMediaStore()
+	if store == nil {
+		return fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
+	}
+
+	for _, part := range msg.Parts {
+		if err := c.sendMediaPart(ctx, msg.ChatID, part, store); err != nil {
+			return err
+		}
+	}
 
 	return nil
 }
 
+// sendMediaPart resolves and sends a single media part.
+func (c *FeishuChannel) sendMediaPart(
+	ctx context.Context,
+	chatID string,
+	part bus.MediaPart,
+	store media.MediaStore,
+) error {
+	localPath, err := store.Resolve(part.Ref)
+	if err != nil {
+		logger.ErrorCF("feishu", "Failed to resolve media ref", map[string]any{
+			"ref":   part.Ref,
+			"error": err.Error(),
+		})
+		return nil // skip this part
+	}
+
+	file, err := os.Open(localPath)
+	if err != nil {
+		logger.ErrorCF("feishu", "Failed to open media file", map[string]any{
+			"path":  localPath,
+			"error": err.Error(),
+		})
+		return nil // skip this part
+	}
+	defer file.Close()
+
+	switch part.Type {
+	case "image":
+		err = c.sendImage(ctx, chatID, file)
+	default:
+		filename := part.Filename
+		if filename == "" {
+			filename = "file"
+		}
+		err = c.sendFile(ctx, chatID, file, filename, part.Type)
+	}
+
+	if err != nil {
+		logger.ErrorCF("feishu", "Failed to send media", map[string]any{
+			"type":  part.Type,
+			"error": err.Error(),
+		})
+		return fmt.Errorf("feishu send media: %w", channels.ErrTemporary)
+	}
+	return nil
+}
+
+// --- Inbound message handling ---
+
 func (c *FeishuChannel) handleMessageReceive(ctx context.Context, event *larkim.P2MessageReceiveV1) error {
 	if event == nil || event.Event == nil || event.Event.Message == nil {
 		return nil
@@ -151,34 +400,77 @@ func (c *FeishuChannel) handleMessageReceive(ctx context.Context, event *larkim.
 		senderID = "unknown"
 	}
 
-	content := extractFeishuMessageContent(message)
+	messageType := stringValue(message.MessageType)
+	messageID := stringValue(message.MessageId)
+	rawContent := stringValue(message.Content)
+
+	// Check allowlist early to avoid downloading media for rejected senders.
+	// BaseChannel.HandleMessage will check again, but this avoids wasted network I/O.
+	senderInfo := bus.SenderInfo{
+		Platform:    "feishu",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("feishu", senderID),
+	}
+	if !c.IsAllowedSender(senderInfo) {
+		return nil
+	}
+
+	// Extract content based on message type
+	content := extractContent(messageType, rawContent)
+
+	// Handle media messages (download and store)
+	var mediaRefs []string
+	if store := c.GetMediaStore(); store != nil && messageID != "" {
+		mediaRefs = c.downloadInboundMedia(ctx, chatID, messageID, messageType, rawContent, store)
+	}
+
+	// For interactive cards, pass external image URLs via media refs.
+	// Keep content as valid raw JSON for downstream parsing.
+	if messageType == larkim.MsgTypeInteractive {
+		_, externalURLs := extractCardImageKeys(rawContent)
+		if len(externalURLs) > 0 {
+			mediaRefs = append(mediaRefs, externalURLs...)
+		}
+	}
+
+	// Append media tags to content (like Telegram does)
+	content = appendMediaTags(content, messageType, mediaRefs)
+
 	if content == "" {
 		content = "[empty message]"
 	}
 
 	metadata := map[string]string{}
-	messageID := ""
-	if mid := stringValue(message.MessageId); mid != "" {
-		messageID = mid
+	if messageID != "" {
+		metadata["message_id"] = messageID
 	}
-	if messageType := stringValue(message.MessageType); messageType != "" {
+	if messageType != "" {
 		metadata["message_type"] = messageType
 	}
-	if chatType := stringValue(message.ChatType); chatType != "" {
+	chatType := stringValue(message.ChatType)
+	if chatType != "" {
 		metadata["chat_type"] = chatType
 	}
 	if sender != nil && sender.TenantKey != nil {
 		metadata["tenant_key"] = *sender.TenantKey
 	}
 
-	chatType := stringValue(message.ChatType)
 	var peer bus.Peer
 	if chatType == "p2p" {
 		peer = bus.Peer{Kind: "direct", ID: senderID}
 	} else {
 		peer = bus.Peer{Kind: "group", ID: chatID}
+
+		// Check if bot was mentioned
+		isMentioned := c.isBotMentioned(message)
+
+		// Strip mention placeholders from content before group trigger check
+		if len(message.Mentions) > 0 {
+			content = stripMentionPlaceholders(content, message.Mentions)
+		}
+
 		// In group chats, apply unified group trigger filtering
-		respond, cleaned := c.ShouldRespondInGroup(false, content)
+		respond, cleaned := c.ShouldRespondInGroup(isMentioned, content)
 		if !respond {
 			return nil
 		}
@@ -186,22 +478,458 @@ func (c *FeishuChannel) handleMessageReceive(ctx context.Context, event *larkim.
 	}
 
 	logger.InfoCF("feishu", "Feishu message received", map[string]any{
-		"sender_id": senderID,
-		"chat_id":   chatID,
-		"preview":   utils.Truncate(content, 80),
+		"sender_id":  senderID,
+		"chat_id":    chatID,
+		"message_id": messageID,
+		"preview":    utils.Truncate(content, 80),
 	})
 
-	senderInfo := bus.SenderInfo{
-		Platform:    "feishu",
-		PlatformID:  senderID,
-		CanonicalID: identity.BuildCanonicalID("feishu", senderID),
+	c.HandleMessage(ctx, peer, messageID, senderID, chatID, content, mediaRefs, metadata, senderInfo)
+	return nil
+}
+
+// --- Internal helpers ---
+
+// fetchBotOpenID calls the Feishu bot info API to retrieve and store the bot's open_id.
+func (c *FeishuChannel) fetchBotOpenID(ctx context.Context) error {
+	resp, err := c.client.Do(ctx, &larkcore.ApiReq{
+		HttpMethod:                http.MethodGet,
+		ApiPath:                   "/open-apis/bot/v3/info",
+		SupportedAccessTokenTypes: []larkcore.AccessTokenType{larkcore.AccessTokenTypeTenant},
+	})
+	if err != nil {
+		return fmt.Errorf("bot info request: %w", err)
 	}
 
-	if !c.IsAllowedSender(senderInfo) {
-		return nil
+	var result struct {
+		Code int `json:"code"`
+		Bot  struct {
+			OpenID string `json:"open_id"`
+		} `json:"bot"`
+	}
+	if err := json.Unmarshal(resp.RawBody, &result); err != nil {
+		return fmt.Errorf("bot info parse: %w", err)
+	}
+	if result.Code != 0 {
+		c.invalidateTokenOnAuthError(result.Code)
+		return fmt.Errorf("bot info api error (code=%d)", result.Code)
+	}
+	if result.Bot.OpenID == "" {
+		return fmt.Errorf("bot info: empty open_id")
 	}
 
-	c.HandleMessage(ctx, peer, messageID, senderID, chatID, content, nil, metadata, senderInfo)
+	c.botOpenID.Store(result.Bot.OpenID)
+	logger.InfoCF("feishu", "Fetched bot open_id from API", map[string]any{
+		"open_id": result.Bot.OpenID,
+	})
+	return nil
+}
+
+// isBotMentioned checks if the bot was @mentioned in the message.
+func (c *FeishuChannel) isBotMentioned(message *larkim.EventMessage) bool {
+	if message.Mentions == nil {
+		return false
+	}
+
+	knownID, _ := c.botOpenID.Load().(string)
+	if knownID == "" {
+		logger.DebugCF("feishu", "Bot open_id unknown, cannot detect @mention", nil)
+		return false
+	}
+
+	for _, m := range message.Mentions {
+		if m.Id == nil {
+			continue
+		}
+		if m.Id.OpenId != nil && *m.Id.OpenId == knownID {
+			return true
+		}
+	}
+	return false
+}
+
+// extractContent extracts text content from different message types.
+func extractContent(messageType, rawContent string) string {
+	if rawContent == "" {
+		return ""
+	}
+
+	switch messageType {
+	case larkim.MsgTypeText:
+		var textPayload struct {
+			Text string `json:"text"`
+		}
+		if err := json.Unmarshal([]byte(rawContent), &textPayload); err == nil {
+			return textPayload.Text
+		}
+		return rawContent
+
+	case larkim.MsgTypePost:
+		// Pass raw JSON to LLM — structured rich text is more informative than flattened plain text
+		return rawContent
+
+	case larkim.MsgTypeInteractive:
+		// Pass raw JSON to LLM — structured card is more informative than flattened text
+		return rawContent
+
+	case larkim.MsgTypeImage:
+		// Image messages don't have text content
+		return ""
+
+	case larkim.MsgTypeFile, larkim.MsgTypeAudio, larkim.MsgTypeMedia:
+		// File/audio/video messages may have a filename
+		name := extractFileName(rawContent)
+		if name != "" {
+			return name
+		}
+		return ""
+
+	default:
+		return rawContent
+	}
+}
+
+// downloadInboundMedia downloads media from inbound messages and stores in MediaStore.
+func (c *FeishuChannel) downloadInboundMedia(
+	ctx context.Context,
+	chatID, messageID, messageType, rawContent string,
+	store media.MediaStore,
+) []string {
+	var refs []string
+	scope := channels.BuildMediaScope("feishu", chatID, messageID)
+
+	switch messageType {
+	case larkim.MsgTypeImage:
+		imageKey := extractImageKey(rawContent)
+		if imageKey == "" {
+			return nil
+		}
+		ref := c.downloadResource(ctx, messageID, imageKey, "image", ".jpg", store, scope)
+		if ref != "" {
+			refs = append(refs, ref)
+		}
+
+	case larkim.MsgTypeInteractive:
+		// Extract and download images embedded in interactive cards
+		feishuKeys, _ := extractCardImageKeys(rawContent)
+		// Download Feishu-hosted images via API
+		for _, imageKey := range feishuKeys {
+			ref := c.downloadResource(ctx, messageID, imageKey, "image", ".jpg", store, scope)
+			if ref != "" {
+				refs = append(refs, ref)
+			}
+		}
+		// External URLs are passed directly to LLM, not downloaded
+
+	case larkim.MsgTypeFile, larkim.MsgTypeAudio, larkim.MsgTypeMedia:
+		fileKey := extractFileKey(rawContent)
+		if fileKey == "" {
+			return nil
+		}
+		// Derive a fallback extension from the message type.
+		var ext string
+		switch messageType {
+		case larkim.MsgTypeAudio:
+			ext = ".ogg"
+		case larkim.MsgTypeMedia:
+			ext = ".mp4"
+		default:
+			ext = "" // generic file — rely on resp.FileName
+		}
+		ref := c.downloadResource(ctx, messageID, fileKey, "file", ext, store, scope)
+		if ref != "" {
+			refs = append(refs, ref)
+		}
+	}
+
+	return refs
+}
+
+// downloadResource downloads a message resource (image/file) from Feishu,
+// writes it to the project media directory, and stores the reference in MediaStore.
+// fallbackExt (e.g. ".jpg") is appended when the resolved filename has no extension.
+func (c *FeishuChannel) downloadResource(
+	ctx context.Context,
+	messageID, fileKey, resourceType, fallbackExt string,
+	store media.MediaStore,
+	scope string,
+) string {
+	req := larkim.NewGetMessageResourceReqBuilder().
+		MessageId(messageID).
+		FileKey(fileKey).
+		Type(resourceType).
+		Build()
+
+	resp, err := c.client.Im.V1.MessageResource.Get(ctx, req)
+	if err != nil {
+		logger.ErrorCF("feishu", "Failed to download resource", map[string]any{
+			"message_id": messageID,
+			"file_key":   fileKey,
+			"error":      err.Error(),
+		})
+		return ""
+	}
+	if !resp.Success() {
+		c.invalidateTokenOnAuthError(resp.Code)
+		logger.ErrorCF("feishu", "Resource download api error", map[string]any{
+			"code": resp.Code,
+			"msg":  resp.Msg,
+		})
+		return ""
+	}
+
+	if resp.File == nil {
+		return ""
+	}
+	// Safely close the underlying reader if it implements io.Closer (e.g. HTTP response body).
+	if closer, ok := resp.File.(io.Closer); ok {
+		defer closer.Close()
+	}
+
+	filename := resp.FileName
+	if filename == "" {
+		filename = fileKey
+	}
+	// If filename still has no extension, append the fallback (like Telegram's ext parameter).
+	if filepath.Ext(filename) == "" && fallbackExt != "" {
+		filename += fallbackExt
+	}
+
+	// Write to the shared picoclaw_media directory using a unique name to avoid collisions.
+	mediaDir := media.TempDir()
+	if mkdirErr := os.MkdirAll(mediaDir, 0o700); mkdirErr != nil {
+		logger.ErrorCF("feishu", "Failed to create media directory", map[string]any{
+			"error": mkdirErr.Error(),
+		})
+		return ""
+	}
+	ext := filepath.Ext(filename)
+	localPath := filepath.Join(mediaDir, utils.SanitizeFilename(messageID+"-"+fileKey+ext))
+
+	out, err := os.Create(localPath)
+	if err != nil {
+		logger.ErrorCF("feishu", "Failed to create local file for resource", map[string]any{
+			"error": err.Error(),
+		})
+		return ""
+	}
+
+	if _, copyErr := io.Copy(out, resp.File); copyErr != nil {
+		out.Close()
+		os.Remove(localPath)
+		logger.ErrorCF("feishu", "Failed to write resource to file", map[string]any{
+			"error": copyErr.Error(),
+		})
+		return ""
+	}
+	out.Close()
+
+	ref, err := store.Store(localPath, media.MediaMeta{
+		Filename:      filename,
+		Source:        "feishu",
+		CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
+	}, scope)
+	if err != nil {
+		logger.ErrorCF("feishu", "Failed to store downloaded resource", map[string]any{
+			"file_key": fileKey,
+			"error":    err.Error(),
+		})
+		os.Remove(localPath)
+		return ""
+	}
+
+	return ref
+}
+
+// appendMediaTags appends media type tags to content (like Telegram's "[image: photo]").
+// For interactive cards, media tags are not appended because content is raw JSON
+// and appending would produce invalid JSON format.
+func appendMediaTags(content, messageType string, mediaRefs []string) string {
+	if len(mediaRefs) == 0 {
+		return content
+	}
+
+	// Don't append tags to JSON content (interactive cards) - would produce invalid JSON
+	if messageType == larkim.MsgTypeInteractive {
+		return content
+	}
+
+	var tag string
+	switch messageType {
+	case larkim.MsgTypeImage:
+		tag = "[image: photo]"
+	case larkim.MsgTypeAudio:
+		tag = "[audio]"
+	case larkim.MsgTypeMedia:
+		tag = "[video]"
+	case larkim.MsgTypeFile:
+		tag = "[file]"
+	default:
+		tag = "[attachment]"
+	}
+
+	if content == "" {
+		return tag
+	}
+	return content + " " + tag
+}
+
+// sendCard sends an interactive card message to a chat.
+func (c *FeishuChannel) sendCard(ctx context.Context, chatID, cardContent string) error {
+	req := larkim.NewCreateMessageReqBuilder().
+		ReceiveIdType(larkim.ReceiveIdTypeChatId).
+		Body(larkim.NewCreateMessageReqBodyBuilder().
+			ReceiveId(chatID).
+			MsgType(larkim.MsgTypeInteractive).
+			Content(cardContent).
+			Build()).
+		Build()
+
+	resp, err := c.client.Im.V1.Message.Create(ctx, req)
+	if err != nil {
+		return fmt.Errorf("feishu send card: %w", channels.ErrTemporary)
+	}
+
+	if !resp.Success() {
+		c.invalidateTokenOnAuthError(resp.Code)
+		return fmt.Errorf("feishu api error (code=%d msg=%s): %w", resp.Code, resp.Msg, channels.ErrTemporary)
+	}
+
+	logger.DebugCF("feishu", "Feishu card message sent", map[string]any{
+		"chat_id": chatID,
+	})
+
+	return nil
+}
+
+// sendText sends a plain text message to a chat (fallback when card fails).
+func (c *FeishuChannel) sendText(ctx context.Context, chatID, text string) error {
+	content, _ := json.Marshal(map[string]string{"text": text})
+
+	req := larkim.NewCreateMessageReqBuilder().
+		ReceiveIdType(larkim.ReceiveIdTypeChatId).
+		Body(larkim.NewCreateMessageReqBodyBuilder().
+			ReceiveId(chatID).
+			MsgType(larkim.MsgTypeText).
+			Content(string(content)).
+			Build()).
+		Build()
+
+	resp, err := c.client.Im.V1.Message.Create(ctx, req)
+	if err != nil {
+		return fmt.Errorf("feishu send text: %w", channels.ErrTemporary)
+	}
+
+	if !resp.Success() {
+		return fmt.Errorf("feishu text api error (code=%d msg=%s): %w", resp.Code, resp.Msg, channels.ErrTemporary)
+	}
+
+	logger.DebugCF("feishu", "Feishu text message sent (fallback)", map[string]any{
+		"chat_id": chatID,
+	})
+
+	return nil
+}
+
+// sendImage uploads an image and sends it as a message.
+func (c *FeishuChannel) sendImage(ctx context.Context, chatID string, file *os.File) error {
+	// Upload image to get image_key
+	uploadReq := larkim.NewCreateImageReqBuilder().
+		Body(larkim.NewCreateImageReqBodyBuilder().
+			ImageType("message").
+			Image(file).
+			Build()).
+		Build()
+
+	uploadResp, err := c.client.Im.V1.Image.Create(ctx, uploadReq)
+	if err != nil {
+		return fmt.Errorf("feishu image upload: %w", err)
+	}
+	if !uploadResp.Success() {
+		c.invalidateTokenOnAuthError(uploadResp.Code)
+		return fmt.Errorf("feishu image upload api error (code=%d msg=%s)", uploadResp.Code, uploadResp.Msg)
+	}
+	if uploadResp.Data == nil || uploadResp.Data.ImageKey == nil {
+		return fmt.Errorf("feishu image upload: no image_key returned")
+	}
+
+	imageKey := *uploadResp.Data.ImageKey
+
+	// Send image message
+	content, _ := json.Marshal(map[string]string{"image_key": imageKey})
+	req := larkim.NewCreateMessageReqBuilder().
+		ReceiveIdType(larkim.ReceiveIdTypeChatId).
+		Body(larkim.NewCreateMessageReqBodyBuilder().
+			ReceiveId(chatID).
+			MsgType(larkim.MsgTypeImage).
+			Content(string(content)).
+			Build()).
+		Build()
+
+	resp, err := c.client.Im.V1.Message.Create(ctx, req)
+	if err != nil {
+		return fmt.Errorf("feishu image send: %w", err)
+	}
+	if !resp.Success() {
+		c.invalidateTokenOnAuthError(resp.Code)
+		return fmt.Errorf("feishu image send api error (code=%d msg=%s)", resp.Code, resp.Msg)
+	}
+	return nil
+}
+
+// sendFile uploads a file and sends it as a message.
+func (c *FeishuChannel) sendFile(ctx context.Context, chatID string, file *os.File, filename, fileType string) error {
+	// Map part type to Feishu file type
+	feishuFileType := "stream"
+	switch fileType {
+	case "audio":
+		feishuFileType = "opus"
+	case "video":
+		feishuFileType = "mp4"
+	}
+
+	// Upload file to get file_key
+	uploadReq := larkim.NewCreateFileReqBuilder().
+		Body(larkim.NewCreateFileReqBodyBuilder().
+			FileType(feishuFileType).
+			FileName(filename).
+			File(file).
+			Build()).
+		Build()
+
+	uploadResp, err := c.client.Im.V1.File.Create(ctx, uploadReq)
+	if err != nil {
+		return fmt.Errorf("feishu file upload: %w", err)
+	}
+	if !uploadResp.Success() {
+		c.invalidateTokenOnAuthError(uploadResp.Code)
+		return fmt.Errorf("feishu file upload api error (code=%d msg=%s)", uploadResp.Code, uploadResp.Msg)
+	}
+	if uploadResp.Data == nil || uploadResp.Data.FileKey == nil {
+		return fmt.Errorf("feishu file upload: no file_key returned")
+	}
+
+	fileKey := *uploadResp.Data.FileKey
+
+	// Send file message
+	content, _ := json.Marshal(map[string]string{"file_key": fileKey})
+	req := larkim.NewCreateMessageReqBuilder().
+		ReceiveIdType(larkim.ReceiveIdTypeChatId).
+		Body(larkim.NewCreateMessageReqBodyBuilder().
+			ReceiveId(chatID).
+			MsgType(larkim.MsgTypeFile).
+			Content(string(content)).
+			Build()).
+		Build()
+
+	resp, err := c.client.Im.V1.Message.Create(ctx, req)
+	if err != nil {
+		return fmt.Errorf("feishu file send: %w", err)
+	}
+	if !resp.Success() {
+		c.invalidateTokenOnAuthError(resp.Code)
+		return fmt.Errorf("feishu file send api error (code=%d msg=%s)", resp.Code, resp.Msg)
+	}
 	return nil
 }
 
@@ -223,19 +951,13 @@ func extractFeishuSenderID(sender *larkim.EventSender) string {
 	return ""
 }
 
-func extractFeishuMessageContent(message *larkim.EventMessage) string {
-	if message == nil || message.Content == nil || *message.Content == "" {
-		return ""
+// invalidateTokenOnAuthError clears the cached tenant_access_token when the
+// Feishu API reports it as invalid (99991663), so the next request fetches a
+// fresh one. The Lark SDK's built-in retry does not clear the cache, causing
+// all API calls to fail until the token naturally expires (~2 hours).
+func (c *FeishuChannel) invalidateTokenOnAuthError(code int) {
+	if code == errCodeTenantTokenInvalid {
+		c.tokenCache.InvalidateAll()
+		logger.WarnCF("feishu", "Invalidated cached token due to auth error", nil)
 	}
-
-	if message.MessageType != nil && *message.MessageType == larkim.MsgTypeText {
-		var textPayload struct {
-			Text string `json:"text"`
-		}
-		if err := json.Unmarshal([]byte(*message.Content), &textPayload); err == nil {
-			return textPayload.Text
-		}
-	}
-
-	return *message.Content
 }
diff --git a/pkg/channels/feishu/feishu_64_test.go b/pkg/channels/feishu/feishu_64_test.go
new file mode 100644
index 000000000..9010abf69
--- /dev/null
+++ b/pkg/channels/feishu/feishu_64_test.go
@@ -0,0 +1,281 @@
+//go:build amd64 || arm64 || riscv64 || mips64 || ppc64
+
+package feishu
+
+import (
+	"testing"
+
+	larkim "github.com/larksuite/oapi-sdk-go/v3/service/im/v1"
+)
+
+func TestExtractContent(t *testing.T) {
+	tests := []struct {
+		name        string
+		messageType string
+		rawContent  string
+		want        string
+	}{
+		{
+			name:        "text message",
+			messageType: "text",
+			rawContent:  `{"text": "hello world"}`,
+			want:        "hello world",
+		},
+		{
+			name:        "text message invalid JSON",
+			messageType: "text",
+			rawContent:  `not json`,
+			want:        "not json",
+		},
+		{
+			name:        "post message returns raw JSON",
+			messageType: "post",
+			rawContent:  `{"title": "test post"}`,
+			want:        `{"title": "test post"}`,
+		},
+		{
+			name:        "image message returns empty",
+			messageType: "image",
+			rawContent:  `{"image_key": "img_xxx"}`,
+			want:        "",
+		},
+		{
+			name:        "file message with filename",
+			messageType: "file",
+			rawContent:  `{"file_key": "file_xxx", "file_name": "report.pdf"}`,
+			want:        "report.pdf",
+		},
+		{
+			name:        "file message without filename",
+			messageType: "file",
+			rawContent:  `{"file_key": "file_xxx"}`,
+			want:        "",
+		},
+		{
+			name:        "audio message with filename",
+			messageType: "audio",
+			rawContent:  `{"file_key": "file_xxx", "file_name": "recording.ogg"}`,
+			want:        "recording.ogg",
+		},
+		{
+			name:        "media message with filename",
+			messageType: "media",
+			rawContent:  `{"file_key": "file_xxx", "file_name": "video.mp4"}`,
+			want:        "video.mp4",
+		},
+		{
+			name:        "unknown message type returns raw",
+			messageType: "sticker",
+			rawContent:  `{"sticker_id": "sticker_xxx"}`,
+			want:        `{"sticker_id": "sticker_xxx"}`,
+		},
+		{
+			name:        "empty raw content",
+			messageType: "text",
+			rawContent:  "",
+			want:        "",
+		},
+		{
+			name:        "interactive card returns raw JSON",
+			messageType: "interactive",
+			rawContent:  `{"schema":"2.0","body":{"elements":[{"tag":"markdown","content":"Hello from card"}]}}`,
+			want:        `{"schema":"2.0","body":{"elements":[{"tag":"markdown","content":"Hello from card"}]}}`,
+		},
+		{
+			name:        "interactive card with complex structure returns raw JSON",
+			messageType: "interactive",
+			rawContent:  `{"header":{"title":{"tag":"plain_text","content":"Title"}},"elements":[{"tag":"div","text":{"tag":"lark_md","content":"Card content"}}]}`,
+			want:        `{"header":{"title":{"tag":"plain_text","content":"Title"}},"elements":[{"tag":"div","text":{"tag":"lark_md","content":"Card content"}}]}`,
+		},
+		{
+			name:        "interactive card invalid JSON returns as-is",
+			messageType: "interactive",
+			rawContent:  `not valid json`,
+			want:        `not valid json`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := extractContent(tt.messageType, tt.rawContent)
+			if got != tt.want {
+				t.Errorf("extractContent(%q, %q) = %q, want %q", tt.messageType, tt.rawContent, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestAppendMediaTags(t *testing.T) {
+	tests := []struct {
+		name        string
+		content     string
+		messageType string
+		mediaRefs   []string
+		want        string
+	}{
+		{
+			name:        "no refs returns content unchanged",
+			content:     "hello",
+			messageType: "image",
+			mediaRefs:   nil,
+			want:        "hello",
+		},
+		{
+			name:        "empty refs returns content unchanged",
+			content:     "hello",
+			messageType: "image",
+			mediaRefs:   []string{},
+			want:        "hello",
+		},
+		{
+			name:        "image with content",
+			content:     "check this",
+			messageType: "image",
+			mediaRefs:   []string{"ref1"},
+			want:        "check this [image: photo]",
+		},
+		{
+			name:        "image empty content",
+			content:     "",
+			messageType: "image",
+			mediaRefs:   []string{"ref1"},
+			want:        "[image: photo]",
+		},
+		{
+			name:        "audio",
+			content:     "listen",
+			messageType: "audio",
+			mediaRefs:   []string{"ref1"},
+			want:        "listen [audio]",
+		},
+		{
+			name:        "media/video",
+			content:     "watch",
+			messageType: "media",
+			mediaRefs:   []string{"ref1"},
+			want:        "watch [video]",
+		},
+		{
+			name:        "file",
+			content:     "report.pdf",
+			messageType: "file",
+			mediaRefs:   []string{"ref1"},
+			want:        "report.pdf [file]",
+		},
+		{
+			name:        "unknown type",
+			content:     "something",
+			messageType: "sticker",
+			mediaRefs:   []string{"ref1"},
+			want:        "something [attachment]",
+		},
+		{
+			name:        "interactive card with images returns content unchanged",
+			content:     `{"schema":"2.0","body":{"elements":[{"tag":"img","img_key":"img_123"}]}}`,
+			messageType: "interactive",
+			mediaRefs:   []string{"ref1"},
+			want:        `{"schema":"2.0","body":{"elements":[{"tag":"img","img_key":"img_123"}]}}`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := appendMediaTags(tt.content, tt.messageType, tt.mediaRefs)
+			if got != tt.want {
+				t.Errorf(
+					"appendMediaTags(%q, %q, %v) = %q, want %q",
+					tt.content,
+					tt.messageType,
+					tt.mediaRefs,
+					got,
+					tt.want,
+				)
+			}
+		})
+	}
+}
+
+func TestExtractFeishuSenderID(t *testing.T) {
+	strPtr := func(s string) *string { return &s }
+
+	tests := []struct {
+		name   string
+		sender *larkim.EventSender
+		want   string
+	}{
+		{
+			name:   "nil sender",
+			sender: nil,
+			want:   "",
+		},
+		{
+			name:   "nil sender ID",
+			sender: &larkim.EventSender{SenderId: nil},
+			want:   "",
+		},
+		{
+			name: "userId preferred",
+			sender: &larkim.EventSender{
+				SenderId: &larkim.UserId{
+					UserId:  strPtr("u_abc123"),
+					OpenId:  strPtr("ou_def456"),
+					UnionId: strPtr("on_ghi789"),
+				},
+			},
+			want: "u_abc123",
+		},
+		{
+			name: "openId fallback",
+			sender: &larkim.EventSender{
+				SenderId: &larkim.UserId{
+					UserId:  strPtr(""),
+					OpenId:  strPtr("ou_def456"),
+					UnionId: strPtr("on_ghi789"),
+				},
+			},
+			want: "ou_def456",
+		},
+		{
+			name: "unionId fallback",
+			sender: &larkim.EventSender{
+				SenderId: &larkim.UserId{
+					UserId:  strPtr(""),
+					OpenId:  strPtr(""),
+					UnionId: strPtr("on_ghi789"),
+				},
+			},
+			want: "on_ghi789",
+		},
+		{
+			name: "all empty strings",
+			sender: &larkim.EventSender{
+				SenderId: &larkim.UserId{
+					UserId:  strPtr(""),
+					OpenId:  strPtr(""),
+					UnionId: strPtr(""),
+				},
+			},
+			want: "",
+		},
+		{
+			name: "nil userId pointer falls through",
+			sender: &larkim.EventSender{
+				SenderId: &larkim.UserId{
+					UserId:  nil,
+					OpenId:  strPtr("ou_def456"),
+					UnionId: nil,
+				},
+			},
+			want: "ou_def456",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := extractFeishuSenderID(tt.sender)
+			if got != tt.want {
+				t.Errorf("extractFeishuSenderID() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
diff --git a/pkg/channels/feishu/token_cache.go b/pkg/channels/feishu/token_cache.go
new file mode 100644
index 000000000..00acbc084
--- /dev/null
+++ b/pkg/channels/feishu/token_cache.go
@@ -0,0 +1,52 @@
+package feishu
+
+import (
+	"context"
+	"sync"
+	"time"
+)
+
+// tokenCache implements larkcore.Cache with an extra InvalidateAll method.
+// This works around a bug in the Lark SDK v3 where the built-in token retry
+// loop does not clear stale tokens from cache on auth errors.
+type tokenCache struct {
+	mu    sync.RWMutex
+	store map[string]*tokenEntry
+}
+
+type tokenEntry struct {
+	value    string
+	expireAt time.Time
+}
+
+func newTokenCache() *tokenCache {
+	return &tokenCache{store: make(map[string]*tokenEntry)}
+}
+
+func (c *tokenCache) Set(_ context.Context, key, value string, ttl time.Duration) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.store[key] = &tokenEntry{value: value, expireAt: time.Now().Add(ttl)}
+	return nil
+}
+
+func (c *tokenCache) Get(_ context.Context, key string) (string, error) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	e, ok := c.store[key]
+	if !ok {
+		return "", nil
+	}
+	if e.expireAt.Before(time.Now()) {
+		delete(c.store, key)
+		return "", nil
+	}
+	return e.value, nil
+}
+
+// InvalidateAll removes all cached tokens, forcing fresh acquisition.
+func (c *tokenCache) InvalidateAll() {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	clear(c.store)
+}
diff --git a/pkg/channels/interfaces.go b/pkg/channels/interfaces.go
index 74caeeac5..0cfd435b0 100644
--- a/pkg/channels/interfaces.go
+++ b/pkg/channels/interfaces.go
@@ -1,6 +1,11 @@
 package channels
 
-import "context"
+import (
+	"context"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/commands"
+)
 
 // TypingCapable — channels that can show a typing/thinking indicator.
 // StartTyping begins the indicator and returns a stop function.
@@ -15,6 +20,11 @@ type MessageEditor interface {
 	EditMessage(ctx context.Context, chatID string, messageID string, content string) error
 }
 
+// MessageDeleter — channels that can delete a message by ID.
+type MessageDeleter interface {
+	DeleteMessage(ctx context.Context, chatID string, messageID string) error
+}
+
 // ReactionCapable — channels that can add a reaction (e.g. 👀) to an inbound message.
 // ReactToMessage adds a reaction and returns an undo function to remove it.
 // The undo function MUST be idempotent and safe to call multiple times.
@@ -31,6 +41,18 @@ type PlaceholderCapable interface {
 	SendPlaceholder(ctx context.Context, chatID string) (messageID string, err error)
 }
 
+// StreamingCapable — channels that can show partial LLM output in real-time.
+// The channel SHOULD gracefully degrade if the platform rejects streaming
+// (e.g. Telegram bot without forum mode). In that case, Update becomes a no-op
+// and Finalize still delivers the final message.
+type StreamingCapable interface {
+	BeginStream(ctx context.Context, chatID string) (Streamer, error)
+}
+
+// Streamer is defined in pkg/bus to avoid circular imports.
+// This alias keeps channel implementations using channels.Streamer unchanged.
+type Streamer = bus.Streamer
+
 // PlaceholderRecorder is injected into channels by Manager.
 // Channels call these methods on inbound to register typing/placeholder state.
 // Manager uses the registered state on outbound to stop typing and edit placeholders.
@@ -39,3 +61,10 @@ type PlaceholderRecorder interface {
 	RecordTypingStop(channel, chatID string, stop func())
 	RecordReactionUndo(channel, chatID string, undo func())
 }
+
+// CommandRegistrarCapable is implemented by channels that can register
+// command menus with their upstream platform (e.g. Telegram BotCommand).
+// Channels that do not support platform-level command menus can ignore it.
+type CommandRegistrarCapable interface {
+	RegisterCommands(ctx context.Context, defs []commands.Definition) error
+}
diff --git a/pkg/channels/interfaces_command_test.go b/pkg/channels/interfaces_command_test.go
new file mode 100644
index 000000000..de5502644
--- /dev/null
+++ b/pkg/channels/interfaces_command_test.go
@@ -0,0 +1,16 @@
+package channels
+
+import (
+	"context"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/commands"
+)
+
+type mockRegistrar struct{}
+
+func (mockRegistrar) RegisterCommands(context.Context, []commands.Definition) error { return nil }
+
+func TestCommandRegistrarCapable_Compiles(t *testing.T) {
+	var _ CommandRegistrarCapable = mockRegistrar{}
+}
diff --git a/pkg/channels/irc/handler.go b/pkg/channels/irc/handler.go
new file mode 100644
index 000000000..3fe9548f4
--- /dev/null
+++ b/pkg/channels/irc/handler.go
@@ -0,0 +1,154 @@
+package irc
+
+import (
+	"fmt"
+	"strings"
+	"time"
+	"unicode"
+
+	"github.com/ergochat/irc-go/ircevent"
+	"github.com/ergochat/irc-go/ircmsg"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/identity"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// onConnect is called after a successful connection (and on reconnect).
+func (c *IRCChannel) onConnect(conn *ircevent.Connection) {
+	// NickServ auth (only if SASL is not configured)
+	if c.config.NickServPassword() != "" && c.config.SASLUser == "" {
+		conn.Privmsg("NickServ", "IDENTIFY "+c.config.NickServPassword())
+	}
+
+	// Join configured channels
+	for _, ch := range c.config.Channels {
+		conn.Join(ch)
+		logger.InfoCF("irc", "Joined IRC channel", map[string]any{
+			"channel": ch,
+		})
+	}
+}
+
+// onPrivmsg handles incoming PRIVMSG events.
+func (c *IRCChannel) onPrivmsg(conn *ircevent.Connection, e ircmsg.Message) {
+	if len(e.Params) < 2 {
+		return
+	}
+
+	nick := e.Nick()
+	currentNick := conn.CurrentNick()
+
+	// Ignore own messages
+	if strings.EqualFold(nick, currentNick) {
+		return
+	}
+
+	target := e.Params[0]  // channel name or bot's nick
+	content := e.Params[1] // message text
+
+	// Determine if this is a DM or channel message
+	isDM := !strings.HasPrefix(target, "#") && !strings.HasPrefix(target, "&")
+
+	var chatID string
+	var peer bus.Peer
+
+	if isDM {
+		chatID = nick
+		peer = bus.Peer{Kind: "direct", ID: nick}
+	} else {
+		chatID = target
+		peer = bus.Peer{Kind: "group", ID: target}
+	}
+
+	sender := bus.SenderInfo{
+		Platform:    "irc",
+		PlatformID:  nick,
+		CanonicalID: identity.BuildCanonicalID("irc", nick),
+		Username:    nick,
+		DisplayName: nick,
+	}
+
+	if !c.IsAllowedSender(sender) {
+		return
+	}
+
+	// For channel messages, check group trigger (mention detection)
+	if !isDM {
+		isMentioned := isBotMentioned(content, currentNick)
+		if isMentioned {
+			content = stripBotMention(content, currentNick)
+		}
+		respond, cleaned := c.ShouldRespondInGroup(isMentioned, content)
+		if !respond {
+			return
+		}
+		content = cleaned
+	}
+
+	if strings.TrimSpace(content) == "" {
+		return
+	}
+
+	messageID := fmt.Sprintf("%s-%d", nick, time.Now().UnixNano())
+
+	metadata := map[string]string{
+		"platform": "irc",
+		"server":   c.config.Server,
+	}
+	if !isDM {
+		metadata["channel"] = target
+	}
+
+	c.HandleMessage(c.ctx, peer, messageID, nick, chatID, content, nil, metadata, sender)
+}
+
+// nickMentionedAt returns the byte index where botNick is mentioned in content
+// with word-boundary checks, or -1 if not found. Also checks for "nick:" /
+// "nick," prefix convention.
+func nickMentionedAt(content, botNick string) int {
+	lower := strings.ToLower(content)
+	lowerNick := strings.ToLower(botNick)
+
+	// "nick:" or "nick," at start (most common IRC convention)
+	if strings.HasPrefix(lower, lowerNick+":") || strings.HasPrefix(lower, lowerNick+",") {
+		return 0
+	}
+
+	// Word-boundary match anywhere in the message
+	idx := strings.Index(lower, lowerNick)
+	if idx < 0 {
+		return -1
+	}
+	runes := []rune(lower)
+	nickRunes := []rune(lowerNick)
+	endIdx := idx + len(string(nickRunes))
+	before := idx == 0 || !unicode.IsLetter(runes[idx-1]) && !unicode.IsDigit(runes[idx-1])
+	after := endIdx >= len(lower) || !unicode.IsLetter(rune(lower[endIdx])) && !unicode.IsDigit(rune(lower[endIdx]))
+	if before && after {
+		return idx
+	}
+	return -1
+}
+
+// isBotMentioned checks if the bot's nick appears in the message.
+func isBotMentioned(content, botNick string) bool {
+	return nickMentionedAt(content, botNick) >= 0
+}
+
+// stripBotMention removes "nick: " or "nick, " prefix from content.
+func stripBotMention(content, botNick string) string {
+	idx := nickMentionedAt(content, botNick)
+	if idx != 0 {
+		return content
+	}
+	lowerNick := strings.ToLower(botNick)
+	lower := strings.ToLower(content)
+	for _, sep := range []string{":", ","} {
+		prefix := lowerNick + sep
+		if strings.HasPrefix(lower, prefix) {
+			return strings.TrimSpace(content[len(prefix):])
+		}
+	}
+	return content
+}
diff --git a/pkg/channels/irc/init.go b/pkg/channels/irc/init.go
new file mode 100644
index 000000000..221d41b62
--- /dev/null
+++ b/pkg/channels/irc/init.go
@@ -0,0 +1,16 @@
+package irc
+
+import (
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("irc", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		if !cfg.Channels.IRC.Enabled {
+			return nil, nil
+		}
+		return NewIRCChannel(cfg.Channels.IRC, b)
+	})
+}
diff --git a/pkg/channels/irc/irc.go b/pkg/channels/irc/irc.go
new file mode 100644
index 000000000..289ce2c9b
--- /dev/null
+++ b/pkg/channels/irc/irc.go
@@ -0,0 +1,194 @@
+package irc
+
+import (
+	"context"
+	"crypto/tls"
+	"fmt"
+	"strings"
+
+	"github.com/ergochat/irc-go/ircevent"
+	"github.com/ergochat/irc-go/ircmsg"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// IRCChannel implements the Channel interface for IRC servers.
+type IRCChannel struct {
+	*channels.BaseChannel
+	config config.IRCConfig
+	conn   *ircevent.Connection
+	ctx    context.Context
+	cancel context.CancelFunc
+}
+
+// NewIRCChannel creates a new IRC channel.
+func NewIRCChannel(cfg config.IRCConfig, messageBus *bus.MessageBus) (*IRCChannel, error) {
+	if cfg.Server == "" {
+		return nil, fmt.Errorf("irc server is required")
+	}
+	if cfg.Nick == "" {
+		return nil, fmt.Errorf("irc nick is required")
+	}
+
+	base := channels.NewBaseChannel("irc", cfg, messageBus, cfg.AllowFrom,
+		channels.WithMaxMessageLength(400),
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
+
+	return &IRCChannel{
+		BaseChannel: base,
+		config:      cfg,
+	}, nil
+}
+
+// Start connects to the IRC server and begins listening.
+func (c *IRCChannel) Start(ctx context.Context) error {
+	logger.InfoC("irc", "Starting IRC channel")
+	c.ctx, c.cancel = context.WithCancel(ctx)
+
+	user := c.config.User
+	if user == "" {
+		user = c.config.Nick
+	}
+	realName := c.config.RealName
+	if realName == "" {
+		realName = c.config.Nick
+	}
+	caps := []string(c.config.RequestCaps)
+	if len(caps) == 0 {
+		caps = []string{"server-time", "message-tags"}
+	}
+
+	conn := &ircevent.Connection{
+		Server:      c.config.Server,
+		Nick:        c.config.Nick,
+		User:        user,
+		RealName:    realName,
+		Password:    c.config.Password(),
+		UseTLS:      c.config.TLS,
+		RequestCaps: caps,
+		QuitMessage: "Goodbye",
+		Debug:       false,
+		Log:         nil,
+	}
+
+	if c.config.TLS {
+		conn.TLSConfig = &tls.Config{
+			ServerName: extractHost(c.config.Server),
+		}
+	}
+
+	// SASL auth (takes priority over NickServ)
+	if c.config.SASLUser != "" && c.config.SASLPassword() != "" {
+		conn.SASLLogin = c.config.SASLUser
+		conn.SASLPassword = c.config.SASLPassword()
+	}
+
+	// Register event handlers
+	conn.AddConnectCallback(func(e ircmsg.Message) {
+		c.onConnect(conn)
+	})
+	conn.AddCallback("PRIVMSG", func(e ircmsg.Message) {
+		c.onPrivmsg(conn, e)
+	})
+
+	if err := conn.Connect(); err != nil {
+		return fmt.Errorf("irc connect failed: %w", err)
+	}
+
+	c.conn = conn
+
+	// ircevent.Connection.Loop() handles reconnection internally.
+	go conn.Loop()
+
+	c.SetRunning(true)
+	logger.InfoCF("irc", "IRC channel started", map[string]any{
+		"server": c.config.Server,
+		"nick":   c.config.Nick,
+	})
+	return nil
+}
+
+// Stop disconnects from the IRC server.
+func (c *IRCChannel) Stop(ctx context.Context) error {
+	logger.InfoC("irc", "Stopping IRC channel")
+	c.SetRunning(false)
+
+	if c.conn != nil {
+		c.conn.Quit()
+	}
+	if c.cancel != nil {
+		c.cancel()
+	}
+
+	logger.InfoC("irc", "IRC channel stopped")
+	return nil
+}
+
+// Send sends a message to an IRC channel or user.
+func (c *IRCChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	target := msg.ChatID
+	if target == "" {
+		return fmt.Errorf("chat ID is empty: %w", channels.ErrSendFailed)
+	}
+
+	if strings.TrimSpace(msg.Content) == "" {
+		return nil
+	}
+
+	// Send each line separately (IRC is line-oriented)
+	lines := strings.Split(msg.Content, "\n")
+	for _, line := range lines {
+		line = strings.TrimRight(line, "\r")
+		if line == "" {
+			continue
+		}
+		c.conn.Privmsg(target, line)
+	}
+
+	logger.DebugCF("irc", "Message sent", map[string]any{
+		"target": target,
+		"lines":  len(lines),
+	})
+	return nil
+}
+
+// StartTyping implements channels.TypingCapable using IRCv3 +typing client tag.
+// Requires typing.enabled in config and server support for message-tags capability.
+func (c *IRCChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+	noop := func() {}
+
+	if !c.config.Typing.Enabled || !c.IsRunning() || c.conn == nil {
+		return noop, nil
+	}
+
+	// Check if server supports message-tags (required for TAGMSG)
+	if _, ok := c.conn.AcknowledgedCaps()["message-tags"]; !ok {
+		return noop, nil
+	}
+
+	c.conn.SendWithTags(map[string]string{"+typing": "active"}, "TAGMSG", chatID)
+
+	return func() {
+		if c.IsRunning() && c.conn != nil {
+			c.conn.SendWithTags(map[string]string{"+typing": "done"}, "TAGMSG", chatID)
+		}
+	}, nil
+}
+
+// extractHost returns the hostname portion of a host:port string.
+func extractHost(server string) string {
+	host, _, found := strings.Cut(server, ":")
+	if found {
+		return host
+	}
+	return server
+}
diff --git a/pkg/channels/irc/irc_test.go b/pkg/channels/irc/irc_test.go
new file mode 100644
index 000000000..168252a4d
--- /dev/null
+++ b/pkg/channels/irc/irc_test.go
@@ -0,0 +1,145 @@
+package irc
+
+import (
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestNewIRCChannel(t *testing.T) {
+	msgBus := bus.NewMessageBus()
+
+	t.Run("missing server", func(t *testing.T) {
+		cfg := config.IRCConfig{Nick: "bot"}
+		_, err := NewIRCChannel(cfg, msgBus)
+		if err == nil {
+			t.Error("expected error for missing server, got nil")
+		}
+	})
+
+	t.Run("missing nick", func(t *testing.T) {
+		cfg := config.IRCConfig{Server: "irc.example.com:6667"}
+		_, err := NewIRCChannel(cfg, msgBus)
+		if err == nil {
+			t.Error("expected error for missing nick, got nil")
+		}
+	})
+
+	t.Run("valid config", func(t *testing.T) {
+		cfg := config.IRCConfig{
+			Server:   "irc.example.com:6667",
+			Nick:     "testbot",
+			Channels: []string{"#test"},
+		}
+		ch, err := NewIRCChannel(cfg, msgBus)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if ch.Name() != "irc" {
+			t.Errorf("Name() = %q, want %q", ch.Name(), "irc")
+		}
+		if ch.IsRunning() {
+			t.Error("new channel should not be running")
+		}
+	})
+}
+
+func TestExtractHost(t *testing.T) {
+	tests := []struct {
+		server string
+		want   string
+	}{
+		{"irc.libera.chat:6697", "irc.libera.chat"},
+		{"localhost:6667", "localhost"},
+		{"irc.example.com", "irc.example.com"},
+		{"", ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.server, func(t *testing.T) {
+			got := extractHost(tt.server)
+			if got != tt.want {
+				t.Errorf("extractHost(%q) = %q, want %q", tt.server, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestNickMentionedAt(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		nick    string
+		want    int
+	}{
+		{"colon prefix", "bot: hello", "bot", 0},
+		{"comma prefix", "bot, hello", "bot", 0},
+		{"case insensitive", "BOT: hello", "bot", 0},
+		{"word boundary mid", "hey bot what's up", "bot", 4},
+		{"no mention", "hello world", "bot", -1},
+		{"substring mismatch", "robotics are cool", "bot", -1},
+		{"nick at end", "hello bot", "bot", 6},
+		{"empty content", "", "bot", -1},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := nickMentionedAt(tt.content, tt.nick)
+			if got != tt.want {
+				t.Errorf("nickMentionedAt(%q, %q) = %d, want %d", tt.content, tt.nick, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsBotMentioned(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		nick    string
+		want    bool
+	}{
+		{"colon prefix", "bot: hello", "bot", true},
+		{"comma prefix", "bot, hello", "bot", true},
+		{"case insensitive", "BOT: hello", "bot", true},
+		{"word boundary mid", "hey bot what's up", "bot", true},
+		{"no mention", "hello world", "bot", false},
+		{"substring mismatch", "robotics are cool", "bot", false},
+		{"nick at end", "hello bot", "bot", true},
+		{"empty content", "", "bot", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isBotMentioned(tt.content, tt.nick)
+			if got != tt.want {
+				t.Errorf("isBotMentioned(%q, %q) = %v, want %v", tt.content, tt.nick, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestStripBotMention(t *testing.T) {
+	tests := []struct {
+		name    string
+		content string
+		nick    string
+		want    string
+	}{
+		{"colon prefix", "bot: hello there", "bot", "hello there"},
+		{"comma prefix", "bot, help me", "bot", "help me"},
+		{"case insensitive", "BOT: hello", "bot", "hello"},
+		{"no prefix match", "hello bot", "bot", "hello bot"},
+		{"only prefix", "bot:", "bot", ""},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := stripBotMention(tt.content, tt.nick)
+			if got != tt.want {
+				t.Errorf("stripBotMention(%q, %q) = %q, want %q", tt.content, tt.nick, got, tt.want)
+			}
+		})
+	}
+}
diff --git a/pkg/channels/line/line.go b/pkg/channels/line/line.go
index 398f12e6b..4eaadae70 100644
--- a/pkg/channels/line/line.go
+++ b/pkg/channels/line/line.go
@@ -32,6 +32,10 @@ const (
 	lineBotInfoEndpoint  = lineAPIBase + "/info"
 	lineLoadingEndpoint  = lineAPIBase + "/chat/loading/start"
 	lineReplyTokenMaxAge = 25 * time.Second
+
+	// Limit request body to prevent memory exhaustion (DoS).
+	// LINE webhook payloads are typically a few KB; 1 MiB is generous.
+	maxWebhookBodySize = 1 << 20 // 1 MiB
 )
 
 type replyTokenEntry struct {
@@ -58,7 +62,7 @@ type LINEChannel struct {
 
 // NewLINEChannel creates a new LINE channel instance.
 func NewLINEChannel(cfg config.LINEConfig, messageBus *bus.MessageBus) (*LINEChannel, error) {
-	if cfg.ChannelSecret == "" || cfg.ChannelAccessToken == "" {
+	if cfg.ChannelSecret() == "" || cfg.ChannelAccessToken() == "" {
 		return nil, fmt.Errorf("line channel_secret and channel_access_token are required")
 	}
 
@@ -106,7 +110,7 @@ func (c *LINEChannel) fetchBotInfo() error {
 	if err != nil {
 		return err
 	}
-	req.Header.Set("Authorization", "Bearer "+c.config.ChannelAccessToken)
+	req.Header.Set("Authorization", "Bearer "+c.config.ChannelAccessToken())
 
 	resp, err := c.infoClient.Do(req)
 	if err != nil {
@@ -166,7 +170,7 @@ func (c *LINEChannel) webhookHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	body, err := io.ReadAll(r.Body)
+	body, err := io.ReadAll(io.LimitReader(r.Body, maxWebhookBodySize+1))
 	if err != nil {
 		logger.ErrorCF("line", "Failed to read request body", map[string]any{
 			"error": err.Error(),
@@ -174,6 +178,11 @@ func (c *LINEChannel) webhookHandler(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "Bad request", http.StatusBadRequest)
 		return
 	}
+	if int64(len(body)) > maxWebhookBodySize {
+		logger.WarnC("line", "Webhook request body too large, rejected")
+		http.Error(w, "Request entity too large", http.StatusRequestEntityTooLarge)
+		return
+	}
 
 	signature := r.Header.Get("X-Line-Signature")
 	if !c.verifySignature(body, signature) {
@@ -207,7 +216,7 @@ func (c *LINEChannel) verifySignature(body []byte, signature string) bool {
 		return false
 	}
 
-	mac := hmac.New(sha256.New, []byte(c.config.ChannelSecret))
+	mac := hmac.New(sha256.New, []byte(c.config.ChannelSecret()))
 	mac.Write(body)
 	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
 
@@ -292,8 +301,9 @@ func (c *LINEChannel) processEvent(event lineEvent) {
 	storeMedia := func(localPath, filename string) string {
 		if store := c.GetMediaStore(); store != nil {
 			ref, err := store.Store(localPath, media.MediaMeta{
-				Filename: filename,
-				Source:   "line",
+				Filename:      filename,
+				Source:        "line",
+				CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
 			}, scope)
 			if err == nil {
 				return ref
@@ -645,7 +655,7 @@ func (c *LINEChannel) callAPI(ctx context.Context, endpoint string, payload any)
 	}
 
 	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("Authorization", "Bearer "+c.config.ChannelAccessToken)
+	req.Header.Set("Authorization", "Bearer "+c.config.ChannelAccessToken())
 
 	resp, err := c.apiClient.Do(req)
 	if err != nil {
@@ -654,7 +664,10 @@ func (c *LINEChannel) callAPI(ctx context.Context, endpoint string, payload any)
 	defer resp.Body.Close()
 
 	if resp.StatusCode != http.StatusOK {
-		respBody, _ := io.ReadAll(resp.Body)
+		respBody, err := io.ReadAll(resp.Body)
+		if err != nil {
+			return channels.ClassifySendError(resp.StatusCode, fmt.Errorf("reading LINE API error response: %w", err))
+		}
 		return channels.ClassifySendError(resp.StatusCode, fmt.Errorf("LINE API error: %s", string(respBody)))
 	}
 
@@ -667,7 +680,7 @@ func (c *LINEChannel) downloadContent(messageID, filename string) string {
 	return utils.DownloadFile(url, filename, utils.DownloadOptions{
 		LoggerPrefix: "line",
 		ExtraHeaders: map[string]string{
-			"Authorization": "Bearer " + c.config.ChannelAccessToken,
+			"Authorization": "Bearer " + c.config.ChannelAccessToken(),
 		},
 	})
 }
diff --git a/pkg/channels/line/line_test.go b/pkg/channels/line/line_test.go
new file mode 100644
index 000000000..00770f1c7
--- /dev/null
+++ b/pkg/channels/line/line_test.go
@@ -0,0 +1,81 @@
+package line
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+func TestWebhookRejectsOversizedBody(t *testing.T) {
+	ch := &LINEChannel{}
+
+	oversized := bytes.Repeat([]byte("A"), maxWebhookBodySize+1)
+	req := httptest.NewRequest(http.MethodPost, "/webhook", bytes.NewReader(oversized))
+	rec := httptest.NewRecorder()
+
+	ch.webhookHandler(rec, req)
+
+	if rec.Code != http.StatusRequestEntityTooLarge {
+		t.Errorf("expected status %d, got %d", http.StatusRequestEntityTooLarge, rec.Code)
+	}
+}
+
+func TestWebhookAcceptsMaxBodySize(t *testing.T) {
+	ch := &LINEChannel{}
+
+	body := bytes.Repeat([]byte("A"), maxWebhookBodySize)
+	req := httptest.NewRequest(http.MethodPost, "/webhook", bytes.NewReader(body))
+	rec := httptest.NewRecorder()
+
+	ch.webhookHandler(rec, req)
+
+	// Missing signature should be rejected, but the body size should not trigger 413.
+	if rec.Code != http.StatusForbidden {
+		t.Errorf("expected status %d, got %d", http.StatusForbidden, rec.Code)
+	}
+}
+
+func TestWebhookRejectsOversizedBodyBeforeSignatureCheck(t *testing.T) {
+	ch := &LINEChannel{}
+
+	oversized := bytes.Repeat([]byte("A"), maxWebhookBodySize+1)
+	req := httptest.NewRequest(http.MethodPost, "/webhook", bytes.NewReader(oversized))
+	req.Header.Set("X-Line-Signature", "invalidsignature")
+	rec := httptest.NewRecorder()
+
+	ch.webhookHandler(rec, req)
+
+	if rec.Code != http.StatusRequestEntityTooLarge {
+		t.Errorf("expected status %d, got %d", http.StatusRequestEntityTooLarge, rec.Code)
+	}
+}
+
+func TestWebhookRejectsNonPostMethod(t *testing.T) {
+	ch := &LINEChannel{}
+
+	req := httptest.NewRequest(http.MethodGet, "/webhook", nil)
+	rec := httptest.NewRecorder()
+
+	ch.webhookHandler(rec, req)
+
+	if rec.Code != http.StatusMethodNotAllowed {
+		t.Errorf("expected status %d, got %d", http.StatusMethodNotAllowed, rec.Code)
+	}
+}
+
+func TestWebhookRejectsInvalidSignature(t *testing.T) {
+	ch := &LINEChannel{}
+
+	body := `{"events":[]}`
+	req := httptest.NewRequest(http.MethodPost, "/webhook", strings.NewReader(body))
+	req.Header.Set("X-Line-Signature", "invalidsignature")
+	rec := httptest.NewRecorder()
+
+	ch.webhookHandler(rec, req)
+
+	if rec.Code != http.StatusForbidden {
+		t.Errorf("expected status %d, got %d", http.StatusForbidden, rec.Code)
+	}
+}
diff --git a/pkg/channels/manager.go b/pkg/channels/manager.go
index 155e50b39..c8269dc77 100644
--- a/pkg/channels/manager.go
+++ b/pkg/channels/manager.go
@@ -61,7 +61,10 @@ var channelRateConfig = map[string]float64{
 	"telegram": 20,
 	"discord":  1,
 	"slack":    1,
+	"matrix":   2,
 	"line":     10,
+	"qq":       5,
+	"irc":      2,
 }
 
 type channelWorker struct {
@@ -83,9 +86,11 @@ type Manager struct {
 	mux           *http.ServeMux
 	httpServer    *http.Server
 	mu            sync.RWMutex
-	placeholders  sync.Map // "channel:chatID" → placeholderID (string)
-	typingStops   sync.Map // "channel:chatID" → func()
-	reactionUndos sync.Map // "channel:chatID" → reactionEntry
+	placeholders  sync.Map          // "channel:chatID" → placeholderID (string)
+	typingStops   sync.Map          // "channel:chatID" → func()
+	reactionUndos sync.Map          // "channel:chatID" → reactionEntry
+	streamActive  sync.Map          // "channel:chatID" → true (set when streamer.Finalize sent the message)
+	channelHashes map[string]string // channel name → config hash
 }
 
 type asyncTask struct {
@@ -99,11 +104,50 @@ func (m *Manager) RecordPlaceholder(channel, chatID, placeholderID string) {
 	m.placeholders.Store(key, placeholderEntry{id: placeholderID, createdAt: time.Now()})
 }
 
+// SendPlaceholder sends a "Thinking…" placeholder for the given channel/chatID
+// and records it for later editing. Returns true if a placeholder was sent.
+func (m *Manager) SendPlaceholder(ctx context.Context, channel, chatID string) bool {
+	m.mu.RLock()
+	ch, ok := m.channels[channel]
+	m.mu.RUnlock()
+	if !ok {
+		return false
+	}
+	pc, ok := ch.(PlaceholderCapable)
+	if !ok {
+		return false
+	}
+	phID, err := pc.SendPlaceholder(ctx, chatID)
+	if err != nil || phID == "" {
+		return false
+	}
+	m.RecordPlaceholder(channel, chatID, phID)
+	return true
+}
+
 // RecordTypingStop registers a typing stop function for later invocation.
 // Implements PlaceholderRecorder.
 func (m *Manager) RecordTypingStop(channel, chatID string, stop func()) {
 	key := channel + ":" + chatID
-	m.typingStops.Store(key, typingEntry{stop: stop, createdAt: time.Now()})
+	entry := typingEntry{stop: stop, createdAt: time.Now()}
+	if previous, loaded := m.typingStops.Swap(key, entry); loaded {
+		if oldEntry, ok := previous.(typingEntry); ok && oldEntry.stop != nil {
+			oldEntry.stop()
+		}
+	}
+}
+
+// InvokeTypingStop invokes the registered typing stop function for the given channel and chatID.
+// It is safe to call even when no typing indicator is active (no-op).
+// Used by the agent loop to stop typing when processing completes (success, error, or panic),
+// regardless of whether an outbound message is published.
+func (m *Manager) InvokeTypingStop(channel, chatID string) {
+	key := channel + ":" + chatID
+	if v, loaded := m.typingStops.LoadAndDelete(key); loaded {
+		if entry, ok := v.(typingEntry); ok {
+			entry.stop()
+		}
+	}
 }
 
 // RecordReactionUndo registers a reaction undo function for later invocation.
@@ -114,7 +158,7 @@ func (m *Manager) RecordReactionUndo(channel, chatID string, undo func()) {
 }
 
 // preSend handles typing stop, reaction undo, and placeholder editing before sending a message.
-// Returns true if the message was edited into a placeholder (skip Send).
+// Returns true if the message was already delivered (skip Send).
 func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMessage, ch Channel) bool {
 	key := name + ":" + msg.ChatID
 
@@ -132,7 +176,22 @@ func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMess
 		}
 	}
 
-	// 3. Try editing placeholder
+	// 3. If a stream already finalized this message, delete the placeholder and skip send
+	if _, loaded := m.streamActive.LoadAndDelete(key); loaded {
+		if v, loaded := m.placeholders.LoadAndDelete(key); loaded {
+			if entry, ok := v.(placeholderEntry); ok && entry.id != "" {
+				// Prefer deleting the placeholder (cleaner UX than editing to same content)
+				if deleter, ok := ch.(MessageDeleter); ok {
+					deleter.DeleteMessage(ctx, msg.ChatID, entry.id) // best effort
+				} else if editor, ok := ch.(MessageEditor); ok {
+					editor.EditMessage(ctx, msg.ChatID, entry.id, msg.Content) // fallback
+				}
+			}
+		}
+		return true
+	}
+
+	// 4. Try editing placeholder
 	if v, loaded := m.placeholders.LoadAndDelete(key); loaded {
 		if entry, ok := v.(placeholderEntry); ok && entry.id != "" {
 			if editor, ok := ch.(MessageEditor); ok {
@@ -147,22 +206,110 @@ func (m *Manager) preSend(ctx context.Context, name string, msg bus.OutboundMess
 	return false
 }
 
-func NewManager(cfg *config.Config, messageBus *bus.MessageBus, store media.MediaStore) (*Manager, error) {
-	m := &Manager{
-		channels:   make(map[string]Channel),
-		workers:    make(map[string]*channelWorker),
-		bus:        messageBus,
-		config:     cfg,
-		mediaStore: store,
+// preSendMedia handles typing stop, reaction undo, and placeholder cleanup
+// before sending media attachments. Unlike preSend for text messages, media
+// delivery never edits the placeholder because there is no text payload to
+// replace it with; it only attempts to delete the placeholder when possible.
+func (m *Manager) preSendMedia(ctx context.Context, name string, msg bus.OutboundMediaMessage, ch Channel) {
+	key := name + ":" + msg.ChatID
+
+	// 1. Stop typing
+	if v, loaded := m.typingStops.LoadAndDelete(key); loaded {
+		if entry, ok := v.(typingEntry); ok {
+			entry.stop() // idempotent, safe
+		}
 	}
 
-	if err := m.initChannels(); err != nil {
+	// 2. Undo reaction
+	if v, loaded := m.reactionUndos.LoadAndDelete(key); loaded {
+		if entry, ok := v.(reactionEntry); ok {
+			entry.undo() // idempotent, safe
+		}
+	}
+
+	// 3. Clear any finalized stream marker for this chat before media delivery.
+	m.streamActive.LoadAndDelete(key)
+
+	// 4. Delete placeholder if present.
+	if v, loaded := m.placeholders.LoadAndDelete(key); loaded {
+		if entry, ok := v.(placeholderEntry); ok && entry.id != "" {
+			if deleter, ok := ch.(MessageDeleter); ok {
+				deleter.DeleteMessage(ctx, msg.ChatID, entry.id) // best effort
+			}
+		}
+	}
+}
+
+func NewManager(cfg *config.Config, messageBus *bus.MessageBus, store media.MediaStore) (*Manager, error) {
+	m := &Manager{
+		channels:      make(map[string]Channel),
+		workers:       make(map[string]*channelWorker),
+		bus:           messageBus,
+		config:        cfg,
+		mediaStore:    store,
+		channelHashes: make(map[string]string),
+	}
+
+	// Register as streaming delegate so the agent loop can obtain streamers
+	messageBus.SetStreamDelegate(m)
+
+	if err := m.initChannels(&cfg.Channels); err != nil {
 		return nil, err
 	}
 
+	// Store initial config hashes for all channels
+	m.channelHashes = toChannelHashes(cfg)
+
 	return m, nil
 }
 
+// GetStreamer implements bus.StreamDelegate.
+// It checks if the named channel supports streaming and returns a Streamer.
+func (m *Manager) GetStreamer(ctx context.Context, channelName, chatID string) (bus.Streamer, bool) {
+	m.mu.RLock()
+	ch, exists := m.channels[channelName]
+	m.mu.RUnlock()
+
+	if !exists {
+		return nil, false
+	}
+
+	sc, ok := ch.(StreamingCapable)
+	if !ok {
+		return nil, false
+	}
+
+	streamer, err := sc.BeginStream(ctx, chatID)
+	if err != nil {
+		logger.DebugCF("channels", "Streaming unavailable, falling back to placeholder", map[string]any{
+			"channel": channelName,
+			"error":   err.Error(),
+		})
+		return nil, false
+	}
+
+	// Mark streamActive on Finalize so preSend knows to clean up the placeholder
+	key := channelName + ":" + chatID
+	return &finalizeHookStreamer{
+		Streamer:   streamer,
+		onFinalize: func() { m.streamActive.Store(key, true) },
+	}, true
+}
+
+// finalizeHookStreamer wraps a Streamer to run a hook on Finalize.
+type finalizeHookStreamer struct {
+	Streamer
+	onFinalize func()
+}
+
+func (s *finalizeHookStreamer) Finalize(ctx context.Context, content string) error {
+	if err := s.Streamer.Finalize(ctx, content); err != nil {
+		return err
+	}
+	s.onFinalize()
+	return nil
+}
+
 // initChannel is a helper that looks up a factory by name and creates the channel.
 func (m *Manager) initChannel(name, displayName string) {
 	f, ok := getFactory(name)
@@ -203,15 +350,15 @@ func (m *Manager) initChannel(name, displayName string) {
 	}
 }
 
-func (m *Manager) initChannels() error {
+func (m *Manager) initChannels(channels *config.ChannelsConfig) error {
 	logger.InfoC("channels", "Initializing channel manager")
 
-	if m.config.Channels.Telegram.Enabled && m.config.Channels.Telegram.Token != "" {
+	if channels.Telegram.Enabled && channels.Telegram.Token() != "" {
 		m.initChannel("telegram", "Telegram")
 	}
 
-	if m.config.Channels.WhatsApp.Enabled {
-		waCfg := m.config.Channels.WhatsApp
+	if channels.WhatsApp.Enabled {
+		waCfg := channels.WhatsApp
 		if waCfg.UseNative {
 			m.initChannel("whatsapp_native", "WhatsApp Native")
 		} else if waCfg.BridgeURL != "" {
@@ -219,50 +366,65 @@ func (m *Manager) initChannels() error {
 		}
 	}
 
-	if m.config.Channels.Feishu.Enabled {
+	if channels.Feishu.Enabled {
 		m.initChannel("feishu", "Feishu")
 	}
 
-	if m.config.Channels.Discord.Enabled && m.config.Channels.Discord.Token != "" {
+	if channels.Discord.Enabled && channels.Discord.Token() != "" {
 		m.initChannel("discord", "Discord")
 	}
 
-	if m.config.Channels.MaixCam.Enabled {
+	if channels.MaixCam.Enabled {
 		m.initChannel("maixcam", "MaixCam")
 	}
 
-	if m.config.Channels.QQ.Enabled {
+	if channels.QQ.Enabled {
 		m.initChannel("qq", "QQ")
 	}
 
-	if m.config.Channels.DingTalk.Enabled && m.config.Channels.DingTalk.ClientID != "" {
+	if channels.DingTalk.Enabled && channels.DingTalk.ClientID != "" {
 		m.initChannel("dingtalk", "DingTalk")
 	}
 
-	if m.config.Channels.Slack.Enabled && m.config.Channels.Slack.BotToken != "" {
+	if channels.Slack.Enabled && channels.Slack.BotToken() != "" {
 		m.initChannel("slack", "Slack")
 	}
 
-	if m.config.Channels.LINE.Enabled && m.config.Channels.LINE.ChannelAccessToken != "" {
+	if channels.Matrix.Enabled &&
+		m.config.Channels.Matrix.Homeserver != "" &&
+		m.config.Channels.Matrix.UserID != "" &&
+		m.config.Channels.Matrix.AccessToken() != "" {
+		m.initChannel("matrix", "Matrix")
+	}
+
+	if channels.LINE.Enabled && channels.LINE.ChannelAccessToken() != "" {
 		m.initChannel("line", "LINE")
 	}
 
-	if m.config.Channels.OneBot.Enabled && m.config.Channels.OneBot.WSUrl != "" {
+	if channels.OneBot.Enabled && channels.OneBot.WSUrl != "" {
 		m.initChannel("onebot", "OneBot")
 	}
 
-	if m.config.Channels.WeCom.Enabled && m.config.Channels.WeCom.Token != "" {
+	if channels.WeCom.Enabled && channels.WeCom.BotID != "" && channels.WeCom.Secret() != "" {
 		m.initChannel("wecom", "WeCom")
 	}
 
-	if m.config.Channels.WeComApp.Enabled && m.config.Channels.WeComApp.CorpID != "" {
-		m.initChannel("wecom_app", "WeCom App")
+	if channels.Weixin.Enabled && channels.Weixin.Token() != "" {
+		m.initChannel("weixin", "Weixin")
 	}
 
-	if m.config.Channels.Pico.Enabled && m.config.Channels.Pico.Token != "" {
+	if channels.Pico.Enabled && channels.Pico.Token() != "" {
 		m.initChannel("pico", "Pico")
 	}
 
+	if channels.PicoClient.Enabled && channels.PicoClient.URL != "" {
+		m.initChannel("pico_client", "Pico Client")
+	}
+
+	if channels.IRC.Enabled && channels.IRC.Server != "" {
+		m.initChannel("irc", "IRC")
+	}
+
 	logger.InfoCF("channels", "Channel initialization completed", map[string]any{
 		"enabled_channels": len(m.channels),
 	})
@@ -313,7 +475,6 @@ func (m *Manager) StartAll(ctx context.Context) error {
 
 	if len(m.channels) == 0 {
 		logger.WarnC("channels", "No channels enabled")
-		return errors.New("no channels enabled")
 	}
 
 	logger.InfoC("channels", "Starting all channels")
@@ -353,7 +514,7 @@ func (m *Manager) StartAll(ctx context.Context) error {
 				"addr": m.httpServer.Addr,
 			})
 			if err := m.httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
-				logger.ErrorCF("channels", "Shared HTTP server error", map[string]any{
+				logger.FatalCF("channels", "Shared HTTP server error", map[string]any{
 					"error": err.Error(),
 				})
 			}
@@ -539,86 +700,94 @@ func (m *Manager) sendWithRetry(ctx context.Context, name string, w *channelWork
 	})
 }
 
-func (m *Manager) dispatchOutbound(ctx context.Context) {
-	logger.InfoC("channels", "Outbound dispatcher started")
+func dispatchLoop[M any](
+	ctx context.Context,
+	m *Manager,
+	ch <-chan M,
+	getChannel func(M) string,
+	enqueue func(context.Context, *channelWorker, M) bool,
+	startMsg, stopMsg, unknownMsg, noWorkerMsg string,
+) {
+	logger.InfoC("channels", startMsg)
 
 	for {
-		msg, ok := m.bus.SubscribeOutbound(ctx)
-		if !ok {
-			logger.InfoC("channels", "Outbound dispatcher stopped")
+		select {
+		case <-ctx.Done():
+			logger.InfoC("channels", stopMsg)
 			return
-		}
 
-		// Silently skip internal channels
-		if constants.IsInternalChannel(msg.Channel) {
-			continue
-		}
-
-		m.mu.RLock()
-		_, exists := m.channels[msg.Channel]
-		w, wExists := m.workers[msg.Channel]
-		m.mu.RUnlock()
-
-		if !exists {
-			logger.WarnCF("channels", "Unknown channel for outbound message", map[string]any{
-				"channel": msg.Channel,
-			})
-			continue
-		}
-
-		if wExists && w != nil {
-			select {
-			case w.queue <- msg:
-			case <-ctx.Done():
+		case msg, ok := <-ch:
+			if !ok {
+				logger.InfoC("channels", stopMsg)
 				return
 			}
-		} else if exists {
-			logger.WarnCF("channels", "Channel has no active worker, skipping message", map[string]any{
-				"channel": msg.Channel,
-			})
+
+			channel := getChannel(msg)
+
+			// Silently skip internal channels
+			if constants.IsInternalChannel(channel) {
+				continue
+			}
+
+			m.mu.RLock()
+			_, exists := m.channels[channel]
+			w, wExists := m.workers[channel]
+			m.mu.RUnlock()
+
+			if !exists {
+				logger.WarnCF("channels", unknownMsg, map[string]any{"channel": channel})
+				continue
+			}
+
+			if wExists && w != nil {
+				if !enqueue(ctx, w, msg) {
+					return
+				}
+			} else if exists {
+				logger.WarnCF("channels", noWorkerMsg, map[string]any{"channel": channel})
+			}
 		}
 	}
 }
 
+func (m *Manager) dispatchOutbound(ctx context.Context) {
+	dispatchLoop(
+		ctx, m,
+		m.bus.OutboundChan(),
+		func(msg bus.OutboundMessage) string { return msg.Channel },
+		func(ctx context.Context, w *channelWorker, msg bus.OutboundMessage) bool {
+			select {
+			case w.queue <- msg:
+				return true
+			case <-ctx.Done():
+				return false
+			}
+		},
+		"Outbound dispatcher started",
+		"Outbound dispatcher stopped",
+		"Unknown channel for outbound message",
+		"Channel has no active worker, skipping message",
+	)
+}
+
 func (m *Manager) dispatchOutboundMedia(ctx context.Context) {
-	logger.InfoC("channels", "Outbound media dispatcher started")
-
-	for {
-		msg, ok := m.bus.SubscribeOutboundMedia(ctx)
-		if !ok {
-			logger.InfoC("channels", "Outbound media dispatcher stopped")
-			return
-		}
-
-		// Silently skip internal channels
-		if constants.IsInternalChannel(msg.Channel) {
-			continue
-		}
-
-		m.mu.RLock()
-		_, exists := m.channels[msg.Channel]
-		w, wExists := m.workers[msg.Channel]
-		m.mu.RUnlock()
-
-		if !exists {
-			logger.WarnCF("channels", "Unknown channel for outbound media message", map[string]any{
-				"channel": msg.Channel,
-			})
-			continue
-		}
-
-		if wExists && w != nil {
+	dispatchLoop(
+		ctx, m,
+		m.bus.OutboundMediaChan(),
+		func(msg bus.OutboundMediaMessage) string { return msg.Channel },
+		func(ctx context.Context, w *channelWorker, msg bus.OutboundMediaMessage) bool {
 			select {
 			case w.mediaQueue <- msg:
+				return true
 			case <-ctx.Done():
-				return
+				return false
 			}
-		} else if exists {
-			logger.WarnCF("channels", "Channel has no active worker, skipping media message", map[string]any{
-				"channel": msg.Channel,
-			})
-		}
-	}
+		},
+		"Outbound media dispatcher started",
+		"Outbound media dispatcher stopped",
+		"Unknown channel for outbound media message",
+		"Channel has no active worker, skipping media message",
+	)
 }
 
 // runMediaWorker processes outbound media messages for a single channel.
@@ -630,7 +799,7 @@ func (m *Manager) runMediaWorker(ctx context.Context, name string, w *channelWor
 			if !ok {
 				return
 			}
-			m.sendMediaWithRetry(ctx, name, w, msg)
+			_ = m.sendMediaWithRetry(ctx, name, w, msg)
 		case <-ctx.Done():
 			return
 		}
@@ -638,26 +807,37 @@ func (m *Manager) runMediaWorker(ctx context.Context, name string, w *channelWor
 }
 
 // sendMediaWithRetry sends a media message through the channel with rate limiting and
-// retry logic. If the channel does not implement MediaSender, it silently skips.
-func (m *Manager) sendMediaWithRetry(ctx context.Context, name string, w *channelWorker, msg bus.OutboundMediaMessage) {
+// retry logic. It returns nil on success, or the last error after retries,
+// including when the channel does not support MediaSender.
+func (m *Manager) sendMediaWithRetry(
+	ctx context.Context,
+	name string,
+	w *channelWorker,
+	msg bus.OutboundMediaMessage,
+) error {
 	ms, ok := w.ch.(MediaSender)
 	if !ok {
-		logger.DebugCF("channels", "Channel does not support MediaSender, skipping media", map[string]any{
+		err := fmt.Errorf("channel %q does not support media sending", name)
+		logger.WarnCF("channels", "Channel does not support MediaSender", map[string]any{
 			"channel": name,
+			"error":   err.Error(),
 		})
-		return
+		return err
 	}
 
 	// Rate limit: wait for token
 	if err := w.limiter.Wait(ctx); err != nil {
-		return
+		return err
 	}
 
+	// Pre-send: stop typing and clean up any placeholder before sending media.
+	m.preSendMedia(ctx, name, msg, w.ch)
+
 	var lastErr error
 	for attempt := 0; attempt <= maxRetries; attempt++ {
 		lastErr = ms.SendMedia(ctx, msg)
 		if lastErr == nil {
-			return
+			return nil
 		}
 
 		// Permanent failures — don't retry
@@ -676,7 +856,7 @@ func (m *Manager) sendMediaWithRetry(ctx context.Context, name string, w *channe
 			case <-time.After(rateLimitDelay):
 				continue
 			case <-ctx.Done():
-				return
+				return ctx.Err()
 			}
 		}
 
@@ -685,7 +865,7 @@ func (m *Manager) sendMediaWithRetry(ctx context.Context, name string, w *channe
 		select {
 		case <-time.After(backoff):
 		case <-ctx.Done():
-			return
+			return ctx.Err()
 		}
 	}
 
@@ -696,6 +876,7 @@ func (m *Manager) sendMediaWithRetry(ctx context.Context, name string, w *channe
 		"error":   lastErr.Error(),
 		"retries": maxRetries,
 	})
+	return lastErr
 }
 
 // runTTLJanitor periodically scans the typingStops and placeholders maps
@@ -774,6 +955,68 @@ func (m *Manager) GetEnabledChannels() []string {
 	return names
 }
 
+// Reload updates the config reference without restarting channels.
+// This is used when channel config hasn't changed but other parts of the config have.
+func (m *Manager) Reload(ctx context.Context, cfg *config.Config) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	list := toChannelHashes(cfg)
+	added, removed := compareChannels(m.channelHashes, list)
+	for _, name := range removed {
+		// Stop all channels
+		channel := m.channels[name]
+		logger.InfoCF("channels", "Stopping channel", map[string]any{
+			"channel": name,
+		})
+		if err := channel.Stop(ctx); err != nil {
+			logger.ErrorCF("channels", "Error stopping channel", map[string]any{
+				"channel": name,
+				"error":   err.Error(),
+			})
+		}
+		go func() {
+			m.UnregisterChannel(name)
+		}()
+	}
+	dispatchCtx, cancel := context.WithCancel(ctx)
+	m.dispatchTask = &asyncTask{cancel: cancel}
+	cc, err := toChannelConfig(cfg, added)
+	if err != nil {
+		logger.ErrorC("channels", fmt.Sprintf("toChannelConfig error: %v", err))
+		return err
+	}
+	err = m.initChannels(cc)
+	if err != nil {
+		logger.ErrorC("channels", fmt.Sprintf("initChannels error: %v", err))
+		return err
+	}
+	for _, name := range added {
+		channel := m.channels[name]
+		logger.InfoCF("channels", "Starting channel", map[string]any{
+			"channel": name,
+		})
+		if err := channel.Start(ctx); err != nil {
+			logger.ErrorCF("channels", "Failed to start channel", map[string]any{
+				"channel": name,
+				"error":   err.Error(),
+			})
+			continue
+		}
+		// Lazily create worker only after channel starts successfully
+		w := newChannelWorker(name, channel)
+		m.workers[name] = w
+		go m.runWorker(dispatchCtx, name, w)
+		go m.runMediaWorker(dispatchCtx, name, w)
+		go func() {
+			m.RegisterChannel(name, channel)
+		}()
+	}
+
+	m.config = cfg
+	m.channelHashes = toChannelHashes(cfg)
+	return nil
+}
+
 func (m *Manager) RegisterChannel(name string, channel Channel) {
 	m.mu.Lock()
 	defer m.mu.Unlock()
@@ -793,6 +1036,59 @@ func (m *Manager) UnregisterChannel(name string) {
 	delete(m.channels, name)
 }
 
+// SendMessage sends an outbound message synchronously through the channel
+// worker's rate limiter and retry logic. It blocks until the message is
+// delivered (or all retries are exhausted), which preserves ordering when
+// a subsequent operation depends on the message having been sent.
+func (m *Manager) SendMessage(ctx context.Context, msg bus.OutboundMessage) error {
+	m.mu.RLock()
+	_, exists := m.channels[msg.Channel]
+	w, wExists := m.workers[msg.Channel]
+	m.mu.RUnlock()
+
+	if !exists {
+		return fmt.Errorf("channel %s not found", msg.Channel)
+	}
+	if !wExists || w == nil {
+		return fmt.Errorf("channel %s has no active worker", msg.Channel)
+	}
+
+	maxLen := 0
+	if mlp, ok := w.ch.(MessageLengthProvider); ok {
+		maxLen = mlp.MaxMessageLength()
+	}
+	if maxLen > 0 && len([]rune(msg.Content)) > maxLen {
+		for _, chunk := range SplitMessage(msg.Content, maxLen) {
+			chunkMsg := msg
+			chunkMsg.Content = chunk
+			m.sendWithRetry(ctx, msg.Channel, w, chunkMsg)
+		}
+	} else {
+		m.sendWithRetry(ctx, msg.Channel, w, msg)
+	}
+	return nil
+}
+
+// SendMedia sends outbound media synchronously through the channel worker's
+// rate limiter and retry logic. It blocks until the media is delivered (or all
+// retries are exhausted), which preserves ordering when later agent behavior
+// depends on actual media delivery.
+func (m *Manager) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	m.mu.RLock()
+	_, exists := m.channels[msg.Channel]
+	w, wExists := m.workers[msg.Channel]
+	m.mu.RUnlock()
+
+	if !exists {
+		return fmt.Errorf("channel %s not found", msg.Channel)
+	}
+	if !wExists || w == nil {
+		return fmt.Errorf("channel %s has no active worker", msg.Channel)
+	}
+
+	return m.sendMediaWithRetry(ctx, msg.Channel, w, msg)
+}
+
 func (m *Manager) SendToChannel(ctx context.Context, channelName, chatID, content string) error {
 	m.mu.RLock()
 	_, exists := m.channels[channelName]
diff --git a/pkg/channels/manager_channel.go b/pkg/channels/manager_channel.go
new file mode 100644
index 000000000..163218b75
--- /dev/null
+++ b/pkg/channels/manager_channel.go
@@ -0,0 +1,169 @@
+package channels
+
+import (
+	"crypto/md5"
+	"encoding/hex"
+	"encoding/json"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+func toChannelHashes(cfg *config.Config) map[string]string {
+	result := make(map[string]string)
+	ch := cfg.Channels
+	// should not be error
+	marshal, _ := json.Marshal(ch)
+	var channelConfig map[string]map[string]any
+	_ = json.Unmarshal(marshal, &channelConfig)
+
+	for key, value := range channelConfig {
+		if !value["enabled"].(bool) {
+			continue
+		}
+		hiddenValues(key, value, ch)
+		valueBytes, _ := json.Marshal(value)
+		hash := md5.Sum(valueBytes)
+		result[key] = hex.EncodeToString(hash[:])
+	}
+
+	return result
+}
+
+func hiddenValues(key string, value map[string]any, ch config.ChannelsConfig) {
+	switch key {
+	case "pico":
+		value["token"] = ch.Pico.Token()
+	case "telegram":
+		value["token"] = ch.Telegram.Token()
+	case "discord":
+		value["token"] = ch.Discord.Token()
+	case "slack":
+		value["bot_token"] = ch.Slack.BotToken()
+		value["app_token"] = ch.Slack.AppToken()
+	case "matrix":
+		value["token"] = ch.Matrix.AccessToken()
+	case "onebot":
+		value["token"] = ch.OneBot.AccessToken()
+	case "line":
+		value["token"] = ch.LINE.ChannelAccessToken()
+		value["secret"] = ch.LINE.ChannelSecret()
+	case "wecom":
+		value["secret"] = ch.WeCom.Secret()
+	case "dingtalk":
+		value["secret"] = ch.QQ.AppSecret()
+	case "qq":
+		value["secret"] = ch.DingTalk.ClientSecret()
+	case "irc":
+		value["password"] = ch.IRC.Password()
+		value["serv_password"] = ch.IRC.NickServPassword()
+		value["sasl_password"] = ch.IRC.SASLPassword()
+	case "feishu":
+		value["app_secret"] = ch.Feishu.AppSecret()
+		value["encrypt_key"] = ch.Feishu.EncryptKey()
+		value["verification_token"] = ch.Feishu.VerificationToken()
+	}
+}
+
+func compareChannels(old, news map[string]string) (added, removed []string) {
+	for key, newHash := range news {
+		if oldHash, ok := old[key]; ok {
+			if newHash != oldHash {
+				removed = append(removed, key)
+				added = append(added, key)
+			}
+		} else {
+			added = append(added, key)
+		}
+	}
+	for key := range old {
+		if _, ok := news[key]; !ok {
+			removed = append(removed, key)
+		}
+	}
+	return added, removed
+}
+
+func toChannelConfig(cfg *config.Config, list []string) (*config.ChannelsConfig, error) {
+	result := &config.ChannelsConfig{}
+	ch := cfg.Channels
+	// should not be error
+	marshal, _ := json.Marshal(ch)
+	var channelConfig map[string]map[string]any
+	_ = json.Unmarshal(marshal, &channelConfig)
+	temp := make(map[string]map[string]any, 0)
+
+	for key, value := range channelConfig {
+		found := false
+		for _, s := range list {
+			if key == s {
+				found = true
+				break
+			}
+		}
+		if !found || !value["enabled"].(bool) {
+			continue
+		}
+		temp[key] = value
+	}
+
+	marshal, err := json.Marshal(temp)
+	if err != nil {
+		logger.Errorf("marshal error: %v", err)
+		return nil, err
+	}
+	err = json.Unmarshal(marshal, result)
+	if err != nil {
+		logger.Errorf("unmarshal error: %v", err)
+		return nil, err
+	}
+
+	updateKeys(result, &ch)
+
+	return result, nil
+}
+
+func updateKeys(newcfg, old *config.ChannelsConfig) {
+	if newcfg.Pico.Enabled {
+		newcfg.Pico.SetToken(old.Pico.Token())
+	}
+	if newcfg.Telegram.Enabled {
+		newcfg.Telegram.SetToken(old.Telegram.Token())
+	}
+	if newcfg.Discord.Enabled {
+		newcfg.Discord.SetToken(old.Discord.Token())
+	}
+	if newcfg.Slack.Enabled {
+		newcfg.Slack.SetBotToken(old.Slack.BotToken())
+		newcfg.Slack.SetAppToken(old.Slack.AppToken())
+	}
+	if newcfg.Matrix.Enabled {
+		newcfg.Matrix.SetAccessToken(old.Matrix.AccessToken())
+	}
+	if newcfg.OneBot.Enabled {
+		newcfg.OneBot.SetAccessToken(old.OneBot.AccessToken())
+	}
+	if newcfg.LINE.Enabled {
+		newcfg.LINE.SetChannelAccessToken(old.LINE.ChannelAccessToken())
+		newcfg.LINE.SetChannelSecret(old.LINE.ChannelSecret())
+	}
+	if newcfg.WeCom.Enabled {
+		newcfg.WeCom.SetSecret(old.WeCom.Secret())
+	}
+	if newcfg.DingTalk.Enabled {
+		newcfg.DingTalk.SetClientSecret(old.DingTalk.ClientSecret())
+	}
+	if newcfg.QQ.Enabled {
+		newcfg.QQ.SetAppSecret(old.QQ.AppSecret())
+	}
+	if newcfg.IRC.Enabled {
+		newcfg.IRC.SetPassword(old.IRC.Password())
+		newcfg.IRC.SetNickServPassword(old.IRC.NickServPassword())
+		newcfg.IRC.SetSASLPassword(old.IRC.SASLPassword())
+	}
+	if newcfg.Feishu.Enabled {
+		newcfg.Feishu.SetAppSecret(old.Feishu.AppSecret())
+		newcfg.Feishu.SetEncryptKey(old.Feishu.EncryptKey())
+		newcfg.Feishu.SetVerificationToken(old.Feishu.VerificationToken())
+	}
+}
diff --git a/pkg/channels/manager_channel_test.go b/pkg/channels/manager_channel_test.go
new file mode 100644
index 000000000..e17dcf17d
--- /dev/null
+++ b/pkg/channels/manager_channel_test.go
@@ -0,0 +1,51 @@
+package channels
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+func TestToChannelHashes(t *testing.T) {
+	logger.SetLevel(logger.DEBUG)
+	cfg := config.DefaultConfig()
+	results := toChannelHashes(cfg)
+	assert.Equal(t, 0, len(results))
+	logger.Debugf("results: %v", results)
+	cfg2 := config.DefaultConfig()
+	cfg2.Channels.DingTalk.Enabled = true
+	results2 := toChannelHashes(cfg2)
+	assert.Equal(t, 1, len(results2))
+	logger.Debugf("results2: %v", results2)
+	added, removed := compareChannels(results, results2)
+	assert.EqualValues(t, []string{"dingtalk"}, added)
+	assert.EqualValues(t, []string(nil), removed)
+	cfg3 := config.DefaultConfig()
+	cfg3.Channels.Telegram.Enabled = true
+	results3 := toChannelHashes(cfg3)
+	assert.Equal(t, 1, len(results3))
+	logger.Debugf("results3: %v", results3)
+	added, removed = compareChannels(results2, results3)
+	assert.EqualValues(t, []string{"dingtalk"}, removed)
+	assert.EqualValues(t, []string{"telegram"}, added)
+	cfg3.Channels.Telegram.SetToken("114314")
+	results4 := toChannelHashes(cfg3)
+	assert.Equal(t, 1, len(results4))
+	logger.Debugf("results4: %v", results4)
+	added, removed = compareChannels(results3, results4)
+	assert.EqualValues(t, []string{"telegram"}, removed)
+	assert.EqualValues(t, []string{"telegram"}, added)
+	cc, err := toChannelConfig(cfg3, added)
+	assert.NoError(t, err)
+	logger.Debugf("cc: %#v", cc.Telegram)
+	assert.Equal(t, "114314", cc.Telegram.Token())
+	assert.Equal(t, true, cc.Telegram.Enabled)
+	cc, err = toChannelConfig(cfg2, added)
+	assert.NoError(t, err)
+	logger.Debugf("cc: %#v", cc.Telegram)
+	assert.Equal(t, "", cc.Telegram.Token())
+	assert.Equal(t, false, cc.Telegram.Enabled)
+}
diff --git a/pkg/channels/manager_test.go b/pkg/channels/manager_test.go
index f09ecfe2f..b4fd2ba3d 100644
--- a/pkg/channels/manager_test.go
+++ b/pkg/channels/manager_test.go
@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"strings"
 	"sync"
 	"sync/atomic"
 	"testing"
@@ -17,16 +18,66 @@ import (
 // mockChannel is a test double that delegates Send to a configurable function.
 type mockChannel struct {
 	BaseChannel
-	sendFn func(ctx context.Context, msg bus.OutboundMessage) error
+	sendFn            func(ctx context.Context, msg bus.OutboundMessage) error
+	sentMessages      []bus.OutboundMessage
+	placeholdersSent  int
+	editedMessages    int
+	lastPlaceholderID string
 }
 
 func (m *mockChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	m.sentMessages = append(m.sentMessages, msg)
 	return m.sendFn(ctx, msg)
 }
 
 func (m *mockChannel) Start(ctx context.Context) error { return nil }
 func (m *mockChannel) Stop(ctx context.Context) error  { return nil }
 
+func (m *mockChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) {
+	m.placeholdersSent++
+	m.lastPlaceholderID = "mock-ph-123"
+	return m.lastPlaceholderID, nil
+}
+
+func (m *mockChannel) EditMessage(ctx context.Context, chatID, messageID, content string) error {
+	m.editedMessages++
+	return nil
+}
+
+type mockMediaChannel struct {
+	mockChannel
+	sendMediaFn       func(ctx context.Context, msg bus.OutboundMediaMessage) error
+	sentMediaMessages []bus.OutboundMediaMessage
+}
+
+func (m *mockMediaChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	m.sentMediaMessages = append(m.sentMediaMessages, msg)
+	if m.sendMediaFn != nil {
+		return m.sendMediaFn(ctx, msg)
+	}
+	return nil
+}
+
+type mockDeletingMediaChannel struct {
+	mockMediaChannel
+	deleteCalls int
+	lastDeleted struct {
+		chatID    string
+		messageID string
+	}
+}
+
+func (m *mockDeletingMediaChannel) DeleteMessage(
+	_ context.Context,
+	chatID string,
+	messageID string,
+) error {
+	m.deleteCalls++
+	m.lastDeleted.chatID = chatID
+	m.lastDeleted.messageID = messageID
+	return nil
+}
+
 // newTestManager creates a minimal Manager suitable for unit tests.
 func newTestManager() *Manager {
 	return &Manager{
@@ -192,6 +243,125 @@ func TestSendWithRetry_MaxRetriesExhausted(t *testing.T) {
 	}
 }
 
+func TestSendMedia_Success(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+	ch := &mockMediaChannel{
+		sendMediaFn: func(_ context.Context, _ bus.OutboundMediaMessage) error {
+			callCount++
+			return nil
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+	m.channels["test"] = ch
+	m.workers["test"] = w
+
+	err := m.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		Channel: "test",
+		ChatID:  "chat1",
+		Parts:   []bus.MediaPart{{Ref: "media://abc"}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+	if callCount != 1 {
+		t.Fatalf("expected 1 SendMedia call, got %d", callCount)
+	}
+}
+
+func TestSendMedia_PropagatesFailure(t *testing.T) {
+	m := newTestManager()
+	ch := &mockMediaChannel{
+		sendMediaFn: func(_ context.Context, _ bus.OutboundMediaMessage) error {
+			return fmt.Errorf("bad upload: %w", ErrSendFailed)
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+	m.channels["test"] = ch
+	m.workers["test"] = w
+
+	err := m.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		Channel: "test",
+		ChatID:  "chat1",
+		Parts:   []bus.MediaPart{{Ref: "media://abc"}},
+	})
+	if err == nil {
+		t.Fatal("expected SendMedia to return error")
+	}
+	if !errors.Is(err, ErrSendFailed) {
+		t.Fatalf("expected ErrSendFailed, got %v", err)
+	}
+}
+
+func TestSendMedia_UnsupportedChannelReturnsError(t *testing.T) {
+	m := newTestManager()
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			return nil
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+	m.channels["test"] = ch
+	m.workers["test"] = w
+
+	err := m.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		Channel: "test",
+		ChatID:  "chat1",
+		Parts:   []bus.MediaPart{{Ref: "media://abc"}},
+	})
+	if err == nil {
+		t.Fatal("expected SendMedia to return error for unsupported channel")
+	}
+	if !strings.Contains(err.Error(), "does not support media sending") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestSendMedia_DeletesPlaceholderBeforeSending(t *testing.T) {
+	m := newTestManager()
+	ch := &mockDeletingMediaChannel{
+		mockMediaChannel: mockMediaChannel{
+			sendMediaFn: func(_ context.Context, _ bus.OutboundMediaMessage) error {
+				return nil
+			},
+		},
+	}
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+	m.channels["test"] = ch
+	m.workers["test"] = w
+	m.RecordPlaceholder("test", "chat1", "placeholder-1")
+
+	err := m.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		Channel: "test",
+		ChatID:  "chat1",
+		Parts:   []bus.MediaPart{{Ref: "media://abc"}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+	if ch.deleteCalls != 1 {
+		t.Fatalf("expected placeholder delete to be called once, got %d", ch.deleteCalls)
+	}
+	if ch.lastDeleted.chatID != "chat1" || ch.lastDeleted.messageID != "placeholder-1" {
+		t.Fatalf("unexpected placeholder deletion target: %+v", ch.lastDeleted)
+	}
+	if len(ch.sentMediaMessages) != 1 {
+		t.Fatalf("expected media to be sent once, got %d", len(ch.sentMediaMessages))
+	}
+}
+
 func TestSendWithRetry_UnknownError(t *testing.T) {
 	m := newTestManager()
 	var callCount int
@@ -495,6 +665,43 @@ func TestPreSend_PlaceholderEditFails_FallsThrough(t *testing.T) {
 	}
 }
 
+func TestInvokeTypingStop_CallsRegisteredStop(t *testing.T) {
+	m := newTestManager()
+	var stopCalled bool
+
+	m.RecordTypingStop("telegram", "chat123", func() {
+		stopCalled = true
+	})
+
+	m.InvokeTypingStop("telegram", "chat123")
+
+	if !stopCalled {
+		t.Fatal("expected typing stop func to be called")
+	}
+}
+
+func TestInvokeTypingStop_NoOpWhenNoEntry(t *testing.T) {
+	m := newTestManager()
+	// Should not panic
+	m.InvokeTypingStop("telegram", "nonexistent")
+}
+
+func TestInvokeTypingStop_Idempotent(t *testing.T) {
+	m := newTestManager()
+	var callCount int
+
+	m.RecordTypingStop("telegram", "chat123", func() {
+		callCount++
+	})
+
+	m.InvokeTypingStop("telegram", "chat123")
+	m.InvokeTypingStop("telegram", "chat123") // Second call: entry already removed, no-op
+
+	if callCount != 1 {
+		t.Fatalf("expected stop to be called once, got %d", callCount)
+	}
+}
+
 func TestPreSend_TypingStopCalled(t *testing.T) {
 	m := newTestManager()
 	var stopCalled bool
@@ -600,6 +807,37 @@ func TestRecordTypingStop_ConcurrentSafe(t *testing.T) {
 	wg.Wait()
 }
 
+func TestRecordTypingStop_ReplacesExistingStop(t *testing.T) {
+	m := newTestManager()
+	var oldStopCalls int
+	var newStopCalls int
+
+	m.RecordTypingStop("test", "123", func() {
+		oldStopCalls++
+	})
+
+	m.RecordTypingStop("test", "123", func() {
+		newStopCalls++
+	})
+
+	if oldStopCalls != 1 {
+		t.Fatalf("expected previous typing stop to be called once when replaced, got %d", oldStopCalls)
+	}
+	if newStopCalls != 0 {
+		t.Fatalf("expected replacement typing stop to stay active until preSend, got %d calls", newStopCalls)
+	}
+
+	msg := bus.OutboundMessage{Channel: "test", ChatID: "123", Content: "hello"}
+	m.preSend(context.Background(), "test", msg, &mockChannel{})
+
+	if newStopCalls != 1 {
+		t.Fatalf("expected replacement typing stop to be called by preSend, got %d", newStopCalls)
+	}
+	if oldStopCalls != 1 {
+		t.Fatalf("expected previous typing stop to not be called again, got %d", oldStopCalls)
+	}
+}
+
 func TestSendWithRetry_PreSendEditsPlaceholder(t *testing.T) {
 	m := newTestManager()
 	var sendCalled bool
@@ -860,3 +1098,286 @@ func TestBuildMediaScope_WithMessageID(t *testing.T) {
 		t.Fatalf("expected %s, got %s", expected, scope)
 	}
 }
+
+func TestManager_PlaceholderConsumedByResponse(t *testing.T) {
+	mgr := &Manager{
+		channels:     make(map[string]Channel),
+		workers:      make(map[string]*channelWorker),
+		placeholders: sync.Map{},
+	}
+
+	mockCh := &mockChannel{
+		sendFn: func(ctx context.Context, msg bus.OutboundMessage) error {
+			return nil
+		},
+	}
+	worker := newChannelWorker("mock", mockCh)
+	mgr.channels["mock"] = mockCh
+	mgr.workers["mock"] = worker
+
+	ctx := context.Background()
+	key := "mock:chat-1"
+
+	// Simulate a placeholder recorded by base.go HandleMessage
+	mgr.RecordPlaceholder("mock", "chat-1", "ph-123")
+
+	if _, ok := mgr.placeholders.Load(key); !ok {
+		t.Fatal("expected placeholder to be recorded")
+	}
+
+	// Transcription feedback arrives first — it should consume the placeholder
+	// and be delivered via EditMessage, not Send.
+	msgTranscript := bus.OutboundMessage{
+		Channel: "mock",
+		ChatID:  "chat-1",
+		Content: "Transcript: hello",
+	}
+	mgr.sendWithRetry(ctx, "mock", worker, msgTranscript)
+
+	if mockCh.editedMessages != 1 {
+		t.Errorf("expected 1 edited message (placeholder consumed by transcript), got %d", mockCh.editedMessages)
+	}
+	if len(mockCh.sentMessages) != 0 {
+		t.Errorf("expected 0 normal messages (transcript used edit), got %d", len(mockCh.sentMessages))
+	}
+
+	// Placeholder should be gone now
+	if _, ok := mgr.placeholders.Load(key); ok {
+		t.Error("expected placeholder to be removed after being consumed")
+	}
+
+	// Final LLM response arrives — no placeholder left, so it goes through Send
+	msgFinal := bus.OutboundMessage{
+		Channel: "mock",
+		ChatID:  "chat-1",
+		Content: "Final Answer",
+	}
+	mgr.sendWithRetry(ctx, "mock", worker, msgFinal)
+
+	if len(mockCh.sentMessages) != 1 {
+		t.Errorf("expected 1 normal message sent, got %d", len(mockCh.sentMessages))
+	}
+}
+
+func TestSendMessage_Synchronous(t *testing.T) {
+	m := newTestManager()
+
+	var received []bus.OutboundMessage
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, msg bus.OutboundMessage) error {
+			received = append(received, msg)
+			return nil
+		},
+	}
+
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+	m.channels["test"] = ch
+	m.workers["test"] = w
+
+	msg := bus.OutboundMessage{
+		Channel:          "test",
+		ChatID:           "123",
+		Content:          "hello world",
+		ReplyToMessageID: "msg-456",
+	}
+
+	err := m.SendMessage(context.Background(), msg)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+
+	// SendMessage is synchronous — message should already be delivered
+	if len(received) != 1 {
+		t.Fatalf("expected 1 message sent, got %d", len(received))
+	}
+	if received[0].ReplyToMessageID != "msg-456" {
+		t.Fatalf("expected ReplyToMessageID msg-456, got %s", received[0].ReplyToMessageID)
+	}
+	if received[0].Content != "hello world" {
+		t.Fatalf("expected content 'hello world', got %s", received[0].Content)
+	}
+}
+
+func TestSendMessage_UnknownChannel(t *testing.T) {
+	m := newTestManager()
+
+	msg := bus.OutboundMessage{
+		Channel: "nonexistent",
+		ChatID:  "123",
+		Content: "hello",
+	}
+
+	err := m.SendMessage(context.Background(), msg)
+	if err == nil {
+		t.Fatal("expected error for unknown channel")
+	}
+}
+
+func TestSendMessage_NoWorker(t *testing.T) {
+	m := newTestManager()
+
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error { return nil },
+	}
+	m.channels["test"] = ch
+	// No worker registered
+
+	msg := bus.OutboundMessage{
+		Channel: "test",
+		ChatID:  "123",
+		Content: "hello",
+	}
+
+	err := m.SendMessage(context.Background(), msg)
+	if err == nil {
+		t.Fatal("expected error when no worker exists")
+	}
+}
+
+func TestSendMessage_WithRetry(t *testing.T) {
+	m := newTestManager()
+
+	var callCount int
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, _ bus.OutboundMessage) error {
+			callCount++
+			if callCount == 1 {
+				return fmt.Errorf("transient: %w", ErrTemporary)
+			}
+			return nil
+		},
+	}
+
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+	m.channels["test"] = ch
+	m.workers["test"] = w
+
+	msg := bus.OutboundMessage{
+		Channel: "test",
+		ChatID:  "123",
+		Content: "retry me",
+	}
+
+	err := m.SendMessage(context.Background(), msg)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+
+	if callCount != 2 {
+		t.Fatalf("expected 2 Send calls (1 failure + 1 success), got %d", callCount)
+	}
+}
+
+func TestSendMessage_WithSplitting(t *testing.T) {
+	m := newTestManager()
+
+	var received []string
+	ch := &mockChannelWithLength{
+		mockChannel: mockChannel{
+			sendFn: func(_ context.Context, msg bus.OutboundMessage) error {
+				received = append(received, msg.Content)
+				return nil
+			},
+		},
+		maxLen: 5,
+	}
+
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+	m.channels["test"] = ch
+	m.workers["test"] = w
+
+	msg := bus.OutboundMessage{
+		Channel: "test",
+		ChatID:  "123",
+		Content: "hello world",
+	}
+
+	err := m.SendMessage(context.Background(), msg)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+
+	if len(received) < 2 {
+		t.Fatalf("expected message to be split into at least 2 chunks, got %d", len(received))
+	}
+}
+
+func TestSendMessage_PreservesOrdering(t *testing.T) {
+	m := newTestManager()
+
+	var order []string
+	ch := &mockChannel{
+		sendFn: func(_ context.Context, msg bus.OutboundMessage) error {
+			order = append(order, msg.Content)
+			return nil
+		},
+	}
+
+	w := &channelWorker{
+		ch:      ch,
+		limiter: rate.NewLimiter(rate.Inf, 1),
+	}
+	m.channels["test"] = ch
+	m.workers["test"] = w
+
+	// Send two messages sequentially — they must arrive in order
+	_ = m.SendMessage(context.Background(), bus.OutboundMessage{
+		Channel: "test", ChatID: "1", Content: "first",
+	})
+	_ = m.SendMessage(context.Background(), bus.OutboundMessage{
+		Channel: "test", ChatID: "1", Content: "second",
+	})
+
+	if len(order) != 2 {
+		t.Fatalf("expected 2 messages, got %d", len(order))
+	}
+	if order[0] != "first" || order[1] != "second" {
+		t.Fatalf("expected [first, second], got %v", order)
+	}
+}
+
+func TestManager_SendPlaceholder(t *testing.T) {
+	mgr := &Manager{
+		channels:     make(map[string]Channel),
+		workers:      make(map[string]*channelWorker),
+		placeholders: sync.Map{},
+	}
+
+	mockCh := &mockChannel{
+		sendFn: func(ctx context.Context, msg bus.OutboundMessage) error {
+			return nil
+		},
+	}
+	mgr.channels["mock"] = mockCh
+
+	ctx := context.Background()
+
+	// SendPlaceholder should send a placeholder and record it
+	ok := mgr.SendPlaceholder(ctx, "mock", "chat-1")
+	if !ok {
+		t.Fatal("expected SendPlaceholder to succeed")
+	}
+	if mockCh.placeholdersSent != 1 {
+		t.Errorf("expected 1 placeholder sent, got %d", mockCh.placeholdersSent)
+	}
+
+	key := "mock:chat-1"
+	if _, loaded := mgr.placeholders.Load(key); !loaded {
+		t.Error("expected placeholder to be recorded in manager")
+	}
+
+	// SendPlaceholder on unknown channel should return false
+	ok = mgr.SendPlaceholder(ctx, "unknown", "chat-1")
+	if ok {
+		t.Error("expected SendPlaceholder to fail for unknown channel")
+	}
+}
diff --git a/pkg/channels/matrix/init.go b/pkg/channels/matrix/init.go
new file mode 100644
index 000000000..4d6ad45a7
--- /dev/null
+++ b/pkg/channels/matrix/init.go
@@ -0,0 +1,20 @@
+package matrix
+
+import (
+	"path/filepath"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func init() {
+	channels.RegisterFactory("matrix", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		matrixCfg := cfg.Channels.Matrix
+		cryptoDatabasePath := matrixCfg.CryptoDatabasePath
+		if cryptoDatabasePath == "" {
+			cryptoDatabasePath = filepath.Join(cfg.WorkspacePath(), "matrix")
+		}
+		return NewMatrixChannel(matrixCfg, b, cryptoDatabasePath)
+	})
+}
diff --git a/pkg/channels/matrix/matrix.go b/pkg/channels/matrix/matrix.go
new file mode 100644
index 000000000..50b86158d
--- /dev/null
+++ b/pkg/channels/matrix/matrix.go
@@ -0,0 +1,1299 @@
+package matrix
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"html"
+	"io"
+	"mime"
+	"net/url"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/gomarkdown/markdown"
+	mdhtml "github.com/gomarkdown/markdown/html"
+	"github.com/gomarkdown/markdown/parser"
+	"go.mau.fi/util/dbutil"
+	"maunium.net/go/mautrix"
+	"maunium.net/go/mautrix/crypto/cryptohelper"
+	"maunium.net/go/mautrix/event"
+	"maunium.net/go/mautrix/id"
+	_ "modernc.org/sqlite"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/identity"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+const (
+	sqliteDriver = "sqlite"
+	dbName       = "store.db"
+
+	typingRefreshInterval      = 20 * time.Second
+	typingServerTTL            = 30 * time.Second
+	roomKindCacheTTL           = 5 * time.Minute
+	roomKindCacheCleanupPeriod = 1 * time.Minute
+	roomKindCacheMaxEntries    = 2048
+)
+
+var matrixMentionHrefRegexp = regexp.MustCompile(`(?i)<a[^>]+href=["']([^"']+)["']`)
+
+type roomKindCacheEntry struct {
+	isGroup   bool
+	expiresAt time.Time
+	touchedAt time.Time
+}
+
+type roomKindCache struct {
+	mu         sync.Mutex
+	entries    map[string]roomKindCacheEntry
+	maxEntries int
+	ttl        time.Duration
+}
+
+func newRoomKindCache(maxEntries int, ttl time.Duration) *roomKindCache {
+	if maxEntries <= 0 {
+		maxEntries = roomKindCacheMaxEntries
+	}
+	if ttl <= 0 {
+		ttl = roomKindCacheTTL
+	}
+
+	return &roomKindCache{
+		entries:    make(map[string]roomKindCacheEntry),
+		maxEntries: maxEntries,
+		ttl:        ttl,
+	}
+}
+
+func (c *roomKindCache) get(roomID string, now time.Time) (bool, bool) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	entry, ok := c.entries[roomID]
+	if !ok {
+		return false, false
+	}
+	if !entry.expiresAt.After(now) {
+		delete(c.entries, roomID)
+		return false, false
+	}
+
+	return entry.isGroup, true
+}
+
+func (c *roomKindCache) set(roomID string, isGroup bool, now time.Time) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if entry, ok := c.entries[roomID]; ok {
+		entry.isGroup = isGroup
+		entry.expiresAt = now.Add(c.ttl)
+		entry.touchedAt = now
+		c.entries[roomID] = entry
+		return
+	}
+
+	c.cleanupExpiredLocked(now)
+	for len(c.entries) >= c.maxEntries {
+		if !c.evictOldestLocked() {
+			break
+		}
+	}
+
+	c.entries[roomID] = roomKindCacheEntry{
+		isGroup:   isGroup,
+		expiresAt: now.Add(c.ttl),
+		touchedAt: now,
+	}
+}
+
+func (c *roomKindCache) cleanupExpired(now time.Time) int {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	return c.cleanupExpiredLocked(now)
+}
+
+func (c *roomKindCache) cleanupExpiredLocked(now time.Time) int {
+	removed := 0
+	for roomID, entry := range c.entries {
+		if !entry.expiresAt.After(now) {
+			delete(c.entries, roomID)
+			removed++
+		}
+	}
+	return removed
+}
+
+func (c *roomKindCache) evictOldestLocked() bool {
+	if len(c.entries) == 0 {
+		return false
+	}
+
+	var (
+		oldestRoomID string
+		oldestAt     time.Time
+	)
+
+	for roomID, entry := range c.entries {
+		if oldestRoomID == "" || entry.touchedAt.Before(oldestAt) {
+			oldestRoomID = roomID
+			oldestAt = entry.touchedAt
+		}
+	}
+
+	delete(c.entries, oldestRoomID)
+	return true
+}
+
+type typingSession struct {
+	stopCh chan struct{}
+	once   sync.Once
+}
+
+func newTypingSession() *typingSession {
+	return &typingSession{
+		stopCh: make(chan struct{}),
+	}
+}
+
+func (s *typingSession) stop() {
+	s.once.Do(func() {
+		close(s.stopCh)
+	})
+}
+
+// MatrixChannel implements the Channel interface for Matrix.
+type MatrixChannel struct {
+	*channels.BaseChannel
+
+	client *mautrix.Client
+	config config.MatrixConfig
+	syncer *mautrix.DefaultSyncer
+
+	ctx       context.Context
+	cancel    context.CancelFunc
+	startTime time.Time
+
+	typingMu       sync.Mutex
+	typingSessions map[string]*typingSession // roomID -> session
+
+	roomKindCache     *roomKindCache
+	localpartMentionR *regexp.Regexp
+
+	cryptoHelper *cryptohelper.CryptoHelper
+	cryptoDbPath string
+}
+
+func NewMatrixChannel(
+	cfg config.MatrixConfig,
+	messageBus *bus.MessageBus,
+	cryptoDatabasePath string,
+) (*MatrixChannel, error) {
+	homeserver := strings.TrimSpace(cfg.Homeserver)
+	userID := strings.TrimSpace(cfg.UserID)
+	accessToken := strings.TrimSpace(cfg.AccessToken())
+	if homeserver == "" {
+		return nil, fmt.Errorf("matrix homeserver is required")
+	}
+	if userID == "" {
+		return nil, fmt.Errorf("matrix user_id is required")
+	}
+	if accessToken == "" {
+		return nil, fmt.Errorf("matrix access_token is required")
+	}
+
+	client, err := mautrix.NewClient(homeserver, id.UserID(userID), accessToken)
+	if err != nil {
+		return nil, fmt.Errorf("create matrix client: %w", err)
+	}
+	if cfg.DeviceID != "" {
+		client.DeviceID = id.DeviceID(cfg.DeviceID)
+	}
+
+	syncer, ok := client.Syncer.(*mautrix.DefaultSyncer)
+	if !ok {
+		return nil, fmt.Errorf("matrix syncer is not *mautrix.DefaultSyncer")
+	}
+
+	base := channels.NewBaseChannel(
+		"matrix",
+		cfg,
+		messageBus,
+		cfg.AllowFrom,
+		channels.WithMaxMessageLength(65536),
+		channels.WithGroupTrigger(cfg.GroupTrigger),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
+
+	return &MatrixChannel{
+		BaseChannel:       base,
+		client:            client,
+		config:            cfg,
+		syncer:            syncer,
+		typingSessions:    make(map[string]*typingSession),
+		startTime:         time.Now(),
+		roomKindCache:     newRoomKindCache(roomKindCacheMaxEntries, roomKindCacheTTL),
+		localpartMentionR: localpartMentionRegexp(matrixLocalpart(client.UserID)),
+		typingMu:          sync.Mutex{},
+		cryptoDbPath:      cryptoDatabasePath,
+	}, nil
+}
+
+func (c *MatrixChannel) Start(ctx context.Context) error {
+	logger.InfoC("matrix", "Starting Matrix channel")
+
+	c.ctx, c.cancel = context.WithCancel(ctx)
+	c.startTime = time.Now()
+
+	// Initialize crypto helper if database and passphrase are configured
+	if c.cryptoDbPath != "" && c.config.CryptoPassphrase != "" {
+		if err := c.initCrypto(ctx); err != nil {
+			logger.WarnCF(
+				"matrix",
+				"Failed to initialize crypto, continuing without encryption support",
+				map[string]any{
+					"error": err.Error(),
+				},
+			)
+		}
+	}
+
+	c.syncer.OnEventType(event.EventMessage, c.handleMessageEvent)
+	c.syncer.OnEventType(event.EventEncrypted, c.handleMessageEvent)
+	c.syncer.OnEventType(event.StateMember, c.handleMemberEvent)
+
+	c.SetRunning(true)
+	go c.runRoomKindCacheJanitor(c.ctx)
+
+	go func() {
+		if err := c.client.SyncWithContext(c.ctx); err != nil && c.ctx.Err() == nil {
+			logger.ErrorCF("matrix", "Matrix sync stopped unexpectedly", map[string]any{
+				"error": err.Error(),
+			})
+		}
+	}()
+
+	logger.InfoC("matrix", "Matrix channel started")
+	return nil
+}
+
+func (c *MatrixChannel) Stop(ctx context.Context) error {
+	logger.InfoC("matrix", "Stopping Matrix channel")
+	c.SetRunning(false)
+
+	if c.cancel != nil {
+		c.cancel()
+	}
+	c.stopTypingSessions(ctx)
+
+	// Close crypto helper if initialized
+	if c.cryptoHelper != nil {
+		c.cryptoHelper.Close()
+		c.cryptoHelper = nil
+		c.client.Crypto = nil
+	}
+
+	logger.InfoC("matrix", "Matrix channel stopped")
+	return nil
+}
+
+func (c *MatrixChannel) initCrypto(ctx context.Context) error {
+	logger.InfoC("matrix", "Initializing crypto helper")
+
+	// Ensure the crypto database directory exists
+	if err := os.MkdirAll(c.cryptoDbPath, 0o700); err != nil {
+		return fmt.Errorf("create crypto database directory: %w", err)
+	}
+
+	// Create database with sqlite driver (modernc.org/sqlite)
+	dbPath := filepath.Join(c.cryptoDbPath, dbName)
+	connStr := "file:" + dbPath + "?_foreign_keys=on"
+
+	db, err := sql.Open(sqliteDriver, connStr)
+	if err != nil {
+		return fmt.Errorf("open crypto database: %w", err)
+	}
+	db.SetMaxOpenConns(1)
+	db.SetMaxIdleConns(1)
+
+	// Execute PRAGMA statements
+	// This is equivalent to the "sqlite3-fk-wal" dialect used by cryptohelper
+	pragmaStmts := []string{
+		"PRAGMA foreign_keys = ON",
+		"PRAGMA journal_mode = WAL",
+		"PRAGMA synchronous = NORMAL",
+		"PRAGMA busy_timeout = 5000",
+	}
+	for _, pragma := range pragmaStmts {
+		if _, err = db.ExecContext(ctx, pragma); err != nil {
+			_ = db.Close()
+			return fmt.Errorf("execute %s: %w", pragma, err)
+		}
+	}
+
+	// Wrap with dbutil for dialect support
+	wrappedDB, err := dbutil.NewWithDB(db, sqliteDriver)
+	if err != nil {
+		_ = db.Close()
+		return fmt.Errorf("wrap database: %w", err)
+	}
+
+	cryptoHelper, err := cryptohelper.NewCryptoHelper(c.client, []byte(c.config.CryptoPassphrase), wrappedDB)
+	if err != nil {
+		return fmt.Errorf("create crypto helper: %w", err)
+	}
+
+	if c.client.DeviceID == "" {
+		resp, whoamiErr := c.client.Whoami(ctx)
+		if whoamiErr != nil {
+			_ = db.Close()
+			return fmt.Errorf("get device ID via whoami: %w", whoamiErr)
+		}
+		c.client.DeviceID = resp.DeviceID
+	}
+
+	if err = cryptoHelper.Init(ctx); err != nil {
+		cryptoHelper.Close()
+		return fmt.Errorf("init crypto helper: %w", err)
+	}
+
+	c.client.Crypto = cryptoHelper
+	c.cryptoHelper = cryptoHelper
+
+	logger.InfoC("matrix", "Crypto helper initialized successfully")
+	return nil
+}
+
+func markdownToHTML(md string) string {
+	p := parser.NewWithExtensions(parser.CommonExtensions | parser.AutoHeadingIDs)
+	renderer := mdhtml.NewRenderer(mdhtml.RendererOptions{Flags: mdhtml.CommonFlags})
+	return strings.TrimSpace(string(markdown.ToHTML([]byte(md), p, renderer)))
+}
+
+func (c *MatrixChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	roomID := id.RoomID(strings.TrimSpace(msg.ChatID))
+	if roomID == "" {
+		return fmt.Errorf("matrix room ID is empty: %w", channels.ErrSendFailed)
+	}
+
+	content := strings.TrimSpace(msg.Content)
+	if content == "" {
+		return nil
+	}
+
+	_, err := c.client.SendMessageEvent(ctx, roomID, event.EventMessage, c.messageContent(content))
+	if err != nil {
+		return fmt.Errorf("matrix send: %w", channels.ErrTemporary)
+	}
+	return nil
+}
+
+func (c *MatrixChannel) messageContent(text string) *event.MessageEventContent {
+	mc := &event.MessageEventContent{MsgType: event.MsgText, Body: text}
+	if c.config.MessageFormat != "plain" {
+		mc.Format = event.FormatHTML
+		mc.FormattedBody = markdownToHTML(text)
+	}
+	return mc
+}
+
+// SendMedia implements channels.MediaSender.
+func (c *MatrixChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+	sendCtx := ctx
+	if sendCtx == nil {
+		sendCtx = context.Background()
+	}
+
+	roomID := id.RoomID(strings.TrimSpace(msg.ChatID))
+	if roomID == "" {
+		return fmt.Errorf("matrix room ID is empty: %w", channels.ErrSendFailed)
+	}
+
+	store := c.GetMediaStore()
+	if store == nil {
+		return fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
+	}
+
+	for _, part := range msg.Parts {
+		if err := sendCtx.Err(); err != nil {
+			return err
+		}
+
+		localPath, meta, err := store.ResolveWithMeta(part.Ref)
+		if err != nil {
+			logger.ErrorCF("matrix", "Failed to resolve media ref", map[string]any{
+				"ref":   part.Ref,
+				"error": err.Error(),
+			})
+			continue
+		}
+
+		fileInfo, err := os.Stat(localPath)
+		if err != nil {
+			logger.ErrorCF("matrix", "Failed to stat media file", map[string]any{
+				"path":  localPath,
+				"error": err.Error(),
+			})
+			continue
+		}
+
+		file, err := os.Open(localPath)
+		if err != nil {
+			logger.ErrorCF("matrix", "Failed to open media file", map[string]any{
+				"path":  localPath,
+				"error": err.Error(),
+			})
+			continue
+		}
+
+		filename := strings.TrimSpace(part.Filename)
+		if filename == "" {
+			filename = strings.TrimSpace(meta.Filename)
+		}
+		if filename == "" {
+			filename = filepath.Base(localPath)
+		}
+		if filename == "" {
+			filename = "file"
+		}
+
+		contentType := strings.TrimSpace(part.ContentType)
+		if contentType == "" {
+			contentType = strings.TrimSpace(meta.ContentType)
+		}
+		if contentType == "" {
+			contentType = mime.TypeByExtension(strings.ToLower(filepath.Ext(filename)))
+		}
+		if contentType == "" {
+			contentType = "application/octet-stream"
+		}
+
+		uploadResp, err := c.client.UploadMedia(sendCtx, mautrix.ReqUploadMedia{
+			Content:       file,
+			ContentLength: fileInfo.Size(),
+			ContentType:   contentType,
+			FileName:      filename,
+		})
+		file.Close()
+		if err != nil {
+			logger.ErrorCF("matrix", "Failed to upload media", map[string]any{
+				"path":  localPath,
+				"type":  part.Type,
+				"error": err.Error(),
+			})
+			return fmt.Errorf("matrix upload media: %w", channels.ErrTemporary)
+		}
+
+		msgType := matrixOutboundMsgType(part.Type, filename, contentType)
+		content := matrixOutboundContent(
+			part.Caption,
+			filename,
+			msgType,
+			contentType,
+			fileInfo.Size(),
+			uploadResp.ContentURI.CUString(),
+		)
+
+		if _, err := c.client.SendMessageEvent(sendCtx, roomID, event.EventMessage, content); err != nil {
+			logger.ErrorCF("matrix", "Failed to send media message", map[string]any{
+				"room_id": roomID.String(),
+				"type":    msgType,
+				"error":   err.Error(),
+			})
+			return fmt.Errorf("matrix send media: %w", channels.ErrTemporary)
+		}
+	}
+
+	return nil
+}
+
+// StartTyping implements channels.TypingCapable.
+func (c *MatrixChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+	if !c.IsRunning() {
+		return func() {}, nil
+	}
+
+	roomID := id.RoomID(strings.TrimSpace(chatID))
+	if roomID == "" {
+		return func() {}, fmt.Errorf("matrix room ID is empty")
+	}
+
+	session := newTypingSession()
+
+	c.typingMu.Lock()
+	if prev := c.typingSessions[chatID]; prev != nil {
+		prev.stop()
+	}
+	c.typingSessions[chatID] = session
+	c.typingMu.Unlock()
+
+	parent := c.baseContext()
+	go c.typingLoop(parent, roomID, session)
+
+	var once sync.Once
+	stop := func() {
+		once.Do(func() {
+			session.stop()
+			c.typingMu.Lock()
+			if current := c.typingSessions[chatID]; current == session {
+				delete(c.typingSessions, chatID)
+			}
+			c.typingMu.Unlock()
+			_, _ = c.client.UserTyping(context.Background(), roomID, false, 0)
+		})
+	}
+
+	return stop, nil
+}
+
+// SendPlaceholder implements channels.PlaceholderCapable.
+func (c *MatrixChannel) SendPlaceholder(ctx context.Context, chatID string) (string, error) {
+	if !c.config.Placeholder.Enabled {
+		return "", nil
+	}
+
+	roomID := id.RoomID(strings.TrimSpace(chatID))
+	if roomID == "" {
+		return "", fmt.Errorf("matrix room ID is empty")
+	}
+
+	text := strings.TrimSpace(c.config.Placeholder.Text)
+	if text == "" {
+		text = "Thinking... 💭"
+	}
+
+	resp, err := c.client.SendMessageEvent(ctx, roomID, event.EventMessage, &event.MessageEventContent{
+		MsgType: event.MsgNotice,
+		Body:    text,
+	})
+	if err != nil {
+		return "", err
+	}
+
+	return resp.EventID.String(), nil
+}
+
+// EditMessage implements channels.MessageEditor.
+func (c *MatrixChannel) EditMessage(ctx context.Context, chatID string, messageID string, content string) error {
+	roomID := id.RoomID(strings.TrimSpace(chatID))
+	if roomID == "" {
+		return fmt.Errorf("matrix room ID is empty")
+	}
+	if strings.TrimSpace(messageID) == "" {
+		return fmt.Errorf("matrix message ID is empty")
+	}
+
+	editContent := c.messageContent(content)
+	editContent.SetEdit(id.EventID(messageID))
+
+	_, err := c.client.SendMessageEvent(ctx, roomID, event.EventMessage, editContent)
+	return err
+}
+
+func (c *MatrixChannel) handleMemberEvent(ctx context.Context, evt *event.Event) {
+	if !c.config.JoinOnInvite {
+		return
+	}
+	if evt == nil {
+		return
+	}
+
+	member := evt.Content.AsMember()
+	if member.Membership != event.MembershipInvite {
+		return
+	}
+	if evt.GetStateKey() != c.client.UserID.String() {
+		return
+	}
+
+	_, err := c.client.JoinRoomByID(c.baseContext(), evt.RoomID)
+	if err != nil {
+		logger.WarnCF("matrix", "Failed to auto-join invited room", map[string]any{
+			"room_id": evt.RoomID.String(),
+			"error":   err.Error(),
+		})
+		return
+	}
+
+	logger.InfoCF("matrix", "Joined room after invite", map[string]any{
+		"room_id": evt.RoomID.String(),
+	})
+}
+
+func (c *MatrixChannel) handleMessageEvent(ctx context.Context, evt *event.Event) {
+	if evt == nil {
+		return
+	}
+
+	// Ignore our own messages.
+	if evt.Sender == c.client.UserID {
+		return
+	}
+
+	// Ignore historical events on first sync.
+	if time.UnixMilli(evt.Timestamp).Before(c.startTime) {
+		return
+	}
+
+	var msgEvt *event.MessageEventContent
+	switch evt.Type {
+	case event.EventMessage:
+		// When crypto is enabled, events marked WasEncrypted=true are
+		// re-dispatched by c.cryptoHelper after decryption and will be
+		// processed again in the EventEncrypted branch. Skip to avoid duplication.
+		if c.client.Crypto != nil && evt.Mautrix.WasEncrypted {
+			return
+		}
+
+		msgEvt = evt.Content.AsMessage()
+		if msgEvt == nil || msgEvt.MsgType == "" {
+			return
+		}
+	case event.EventEncrypted:
+		var ok bool
+		msgEvt, ok = c.decryptEvent(ctx, evt)
+		if !ok {
+			return
+		}
+	}
+
+	// Ignore edits.
+	if msgEvt.RelatesTo != nil && msgEvt.RelatesTo.GetReplaceID() != "" {
+		return
+	}
+
+	roomID := evt.RoomID.String()
+	scope := channels.BuildMediaScope("matrix", roomID, evt.ID.String())
+
+	content, mediaPaths, ok := c.extractInboundContent(ctx, msgEvt, scope)
+	if !ok {
+		return
+	}
+	content = strings.TrimSpace(content)
+	if content == "" && len(mediaPaths) == 0 {
+		return
+	}
+
+	senderID := evt.Sender.String()
+	sender := bus.SenderInfo{
+		Platform:    "matrix",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("matrix", senderID),
+		Username:    senderID,
+		DisplayName: senderID,
+	}
+
+	if !c.IsAllowedSender(sender) {
+		logger.DebugCF("matrix", "Message rejected by allowlist", map[string]any{
+			"sender_id": senderID,
+		})
+		return
+	}
+
+	isGroup := c.isGroupRoom(ctx, evt.RoomID)
+	if isGroup {
+		isMentioned := c.isBotMentioned(msgEvt)
+		if isMentioned {
+			content = c.stripSelfMention(content)
+		}
+		respond, cleaned := c.ShouldRespondInGroup(isMentioned, content)
+		if !respond {
+			logger.DebugCF("matrix", "Ignoring group message by trigger rules", map[string]any{
+				"room_id":      roomID,
+				"is_mentioned": isMentioned,
+				"mention_only": c.config.GroupTrigger.MentionOnly,
+				"prefixes":     c.config.GroupTrigger.Prefixes,
+			})
+			return
+		}
+		content = cleaned
+	} else {
+		content = c.stripSelfMention(content)
+	}
+
+	content = strings.TrimSpace(content)
+	if content == "" {
+		return
+	}
+
+	peerKind := "direct"
+	peerID := senderID
+	if isGroup {
+		peerKind = "group"
+		peerID = roomID
+	}
+
+	metadata := map[string]string{
+		"room_id":    roomID,
+		"timestamp":  fmt.Sprintf("%d", evt.Timestamp),
+		"is_group":   fmt.Sprintf("%t", isGroup),
+		"sender_raw": senderID,
+	}
+	if replyTo := msgEvt.GetRelatesTo().GetReplyTo(); replyTo != "" {
+		metadata["reply_to_msg_id"] = replyTo.String()
+	}
+
+	c.HandleMessage(
+		c.baseContext(),
+		bus.Peer{Kind: peerKind, ID: peerID},
+		evt.ID.String(),
+		senderID,
+		roomID,
+		content,
+		mediaPaths,
+		metadata,
+		sender,
+	)
+}
+
+// decryptEvent decrypts an encrypted event and returns the decrypted message event content.
+// It returns the decrypted content and a boolean indicating whether decryption was successful.
+func (c *MatrixChannel) decryptEvent(ctx context.Context, evt *event.Event) (*event.MessageEventContent, bool) {
+	if c.client.Crypto == nil {
+		logger.DebugCF("matrix", "Received encrypted message but crypto is not enabled", map[string]any{
+			"room_id": evt.RoomID.String(),
+		})
+		return nil, false
+	}
+
+	decrypted, err := c.client.Crypto.Decrypt(ctx, evt)
+	if err != nil {
+		logger.WarnCF("matrix", "Failed to decrypt message", map[string]any{
+			"room_id": evt.RoomID.String(),
+			"error":   err.Error(),
+		})
+		return nil, false
+	}
+
+	if decrypted.Type != event.EventMessage {
+		logger.DebugCF("matrix", "Decrypted event is not a message event", map[string]any{
+			"room_id": evt.RoomID.String(),
+			"type":    decrypted.Type.String(),
+		})
+		return nil, false
+	}
+
+	return decrypted.Content.AsMessage(), true
+}
+
+func (c *MatrixChannel) extractInboundContent(
+	ctx context.Context,
+	msgEvt *event.MessageEventContent,
+	scope string,
+) (string, []string, bool) {
+	switch msgEvt.MsgType {
+	case event.MsgText, event.MsgNotice:
+		return msgEvt.Body, nil, true
+	case event.MsgImage, event.MsgAudio, event.MsgVideo, event.MsgFile:
+		return c.extractInboundMedia(ctx, msgEvt, scope)
+	default:
+		logger.DebugCF("matrix", "Ignoring unsupported matrix msgtype", map[string]any{
+			"msgtype": msgEvt.MsgType,
+		})
+		return "", nil, false
+	}
+}
+
+func (c *MatrixChannel) extractInboundMedia(
+	ctx context.Context,
+	msgEvt *event.MessageEventContent,
+	scope string,
+) (string, []string, bool) {
+	mediaKind := matrixMediaKind(msgEvt.MsgType)
+	label := matrixMediaLabel(msgEvt, mediaKind)
+	content := fmt.Sprintf("[%s: %s]", mediaKind, label)
+	if caption := strings.TrimSpace(msgEvt.GetCaption()); caption != "" {
+		content = caption + "\n" + content
+	}
+
+	localPath, err := c.downloadMedia(ctx, msgEvt, mediaKind)
+	if err != nil {
+		logger.WarnCF("matrix", "Failed to download media; forwarding as text-only marker", map[string]any{
+			"msgtype": msgEvt.MsgType,
+			"error":   err.Error(),
+		})
+		return content, nil, true
+	}
+
+	filename := matrixMediaFilename(label, mediaKind, matrixContentType(msgEvt))
+	ref := c.storeMedia(localPath, media.MediaMeta{
+		Filename:    filename,
+		ContentType: matrixContentType(msgEvt),
+		Source:      "matrix",
+	}, scope)
+	return content, []string{ref}, true
+}
+
+func (c *MatrixChannel) storeMedia(localPath string, meta media.MediaMeta, scope string) string {
+	if store := c.GetMediaStore(); store != nil {
+		if meta.CleanupPolicy == "" {
+			meta.CleanupPolicy = media.CleanupPolicyDeleteOnCleanup
+		}
+		ref, err := store.Store(localPath, meta, scope)
+		if err == nil {
+			return ref
+		}
+		logger.WarnCF("matrix", "Failed to store media in MediaStore, falling back to local path", map[string]any{
+			"path":  localPath,
+			"error": err.Error(),
+		})
+	}
+	return localPath
+}
+
+func (c *MatrixChannel) downloadMedia(
+	ctx context.Context,
+	msgEvt *event.MessageEventContent,
+	mediaKind string,
+) (string, error) {
+	uri := matrixMediaURI(msgEvt)
+	if uri == "" {
+		return "", fmt.Errorf("empty matrix media URL")
+	}
+	parsed := uri.ParseOrIgnore()
+	if parsed.IsEmpty() {
+		return "", fmt.Errorf("invalid matrix media URL: %s", uri)
+	}
+
+	dlCtx := c.baseContext()
+	if ctx != nil {
+		dlCtx = ctx
+	}
+	reqCtx, cancel := context.WithTimeout(dlCtx, 20*time.Second)
+	defer cancel()
+
+	resp, err := c.client.Download(reqCtx, parsed)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+
+	reader := resp.Body
+	readerClose := func() error { return nil }
+
+	// Encrypted attachments put URL in msgEvt.File and require client-side decryption.
+	if msgEvt != nil && msgEvt.File != nil && msgEvt.URL == "" {
+		if err = msgEvt.File.PrepareForDecryption(); err != nil {
+			return "", fmt.Errorf("decrypt matrix media: %w", err)
+		}
+		decryptReader := msgEvt.File.DecryptStream(resp.Body)
+		reader = decryptReader
+		readerClose = decryptReader.Close
+	}
+
+	label := matrixMediaLabel(msgEvt, mediaKind)
+	ext := matrixMediaExt(label, matrixContentType(msgEvt), mediaKind)
+	mediaDir, err := matrixMediaTempDir()
+	if err != nil {
+		return "", fmt.Errorf("create matrix media directory: %w", err)
+	}
+	tmp, err := os.CreateTemp(mediaDir, "matrix-media-*"+ext)
+	if err != nil {
+		return "", err
+	}
+	tmpPath := tmp.Name()
+	cleanup := true
+	defer func() {
+		_ = tmp.Close()
+		if cleanup {
+			_ = os.Remove(tmpPath)
+		}
+	}()
+
+	_, err = io.Copy(tmp, reader)
+	if err != nil {
+		return "", err
+	}
+	if err = readerClose(); err != nil {
+		return "", fmt.Errorf("decrypt matrix media: %w", err)
+	}
+	if err = tmp.Close(); err != nil {
+		return "", err
+	}
+
+	cleanup = false
+	return tmpPath, nil
+}
+
+func matrixContentType(msgEvt *event.MessageEventContent) string {
+	if msgEvt != nil && msgEvt.Info != nil {
+		return strings.TrimSpace(msgEvt.Info.MimeType)
+	}
+	return ""
+}
+
+func matrixMediaURI(msgEvt *event.MessageEventContent) id.ContentURIString {
+	if msgEvt == nil {
+		return ""
+	}
+	if msgEvt.URL != "" {
+		return msgEvt.URL
+	}
+	if msgEvt.File != nil {
+		return msgEvt.File.URL
+	}
+	return ""
+}
+
+func matrixMediaKind(msgType event.MessageType) string {
+	switch msgType {
+	case event.MsgAudio:
+		return "audio"
+	case event.MsgVideo:
+		return "video"
+	case event.MsgFile:
+		return "file"
+	default:
+		return "image"
+	}
+}
+
+func matrixOutboundMsgType(partType, filename, contentType string) event.MessageType {
+	switch strings.ToLower(strings.TrimSpace(partType)) {
+	case "image":
+		return event.MsgImage
+	case "audio", "voice":
+		return event.MsgAudio
+	case "video":
+		return event.MsgVideo
+	case "file", "document":
+		return event.MsgFile
+	}
+
+	ct := strings.ToLower(strings.TrimSpace(contentType))
+	switch {
+	case strings.HasPrefix(ct, "image/"):
+		return event.MsgImage
+	case strings.HasPrefix(ct, "audio/"), ct == "application/ogg", ct == "application/x-ogg":
+		return event.MsgAudio
+	case strings.HasPrefix(ct, "video/"):
+		return event.MsgVideo
+	}
+
+	switch strings.ToLower(strings.TrimSpace(filepath.Ext(filename))) {
+	case ".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".svg":
+		return event.MsgImage
+	case ".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".wma", ".opus":
+		return event.MsgAudio
+	case ".mp4", ".avi", ".mov", ".webm", ".mkv":
+		return event.MsgVideo
+	default:
+		return event.MsgFile
+	}
+}
+
+func matrixOutboundContent(
+	caption, filename string,
+	msgType event.MessageType,
+	contentType string,
+	size int64,
+	uri id.ContentURIString,
+) *event.MessageEventContent {
+	body := strings.TrimSpace(caption)
+	if body == "" {
+		body = filename
+	}
+	if body == "" {
+		body = matrixMediaKind(msgType)
+	}
+
+	info := &event.FileInfo{MimeType: strings.TrimSpace(contentType)}
+	if size > 0 && size <= int64(int(^uint(0)>>1)) {
+		info.Size = int(size)
+	}
+
+	content := &event.MessageEventContent{
+		MsgType:  msgType,
+		Body:     body,
+		URL:      uri,
+		FileName: filename,
+		Info:     info,
+	}
+	return content
+}
+
+func matrixMediaLabel(msgEvt *event.MessageEventContent, fallback string) string {
+	if msgEvt == nil {
+		return fallback
+	}
+	if v := strings.TrimSpace(msgEvt.FileName); v != "" {
+		return v
+	}
+	if v := strings.TrimSpace(msgEvt.Body); v != "" {
+		return v
+	}
+	return fallback
+}
+
+func matrixMediaFilename(label, mediaKind, contentType string) string {
+	filename := strings.TrimSpace(label)
+	if filename == "" {
+		filename = mediaKind
+	}
+	if filepath.Ext(filename) == "" {
+		filename += matrixMediaExt("", contentType, mediaKind)
+	}
+	return filename
+}
+
+func matrixMediaExt(filename, contentType, mediaKind string) string {
+	if ext := strings.TrimSpace(filepath.Ext(filename)); ext != "" {
+		return ext
+	}
+	if contentType != "" {
+		if exts, err := mime.ExtensionsByType(contentType); err == nil && len(exts) > 0 {
+			return exts[0]
+		}
+	}
+	switch mediaKind {
+	case "audio":
+		return ".ogg"
+	case "video":
+		return ".mp4"
+	case "file":
+		return ".bin"
+	default:
+		return ".jpg"
+	}
+}
+
+func (c *MatrixChannel) isGroupRoom(ctx context.Context, roomID id.RoomID) bool {
+	now := time.Now()
+	if isGroup, ok := c.roomKindCache.get(roomID.String(), now); ok {
+		return isGroup
+	}
+
+	qctx := c.baseContext()
+	if ctx != nil {
+		qctx = ctx
+	}
+	reqCtx, cancel := context.WithTimeout(qctx, 5*time.Second)
+	defer cancel()
+
+	resp, err := c.client.JoinedMembers(reqCtx, roomID)
+	if err != nil {
+		logger.DebugCF("matrix", "Failed to query room members; assume direct", map[string]any{
+			"room_id": roomID.String(),
+			"error":   err.Error(),
+		})
+		return false
+	}
+
+	isGroup := len(resp.Joined) > 2
+	c.roomKindCache.set(roomID.String(), isGroup, now)
+	return isGroup
+}
+
+func (c *MatrixChannel) isBotMentioned(msgEvt *event.MessageEventContent) bool {
+	if msgEvt == nil {
+		return false
+	}
+
+	if msgEvt.Mentions != nil && msgEvt.Mentions.Has(c.client.UserID) {
+		return true
+	}
+
+	userID := c.client.UserID.String()
+	if userID != "" && strings.Contains(msgEvt.Body, userID) {
+		return true
+	}
+	if mentionsUserInFormattedBody(msgEvt.FormattedBody, c.client.UserID) {
+		return true
+	}
+
+	mentionR := c.localpartMentionR
+	if mentionR == nil {
+		mentionR = localpartMentionRegexp(matrixLocalpart(c.client.UserID))
+	}
+	if mentionR == nil {
+		return false
+	}
+
+	// Matrix users are addressed as MXID "@localpart:server", but many clients
+	// emit plain-text mentions as "@localpart". Both forms are handled here.
+	return mentionR.MatchString(msgEvt.Body) || mentionR.MatchString(msgEvt.FormattedBody)
+}
+
+func mentionsUserInFormattedBody(formattedBody string, userID id.UserID) bool {
+	target := strings.ToLower(strings.TrimSpace(userID.String()))
+	if target == "" {
+		return false
+	}
+
+	formattedBody = strings.TrimSpace(formattedBody)
+	if formattedBody == "" {
+		return false
+	}
+
+	if strings.Contains(strings.ToLower(formattedBody), target) {
+		return true
+	}
+
+	matches := matrixMentionHrefRegexp.FindAllStringSubmatch(formattedBody, -1)
+	for _, match := range matches {
+		if len(match) < 2 {
+			continue
+		}
+		decoded := decodeMatrixMentionHref(match[1])
+		if strings.Contains(strings.ToLower(decoded), target) {
+			return true
+		}
+
+		u, err := url.Parse(decoded)
+		if err != nil {
+			continue
+		}
+
+		if strings.Contains(strings.ToLower(u.Path), target) || strings.Contains(strings.ToLower(u.Fragment), target) {
+			return true
+		}
+		if strings.Contains(strings.ToLower(decodeMatrixMentionHref(u.Fragment)), target) {
+			return true
+		}
+	}
+
+	return false
+}
+
+func decodeMatrixMentionHref(v string) string {
+	decoded := html.UnescapeString(strings.TrimSpace(v))
+	if decoded == "" {
+		return ""
+	}
+
+	for i := 0; i < 2; i++ {
+		next, err := url.QueryUnescape(decoded)
+		if err != nil || next == decoded {
+			break
+		}
+		decoded = next
+	}
+	return decoded
+}
+
+func (c *MatrixChannel) typingLoop(ctx context.Context, roomID id.RoomID, session *typingSession) {
+	sendTyping := func() {
+		_, err := c.client.UserTyping(ctx, roomID, true, typingServerTTL)
+		if err != nil {
+			logger.DebugCF("matrix", "Failed to send typing status", map[string]any{
+				"room_id": roomID.String(),
+				"error":   err.Error(),
+			})
+		}
+	}
+
+	sendTyping()
+	ticker := time.NewTicker(typingRefreshInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-session.stopCh:
+			return
+		case <-ticker.C:
+			sendTyping()
+		}
+	}
+}
+
+func (c *MatrixChannel) stopTypingSessions(ctx context.Context) {
+	c.typingMu.Lock()
+	sessions := c.typingSessions
+	c.typingSessions = make(map[string]*typingSession)
+	c.typingMu.Unlock()
+
+	stopCtx := ctx
+	if stopCtx == nil {
+		stopCtx = context.Background()
+	}
+	for roomID, session := range sessions {
+		session.stop()
+		_, _ = c.client.UserTyping(stopCtx, id.RoomID(roomID), false, 0)
+	}
+}
+
+func (c *MatrixChannel) baseContext() context.Context {
+	if c.ctx != nil {
+		return c.ctx
+	}
+	return context.Background()
+}
+
+func (c *MatrixChannel) runRoomKindCacheJanitor(ctx context.Context) {
+	ticker := time.NewTicker(roomKindCacheCleanupPeriod)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case now := <-ticker.C:
+			c.roomKindCache.cleanupExpired(now)
+		}
+	}
+}
+
+func (c *MatrixChannel) stripSelfMention(text string) string {
+	return stripUserMentionWithRegexp(text, c.client.UserID, c.localpartMentionR)
+}
+
+func matrixMediaTempDir() (string, error) {
+	mediaDir := media.TempDir()
+	if err := os.MkdirAll(mediaDir, 0o700); err != nil {
+		return "", err
+	}
+	return mediaDir, nil
+}
+
+func matrixLocalpart(userID id.UserID) string {
+	s := strings.TrimPrefix(userID.String(), "@")
+	localpart, _, _ := strings.Cut(s, ":")
+	return strings.TrimSpace(localpart)
+}
+
+func localpartMentionRegexp(localpart string) *regexp.Regexp {
+	localpart = strings.TrimSpace(localpart)
+	if localpart == "" {
+		return nil
+	}
+
+	// Match Matrix mentions in plain text while avoiding false positives:
+	//   "@picoclaw" and "@picoclaw:matrix.org" should match,
+	//   "test@example.com" and "hellopicoclawworld" should not.
+	pattern := `(?i)(^|[^[:alnum:]_])@` + regexp.QuoteMeta(localpart) + `(?::[A-Za-z0-9._:-]+)?([^[:alnum:]_]|$)`
+	return regexp.MustCompile(pattern)
+}
+
+func stripUserMention(text string, userID id.UserID) string {
+	return stripUserMentionWithRegexp(text, userID, localpartMentionRegexp(matrixLocalpart(userID)))
+}
+
+func stripUserMentionWithRegexp(text string, userID id.UserID, mentionR *regexp.Regexp) string {
+	cleaned := strings.ReplaceAll(text, userID.String(), "")
+
+	if mentionR != nil {
+		cleaned = mentionR.ReplaceAllString(cleaned, "$1$2")
+	}
+
+	cleaned = strings.TrimSpace(cleaned)
+	cleaned = strings.TrimLeft(cleaned, ",:; ")
+	return strings.TrimSpace(cleaned)
+}
diff --git a/pkg/channels/matrix/matrix_test.go b/pkg/channels/matrix/matrix_test.go
new file mode 100644
index 000000000..7484c8d87
--- /dev/null
+++ b/pkg/channels/matrix/matrix_test.go
@@ -0,0 +1,388 @@
+package matrix
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"maunium.net/go/mautrix"
+	"maunium.net/go/mautrix/event"
+	"maunium.net/go/mautrix/id"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+func TestMatrixLocalpartMentionRegexp(t *testing.T) {
+	re := localpartMentionRegexp("picoclaw")
+
+	cases := []struct {
+		text string
+		want bool
+	}{
+		{text: "@picoclaw hello", want: true},
+		{text: "hi @picoclaw:matrix.org", want: true},
+		{
+			text: "\u6b22\u8fce\u4e00\u4e0bpicoclaw\u5c0f\u9f99\u867e",
+			want: false, // historical false-positive case in PR #356
+		},
+		{text: "mail test@example.com", want: false},
+	}
+
+	for _, tc := range cases {
+		if got := re.MatchString(tc.text); got != tc.want {
+			t.Fatalf("text=%q match=%v want=%v", tc.text, got, tc.want)
+		}
+	}
+}
+
+func TestStripUserMention(t *testing.T) {
+	userID := id.UserID("@picoclaw:matrix.org")
+
+	cases := []struct {
+		in   string
+		want string
+	}{
+		{in: "@picoclaw:matrix.org hello", want: "hello"},
+		{in: "@picoclaw, hello", want: "hello"},
+		{in: "no mention here", want: "no mention here"},
+	}
+
+	for _, tc := range cases {
+		if got := stripUserMention(tc.in, userID); got != tc.want {
+			t.Fatalf("stripUserMention(%q)=%q want=%q", tc.in, got, tc.want)
+		}
+	}
+}
+
+func TestIsBotMentioned(t *testing.T) {
+	ch := &MatrixChannel{
+		client: &mautrix.Client{
+			UserID: id.UserID("@picoclaw:matrix.org"),
+		},
+	}
+
+	cases := []struct {
+		name string
+		msg  event.MessageEventContent
+		want bool
+	}{
+		{
+			name: "mentions field",
+			msg: event.MessageEventContent{
+				Body: "hello",
+				Mentions: &event.Mentions{
+					UserIDs: []id.UserID{id.UserID("@picoclaw:matrix.org")},
+				},
+			},
+			want: true,
+		},
+		{
+			name: "full user id in body",
+			msg: event.MessageEventContent{
+				Body: "@picoclaw:matrix.org hello",
+			},
+			want: true,
+		},
+		{
+			name: "localpart with at sign",
+			msg: event.MessageEventContent{
+				Body: "@picoclaw hello",
+			},
+			want: true,
+		},
+		{
+			name: "localpart without at sign should not match",
+			msg: event.MessageEventContent{
+				Body: "\u6b22\u8fce\u4e00\u4e0bpicoclaw\u5c0f\u9f99\u867e",
+			},
+			want: false,
+		},
+		{
+			name: "formatted mention href matrix.to plain",
+			msg: event.MessageEventContent{
+				Body:          "hello bot",
+				FormattedBody: `<a href="https://matrix.to/#/@picoclaw:matrix.org">PicoClaw</a> hello`,
+			},
+			want: true,
+		},
+		{
+			name: "formatted mention href matrix.to encoded",
+			msg: event.MessageEventContent{
+				Body:          "hello bot",
+				FormattedBody: `<a href="https://matrix.to/#/%40picoclaw%3Amatrix.org">PicoClaw</a> hello`,
+			},
+			want: true,
+		},
+	}
+
+	for _, tc := range cases {
+		if got := ch.isBotMentioned(&tc.msg); got != tc.want {
+			t.Fatalf("%s: got=%v want=%v", tc.name, got, tc.want)
+		}
+	}
+}
+
+func TestRoomKindCache_ExpiresEntries(t *testing.T) {
+	cache := newRoomKindCache(4, 5*time.Second)
+	now := time.Unix(100, 0)
+	cache.set("!room:matrix.org", true, now)
+
+	if got, ok := cache.get("!room:matrix.org", now.Add(2*time.Second)); !ok || !got {
+		t.Fatalf("expected cached group room before ttl, got ok=%v group=%v", ok, got)
+	}
+
+	if _, ok := cache.get("!room:matrix.org", now.Add(6*time.Second)); ok {
+		t.Fatal("expected cache miss after ttl expiry")
+	}
+}
+
+func TestRoomKindCache_EvictsOldestWhenFull(t *testing.T) {
+	cache := newRoomKindCache(2, time.Minute)
+	now := time.Unix(200, 0)
+
+	cache.set("!room1:matrix.org", false, now)
+	cache.set("!room2:matrix.org", false, now.Add(1*time.Second))
+	cache.set("!room3:matrix.org", true, now.Add(2*time.Second))
+
+	if _, ok := cache.get("!room1:matrix.org", now.Add(2*time.Second)); ok {
+		t.Fatal("expected oldest cache entry to be evicted")
+	}
+	if got, ok := cache.get("!room2:matrix.org", now.Add(2*time.Second)); !ok || got {
+		t.Fatalf("expected room2 to remain and be direct, got ok=%v group=%v", ok, got)
+	}
+	if got, ok := cache.get("!room3:matrix.org", now.Add(2*time.Second)); !ok || !got {
+		t.Fatalf("expected room3 to remain and be group, got ok=%v group=%v", ok, got)
+	}
+}
+
+func TestMatrixMediaTempDir(t *testing.T) {
+	dir, err := matrixMediaTempDir()
+	if err != nil {
+		t.Fatalf("matrixMediaTempDir failed: %v", err)
+	}
+	if filepath.Base(dir) != media.TempDirName {
+		t.Fatalf("unexpected media dir base: %q", filepath.Base(dir))
+	}
+
+	info, err := os.Stat(dir)
+	if err != nil {
+		t.Fatalf("media dir not created: %v", err)
+	}
+	if !info.IsDir() {
+		t.Fatalf("expected directory, got mode=%v", info.Mode())
+	}
+}
+
+func TestMatrixMediaExt(t *testing.T) {
+	if got := matrixMediaExt("photo.png", "", "image"); got != ".png" {
+		t.Fatalf("filename extension mismatch: got=%q", got)
+	}
+	if got := matrixMediaExt("", "image/webp", "image"); got != ".webp" {
+		t.Fatalf("content-type extension mismatch: got=%q", got)
+	}
+	if got := matrixMediaExt("", "", "image"); got != ".jpg" {
+		t.Fatalf("default image extension mismatch: got=%q", got)
+	}
+	if got := matrixMediaExt("", "", "audio"); got != ".ogg" {
+		t.Fatalf("default audio extension mismatch: got=%q", got)
+	}
+	if got := matrixMediaExt("", "", "video"); got != ".mp4" {
+		t.Fatalf("default video extension mismatch: got=%q", got)
+	}
+	if got := matrixMediaExt("", "", "file"); got != ".bin" {
+		t.Fatalf("default file extension mismatch: got=%q", got)
+	}
+}
+
+func TestDownloadMedia_WritesResponseToTempFile(t *testing.T) {
+	const wantBody = "matrix-media-payload"
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !strings.HasSuffix(r.URL.Path, "/_matrix/client/v1/media/download/matrix.test/abc123") {
+			t.Fatalf("unexpected download path: %s", r.URL.Path)
+		}
+		w.Header().Set("Content-Type", "image/png")
+		_, _ = w.Write([]byte(wantBody))
+	}))
+	defer server.Close()
+
+	client, err := mautrix.NewClient(server.URL, id.UserID("@picoclaw:matrix.test"), "")
+	if err != nil {
+		t.Fatalf("NewClient: %v", err)
+	}
+
+	ch := &MatrixChannel{client: client}
+	msg := &event.MessageEventContent{
+		MsgType: event.MsgImage,
+		Body:    "image.png",
+		URL:     id.ContentURIString("mxc://matrix.test/abc123"),
+		Info:    &event.FileInfo{MimeType: "image/png"},
+	}
+
+	path, err := ch.downloadMedia(context.Background(), msg, "image")
+	if err != nil {
+		t.Fatalf("downloadMedia: %v", err)
+	}
+	defer os.Remove(path)
+
+	if ext := filepath.Ext(path); ext != ".png" {
+		t.Fatalf("temp file extension=%q want=.png", ext)
+	}
+
+	got, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile: %v", err)
+	}
+	if string(got) != wantBody {
+		t.Fatalf("file contents=%q want=%q", string(got), wantBody)
+	}
+}
+
+func TestExtractInboundContent_ImageNoURLFallback(t *testing.T) {
+	ch := &MatrixChannel{}
+	msg := &event.MessageEventContent{
+		MsgType: event.MsgImage,
+		Body:    "test.png",
+	}
+
+	content, mediaRefs, ok := ch.extractInboundContent(context.Background(), msg, "matrix:room:event")
+	if !ok {
+		t.Fatal("expected ok for image fallback")
+	}
+	if content != "[image: test.png]" {
+		t.Fatalf("unexpected content: %q", content)
+	}
+	if len(mediaRefs) != 0 {
+		t.Fatalf("expected no media refs, got %d", len(mediaRefs))
+	}
+}
+
+func TestExtractInboundContent_AudioNoURLFallback(t *testing.T) {
+	ch := &MatrixChannel{}
+	msg := &event.MessageEventContent{
+		MsgType:  event.MsgAudio,
+		FileName: "voice.ogg",
+		Body:     "please transcribe",
+	}
+
+	content, mediaRefs, ok := ch.extractInboundContent(context.Background(), msg, "matrix:room:event")
+	if !ok {
+		t.Fatal("expected ok for audio fallback")
+	}
+	if content != "please transcribe\n[audio: voice.ogg]" {
+		t.Fatalf("unexpected content: %q", content)
+	}
+	if len(mediaRefs) != 0 {
+		t.Fatalf("expected no media refs, got %d", len(mediaRefs))
+	}
+}
+
+func TestMatrixOutboundMsgType(t *testing.T) {
+	cases := []struct {
+		name        string
+		partType    string
+		filename    string
+		contentType string
+		want        event.MessageType
+	}{
+		{name: "explicit image", partType: "image", want: event.MsgImage},
+		{name: "explicit audio", partType: "audio", want: event.MsgAudio},
+		{name: "mime fallback video", contentType: "video/mp4", want: event.MsgVideo},
+		{name: "extension fallback audio", filename: "voice.ogg", want: event.MsgAudio},
+		{name: "unknown defaults file", filename: "report.txt", want: event.MsgFile},
+	}
+
+	for _, tc := range cases {
+		if got := matrixOutboundMsgType(tc.partType, tc.filename, tc.contentType); got != tc.want {
+			t.Fatalf("%s: got=%q want=%q", tc.name, got, tc.want)
+		}
+	}
+}
+
+func TestMatrixOutboundContent(t *testing.T) {
+	content := matrixOutboundContent(
+		"please review",
+		"voice.ogg",
+		event.MsgAudio,
+		"audio/ogg",
+		1234,
+		id.ContentURIString("mxc://matrix.org/abc"),
+	)
+	if content.Body != "please review" {
+		t.Fatalf("unexpected body: %q", content.Body)
+	}
+	if content.FileName != "voice.ogg" {
+		t.Fatalf("unexpected filename: %q", content.FileName)
+	}
+	if content.Info == nil || content.Info.MimeType != "audio/ogg" {
+		t.Fatalf("unexpected content type: %+v", content.Info)
+	}
+	if content.Info == nil || content.Info.Size != 1234 {
+		t.Fatalf("unexpected size: %+v", content.Info)
+	}
+
+	noCaption := matrixOutboundContent(
+		"",
+		"image.png",
+		event.MsgImage,
+		"image/png",
+		0,
+		id.ContentURIString("mxc://matrix.org/def"),
+	)
+	if noCaption.Body != "image.png" {
+		t.Fatalf("unexpected fallback body: %q", noCaption.Body)
+	}
+}
+
+func TestMarkdownToHTML(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		contains string
+	}{
+		{"bold", "**hello**", "<strong>hello</strong>"},
+		{"italic", "_world_", "<em>world</em>"},
+		{"header", "### Title", "<h3"},
+		{"code block", "```\nfoo()\n```", "<code>"},
+		{"inline code", "`x`", "<code>x</code>"},
+		{"plain text", "just text", "just text"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := markdownToHTML(tt.input)
+			if !strings.Contains(got, tt.contains) {
+				t.Fatalf("markdownToHTML(%q) = %q, want it to contain %q", tt.input, got, tt.contains)
+			}
+		})
+	}
+}
+
+func TestMessageContent(t *testing.T) {
+	richtext := &MatrixChannel{config: config.MatrixConfig{MessageFormat: "richtext"}}
+	plain := &MatrixChannel{config: config.MatrixConfig{MessageFormat: "plain"}}
+	defaultt := &MatrixChannel{config: config.MatrixConfig{}}
+
+	for _, c := range []*MatrixChannel{richtext, defaultt} {
+		mc := c.messageContent("**hi**")
+		if mc.Format != event.FormatHTML {
+			t.Errorf("format %q: expected FormatHTML, got %q", c.config.MessageFormat, mc.Format)
+		}
+		if !strings.Contains(mc.FormattedBody, "<strong>hi</strong>") {
+			t.Errorf("format %q: FormattedBody %q missing <strong>", c.config.MessageFormat, mc.FormattedBody)
+		}
+		if mc.Body != "**hi**" {
+			t.Errorf("format %q: Body should remain plain, got %q", c.config.MessageFormat, mc.Body)
+		}
+	}
+
+	mc := plain.messageContent("**hi**")
+	if mc.Format != "" || mc.FormattedBody != "" {
+		t.Errorf("plain: expected no formatting, got format=%q formattedBody=%q", mc.Format, mc.FormattedBody)
+	}
+}
diff --git a/pkg/channels/onebot/onebot.go b/pkg/channels/onebot/onebot.go
index 62a9eb34a..048be48eb 100644
--- a/pkg/channels/onebot/onebot.go
+++ b/pkg/channels/onebot/onebot.go
@@ -184,8 +184,8 @@ func (c *OneBotChannel) connect() error {
 	dialer.HandshakeTimeout = 10 * time.Second
 
 	header := make(map[string][]string)
-	if c.config.AccessToken != "" {
-		header["Authorization"] = []string{"Bearer " + c.config.AccessToken}
+	if c.config.AccessToken() != "" {
+		header["Authorization"] = []string{"Bearer " + c.config.AccessToken()}
 	}
 
 	conn, resp, err := dialer.Dial(c.config.WSUrl, header)
@@ -749,8 +749,9 @@ func (c *OneBotChannel) parseMessageSegments(
 	storeFile := func(localPath, filename string) string {
 		if store != nil {
 			ref, err := store.Store(localPath, media.MediaMeta{
-				Filename: filename,
-				Source:   "onebot",
+				Filename:      filename,
+				Source:        "onebot",
+				CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
 			}, scope)
 			if err == nil {
 				return ref
diff --git a/pkg/channels/pico/client.go b/pkg/channels/pico/client.go
new file mode 100644
index 000000000..2c335050d
--- /dev/null
+++ b/pkg/channels/pico/client.go
@@ -0,0 +1,319 @@
+package pico
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/gorilla/websocket"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/identity"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// PicoClientChannel connects to a remote Pico Protocol WebSocket server.
+type PicoClientChannel struct {
+	*channels.BaseChannel
+	config config.PicoClientConfig
+	conn   *picoConn
+	mu     sync.Mutex
+	ctx    context.Context
+	cancel context.CancelFunc
+}
+
+// NewPicoClientChannel creates a new Pico Protocol client channel.
+func NewPicoClientChannel(
+	cfg config.PicoClientConfig,
+	messageBus *bus.MessageBus,
+) (*PicoClientChannel, error) {
+	if cfg.URL == "" {
+		return nil, fmt.Errorf("pico_client url is required")
+	}
+
+	base := channels.NewBaseChannel("pico_client", cfg, messageBus, cfg.AllowFrom)
+
+	return &PicoClientChannel{
+		BaseChannel: base,
+		config:      cfg,
+	}, nil
+}
+
+// Start dials the remote server and begins reading.
+func (c *PicoClientChannel) Start(ctx context.Context) error {
+	logger.InfoC("pico_client", "Starting Pico Client channel")
+	c.ctx, c.cancel = context.WithCancel(ctx)
+
+	if err := c.dial(); err != nil {
+		c.cancel()
+		return fmt.Errorf("pico_client initial connect: %w", err)
+	}
+
+	c.SetRunning(true)
+	go c.reconnectLoop()
+
+	logger.InfoCF("pico_client", "Connected", map[string]any{"url": c.config.URL})
+	return nil
+}
+
+// Stop closes the connection.
+func (c *PicoClientChannel) Stop(ctx context.Context) error {
+	logger.InfoC("pico_client", "Stopping Pico Client channel")
+	c.SetRunning(false)
+	if c.cancel != nil {
+		c.cancel()
+	}
+	c.mu.Lock()
+	if c.conn != nil {
+		c.conn.close()
+	}
+	c.mu.Unlock()
+	logger.InfoC("pico_client", "Pico Client channel stopped")
+	return nil
+}
+
+func (c *PicoClientChannel) dial() error {
+	header := http.Header{}
+	if c.config.Token != "" {
+		header.Set("Authorization", "Bearer "+c.config.Token)
+	}
+
+	ws, resp, err := websocket.DefaultDialer.DialContext(c.ctx, c.config.URL, header)
+	if resp != nil && resp.Body != nil {
+		resp.Body.Close()
+	}
+	if err != nil {
+		return err
+	}
+
+	connCtx, connCancel := context.WithCancel(c.ctx)
+
+	pc := &picoConn{
+		id:        uuid.New().String(),
+		conn:      ws,
+		sessionID: c.config.SessionID,
+		cancel:    connCancel,
+	}
+	if pc.sessionID == "" {
+		pc.sessionID = uuid.New().String()
+	}
+
+	c.mu.Lock()
+	c.conn = pc
+	c.mu.Unlock()
+
+	go c.readLoop(connCtx, pc)
+	return nil
+}
+
+// reconnectLoop re-dials when the connection drops.
+func (c *PicoClientChannel) reconnectLoop() {
+	for {
+		select {
+		case <-c.ctx.Done():
+			return
+		default:
+		}
+
+		c.mu.Lock()
+		pc := c.conn
+		c.mu.Unlock()
+
+		if pc == nil || pc.closed.Load() {
+			backoff := 5 * time.Second
+			logger.InfoC("pico_client", "Reconnecting...")
+			if err := c.dial(); err != nil {
+				logger.WarnCF("pico_client", "Reconnect failed", map[string]any{
+					"error": err.Error(),
+				})
+				select {
+				case <-c.ctx.Done():
+					return
+				case <-time.After(backoff):
+				}
+				continue
+			}
+			logger.InfoC("pico_client", "Reconnected")
+		}
+
+		select {
+		case <-c.ctx.Done():
+			return
+		case <-time.After(1 * time.Second):
+		}
+	}
+}
+
+func (c *PicoClientChannel) readLoop(connCtx context.Context, pc *picoConn) {
+	defer pc.close()
+
+	readTimeout := time.Duration(c.config.ReadTimeout) * time.Second
+	if readTimeout <= 0 {
+		readTimeout = 60 * time.Second
+	}
+
+	_ = pc.conn.SetReadDeadline(time.Now().Add(readTimeout))
+	pc.conn.SetPongHandler(func(string) error {
+		return pc.conn.SetReadDeadline(time.Now().Add(readTimeout))
+	})
+
+	pingInterval := time.Duration(c.config.PingInterval) * time.Second
+	if pingInterval <= 0 {
+		pingInterval = 30 * time.Second
+	}
+	go c.pingLoop(connCtx, pc, pingInterval)
+
+	for {
+		select {
+		case <-connCtx.Done():
+			return
+		default:
+		}
+
+		_, raw, err := pc.conn.ReadMessage()
+		if err != nil {
+			if websocket.IsUnexpectedCloseError(
+				err,
+				websocket.CloseGoingAway,
+				websocket.CloseNormalClosure,
+			) {
+				logger.DebugCF("pico_client", "Read error", map[string]any{
+					"error": err.Error(),
+				})
+			}
+			return
+		}
+
+		_ = pc.conn.SetReadDeadline(time.Now().Add(readTimeout))
+
+		var msg PicoMessage
+		if err := json.Unmarshal(raw, &msg); err != nil {
+			continue
+		}
+
+		c.handleInbound(pc, msg)
+	}
+}
+
+func (c *PicoClientChannel) pingLoop(connCtx context.Context, pc *picoConn, interval time.Duration) {
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-connCtx.Done():
+			return
+		case <-ticker.C:
+			if pc.closed.Load() {
+				return
+			}
+			pc.writeMu.Lock()
+			err := pc.conn.WriteMessage(websocket.PingMessage, nil)
+			pc.writeMu.Unlock()
+			if err != nil {
+				return
+			}
+		}
+	}
+}
+
+// handleInbound processes messages from the remote server.
+// In client mode the server sends message.create (responses) and the client
+// sends message.send (user input). We treat message.create from the server
+// as inbound user messages to feed into the agent loop.
+func (c *PicoClientChannel) handleInbound(pc *picoConn, msg PicoMessage) {
+	switch msg.Type {
+	case TypePong:
+		// response to our ping, ignore
+	case TypeMessageCreate:
+		// Server sent us a message — treat as inbound
+		c.handleServerMessage(pc, msg)
+	default:
+		logger.DebugCF("pico_client", "Ignoring message type", map[string]any{
+			"type": msg.Type,
+		})
+	}
+}
+
+func (c *PicoClientChannel) handleServerMessage(pc *picoConn, msg PicoMessage) {
+	content, _ := msg.Payload["content"].(string)
+	if strings.TrimSpace(content) == "" {
+		return
+	}
+
+	sessionID := msg.SessionID
+	if sessionID == "" {
+		sessionID = pc.sessionID
+	}
+
+	chatID := "pico_client:" + sessionID
+	senderID := "pico-remote"
+	peer := bus.Peer{Kind: "direct", ID: chatID}
+
+	sender := bus.SenderInfo{
+		Platform:    "pico_client",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("pico_client", senderID),
+	}
+
+	if !c.IsAllowedSender(sender) {
+		return
+	}
+
+	c.HandleMessage(c.ctx, peer, msg.ID, senderID, chatID, content, nil, map[string]string{
+		"platform":   "pico_client",
+		"session_id": sessionID,
+	}, sender)
+}
+
+// Send sends a message to the remote server.
+func (c *PicoClientChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+	c.mu.Lock()
+	pc := c.conn
+	c.mu.Unlock()
+	if pc == nil || pc.closed.Load() {
+		return channels.ErrSendFailed
+	}
+
+	outMsg := newMessage(TypeMessageSend, map[string]any{
+		"content": msg.Content,
+	})
+	outMsg.SessionID = strings.TrimPrefix(msg.ChatID, "pico_client:")
+	return pc.writeJSON(outMsg)
+}
+
+// StartTyping implements channels.TypingCapable.
+func (c *PicoClientChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+	c.mu.Lock()
+	pc := c.conn
+	c.mu.Unlock()
+	if pc == nil || pc.closed.Load() {
+		return func() {}, nil
+	}
+
+	startMsg := newMessage(TypeTypingStart, nil)
+	startMsg.SessionID = strings.TrimPrefix(chatID, "pico_client:")
+	if err := pc.writeJSON(startMsg); err != nil {
+		return func() {}, err
+	}
+	return func() {
+		c.mu.Lock()
+		currentPC := c.conn
+		c.mu.Unlock()
+		if currentPC == nil {
+			return
+		}
+		stopMsg := newMessage(TypeTypingStop, nil)
+		stopMsg.SessionID = strings.TrimPrefix(chatID, "pico_client:")
+		currentPC.writeJSON(stopMsg)
+	}, nil
+}
diff --git a/pkg/channels/pico/client_test.go b/pkg/channels/pico/client_test.go
new file mode 100644
index 000000000..118c9abea
--- /dev/null
+++ b/pkg/channels/pico/client_test.go
@@ -0,0 +1,264 @@
+package pico
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/gorilla/websocket"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestNewPicoClientChannel_MissingURL(t *testing.T) {
+	_, err := NewPicoClientChannel(config.PicoClientConfig{}, bus.NewMessageBus())
+	if err == nil {
+		t.Fatal("expected error for missing URL")
+	}
+	if !strings.Contains(err.Error(), "url is required") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestNewPicoClientChannel_OK(t *testing.T) {
+	ch, err := NewPicoClientChannel(config.PicoClientConfig{
+		URL: "ws://localhost:9999/ws",
+	}, bus.NewMessageBus())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if ch.Name() != "pico_client" {
+		t.Fatalf("name = %q, want pico_client", ch.Name())
+	}
+}
+
+func TestSend_NotRunning(t *testing.T) {
+	ch, err := NewPicoClientChannel(config.PicoClientConfig{
+		URL: "ws://localhost:9999/ws",
+	}, bus.NewMessageBus())
+	if err != nil {
+		t.Fatal(err)
+	}
+	err = ch.Send(context.Background(), bus.OutboundMessage{Content: "hi"})
+	if !errors.Is(err, channels.ErrNotRunning) {
+		t.Fatalf("expected ErrNotRunning, got %v", err)
+	}
+}
+
+// testServer starts a WS server that echoes message.send back as message.create.
+func testServer(t *testing.T, token string) *httptest.Server {
+	t.Helper()
+	upgrader := websocket.Upgrader{CheckOrigin: func(*http.Request) bool { return true }}
+
+	return httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if token != "" {
+			auth := r.Header.Get("Authorization")
+			if auth != "Bearer "+token {
+				http.Error(w, "unauthorized", http.StatusUnauthorized)
+				return
+			}
+		}
+
+		conn, err := upgrader.Upgrade(w, r, nil)
+		if err != nil {
+			t.Logf("upgrade error: %v", err)
+			return
+		}
+		defer conn.Close()
+
+		for {
+			_, raw, err := conn.ReadMessage()
+			if err != nil {
+				return
+			}
+
+			var msg PicoMessage
+			if err := json.Unmarshal(raw, &msg); err != nil {
+				continue
+			}
+
+			if msg.Type == TypeMessageSend {
+				reply := newMessage(TypeMessageCreate, msg.Payload)
+				reply.SessionID = msg.SessionID
+				if err := conn.WriteJSON(reply); err != nil {
+					return
+				}
+			}
+		}
+	}))
+}
+
+func wsURL(httpURL string) string {
+	return "ws" + strings.TrimPrefix(httpURL, "http")
+}
+
+func TestClientChannel_ConnectAndSend(t *testing.T) {
+	srv := testServer(t, "test-token")
+	defer srv.Close()
+
+	mb := bus.NewMessageBus()
+	ch, err := NewPicoClientChannel(config.PicoClientConfig{
+		URL:          wsURL(srv.URL),
+		Token:        "test-token",
+		SessionID:    "sess-1",
+		PingInterval: 60,
+		ReadTimeout:  10,
+	}, mb)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	if err = ch.Start(ctx); err != nil {
+		t.Fatalf("Start: %v", err)
+	}
+	defer ch.Stop(ctx)
+
+	// Send a message
+	err = ch.Send(ctx, bus.OutboundMessage{
+		ChatID:  "pico_client:sess-1",
+		Content: "hello",
+	})
+	if err != nil {
+		t.Fatalf("Send: %v", err)
+	}
+}
+
+func TestClientChannel_AuthFailure(t *testing.T) {
+	srv := testServer(t, "correct-token")
+	defer srv.Close()
+
+	ch, err := NewPicoClientChannel(config.PicoClientConfig{
+		URL:   wsURL(srv.URL),
+		Token: "wrong-token",
+	}, bus.NewMessageBus())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+
+	err = ch.Start(ctx)
+	if err == nil {
+		ch.Stop(ctx)
+		t.Fatal("expected auth failure")
+	}
+}
+
+func TestClientChannel_ReceivesServerMessage(t *testing.T) {
+	srv := testServer(t, "")
+	defer srv.Close()
+
+	mb := bus.NewMessageBus()
+
+	ch, err := NewPicoClientChannel(config.PicoClientConfig{
+		URL:         wsURL(srv.URL),
+		SessionID:   "sess-echo",
+		ReadTimeout: 10,
+	}, mb)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	if err = ch.Start(ctx); err != nil {
+		t.Fatalf("Start: %v", err)
+	}
+	defer ch.Stop(ctx)
+
+	// Send a message; the echo server replies with message.create
+	err = ch.Send(ctx, bus.OutboundMessage{
+		ChatID:  "pico_client:sess-echo",
+		Content: "ping",
+	})
+	if err != nil {
+		t.Fatalf("Send: %v", err)
+	}
+
+	// The echoed message.create is processed by handleServerMessage which
+	// calls HandleMessage → PublishInbound. Consume it from the bus.
+	select {
+	case msg := <-mb.InboundChan():
+		if msg.Content != "ping" {
+			t.Fatalf("received = %q, want %q", msg.Content, "ping")
+		}
+	case <-ctx.Done():
+		t.Fatal("timed out waiting for echoed message")
+	}
+}
+
+func TestClientChannel_StartTyping(t *testing.T) {
+	srv := testServer(t, "")
+	defer srv.Close()
+
+	ch, err := NewPicoClientChannel(config.PicoClientConfig{
+		URL:         wsURL(srv.URL),
+		SessionID:   "sess-type",
+		ReadTimeout: 10,
+	}, bus.NewMessageBus())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	if err = ch.Start(ctx); err != nil {
+		t.Fatalf("Start: %v", err)
+	}
+	defer ch.Stop(ctx)
+
+	stop, err := ch.StartTyping(ctx, "pico_client:sess-type")
+	if err != nil {
+		t.Fatalf("StartTyping: %v", err)
+	}
+	stop() // should not panic
+}
+
+func TestSend_ClosedConnection(t *testing.T) {
+	srv := testServer(t, "")
+	defer srv.Close()
+
+	ch, err := NewPicoClientChannel(config.PicoClientConfig{
+		URL:         wsURL(srv.URL),
+		SessionID:   "sess-close",
+		ReadTimeout: 10,
+	}, bus.NewMessageBus())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	if err = ch.Start(ctx); err != nil {
+		t.Fatalf("Start: %v", err)
+	}
+
+	// Force close the underlying connection
+	ch.mu.Lock()
+	ch.conn.close()
+	ch.mu.Unlock()
+
+	err = ch.Send(ctx, bus.OutboundMessage{
+		ChatID:  "pico_client:sess-close",
+		Content: "should fail",
+	})
+	if !errors.Is(err, channels.ErrSendFailed) {
+		t.Fatalf("expected ErrSendFailed, got %v", err)
+	}
+
+	ch.Stop(ctx)
+}
diff --git a/pkg/channels/pico/init.go b/pkg/channels/pico/init.go
index 96d764418..0319279d8 100644
--- a/pkg/channels/pico/init.go
+++ b/pkg/channels/pico/init.go
@@ -10,4 +10,7 @@ func init() {
 	channels.RegisterFactory("pico", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
 		return NewPicoChannel(cfg.Channels.Pico, b)
 	})
+	channels.RegisterFactory("pico_client", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
+		return NewPicoClientChannel(cfg.Channels.PicoClient, b)
+	})
 }
diff --git a/pkg/channels/pico/pico.go b/pkg/channels/pico/pico.go
index 8d8b62a67..f3ba55a92 100644
--- a/pkg/channels/pico/pico.go
+++ b/pkg/channels/pico/pico.go
@@ -27,6 +27,7 @@ type picoConn struct {
 	sessionID string
 	writeMu   sync.Mutex
 	closed    atomic.Bool
+	cancel    context.CancelFunc // cancels per-connection goroutines (e.g. pingLoop)
 }
 
 // writeJSON sends a JSON message to the connection with write locking.
@@ -42,6 +43,9 @@ func (pc *picoConn) writeJSON(v any) error {
 // close closes the connection.
 func (pc *picoConn) close() {
 	if pc.closed.CompareAndSwap(false, true) {
+		if pc.cancel != nil {
+			pc.cancel()
+		}
 		pc.conn.Close()
 	}
 }
@@ -50,17 +54,18 @@ func (pc *picoConn) close() {
 // It serves as the reference implementation for all optional capability interfaces.
 type PicoChannel struct {
 	*channels.BaseChannel
-	config      config.PicoConfig
-	upgrader    websocket.Upgrader
-	connections sync.Map // connID → *picoConn
-	connCount   atomic.Int32
-	ctx         context.Context
-	cancel      context.CancelFunc
+	config             config.PicoConfig
+	upgrader           websocket.Upgrader
+	connections        map[string]*picoConn            // connID -> *picoConn
+	sessionConnections map[string]map[string]*picoConn // sessionID -> connID -> *picoConn
+	connsMu            sync.RWMutex
+	ctx                context.Context
+	cancel             context.CancelFunc
 }
 
 // NewPicoChannel creates a new Pico Protocol channel.
 func NewPicoChannel(cfg config.PicoConfig, messageBus *bus.MessageBus) (*PicoChannel, error) {
-	if cfg.Token == "" {
+	if cfg.Token() == "" {
 		return nil, fmt.Errorf("pico token is required")
 	}
 
@@ -88,9 +93,104 @@ func NewPicoChannel(cfg config.PicoConfig, messageBus *bus.MessageBus) (*PicoCha
 			ReadBufferSize:  1024,
 			WriteBufferSize: 1024,
 		},
+		connections:        make(map[string]*picoConn),
+		sessionConnections: make(map[string]map[string]*picoConn),
 	}, nil
 }
 
+// createAndAddConnection checks MaxConnections and registers a connection atomically.
+func (c *PicoChannel) createAndAddConnection(conn *websocket.Conn, sessionID string, maxConns int) (*picoConn, error) {
+	c.connsMu.Lock()
+	defer c.connsMu.Unlock()
+	if len(c.connections) >= maxConns {
+		return nil, channels.ErrTemporary
+	}
+
+	var connID string
+	for {
+		connID = uuid.New().String()
+		if _, exists := c.connections[connID]; !exists {
+			break
+		}
+	}
+
+	pc := &picoConn{
+		id:        connID,
+		conn:      conn,
+		sessionID: sessionID,
+	}
+
+	c.connections[pc.id] = pc
+	bySession, ok := c.sessionConnections[pc.sessionID]
+	if !ok {
+		bySession = make(map[string]*picoConn)
+		c.sessionConnections[pc.sessionID] = bySession
+	}
+	bySession[pc.id] = pc
+
+	return pc, nil
+}
+
+// removeConnection deletes a connection from indexes and returns it when found.
+func (c *PicoChannel) removeConnection(connID string) *picoConn {
+	c.connsMu.Lock()
+	defer c.connsMu.Unlock()
+
+	pc, ok := c.connections[connID]
+	if !ok {
+		return nil
+	}
+
+	delete(c.connections, connID)
+	if bySession, ok := c.sessionConnections[pc.sessionID]; ok {
+		delete(bySession, connID)
+		if len(bySession) == 0 {
+			delete(c.sessionConnections, pc.sessionID)
+		}
+	}
+
+	return pc
+}
+
+// takeAllConnections snapshots and clears all connection indexes.
+func (c *PicoChannel) takeAllConnections() []*picoConn {
+	c.connsMu.Lock()
+	defer c.connsMu.Unlock()
+
+	all := make([]*picoConn, 0, len(c.connections))
+	for _, pc := range c.connections {
+		all = append(all, pc)
+	}
+	clear(c.connections)
+	clear(c.sessionConnections)
+
+	return all
+}
+
+// sessionConnectionsSnapshot returns all active connections for a session.
+func (c *PicoChannel) sessionConnectionsSnapshot(sessionID string) []*picoConn {
+	c.connsMu.RLock()
+	defer c.connsMu.RUnlock()
+
+	bySession, ok := c.sessionConnections[sessionID]
+	if !ok || len(bySession) == 0 {
+		return nil
+	}
+
+	conns := make([]*picoConn, 0, len(bySession))
+	for _, pc := range bySession {
+		conns = append(conns, pc)
+	}
+	return conns
+}
+
+// currentConnCount returns a lock-protected snapshot of active connection count.
+func (c *PicoChannel) currentConnCount() int {
+	c.connsMu.RLock()
+	defer c.connsMu.RUnlock()
+	return len(c.connections)
+}
+
 // Start implements Channel.
 func (c *PicoChannel) Start(ctx context.Context) error {
 	logger.InfoC("pico", "Starting Pico Protocol channel")
@@ -106,13 +206,9 @@ func (c *PicoChannel) Stop(ctx context.Context) error {
 	c.SetRunning(false)
 
 	// Close all connections
-	c.connections.Range(func(key, value any) bool {
-		if pc, ok := value.(*picoConn); ok {
-			pc.close()
-		}
-		c.connections.Delete(key)
-		return true
-	})
+	for _, pc := range c.takeAllConnections() {
+		pc.close()
+	}
 
 	if c.cancel != nil {
 		c.cancel()
@@ -129,8 +225,8 @@ func (c *PicoChannel) WebhookPath() string { return "/pico/" }
 func (c *PicoChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	path := strings.TrimPrefix(r.URL.Path, "/pico")
 
-	switch {
-	case path == "/ws" || path == "/ws/":
+	switch path {
+	case "/ws", "/ws/":
 		c.handleWebSocket(w, r)
 	default:
 		http.NotFound(w, r)
@@ -204,23 +300,16 @@ func (c *PicoChannel) broadcastToSession(chatID string, msg PicoMessage) error {
 	msg.SessionID = sessionID
 
 	var sent bool
-	c.connections.Range(func(key, value any) bool {
-		pc, ok := value.(*picoConn)
-		if !ok {
-			return true
+	for _, pc := range c.sessionConnectionsSnapshot(sessionID) {
+		if err := pc.writeJSON(msg); err != nil {
+			logger.DebugCF("pico", "Write to connection failed", map[string]any{
+				"conn_id": pc.id,
+				"error":   err.Error(),
+			})
+		} else {
+			sent = true
 		}
-		if pc.sessionID == sessionID {
-			if err := pc.writeJSON(msg); err != nil {
-				logger.DebugCF("pico", "Write to connection failed", map[string]any{
-					"conn_id": pc.id,
-					"error":   err.Error(),
-				})
-			} else {
-				sent = true
-			}
-		}
-		return true
-	})
+	}
 
 	if !sent {
 		return fmt.Errorf("no active connections for session %s: %w", sessionID, channels.ErrSendFailed)
@@ -246,12 +335,18 @@ func (c *PicoChannel) handleWebSocket(w http.ResponseWriter, r *http.Request) {
 	if maxConns <= 0 {
 		maxConns = 100
 	}
-	if int(c.connCount.Load()) >= maxConns {
+	if c.currentConnCount() >= maxConns {
 		http.Error(w, "too many connections", http.StatusServiceUnavailable)
 		return
 	}
 
-	conn, err := c.upgrader.Upgrade(w, r, nil)
+	// Echo the matched subprotocol back so the browser accepts the upgrade.
+	var responseHeader http.Header
+	if proto := c.matchedSubprotocol(r); proto != "" {
+		responseHeader = http.Header{"Sec-WebSocket-Protocol": {proto}}
+	}
+
+	conn, err := c.upgrader.Upgrade(w, r, responseHeader)
 	if err != nil {
 		logger.ErrorCF("pico", "WebSocket upgrade failed", map[string]any{
 			"error": err.Error(),
@@ -265,15 +360,17 @@ func (c *PicoChannel) handleWebSocket(w http.ResponseWriter, r *http.Request) {
 		sessionID = uuid.New().String()
 	}
 
-	pc := &picoConn{
-		id:        uuid.New().String(),
-		conn:      conn,
-		sessionID: sessionID,
+	pc, err := c.createAndAddConnection(conn, sessionID, maxConns)
+	if err != nil {
+		_ = conn.WriteControl(
+			websocket.CloseMessage,
+			websocket.FormatCloseMessage(websocket.CloseTryAgainLater, "too many connections"),
+			time.Now().Add(2*time.Second),
+		)
+		_ = conn.Close()
+		return
 	}
 
-	c.connections.Store(pc.id, pc)
-	c.connCount.Add(1)
-
 	logger.InfoCF("pico", "WebSocket client connected", map[string]any{
 		"conn_id":    pc.id,
 		"session_id": sessionID,
@@ -282,10 +379,12 @@ func (c *PicoChannel) handleWebSocket(w http.ResponseWriter, r *http.Request) {
 	go c.readLoop(pc)
 }
 
-// authenticate checks the Bearer token from the Authorization header.
-// Query parameter authentication is only allowed when AllowTokenQuery is explicitly enabled.
+// authenticate checks the request for a valid token:
+//  1. Authorization: Bearer <token> header
+//  2. Sec-WebSocket-Protocol "token.<value>" (for browsers that can't set headers)
+//  3. Query parameter "token" (only when AllowTokenQuery is on)
 func (c *PicoChannel) authenticate(r *http.Request) bool {
-	token := c.config.Token
+	token := c.config.Token()
 	if token == "" {
 		return false
 	}
@@ -298,6 +397,11 @@ func (c *PicoChannel) authenticate(r *http.Request) bool {
 		}
 	}
 
+	// Check Sec-WebSocket-Protocol subprotocol ("token.<value>")
+	if c.matchedSubprotocol(r) != "" {
+		return true
+	}
+
 	// Check query parameter only when explicitly allowed
 	if c.config.AllowTokenQuery {
 		if r.URL.Query().Get("token") == token {
@@ -308,16 +412,28 @@ func (c *PicoChannel) authenticate(r *http.Request) bool {
 	return false
 }
 
+// matchedSubprotocol returns the "token.<value>" subprotocol that matches
+// the configured token, or "" if none do.
+func (c *PicoChannel) matchedSubprotocol(r *http.Request) string {
+	token := c.config.Token()
+	for _, proto := range websocket.Subprotocols(r) {
+		if after, ok := strings.CutPrefix(proto, "token."); ok && after == token {
+			return proto
+		}
+	}
+	return ""
+}
+
 // readLoop reads messages from a WebSocket connection.
 func (c *PicoChannel) readLoop(pc *picoConn) {
 	defer func() {
 		pc.close()
-		c.connections.Delete(pc.id)
-		c.connCount.Add(-1)
-		logger.InfoCF("pico", "WebSocket client disconnected", map[string]any{
-			"conn_id":    pc.id,
-			"session_id": pc.sessionID,
-		})
+		if removed := c.removeConnection(pc.id); removed != nil {
+			logger.InfoCF("pico", "WebSocket client disconnected", map[string]any{
+				"conn_id":    removed.id,
+				"session_id": removed.sessionID,
+			})
+		}
 	}()
 
 	readTimeout := time.Duration(c.config.ReadTimeout) * time.Second
diff --git a/pkg/channels/pico/pico_test.go b/pkg/channels/pico/pico_test.go
new file mode 100644
index 000000000..e712767ad
--- /dev/null
+++ b/pkg/channels/pico/pico_test.go
@@ -0,0 +1,144 @@
+package pico
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func newTestPicoChannel(t *testing.T) *PicoChannel {
+	t.Helper()
+
+	cfg := config.PicoConfig{}
+	cfg.SetToken("test-token")
+	ch, err := NewPicoChannel(cfg, bus.NewMessageBus())
+	if err != nil {
+		t.Fatalf("NewPicoChannel: %v", err)
+	}
+
+	ch.ctx = context.Background()
+	return ch
+}
+
+func TestCreateAndAddConnection_RespectsMaxConnectionsConcurrently(t *testing.T) {
+	ch := newTestPicoChannel(t)
+
+	const (
+		maxConns   = 5
+		goroutines = 64
+		sessionID  = "session-a"
+	)
+
+	var wg sync.WaitGroup
+	var mu sync.Mutex
+	successCount := 0
+	errCount := 0
+
+	wg.Add(goroutines)
+	for i := 0; i < goroutines; i++ {
+		go func() {
+			defer wg.Done()
+
+			pc, err := ch.createAndAddConnection(nil, sessionID, maxConns)
+			mu.Lock()
+			defer mu.Unlock()
+
+			if err == nil {
+				successCount++
+				if pc == nil {
+					t.Errorf("pc is nil on success")
+				}
+				return
+			}
+			if !errors.Is(err, channels.ErrTemporary) {
+				t.Errorf("unexpected error: %v", err)
+				return
+			}
+			errCount++
+		}()
+	}
+	wg.Wait()
+
+	if successCount > maxConns {
+		t.Fatalf("successCount=%d > maxConns=%d", successCount, maxConns)
+	}
+	if successCount+errCount != goroutines {
+		t.Fatalf("success=%d err=%d total=%d want=%d", successCount, errCount, successCount+errCount, goroutines)
+	}
+	if got := ch.currentConnCount(); got != maxConns {
+		t.Fatalf("currentConnCount=%d want=%d", got, maxConns)
+	}
+}
+
+func TestRemoveConnection_CleansBothIndexes(t *testing.T) {
+	ch := newTestPicoChannel(t)
+
+	pc, err := ch.createAndAddConnection(nil, "session-cleanup", 10)
+	if err != nil {
+		t.Fatalf("createAndAddConnection: %v", err)
+	}
+
+	removed := ch.removeConnection(pc.id)
+	if removed == nil {
+		t.Fatal("removeConnection returned nil")
+	}
+
+	ch.connsMu.RLock()
+	defer ch.connsMu.RUnlock()
+
+	if _, ok := ch.connections[pc.id]; ok {
+		t.Fatalf("connID %s still exists in connections", pc.id)
+	}
+	if _, ok := ch.sessionConnections[pc.sessionID]; ok {
+		t.Fatalf("session %s still exists in sessionConnections", pc.sessionID)
+	}
+	if got := len(ch.connections); got != 0 {
+		t.Fatalf("len(connections)=%d want=0", got)
+	}
+}
+
+func TestBroadcastToSession_TargetsOnlyRequestedSession(t *testing.T) {
+	ch := newTestPicoChannel(t)
+
+	target := &picoConn{id: "target", sessionID: "s-target"}
+	target.closed.Store(true)
+	ch.addConnForTest(target)
+
+	other := &picoConn{id: "other", sessionID: "s-other"}
+	ch.addConnForTest(other)
+
+	err := ch.broadcastToSession("pico:s-target", newMessage(TypeMessageCreate, map[string]any{"content": "hello"}))
+	if err == nil {
+		t.Fatal("expected send failure due to closed target connection")
+	}
+	if !errors.Is(err, channels.ErrSendFailed) {
+		t.Fatalf("expected ErrSendFailed, got %v", err)
+	}
+}
+
+func (c *PicoChannel) addConnForTest(pc *picoConn) {
+	c.connsMu.Lock()
+	defer c.connsMu.Unlock()
+	if c.connections == nil {
+		c.connections = make(map[string]*picoConn)
+	}
+	if c.sessionConnections == nil {
+		c.sessionConnections = make(map[string]map[string]*picoConn)
+	}
+	if _, exists := c.connections[pc.id]; exists {
+		panic(fmt.Sprintf("duplicate conn id in test: %s", pc.id))
+	}
+	c.connections[pc.id] = pc
+	bySession, ok := c.sessionConnections[pc.sessionID]
+	if !ok {
+		bySession = make(map[string]*picoConn)
+		c.sessionConnections[pc.sessionID] = bySession
+	}
+	bySession[pc.id] = pc
+}
diff --git a/pkg/channels/qq/audio_duration.go b/pkg/channels/qq/audio_duration.go
new file mode 100644
index 000000000..28a9b2e83
--- /dev/null
+++ b/pkg/channels/qq/audio_duration.go
@@ -0,0 +1,231 @@
+package qq
+
+import (
+	"encoding/binary"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+const qqVoiceMaxDuration = 60 * time.Second
+
+func qqAudioDuration(localPath, filename, contentType string) (time.Duration, bool, error) {
+	if localPath == "" {
+		return 0, false, nil
+	}
+
+	switch qqAudioDurationFormat(localPath, filename, contentType) {
+	case "wav":
+		return qqWAVDuration(localPath)
+	case "ogg":
+		return qqOggDuration(localPath)
+	default:
+		return 0, false, nil
+	}
+}
+
+func qqAudioDurationFormat(localPath, filename, contentType string) string {
+	contentType = strings.ToLower(contentType)
+
+	switch {
+	case strings.HasPrefix(contentType, "audio/wav"), strings.HasPrefix(contentType, "audio/x-wav"):
+		return "wav"
+	case strings.HasPrefix(contentType, "audio/ogg"),
+		contentType == "application/ogg",
+		contentType == "application/x-ogg":
+		return "ogg"
+	}
+
+	switch filepath.Ext(strings.ToLower(filename)) {
+	case ".wav":
+		return "wav"
+	case ".ogg", ".opus":
+		return "ogg"
+	}
+
+	switch filepath.Ext(strings.ToLower(localPath)) {
+	case ".wav":
+		return "wav"
+	case ".ogg", ".opus":
+		return "ogg"
+	}
+
+	return ""
+}
+
+func qqWAVDuration(localPath string) (time.Duration, bool, error) {
+	file, err := os.Open(localPath)
+	if err != nil {
+		return 0, false, err
+	}
+	defer file.Close()
+
+	var header [12]byte
+	if _, err := io.ReadFull(file, header[:]); err != nil {
+		return 0, false, err
+	}
+
+	var order binary.ByteOrder
+	switch string(header[:4]) {
+	case "RIFF":
+		order = binary.LittleEndian
+	case "RIFX":
+		order = binary.BigEndian
+	default:
+		return 0, false, nil
+	}
+
+	if string(header[8:12]) != "WAVE" {
+		return 0, false, nil
+	}
+
+	var byteRate uint32
+	var dataSize uint32
+	var foundFmt bool
+	var foundData bool
+
+	for {
+		var chunkHeader [8]byte
+		if _, err := io.ReadFull(file, chunkHeader[:]); err != nil {
+			if err == io.EOF {
+				break
+			}
+			return 0, false, err
+		}
+
+		chunkSize := order.Uint32(chunkHeader[4:8])
+		switch string(chunkHeader[:4]) {
+		case "fmt ":
+			chunkData := make([]byte, chunkSize)
+			if _, err := io.ReadFull(file, chunkData); err != nil {
+				return 0, false, err
+			}
+			if len(chunkData) >= 12 {
+				byteRate = order.Uint32(chunkData[8:12])
+				foundFmt = true
+			}
+		case "data":
+			dataSize = chunkSize
+			foundData = true
+			if _, err := io.CopyN(io.Discard, file, int64(chunkSize)); err != nil {
+				return 0, false, err
+			}
+		default:
+			if _, err := io.CopyN(io.Discard, file, int64(chunkSize)); err != nil {
+				return 0, false, err
+			}
+		}
+
+		if chunkSize%2 == 1 {
+			if _, err := io.CopyN(io.Discard, file, 1); err != nil {
+				return 0, false, err
+			}
+		}
+
+		if foundFmt && foundData {
+			break
+		}
+	}
+
+	if !foundFmt || !foundData || byteRate == 0 {
+		return 0, false, nil
+	}
+
+	durationNS := int64(dataSize) * int64(time.Second) / int64(byteRate)
+	return time.Duration(durationNS), true, nil
+}
+
+func qqOggDuration(localPath string) (time.Duration, bool, error) {
+	file, err := os.Open(localPath)
+	if err != nil {
+		return 0, false, err
+	}
+	defer file.Close()
+
+	var firstPacket []byte
+	var codec string
+	var sampleRate uint32
+	var lastGranule uint64
+	var haveGranule bool
+
+	for {
+		var header [27]byte
+		if _, err := io.ReadFull(file, header[:]); err != nil {
+			if err == io.EOF {
+				break
+			}
+			return 0, false, err
+		}
+
+		if string(header[:4]) != "OggS" {
+			return 0, false, nil
+		}
+
+		pageSegments := int(header[26])
+		segments := make([]byte, pageSegments)
+		if _, err := io.ReadFull(file, segments); err != nil {
+			return 0, false, err
+		}
+
+		payloadLen := 0
+		for _, segLen := range segments {
+			payloadLen += int(segLen)
+		}
+
+		payload := make([]byte, payloadLen)
+		if _, err := io.ReadFull(file, payload); err != nil {
+			return 0, false, err
+		}
+
+		granule := binary.LittleEndian.Uint64(header[6:14])
+		if granule != ^uint64(0) {
+			lastGranule = granule
+			haveGranule = true
+		}
+
+		if codec == "" {
+			offset := 0
+			for _, segLen := range segments {
+				firstPacket = append(firstPacket, payload[offset:offset+int(segLen)]...)
+				offset += int(segLen)
+				if segLen < 255 {
+					codec, sampleRate = qqParseOggCodec(firstPacket)
+					break
+				}
+			}
+		}
+	}
+
+	if !haveGranule || codec == "" {
+		return 0, false, nil
+	}
+
+	switch codec {
+	case "opus":
+		return time.Duration(lastGranule) * time.Second / 48000, true, nil
+	case "vorbis":
+		if sampleRate == 0 {
+			return 0, false, nil
+		}
+		return time.Duration(lastGranule) * time.Second / time.Duration(sampleRate), true, nil
+	default:
+		return 0, false, nil
+	}
+}
+
+func qqParseOggCodec(packet []byte) (string, uint32) {
+	if len(packet) >= 8 && string(packet[:8]) == "OpusHead" {
+		return "opus", 48000
+	}
+
+	if len(packet) >= 16 && packet[0] == 0x01 && string(packet[1:7]) == "vorbis" {
+		sampleRate := binary.LittleEndian.Uint32(packet[12:16])
+		if sampleRate > 0 {
+			return "vorbis", sampleRate
+		}
+	}
+
+	return "", 0
+}
diff --git a/pkg/channels/qq/botgo_logger.go b/pkg/channels/qq/botgo_logger.go
new file mode 100644
index 000000000..e1d2462a3
--- /dev/null
+++ b/pkg/channels/qq/botgo_logger.go
@@ -0,0 +1,41 @@
+package qq
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// botGoLogger preserves useful SDK info logs while demoting noisy heartbeat
+// traffic to DEBUG so long-running QQ sessions do not spam the console.
+type botGoLogger struct {
+	*logger.Logger
+}
+
+func newBotGoLogger(component string) *botGoLogger {
+	return &botGoLogger{Logger: logger.NewLogger(component)}
+}
+
+func (b *botGoLogger) Info(v ...any) {
+	message := fmt.Sprint(v...)
+	if shouldDemoteBotGoInfo(message) {
+		b.Logger.Debug(message)
+		return
+	}
+	b.Logger.Info(message)
+}
+
+func (b *botGoLogger) Infof(format string, v ...any) {
+	message := fmt.Sprintf(format, v...)
+	if shouldDemoteBotGoInfo(message) {
+		b.Logger.Debug(message)
+		return
+	}
+	b.Logger.Info(message)
+}
+
+func shouldDemoteBotGoInfo(message string) bool {
+	return strings.Contains(message, " write Heartbeat message") ||
+		strings.Contains(message, " receive HeartbeatAck message")
+}
diff --git a/pkg/channels/qq/qq.go b/pkg/channels/qq/qq.go
index 112964143..4ea71f6df 100644
--- a/pkg/channels/qq/qq.go
+++ b/pkg/channels/qq/qq.go
@@ -2,14 +2,26 @@ package qq
 
 import (
 	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
 	"fmt"
+	"net/http"
+	"net/url"
+	"os"
+	"path"
+	"path/filepath"
+	"regexp"
+	"strings"
 	"sync"
+	"sync/atomic"
 	"time"
 
 	"github.com/tencent-connect/botgo"
+	"github.com/tencent-connect/botgo/constant"
 	"github.com/tencent-connect/botgo/dto"
 	"github.com/tencent-connect/botgo/event"
-	"github.com/tencent-connect/botgo/openapi"
+	"github.com/tencent-connect/botgo/openapi/options"
 	"github.com/tencent-connect/botgo/token"
 	"golang.org/x/oauth2"
 
@@ -18,44 +30,89 @@ import (
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/identity"
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
+	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
+const (
+	dedupTTL      = 5 * time.Minute
+	dedupInterval = 60 * time.Second
+	dedupMaxSize  = 10000 // hard cap on dedup map entries
+	typingResend  = 8 * time.Second
+	typingSeconds = 10
+	bytesPerMiB   = 1024 * 1024
+)
+
+type qqAPI interface {
+	WS(ctx context.Context, params map[string]string, body string) (*dto.WebsocketAP, error)
+	PostGroupMessage(
+		ctx context.Context, groupID string, msg dto.APIMessage, opt ...options.Option,
+	) (*dto.Message, error)
+	PostC2CMessage(
+		ctx context.Context, userID string, msg dto.APIMessage, opt ...options.Option,
+	) (*dto.Message, error)
+	Transport(ctx context.Context, method, url string, body any) ([]byte, error)
+}
+
 type QQChannel struct {
 	*channels.BaseChannel
 	config         config.QQConfig
-	api            openapi.OpenAPI
+	api            qqAPI
 	tokenSource    oauth2.TokenSource
 	ctx            context.Context
 	cancel         context.CancelFunc
 	sessionManager botgo.SessionManager
-	processedIDs   map[string]bool
-	mu             sync.RWMutex
+	downloadFn     func(urlStr, filename string) string
+
+	// Chat routing: track whether a chatID is group or direct.
+	chatType sync.Map // chatID → "group" | "direct"
+
+	// Passive reply: store last inbound message ID per chat.
+	lastMsgID sync.Map // chatID → string
+
+	// msg_seq: per-chat atomic counter for multi-part replies.
+	msgSeqCounters sync.Map // chatID → *atomic.Uint64
+
+	// Time-based dedup replacing the unbounded map.
+	dedup   map[string]time.Time
+	muDedup sync.Mutex
+
+	// done is closed on Stop to shut down the dedup janitor.
+	done     chan struct{}
+	stopOnce sync.Once
 }
 
 func NewQQChannel(cfg config.QQConfig, messageBus *bus.MessageBus) (*QQChannel, error) {
 	base := channels.NewBaseChannel("qq", cfg, messageBus, cfg.AllowFrom,
+		channels.WithMaxMessageLength(cfg.MaxMessageLength),
 		channels.WithGroupTrigger(cfg.GroupTrigger),
 		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
 	)
 
 	return &QQChannel{
-		BaseChannel:  base,
-		config:       cfg,
-		processedIDs: make(map[string]bool),
+		BaseChannel: base,
+		config:      cfg,
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
 	}, nil
 }
 
 func (c *QQChannel) Start(ctx context.Context) error {
-	if c.config.AppID == "" || c.config.AppSecret == "" {
+	if c.config.AppID == "" || c.config.AppSecret() == "" {
 		return fmt.Errorf("QQ app_id and app_secret not configured")
 	}
 
+	botgo.SetLogger(newBotGoLogger("botgo"))
 	logger.InfoC("qq", "Starting QQ bot (WebSocket mode)")
 
+	// Reinitialize shutdown signal for clean restart.
+	c.done = make(chan struct{})
+	c.stopOnce = sync.Once{}
+
 	// create token source
 	credentials := &token.QQBotCredentials{
 		AppID:     c.config.AppID,
-		AppSecret: c.config.AppSecret,
+		AppSecret: c.config.AppSecret(),
 	}
 	c.tokenSource = token.NewQQBotTokenSource(credentials)
 
@@ -99,6 +156,15 @@ func (c *QQChannel) Start(ctx context.Context) error {
 		}
 	}()
 
+	// start dedup janitor goroutine
+	go c.dedupJanitor()
+
+	// Pre-register reasoning_channel_id as group chat if configured,
+	// so outbound-only destinations are routed correctly.
+	if c.config.ReasoningChannelID != "" {
+		c.chatType.Store(c.config.ReasoningChannelID, "group")
+	}
+
 	c.SetRunning(true)
 	logger.InfoC("qq", "QQ bot started successfully")
 
@@ -109,6 +175,9 @@ func (c *QQChannel) Stop(ctx context.Context) error {
 	logger.InfoC("qq", "Stopping QQ bot")
 	c.SetRunning(false)
 
+	// Signal the dedup janitor to stop (idempotent).
+	c.stopOnce.Do(func() { close(c.done) })
+
 	if c.cancel != nil {
 		c.cancel()
 	}
@@ -116,21 +185,69 @@ func (c *QQChannel) Stop(ctx context.Context) error {
 	return nil
 }
 
+// getChatKind returns the chat type for a given chatID ("group" or "direct").
+// Unknown chatIDs default to "group" and log a warning, since QQ group IDs are
+// more common as outbound-only destinations (e.g. reasoning_channel_id).
+func (c *QQChannel) getChatKind(chatID string) string {
+	if v, ok := c.chatType.Load(chatID); ok {
+		if k, ok := v.(string); ok {
+			return k
+		}
+	}
+	logger.DebugCF("qq", "Unknown chat type for chatID, defaulting to group", map[string]any{
+		"chat_id": chatID,
+	})
+	return "group"
+}
+
 func (c *QQChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	if !c.IsRunning() {
 		return channels.ErrNotRunning
 	}
 
-	// construct message
+	chatKind := c.getChatKind(msg.ChatID)
+
+	// Build message with content.
 	msgToCreate := &dto.MessageToCreate{
 		Content: msg.Content,
+		MsgType: dto.TextMsg,
+	}
+
+	// Use Markdown message type if enabled in config.
+	if c.config.SendMarkdown {
+		msgToCreate.MsgType = dto.MarkdownMsg
+		msgToCreate.Markdown = &dto.Markdown{
+			Content: msg.Content,
+		}
+		// Clear plain content to avoid sending duplicate text.
+		msgToCreate.Content = ""
+	}
+
+	c.applyPassiveReplyMetadata(msg.ChatID, msgToCreate)
+
+	// Sanitize URLs in group messages to avoid QQ's URL blacklist rejection.
+	if chatKind == "group" {
+		if msgToCreate.Content != "" {
+			msgToCreate.Content = sanitizeURLs(msgToCreate.Content)
+		}
+		if msgToCreate.Markdown != nil && msgToCreate.Markdown.Content != "" {
+			msgToCreate.Markdown.Content = sanitizeURLs(msgToCreate.Markdown.Content)
+		}
+	}
+
+	// Route to group or C2C.
+	var err error
+	if chatKind == "group" {
+		_, err = c.api.PostGroupMessage(ctx, msg.ChatID, msgToCreate)
+	} else {
+		_, err = c.api.PostC2CMessage(ctx, msg.ChatID, msgToCreate)
 	}
 
-	// send C2C message
-	_, err := c.api.PostC2CMessage(ctx, msg.ChatID, msgToCreate)
 	if err != nil {
-		logger.ErrorCF("qq", "Failed to send C2C message", map[string]any{
-			"error": err.Error(),
+		logger.ErrorCF("qq", "Failed to send message", map[string]any{
+			"chat_id":   msg.ChatID,
+			"chat_kind": chatKind,
+			"error":     err.Error(),
 		})
 		return fmt.Errorf("qq send: %w", channels.ErrTemporary)
 	}
@@ -138,7 +255,335 @@ func (c *QQChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
 	return nil
 }
 
-// handleC2CMessage handles QQ private messages
+// StartTyping implements channels.TypingCapable.
+// It sends an InputNotify (msg_type=6) immediately and re-sends every 8 seconds.
+// The returned stop function is idempotent and cancels the goroutine.
+func (c *QQChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+	// We need a stored msg_id for passive InputNotify; skip if none available.
+	v, ok := c.lastMsgID.Load(chatID)
+	if !ok {
+		return func() {}, nil
+	}
+	msgID, ok := v.(string)
+	if !ok || msgID == "" {
+		return func() {}, nil
+	}
+
+	chatKind := c.getChatKind(chatID)
+
+	sendTyping := func(sendCtx context.Context) {
+		typingMsg := &dto.MessageToCreate{
+			MsgType: dto.InputNotifyMsg,
+			MsgID:   msgID,
+			InputNotify: &dto.InputNotify{
+				InputType:   1,
+				InputSecond: typingSeconds,
+			},
+		}
+
+		var err error
+		if chatKind == "group" {
+			_, err = c.api.PostGroupMessage(sendCtx, chatID, typingMsg)
+		} else {
+			_, err = c.api.PostC2CMessage(sendCtx, chatID, typingMsg)
+		}
+		if err != nil {
+			logger.DebugCF("qq", "Failed to send typing indicator", map[string]any{
+				"chat_id": chatID,
+				"error":   err.Error(),
+			})
+		}
+	}
+
+	// Send immediately.
+	sendTyping(c.ctx)
+
+	typingCtx, cancel := context.WithCancel(c.ctx)
+	go func() {
+		ticker := time.NewTicker(typingResend)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-typingCtx.Done():
+				return
+			case <-ticker.C:
+				sendTyping(typingCtx)
+			}
+		}
+	}()
+
+	return cancel, nil
+}
+
+// SendMedia implements the channels.MediaSender interface.
+// QQ group/C2C media sending is a two-step flow:
+// 1. Upload media to /files using a remote URL or base64-encoded local bytes.
+// 2. Send a msg_type=7 message using the returned file_info.
+func (c *QQChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	chatKind := c.getChatKind(msg.ChatID)
+
+	for _, part := range msg.Parts {
+		fileInfo, err := c.uploadMedia(ctx, chatKind, msg.ChatID, part)
+		if err != nil {
+			logger.ErrorCF("qq", "Failed to upload media", map[string]any{
+				"type":    part.Type,
+				"chat_id": msg.ChatID,
+				"error":   err.Error(),
+			})
+			if errors.Is(err, channels.ErrSendFailed) {
+				return err
+			}
+			return fmt.Errorf("qq send media: %w", channels.ErrTemporary)
+		}
+
+		if err := c.sendUploadedMedia(ctx, chatKind, msg.ChatID, part, fileInfo); err != nil {
+			logger.ErrorCF("qq", "Failed to send media", map[string]any{
+				"type":    part.Type,
+				"chat_id": msg.ChatID,
+				"error":   err.Error(),
+			})
+			return fmt.Errorf("qq send media: %w", channels.ErrTemporary)
+		}
+	}
+
+	return nil
+}
+
+type qqMediaUpload struct {
+	FileType   uint64 `json:"file_type"`
+	URL        string `json:"url,omitempty"`
+	FileData   string `json:"file_data,omitempty"`
+	FileName   string `json:"file_name,omitempty"`
+	SrvSendMsg bool   `json:"srv_send_msg,omitempty"`
+}
+
+func (c *QQChannel) uploadMedia(
+	ctx context.Context,
+	chatKind, chatID string,
+	part bus.MediaPart,
+) ([]byte, error) {
+	payload, err := c.buildMediaUpload(part)
+	if err != nil {
+		return nil, err
+	}
+
+	body, err := c.api.Transport(ctx, http.MethodPost, c.mediaUploadURL(chatKind, chatID), payload)
+	if err != nil {
+		return nil, err
+	}
+
+	var uploaded dto.Message
+	if err := json.Unmarshal(body, &uploaded); err != nil {
+		return nil, fmt.Errorf("qq decode media upload response: %w", err)
+	}
+	if len(uploaded.FileInfo) == 0 {
+		return nil, fmt.Errorf("qq upload media: missing file_info")
+	}
+
+	return uploaded.FileInfo, nil
+}
+
+func (c *QQChannel) buildMediaUpload(part bus.MediaPart) (*qqMediaUpload, error) {
+	payload := &qqMediaUpload{}
+
+	mediaRef := part.Ref
+	if isHTTPURL(mediaRef) {
+		payload.FileType = qqFileType(c.outboundMediaType(part, ""))
+		payload.URL = mediaRef
+		payload.FileName = qqUploadFilename(part, mediaRef, payload.FileType)
+		return payload, nil
+	}
+
+	store := c.GetMediaStore()
+	if store == nil {
+		return nil, fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
+	}
+
+	resolved, meta, err := store.ResolveWithMeta(part.Ref)
+	if err != nil {
+		return nil, fmt.Errorf("qq resolve media ref %q: %v: %w", part.Ref, err, channels.ErrSendFailed)
+	}
+	if part.Filename == "" {
+		part.Filename = meta.Filename
+	}
+	if part.ContentType == "" {
+		part.ContentType = meta.ContentType
+	}
+
+	if isHTTPURL(resolved) {
+		payload.FileType = qqFileType(c.outboundMediaType(part, ""))
+		payload.URL = resolved
+		payload.FileName = qqUploadFilename(part, resolved, payload.FileType)
+		return payload, nil
+	}
+	payload.FileType = qqFileType(c.outboundMediaType(part, resolved))
+	payload.FileName = qqUploadFilename(part, resolved, payload.FileType)
+
+	if limitBytes := c.maxBase64FileSizeBytes(); limitBytes > 0 {
+		info, statErr := os.Stat(resolved)
+		if statErr != nil {
+			return nil, fmt.Errorf("qq stat local media %q: %v: %w", resolved, statErr, channels.ErrSendFailed)
+		}
+		if info.Size() > limitBytes {
+			return nil, fmt.Errorf(
+				"qq local media %q exceeds max_base64_file_size_mib (%d > %d bytes): %w",
+				resolved,
+				info.Size(),
+				limitBytes,
+				channels.ErrSendFailed,
+			)
+		}
+	}
+
+	data, err := os.ReadFile(resolved)
+	if err != nil {
+		return nil, fmt.Errorf("qq read local media %q: %v: %w", resolved, err, channels.ErrSendFailed)
+	}
+
+	payload.FileData = base64.StdEncoding.EncodeToString(data)
+	return payload, nil
+}
+
+func qqUploadFilename(part bus.MediaPart, resolved string, fileType uint64) string {
+	if fileType != qqFileType("file") {
+		return ""
+	}
+	if part.Filename != "" {
+		return part.Filename
+	}
+	if isHTTPURL(resolved) {
+		if parsed, err := url.Parse(resolved); err == nil {
+			if base := path.Base(parsed.Path); base != "" && base != "." && base != "/" {
+				return base
+			}
+		}
+		return ""
+	}
+
+	if base := filepath.Base(resolved); base != "" && base != "." {
+		return base
+	}
+	return ""
+}
+
+func (c *QQChannel) outboundMediaType(part bus.MediaPart, localPath string) string {
+	if part.Type != "audio" {
+		return part.Type
+	}
+
+	if localPath == "" {
+		logger.InfoCF("qq", "Sending audio as file because duration is unavailable", map[string]any{
+			"ref":      part.Ref,
+			"filename": part.Filename,
+		})
+		return "file"
+	}
+
+	duration, ok, err := qqAudioDuration(localPath, part.Filename, part.ContentType)
+	if err != nil {
+		logger.WarnCF("qq", "Failed to detect audio duration, sending as file", map[string]any{
+			"ref":      part.Ref,
+			"filename": part.Filename,
+			"error":    err.Error(),
+		})
+		return "file"
+	}
+	if !ok {
+		logger.InfoCF("qq", "Sending audio as file because duration is unavailable", map[string]any{
+			"ref":      part.Ref,
+			"filename": part.Filename,
+		})
+		return "file"
+	}
+	if duration > qqVoiceMaxDuration {
+		logger.InfoCF("qq", "Sending audio as file because it exceeds QQ voice limit", map[string]any{
+			"ref":              part.Ref,
+			"filename":         part.Filename,
+			"duration_seconds": duration.Seconds(),
+			"limit_seconds":    qqVoiceMaxDuration.Seconds(),
+		})
+		return "file"
+	}
+
+	return "audio"
+}
+
+func (c *QQChannel) sendUploadedMedia(
+	ctx context.Context,
+	chatKind, chatID string,
+	part bus.MediaPart,
+	fileInfo []byte,
+) error {
+	msg := &dto.MessageToCreate{
+		Content: part.Caption,
+		MsgType: dto.RichMediaMsg,
+		Media: &dto.MediaInfo{
+			FileInfo: fileInfo,
+		},
+	}
+	c.applyPassiveReplyMetadata(chatID, msg)
+
+	if chatKind == "group" && msg.Content != "" {
+		msg.Content = sanitizeURLs(msg.Content)
+	}
+
+	if chatKind == "group" {
+		_, err := c.api.PostGroupMessage(ctx, chatID, msg)
+		return err
+	}
+	_, err := c.api.PostC2CMessage(ctx, chatID, msg)
+	return err
+}
+
+func (c *QQChannel) applyPassiveReplyMetadata(chatID string, msg *dto.MessageToCreate) {
+	if v, ok := c.lastMsgID.Load(chatID); ok {
+		if msgID, ok := v.(string); ok && msgID != "" {
+			msg.MsgID = msgID
+
+			// Increment msg_seq atomically for multi-part replies.
+			if counterVal, ok := c.msgSeqCounters.Load(chatID); ok {
+				if counter, ok := counterVal.(*atomic.Uint64); ok {
+					seq := counter.Add(1)
+					msg.MsgSeq = uint32(seq)
+				}
+			}
+		}
+	}
+}
+
+func (c *QQChannel) mediaUploadURL(chatKind, chatID string) string {
+	base := constant.APIDomain
+	if chatKind == "group" {
+		return fmt.Sprintf("%s/v2/groups/%s/files", base, chatID)
+	}
+	return fmt.Sprintf("%s/v2/users/%s/files", base, chatID)
+}
+
+func qqFileType(partType string) uint64 {
+	switch partType {
+	case "image":
+		return 1
+	case "video":
+		return 2
+	case "audio":
+		return 3
+	default:
+		return 4
+	}
+}
+
+func (c *QQChannel) maxBase64FileSizeBytes() int64 {
+	if c.config.MaxBase64FileSizeMiB <= 0 {
+		return 0
+	}
+	return c.config.MaxBase64FileSizeMiB * bytesPerMiB
+}
+
+// handleC2CMessage handles QQ private messages.
 func (c *QQChannel) handleC2CMessage() event.C2CMessageEventHandler {
 	return func(event *dto.WSPayload, data *dto.WSC2CMessageData) error {
 		// deduplication check
@@ -155,21 +600,6 @@ func (c *QQChannel) handleC2CMessage() event.C2CMessageEventHandler {
 			return nil
 		}
 
-		// extract message content
-		content := data.Content
-		if content == "" {
-			logger.DebugC("qq", "Received empty message, ignoring")
-			return nil
-		}
-
-		logger.InfoCF("qq", "Received C2C message", map[string]any{
-			"sender": senderID,
-			"length": len(content),
-		})
-
-		// 转发到消息总线
-		metadata := map[string]string{}
-
 		sender := bus.SenderInfo{
 			Platform:    "qq",
 			PlatformID:  data.Author.ID,
@@ -180,13 +610,40 @@ func (c *QQChannel) handleC2CMessage() event.C2CMessageEventHandler {
 			return nil
 		}
 
+		content := strings.TrimSpace(data.Content)
+		mediaPaths, attachmentNotes := c.extractInboundAttachments(senderID, data.ID, data.Attachments)
+		for _, note := range attachmentNotes {
+			content = appendContent(content, note)
+		}
+		if content == "" && len(mediaPaths) == 0 {
+			logger.DebugC("qq", "Received empty C2C message with no attachments, ignoring")
+			return nil
+		}
+
+		logger.InfoCF("qq", "Received C2C message", map[string]any{
+			"sender":      senderID,
+			"length":      len(content),
+			"media_count": len(mediaPaths),
+		})
+
+		// Store chat routing context.
+		c.chatType.Store(senderID, "direct")
+		c.lastMsgID.Store(senderID, data.ID)
+
+		// Reset msg_seq counter for new inbound message.
+		c.msgSeqCounters.Store(senderID, new(atomic.Uint64))
+
+		metadata := map[string]string{
+			"account_id": senderID,
+		}
+
 		c.HandleMessage(c.ctx,
 			bus.Peer{Kind: "direct", ID: senderID},
 			data.ID,
 			senderID,
 			senderID,
 			content,
-			[]string{},
+			mediaPaths,
 			metadata,
 			sender,
 		)
@@ -195,7 +652,7 @@ func (c *QQChannel) handleC2CMessage() event.C2CMessageEventHandler {
 	}
 }
 
-// handleGroupATMessage handles QQ group @ messages
+// handleGroupATMessage handles QQ group @ messages.
 func (c *QQChannel) handleGroupATMessage() event.GroupATMessageEventHandler {
 	return func(event *dto.WSPayload, data *dto.WSGroupATMessageData) error {
 		// deduplication check
@@ -212,31 +669,6 @@ func (c *QQChannel) handleGroupATMessage() event.GroupATMessageEventHandler {
 			return nil
 		}
 
-		// extract message content (remove @ bot part)
-		content := data.Content
-		if content == "" {
-			logger.DebugC("qq", "Received empty group message, ignoring")
-			return nil
-		}
-
-		// GroupAT event means bot is always mentioned; apply group trigger filtering
-		respond, cleaned := c.ShouldRespondInGroup(true, content)
-		if !respond {
-			return nil
-		}
-		content = cleaned
-
-		logger.InfoCF("qq", "Received group AT message", map[string]any{
-			"sender": senderID,
-			"group":  data.GroupID,
-			"length": len(content),
-		})
-
-		// 转发到消息总线（使用 GroupID 作为 ChatID）
-		metadata := map[string]string{
-			"group_id": data.GroupID,
-		}
-
 		sender := bus.SenderInfo{
 			Platform:    "qq",
 			PlatformID:  data.Author.ID,
@@ -247,13 +679,49 @@ func (c *QQChannel) handleGroupATMessage() event.GroupATMessageEventHandler {
 			return nil
 		}
 
+		content := strings.TrimSpace(data.Content)
+		mediaPaths, attachmentNotes := c.extractInboundAttachments(data.GroupID, data.ID, data.Attachments)
+		for _, note := range attachmentNotes {
+			content = appendContent(content, note)
+		}
+
+		// GroupAT event means bot is always mentioned; apply group trigger filtering.
+		respond, cleaned := c.ShouldRespondInGroup(true, content)
+		if !respond {
+			return nil
+		}
+		content = cleaned
+		if content == "" && len(mediaPaths) == 0 {
+			logger.DebugC("qq", "Received empty group message with no attachments, ignoring")
+			return nil
+		}
+
+		logger.InfoCF("qq", "Received group AT message", map[string]any{
+			"sender":      senderID,
+			"group":       data.GroupID,
+			"length":      len(content),
+			"media_count": len(mediaPaths),
+		})
+
+		// Store chat routing context using GroupID as chatID.
+		c.chatType.Store(data.GroupID, "group")
+		c.lastMsgID.Store(data.GroupID, data.ID)
+
+		// Reset msg_seq counter for new inbound message.
+		c.msgSeqCounters.Store(data.GroupID, new(atomic.Uint64))
+
+		metadata := map[string]string{
+			"account_id": senderID,
+			"group_id":   data.GroupID,
+		}
+
 		c.HandleMessage(c.ctx,
 			bus.Peer{Kind: "group", ID: data.GroupID},
 			data.ID,
 			senderID,
 			data.GroupID,
 			content,
-			[]string{},
+			mediaPaths,
 			metadata,
 			sender,
 		)
@@ -262,29 +730,264 @@ func (c *QQChannel) handleGroupATMessage() event.GroupATMessageEventHandler {
 	}
 }
 
-// isDuplicate 检查消息是否重复
-func (c *QQChannel) isDuplicate(messageID string) bool {
-	c.mu.Lock()
-	defer c.mu.Unlock()
-
-	if c.processedIDs[messageID] {
-		return true
+func (c *QQChannel) extractInboundAttachments(
+	chatID, messageID string,
+	attachments []*dto.MessageAttachment,
+) ([]string, []string) {
+	if len(attachments) == 0 {
+		return nil, nil
 	}
 
-	c.processedIDs[messageID] = true
+	scope := channels.BuildMediaScope("qq", chatID, messageID)
+	mediaPaths := make([]string, 0, len(attachments))
+	notes := make([]string, 0, len(attachments))
 
-	// 简单清理：限制 map 大小
-	if len(c.processedIDs) > 10000 {
-		// 清空一半
-		count := 0
-		for id := range c.processedIDs {
-			if count >= 5000 {
-				break
+	storeMedia := func(localPath string, attachment *dto.MessageAttachment) string {
+		if store := c.GetMediaStore(); store != nil {
+			ref, err := store.Store(localPath, media.MediaMeta{
+				Filename:      qqAttachmentFilename(attachment),
+				ContentType:   attachment.ContentType,
+				Source:        "qq",
+				CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
+			}, scope)
+			if err == nil {
+				return ref
+			}
+		}
+		return localPath
+	}
+
+	for _, attachment := range attachments {
+		if attachment == nil {
+			continue
+		}
+
+		filename := qqAttachmentFilename(attachment)
+		if localPath := c.downloadAttachment(attachment.URL, filename); localPath != "" {
+			mediaPaths = append(mediaPaths, storeMedia(localPath, attachment))
+		} else if attachment.URL != "" {
+			mediaPaths = append(mediaPaths, attachment.URL)
+		}
+
+		notes = append(notes, qqAttachmentNote(attachment))
+	}
+
+	return mediaPaths, notes
+}
+
+func (c *QQChannel) downloadAttachment(urlStr, filename string) string {
+	if urlStr == "" {
+		return ""
+	}
+	if c.downloadFn != nil {
+		return c.downloadFn(urlStr, filename)
+	}
+
+	return utils.DownloadFile(urlStr, filename, utils.DownloadOptions{
+		LoggerPrefix: "qq",
+		ExtraHeaders: c.downloadHeaders(),
+	})
+}
+
+func (c *QQChannel) downloadHeaders() map[string]string {
+	headers := map[string]string{}
+
+	if c.config.AppID != "" {
+		headers["X-Union-Appid"] = c.config.AppID
+	}
+
+	if c.tokenSource != nil {
+		if tk, err := c.tokenSource.Token(); err == nil && tk.AccessToken != "" {
+			auth := strings.TrimSpace(tk.TokenType + " " + tk.AccessToken)
+			if auth != "" {
+				headers["Authorization"] = auth
 			}
-			delete(c.processedIDs, id)
-			count++
 		}
 	}
 
+	if len(headers) == 0 {
+		return nil
+	}
+	return headers
+}
+
+func qqAttachmentFilename(attachment *dto.MessageAttachment) string {
+	if attachment == nil {
+		return "attachment"
+	}
+	if attachment.FileName != "" {
+		return attachment.FileName
+	}
+	if attachment.URL != "" {
+		if parsed, err := url.Parse(attachment.URL); err == nil {
+			if base := path.Base(parsed.Path); base != "" && base != "." && base != "/" {
+				return base
+			}
+		}
+	}
+
+	switch qqAttachmentKind(attachment) {
+	case "image":
+		return "image"
+	case "audio":
+		return "audio"
+	case "video":
+		return "video"
+	default:
+		return "attachment"
+	}
+}
+
+func qqAttachmentKind(attachment *dto.MessageAttachment) string {
+	if attachment == nil {
+		return "file"
+	}
+
+	contentType := strings.ToLower(attachment.ContentType)
+	filename := strings.ToLower(attachment.FileName)
+
+	switch {
+	case strings.HasPrefix(contentType, "image/"):
+		return "image"
+	case strings.HasPrefix(contentType, "video/"):
+		return "video"
+	case strings.HasPrefix(contentType, "audio/"), contentType == "application/ogg", contentType == "application/x-ogg":
+		return "audio"
+	}
+
+	switch filepath.Ext(filename) {
+	case ".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".svg":
+		return "image"
+	case ".mp4", ".avi", ".mov", ".webm", ".mkv":
+		return "video"
+	case ".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".wma", ".opus", ".silk":
+		return "audio"
+	default:
+		return "file"
+	}
+}
+
+func qqAttachmentNote(attachment *dto.MessageAttachment) string {
+	filename := qqAttachmentFilename(attachment)
+
+	switch qqAttachmentKind(attachment) {
+	case "image":
+		return fmt.Sprintf("[image: %s]", filename)
+	case "audio":
+		return fmt.Sprintf("[audio: %s]", filename)
+	case "video":
+		return fmt.Sprintf("[video: %s]", filename)
+	default:
+		return fmt.Sprintf("[file: %s]", filename)
+	}
+}
+
+// isDuplicate checks whether a message has been seen within the TTL window.
+// It also enforces a hard cap on map size by evicting oldest entries.
+func (c *QQChannel) isDuplicate(messageID string) bool {
+	c.muDedup.Lock()
+	defer c.muDedup.Unlock()
+
+	if ts, exists := c.dedup[messageID]; exists && time.Since(ts) < dedupTTL {
+		return true
+	}
+
+	// Enforce hard cap: evict oldest entries when at capacity.
+	if len(c.dedup) >= dedupMaxSize {
+		var oldestID string
+		var oldestTS time.Time
+		for id, ts := range c.dedup {
+			if oldestID == "" || ts.Before(oldestTS) {
+				oldestID = id
+				oldestTS = ts
+			}
+		}
+		if oldestID != "" {
+			delete(c.dedup, oldestID)
+		}
+	}
+
+	c.dedup[messageID] = time.Now()
 	return false
 }
+
+// dedupJanitor periodically evicts expired entries from the dedup map.
+func (c *QQChannel) dedupJanitor() {
+	ticker := time.NewTicker(dedupInterval)
+	defer ticker.Stop()
+
+	for {
+		select {
+		case <-c.done:
+			return
+		case <-ticker.C:
+			// Collect expired keys under read-like scan.
+			c.muDedup.Lock()
+			now := time.Now()
+			var expired []string
+			for id, ts := range c.dedup {
+				if now.Sub(ts) >= dedupTTL {
+					expired = append(expired, id)
+				}
+			}
+			for _, id := range expired {
+				delete(c.dedup, id)
+			}
+			c.muDedup.Unlock()
+		}
+	}
+}
+
+// isHTTPURL returns true if s starts with http:// or https://.
+func isHTTPURL(s string) bool {
+	return strings.HasPrefix(s, "http://") || strings.HasPrefix(s, "https://")
+}
+
+func appendContent(content, suffix string) string {
+	if suffix == "" {
+		return content
+	}
+	if content == "" {
+		return suffix
+	}
+	return content + "\n" + suffix
+}
+
+// urlPattern matches URLs with explicit http(s):// scheme.
+// Only scheme-prefixed URLs are matched to avoid false positives on bare text
+// like version numbers (e.g., "1.2.3") or domain-like fragments.
+var urlPattern = regexp.MustCompile(
+	`(?i)` +
+		`https?://` + // required scheme
+		`(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+` + // domain parts
+		`[a-zA-Z]{2,}` + // TLD
+		`(?:[/?#]\S*)?`, // optional path/query/fragment
+)
+
+// sanitizeURLs replaces dots in URL domains with "。" (fullwidth period)
+// to prevent QQ's URL blacklist from rejecting the message.
+func sanitizeURLs(text string) string {
+	return urlPattern.ReplaceAllStringFunc(text, func(match string) string {
+		// Split into scheme + rest (scheme is always present).
+		idx := strings.Index(match, "://")
+		scheme := match[:idx+3]
+		rest := match[idx+3:]
+
+		// Find where the domain ends (first / ? or #).
+		domainEnd := len(rest)
+		for i, ch := range rest {
+			if ch == '/' || ch == '?' || ch == '#' {
+				domainEnd = i
+				break
+			}
+		}
+
+		domain := rest[:domainEnd]
+		path := rest[domainEnd:]
+
+		// Replace dots in domain only.
+		domain = strings.ReplaceAll(domain, ".", "。")
+
+		return scheme + domain + path
+	})
+}
diff --git a/pkg/channels/qq/qq_test.go b/pkg/channels/qq/qq_test.go
new file mode 100644
index 000000000..7ed736827
--- /dev/null
+++ b/pkg/channels/qq/qq_test.go
@@ -0,0 +1,740 @@
+package qq
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/json"
+	"errors"
+	"os"
+	"strings"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/tencent-connect/botgo/dto"
+	"github.com/tencent-connect/botgo/openapi/options"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+func TestHandleC2CMessage_IncludesAccountIDMetadata(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+	}
+
+	err := ch.handleC2CMessage()(nil, &dto.WSC2CMessageData{
+		ID:      "msg-1",
+		Content: "hello",
+		Author: &dto.User{
+			ID: "7750283E123456",
+		},
+	})
+	if err != nil {
+		t.Fatalf("handleC2CMessage() error = %v", err)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+
+	for {
+		select {
+		case <-ctx.Done():
+			t.Fatal("timeout waiting for inbound message")
+			return
+		case inbound, ok := <-messageBus.InboundChan():
+			if !ok {
+				t.Fatal("expected inbound message")
+			}
+			if inbound.Metadata["account_id"] != "7750283E123456" {
+				t.Fatalf("account_id metadata = %q, want %q", inbound.Metadata["account_id"], "7750283E123456")
+			}
+			return
+		}
+	}
+}
+
+func TestHandleC2CMessage_AttachmentOnlyPublishesMedia(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	store := media.NewFileMediaStore()
+	localPath := writeTempFile(t, t.TempDir(), "image.png", []byte("fake-image"))
+
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+		downloadFn: func(urlStr, filename string) string {
+			if filename != "image.png" {
+				t.Fatalf("download filename = %q, want image.png", filename)
+			}
+			return localPath
+		},
+	}
+	ch.SetMediaStore(store)
+
+	err := ch.handleC2CMessage()(nil, &dto.WSC2CMessageData{
+		ID:      "msg-attachment",
+		Content: "",
+		Author: &dto.User{
+			ID: "7750283E123456",
+		},
+		Attachments: []*dto.MessageAttachment{{
+			URL:         "https://example.com/image.png",
+			FileName:    "image.png",
+			ContentType: "image/png",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("handleC2CMessage() error = %v", err)
+	}
+
+	inbound := waitInboundMessage(t, messageBus)
+	if inbound.Content != "[image: image.png]" {
+		t.Fatalf("inbound.Content = %q", inbound.Content)
+	}
+	if len(inbound.Media) != 1 {
+		t.Fatalf("len(inbound.Media) = %d, want 1", len(inbound.Media))
+	}
+	if !strings.HasPrefix(inbound.Media[0], "media://") {
+		t.Fatalf("inbound.Media[0] = %q, want media:// ref", inbound.Media[0])
+	}
+	_, meta, err := store.ResolveWithMeta(inbound.Media[0])
+	if err != nil {
+		t.Fatalf("ResolveWithMeta() error = %v", err)
+	}
+	if meta.Filename != "image.png" {
+		t.Fatalf("meta.Filename = %q, want image.png", meta.Filename)
+	}
+	if meta.ContentType != "image/png" {
+		t.Fatalf("meta.ContentType = %q, want image/png", meta.ContentType)
+	}
+}
+
+func TestHandleGroupATMessage_AttachmentOnlyPublishesMedia(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	store := media.NewFileMediaStore()
+	localPath := writeTempFile(t, t.TempDir(), "report.pdf", []byte("fake-pdf"))
+
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+		downloadFn: func(urlStr, filename string) string {
+			if filename != "report.pdf" {
+				t.Fatalf("download filename = %q, want report.pdf", filename)
+			}
+			return localPath
+		},
+	}
+	ch.SetMediaStore(store)
+
+	err := ch.handleGroupATMessage()(nil, &dto.WSGroupATMessageData{
+		ID:      "group-attachment",
+		GroupID: "group-1",
+		Content: "",
+		Author: &dto.User{
+			ID: "7750283E123456",
+		},
+		Attachments: []*dto.MessageAttachment{{
+			URL:         "https://example.com/report.pdf",
+			FileName:    "report.pdf",
+			ContentType: "application/pdf",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("handleGroupATMessage() error = %v", err)
+	}
+
+	inbound := waitInboundMessage(t, messageBus)
+	if inbound.Content != "[file: report.pdf]" {
+		t.Fatalf("inbound.Content = %q", inbound.Content)
+	}
+	if len(inbound.Media) != 1 {
+		t.Fatalf("len(inbound.Media) = %d, want 1", len(inbound.Media))
+	}
+	if !strings.HasPrefix(inbound.Media[0], "media://") {
+		t.Fatalf("inbound.Media[0] = %q, want media:// ref", inbound.Media[0])
+	}
+	if inbound.Peer.Kind != "group" || inbound.Peer.ID != "group-1" {
+		t.Fatalf("inbound.Peer = %+v, want group/group-1", inbound.Peer)
+	}
+}
+
+func TestSendMedia_UploadsLocalFileAsBase64(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	store := media.NewFileMediaStore()
+
+	tmpFile, err := os.CreateTemp(t.TempDir(), "qq-media-*.png")
+	if err != nil {
+		t.Fatalf("CreateTemp() error = %v", err)
+	}
+	defer tmpFile.Close()
+
+	content := []byte("local-image-data")
+	if _, writeErr := tmpFile.Write(content); writeErr != nil {
+		t.Fatalf("Write() error = %v", writeErr)
+	}
+
+	ref, err := store.Store(tmpFile.Name(), media.MediaMeta{
+		Filename:    "reply.png",
+		ContentType: "image/png",
+	}, "qq:test")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	api := &fakeQQAPI{
+		transportResp: mustJSON(t, dto.Message{FileInfo: []byte("uploaded-file-info")}),
+	}
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		api:         api,
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+	}
+	ch.SetRunning(true)
+	ch.SetMediaStore(store)
+	ch.chatType.Store("group-1", "group")
+	ch.lastMsgID.Store("group-1", "msg-1")
+	ch.msgSeqCounters.Store("group-1", new(atomic.Uint64))
+
+	err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "group-1",
+		Parts: []bus.MediaPart{{
+			Type:    "image",
+			Ref:     ref,
+			Caption: "see https://example.com/image",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+
+	if len(api.transportCalls) != 1 {
+		t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls))
+	}
+	upload := api.transportCalls[0]
+	if upload.method != "POST" {
+		t.Fatalf("upload method = %q, want POST", upload.method)
+	}
+	if upload.url != "https://api.sgroup.qq.com/v2/groups/group-1/files" {
+		t.Fatalf("upload url = %q", upload.url)
+	}
+	if upload.body.URL != "" {
+		t.Fatalf("upload URL = %q, want empty", upload.body.URL)
+	}
+	wantBase64 := base64.StdEncoding.EncodeToString(content)
+	if upload.body.FileData != wantBase64 {
+		t.Fatalf("upload file_data = %q, want %q", upload.body.FileData, wantBase64)
+	}
+	if upload.body.FileType != 1 {
+		t.Fatalf("upload file_type = %d, want 1", upload.body.FileType)
+	}
+
+	if len(api.groupMessages) != 1 {
+		t.Fatalf("groupMessages = %d, want 1", len(api.groupMessages))
+	}
+	msg, ok := api.groupMessages[0].(*dto.MessageToCreate)
+	if !ok {
+		t.Fatalf("groupMessages[0] type = %T, want *dto.MessageToCreate", api.groupMessages[0])
+	}
+	if msg.MsgType != dto.RichMediaMsg {
+		t.Fatalf("msg.MsgType = %d, want %d", msg.MsgType, dto.RichMediaMsg)
+	}
+	if msg.MsgID != "msg-1" {
+		t.Fatalf("msg.MsgID = %q, want msg-1", msg.MsgID)
+	}
+	if msg.MsgSeq != 1 {
+		t.Fatalf("msg.MsgSeq = %d, want 1", msg.MsgSeq)
+	}
+	if msg.Content != "see https://example。com/image" {
+		t.Fatalf("msg.Content = %q", msg.Content)
+	}
+	if msg.Media == nil || string(msg.Media.FileInfo) != "uploaded-file-info" {
+		t.Fatalf("msg.Media.FileInfo = %q, want uploaded-file-info", string(msg.Media.FileInfo))
+	}
+}
+
+func TestSendMedia_AudioAt60SecondsUsesVoiceUpload(t *testing.T) {
+	assertAudioWAVUploadType(t, 60*time.Second, 3)
+}
+
+func TestSendMedia_AudioOver60SecondsFallsBackToFileUpload(t *testing.T) {
+	assertAudioWAVUploadType(t, 61*time.Second, 4)
+}
+
+func assertAudioWAVUploadType(t *testing.T, duration time.Duration, wantFileType uint64) {
+	t.Helper()
+
+	messageBus := bus.NewMessageBus()
+	store := media.NewFileMediaStore()
+
+	localPath := writeWAVFile(t, t.TempDir(), "voice.wav", duration)
+	ref, err := store.Store(localPath, media.MediaMeta{
+		Filename:    "voice.wav",
+		ContentType: "audio/wav",
+	}, "qq:test")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	api := &fakeQQAPI{
+		transportResp: mustJSON(t, dto.Message{FileInfo: []byte("file-info")}),
+	}
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		api:         api,
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+	}
+	ch.SetRunning(true)
+	ch.SetMediaStore(store)
+	ch.chatType.Store("group-1", "group")
+
+	err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "group-1",
+		Parts: []bus.MediaPart{{
+			Type: "audio",
+			Ref:  ref,
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+
+	if len(api.transportCalls) != 1 {
+		t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls))
+	}
+	if api.transportCalls[0].body.FileType != wantFileType {
+		t.Fatalf("upload file_type = %d, want %d", api.transportCalls[0].body.FileType, wantFileType)
+	}
+}
+
+func TestSendMedia_RemoteAudioFallsBackToFileUpload(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	api := &fakeQQAPI{
+		transportResp: mustJSON(t, dto.Message{FileInfo: []byte("remote-file-info")}),
+	}
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		api:         api,
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+	}
+	ch.SetRunning(true)
+	ch.chatType.Store("user-1", "direct")
+
+	err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "user-1",
+		Parts: []bus.MediaPart{{
+			Type: "audio",
+			Ref:  "https://cdn.example.com/voice.ogg",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+
+	if len(api.transportCalls) != 1 {
+		t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls))
+	}
+	if api.transportCalls[0].body.FileType != 4 {
+		t.Fatalf("upload file_type = %d, want 4", api.transportCalls[0].body.FileType)
+	}
+}
+
+func TestSendMedia_LocalAudioWithUnknownDurationFallsBackToFileUpload(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	store := media.NewFileMediaStore()
+
+	localPath := writeTempFile(t, t.TempDir(), "voice.mp3", []byte("not-a-real-mp3"))
+	ref, err := store.Store(localPath, media.MediaMeta{
+		Filename:    "voice.mp3",
+		ContentType: "audio/mpeg",
+	}, "qq:test")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	api := &fakeQQAPI{
+		transportResp: mustJSON(t, dto.Message{FileInfo: []byte("file-info")}),
+	}
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		api:         api,
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+	}
+	ch.SetRunning(true)
+	ch.SetMediaStore(store)
+	ch.chatType.Store("group-1", "group")
+
+	err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "group-1",
+		Parts: []bus.MediaPart{{
+			Type: "audio",
+			Ref:  ref,
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+
+	if len(api.transportCalls) != 1 {
+		t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls))
+	}
+	if api.transportCalls[0].body.FileType != 4 {
+		t.Fatalf("upload file_type = %d, want 4", api.transportCalls[0].body.FileType)
+	}
+}
+
+func TestSendMedia_UsesRemoteURLUploadForC2C(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	api := &fakeQQAPI{
+		transportResp: mustJSON(t, dto.Message{FileInfo: []byte("remote-file-info")}),
+	}
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		api:         api,
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+	}
+	ch.SetRunning(true)
+	ch.chatType.Store("user-1", "direct")
+
+	err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "user-1",
+		Parts: []bus.MediaPart{{
+			Type: "file",
+			Ref:  "https://cdn.example.com/report.pdf",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+
+	if len(api.transportCalls) != 1 {
+		t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls))
+	}
+	upload := api.transportCalls[0]
+	if upload.url != "https://api.sgroup.qq.com/v2/users/user-1/files" {
+		t.Fatalf("upload url = %q", upload.url)
+	}
+	if upload.body.URL != "https://cdn.example.com/report.pdf" {
+		t.Fatalf("upload URL = %q", upload.body.URL)
+	}
+	if upload.body.FileData != "" {
+		t.Fatalf("upload file_data = %q, want empty", upload.body.FileData)
+	}
+	if upload.body.FileType != 4 {
+		t.Fatalf("upload file_type = %d, want 4", upload.body.FileType)
+	}
+	if upload.body.FileName != "report.pdf" {
+		t.Fatalf("upload file_name = %q, want report.pdf", upload.body.FileName)
+	}
+
+	if len(api.c2cMessages) != 1 {
+		t.Fatalf("c2cMessages = %d, want 1", len(api.c2cMessages))
+	}
+	msg, ok := api.c2cMessages[0].(*dto.MessageToCreate)
+	if !ok {
+		t.Fatalf("c2cMessages[0] type = %T, want *dto.MessageToCreate", api.c2cMessages[0])
+	}
+	if msg.MsgType != dto.RichMediaMsg {
+		t.Fatalf("msg.MsgType = %d, want %d", msg.MsgType, dto.RichMediaMsg)
+	}
+	if msg.Media == nil || string(msg.Media.FileInfo) != "remote-file-info" {
+		t.Fatalf("msg.Media.FileInfo = %q, want remote-file-info", string(msg.Media.FileInfo))
+	}
+}
+
+func TestSendMedia_LocalFileUploadIncludesStoredFilename(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	store := media.NewFileMediaStore()
+
+	localPath := writeTempFile(t, t.TempDir(), "report.pdf", []byte("fake-pdf"))
+	ref, err := store.Store(localPath, media.MediaMeta{
+		Filename:    "report.pdf",
+		ContentType: "application/pdf",
+	}, "qq:test")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	api := &fakeQQAPI{
+		transportResp: mustJSON(t, dto.Message{FileInfo: []byte("local-file-info")}),
+	}
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		api:         api,
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+	}
+	ch.SetRunning(true)
+	ch.SetMediaStore(store)
+	ch.chatType.Store("user-1", "direct")
+
+	err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "user-1",
+		Parts: []bus.MediaPart{{
+			Type: "file",
+			Ref:  ref,
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+
+	if len(api.transportCalls) != 1 {
+		t.Fatalf("transportCalls = %d, want 1", len(api.transportCalls))
+	}
+	upload := api.transportCalls[0]
+	if upload.body.FileType != 4 {
+		t.Fatalf("upload file_type = %d, want 4", upload.body.FileType)
+	}
+	if upload.body.FileName != "report.pdf" {
+		t.Fatalf("upload file_name = %q, want report.pdf", upload.body.FileName)
+	}
+	if upload.body.FileData == "" {
+		t.Fatal("upload file_data = empty, want base64 payload")
+	}
+}
+
+func TestSendMedia_ReturnsSendFailedWithoutMediaStore(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		api:         &fakeQQAPI{},
+		dedup:       make(map[string]time.Time),
+		done:        make(chan struct{}),
+		ctx:         context.Background(),
+	}
+	ch.SetRunning(true)
+	ch.chatType.Store("group-1", "group")
+
+	err := ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "group-1",
+		Parts: []bus.MediaPart{{
+			Type: "image",
+			Ref:  "media://missing",
+		}},
+	})
+	if !errors.Is(err, channels.ErrSendFailed) {
+		t.Fatalf("SendMedia() error = %v, want ErrSendFailed", err)
+	}
+}
+
+func TestSendMedia_ReturnsSendFailedWhenLocalFileExceedsBase64MiBLimit(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	store := media.NewFileMediaStore()
+
+	tmpFile, err := os.CreateTemp(t.TempDir(), "qq-media-too-large-*.bin")
+	if err != nil {
+		t.Fatalf("CreateTemp() error = %v", err)
+	}
+	defer tmpFile.Close()
+
+	content := make([]byte, bytesPerMiB+1)
+	if _, writeErr := tmpFile.Write(content); writeErr != nil {
+		t.Fatalf("Write() error = %v", writeErr)
+	}
+
+	ref, err := store.Store(tmpFile.Name(), media.MediaMeta{
+		Filename:    "large.bin",
+		ContentType: "application/octet-stream",
+	}, "qq:test")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	api := &fakeQQAPI{}
+	ch := &QQChannel{
+		BaseChannel: channels.NewBaseChannel("qq", nil, messageBus, nil),
+		config: config.QQConfig{
+			MaxBase64FileSizeMiB: 1,
+		},
+		api:   api,
+		dedup: make(map[string]time.Time),
+		done:  make(chan struct{}),
+		ctx:   context.Background(),
+	}
+	ch.SetRunning(true)
+	ch.SetMediaStore(store)
+	ch.chatType.Store("group-1", "group")
+
+	err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "group-1",
+		Parts: []bus.MediaPart{{
+			Type: "file",
+			Ref:  ref,
+		}},
+	})
+	if !errors.Is(err, channels.ErrSendFailed) {
+		t.Fatalf("SendMedia() error = %v, want ErrSendFailed", err)
+	}
+	if len(api.transportCalls) != 0 {
+		t.Fatalf("transportCalls = %d, want 0", len(api.transportCalls))
+	}
+}
+
+type fakeQQAPI struct {
+	transportResp  []byte
+	transportErr   error
+	groupErr       error
+	c2cErr         error
+	transportCalls []fakeTransportCall
+	groupMessages  []dto.APIMessage
+	c2cMessages    []dto.APIMessage
+}
+
+type fakeTransportCall struct {
+	method string
+	url    string
+	body   qqMediaUpload
+}
+
+func (f *fakeQQAPI) WS(
+	context.Context,
+	map[string]string,
+	string,
+) (*dto.WebsocketAP, error) {
+	return nil, nil
+}
+
+func (f *fakeQQAPI) PostGroupMessage(
+	_ context.Context,
+	_ string,
+	msg dto.APIMessage,
+	_ ...options.Option,
+) (*dto.Message, error) {
+	f.groupMessages = append(f.groupMessages, msg)
+	return &dto.Message{}, f.groupErr
+}
+
+func (f *fakeQQAPI) PostC2CMessage(
+	_ context.Context,
+	_ string,
+	msg dto.APIMessage,
+	_ ...options.Option,
+) (*dto.Message, error) {
+	f.c2cMessages = append(f.c2cMessages, msg)
+	return &dto.Message{}, f.c2cErr
+}
+
+func (f *fakeQQAPI) Transport(_ context.Context, method, url string, body any) ([]byte, error) {
+	upload, ok := body.(*qqMediaUpload)
+	if !ok {
+		return nil, errors.New("unexpected transport body type")
+	}
+	f.transportCalls = append(f.transportCalls, fakeTransportCall{
+		method: method,
+		url:    url,
+		body:   *upload,
+	})
+	return f.transportResp, f.transportErr
+}
+
+func mustJSON(t *testing.T, v any) []byte {
+	t.Helper()
+
+	b, err := json.Marshal(v)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+	return b
+}
+
+func waitInboundMessage(t *testing.T, messageBus *bus.MessageBus) bus.InboundMessage {
+	t.Helper()
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+
+	for {
+		select {
+		case <-ctx.Done():
+			t.Fatal("timeout waiting for inbound message")
+		case inbound, ok := <-messageBus.InboundChan():
+			if !ok {
+				t.Fatal("expected inbound message")
+			}
+			return inbound
+		}
+	}
+}
+
+func writeTempFile(t *testing.T, dir, name string, content []byte) string {
+	t.Helper()
+
+	path := dir + "/" + name
+	if err := os.WriteFile(path, content, 0o600); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+	return path
+}
+
+func writeWAVFile(t *testing.T, dir, name string, duration time.Duration) string {
+	t.Helper()
+
+	const (
+		sampleRate    = 8000
+		numChannels   = 1
+		bitsPerSample = 8
+	)
+
+	dataSize := uint32(duration / time.Second * sampleRate * numChannels * (bitsPerSample / 8))
+	byteRate := uint32(sampleRate * numChannels * (bitsPerSample / 8))
+	blockAlign := uint16(numChannels * (bitsPerSample / 8))
+
+	var buf bytes.Buffer
+	buf.WriteString("RIFF")
+	if err := binary.Write(&buf, binary.LittleEndian, uint32(36)+dataSize); err != nil {
+		t.Fatalf("binary.Write(riff size) error = %v", err)
+	}
+	buf.WriteString("WAVE")
+	buf.WriteString("fmt ")
+	if err := binary.Write(&buf, binary.LittleEndian, uint32(16)); err != nil {
+		t.Fatalf("binary.Write(fmt chunk size) error = %v", err)
+	}
+	if err := binary.Write(&buf, binary.LittleEndian, uint16(1)); err != nil {
+		t.Fatalf("binary.Write(audio format) error = %v", err)
+	}
+	if err := binary.Write(&buf, binary.LittleEndian, uint16(numChannels)); err != nil {
+		t.Fatalf("binary.Write(channels) error = %v", err)
+	}
+	if err := binary.Write(&buf, binary.LittleEndian, uint32(sampleRate)); err != nil {
+		t.Fatalf("binary.Write(sample rate) error = %v", err)
+	}
+	if err := binary.Write(&buf, binary.LittleEndian, byteRate); err != nil {
+		t.Fatalf("binary.Write(byte rate) error = %v", err)
+	}
+	if err := binary.Write(&buf, binary.LittleEndian, blockAlign); err != nil {
+		t.Fatalf("binary.Write(block align) error = %v", err)
+	}
+	if err := binary.Write(&buf, binary.LittleEndian, uint16(bitsPerSample)); err != nil {
+		t.Fatalf("binary.Write(bits per sample) error = %v", err)
+	}
+	buf.WriteString("data")
+	if err := binary.Write(&buf, binary.LittleEndian, dataSize); err != nil {
+		t.Fatalf("binary.Write(data size) error = %v", err)
+	}
+	buf.Write(make([]byte, dataSize))
+
+	return writeTempFile(t, dir, name, buf.Bytes())
+}
diff --git a/pkg/channels/slack/slack.go b/pkg/channels/slack/slack.go
index 024b1b023..f03283ea4 100644
--- a/pkg/channels/slack/slack.go
+++ b/pkg/channels/slack/slack.go
@@ -37,13 +37,13 @@ type slackMessageRef struct {
 }
 
 func NewSlackChannel(cfg config.SlackConfig, messageBus *bus.MessageBus) (*SlackChannel, error) {
-	if cfg.BotToken == "" || cfg.AppToken == "" {
+	if cfg.BotToken() == "" || cfg.AppToken() == "" {
 		return nil, fmt.Errorf("slack bot_token and app_token are required")
 	}
 
 	api := slack.New(
-		cfg.BotToken,
-		slack.OptionAppLevelToken(cfg.AppToken),
+		cfg.BotToken(),
+		slack.OptionAppLevelToken(cfg.AppToken()),
 	)
 
 	socketClient := socketmode.New(api)
@@ -122,7 +122,11 @@ func (c *SlackChannel) Send(ctx context.Context, msg bus.OutboundMessage) error
 		slack.MsgOptionText(msg.Content, false),
 	}
 
-	if threadTS != "" {
+	if msg.ReplyToMessageID != "" && threadTS == "" {
+		// Answer to the message by creating a Thread under it
+		opts = append(opts, slack.MsgOptionTS(msg.ReplyToMessageID))
+	} else if threadTS != "" {
+		// If we are already in a thread, continue in the thread
 		opts = append(opts, slack.MsgOptionTS(threadTS))
 	}
 
@@ -323,8 +327,9 @@ func (c *SlackChannel) handleMessageEvent(ev *slackevents.MessageEvent) {
 	storeMedia := func(localPath, filename string) string {
 		if store := c.GetMediaStore(); store != nil {
 			ref, err := store.Store(localPath, media.MediaMeta{
-				Filename: filename,
-				Source:   "slack",
+				Filename:      filename,
+				Source:        "slack",
+				CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
 			}, scope)
 			if err == nil {
 				return ref
@@ -511,7 +516,7 @@ func (c *SlackChannel) downloadSlackFile(file slack.File) string {
 	return utils.DownloadFile(downloadURL, file.Name, utils.DownloadOptions{
 		LoggerPrefix: "slack",
 		ExtraHeaders: map[string]string{
-			"Authorization": "Bearer " + c.config.BotToken,
+			"Authorization": "Bearer " + c.config.BotToken(),
 		},
 	})
 }
diff --git a/pkg/channels/slack/slack_test.go b/pkg/channels/slack/slack_test.go
index 30e0d2d73..23a7ee5c4 100644
--- a/pkg/channels/slack/slack_test.go
+++ b/pkg/channels/slack/slack_test.go
@@ -102,10 +102,8 @@ func TestNewSlackChannel(t *testing.T) {
 	msgBus := bus.NewMessageBus()
 
 	t.Run("missing bot token", func(t *testing.T) {
-		cfg := config.SlackConfig{
-			BotToken: "",
-			AppToken: "xapp-test",
-		}
+		cfg := config.SlackConfig{}
+		cfg.SetAppToken("xapp-test")
 		_, err := NewSlackChannel(cfg, msgBus)
 		if err == nil {
 			t.Error("expected error for missing bot_token, got nil")
@@ -113,10 +111,8 @@ func TestNewSlackChannel(t *testing.T) {
 	})
 
 	t.Run("missing app token", func(t *testing.T) {
-		cfg := config.SlackConfig{
-			BotToken: "xoxb-test",
-			AppToken: "",
-		}
+		cfg := config.SlackConfig{}
+		cfg.SetBotToken("xoxb-test")
 		_, err := NewSlackChannel(cfg, msgBus)
 		if err == nil {
 			t.Error("expected error for missing app_token, got nil")
@@ -125,10 +121,10 @@ func TestNewSlackChannel(t *testing.T) {
 
 	t.Run("valid config", func(t *testing.T) {
 		cfg := config.SlackConfig{
-			BotToken:  "xoxb-test",
-			AppToken:  "xapp-test",
 			AllowFrom: []string{"U123"},
 		}
+		cfg.SetBotToken("xoxb-test")
+		cfg.SetAppToken("xapp-test")
 		ch, err := NewSlackChannel(cfg, msgBus)
 		if err != nil {
 			t.Fatalf("unexpected error: %v", err)
@@ -147,10 +143,10 @@ func TestSlackChannelIsAllowed(t *testing.T) {
 
 	t.Run("empty allowlist allows all", func(t *testing.T) {
 		cfg := config.SlackConfig{
-			BotToken:  "xoxb-test",
-			AppToken:  "xapp-test",
 			AllowFrom: []string{},
 		}
+		cfg.SetBotToken("xoxb-test")
+		cfg.SetAppToken("xapp-test")
 		ch, _ := NewSlackChannel(cfg, msgBus)
 		if !ch.IsAllowed("U_ANYONE") {
 			t.Error("empty allowlist should allow all users")
@@ -159,10 +155,10 @@ func TestSlackChannelIsAllowed(t *testing.T) {
 
 	t.Run("allowlist restricts users", func(t *testing.T) {
 		cfg := config.SlackConfig{
-			BotToken:  "xoxb-test",
-			AppToken:  "xapp-test",
 			AllowFrom: []string{"U_ALLOWED"},
 		}
+		cfg.SetBotToken("xoxb-test")
+		cfg.SetAppToken("xapp-test")
 		ch, _ := NewSlackChannel(cfg, msgBus)
 		if !ch.IsAllowed("U_ALLOWED") {
 			t.Error("allowed user should pass allowlist check")
diff --git a/pkg/channels/telegram/command_registration.go b/pkg/channels/telegram/command_registration.go
new file mode 100644
index 000000000..d3152ec3d
--- /dev/null
+++ b/pkg/channels/telegram/command_registration.go
@@ -0,0 +1,116 @@
+package telegram
+
+import (
+	"context"
+	"math/rand"
+	"slices"
+	"time"
+
+	"github.com/mymmrac/telego"
+
+	"github.com/sipeed/picoclaw/pkg/commands"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+var commandRegistrationBackoff = []time.Duration{
+	5 * time.Second,
+	15 * time.Second,
+	60 * time.Second,
+	5 * time.Minute,
+	10 * time.Minute,
+}
+
+func commandRegistrationDelay(attempt int) time.Duration {
+	if len(commandRegistrationBackoff) == 0 {
+		return 0
+	}
+	base := commandRegistrationBackoff[min(attempt, len(commandRegistrationBackoff)-1)]
+	// Full jitter in [0.5, 1.0) to avoid synchronized retries across instances.
+	return time.Duration(float64(base) * (0.5 + rand.Float64()*0.5))
+}
+
+// RegisterCommands registers bot commands on Telegram platform.
+func (c *TelegramChannel) RegisterCommands(ctx context.Context, defs []commands.Definition) error {
+	botCommands := make([]telego.BotCommand, 0, len(defs))
+	for _, def := range defs {
+		if def.Name == "" || def.Description == "" {
+			continue
+		}
+		botCommands = append(botCommands, telego.BotCommand{
+			Command:     def.Name,
+			Description: def.Description,
+		})
+	}
+
+	current, err := c.bot.GetMyCommands(ctx, &telego.GetMyCommandsParams{})
+	if err != nil {
+		// If we can't read current commands, fall through to set them.
+		logger.WarnCF("telegram", "Failed to get current commands, will set unconditionally",
+			map[string]any{"error": err.Error()})
+	} else if slices.Equal(current, botCommands) {
+		logger.DebugCF("telegram", "Bot commands are up to date", nil)
+		return nil
+	}
+
+	return c.bot.SetMyCommands(ctx, &telego.SetMyCommandsParams{
+		Commands: botCommands,
+	})
+}
+
+func (c *TelegramChannel) startCommandRegistration(ctx context.Context, defs []commands.Definition) {
+	if len(defs) == 0 {
+		return
+	}
+
+	register := c.registerFunc
+	if register == nil {
+		register = c.RegisterCommands
+	}
+
+	regCtx, cancel := context.WithCancel(ctx)
+	c.commandRegCancel = cancel
+
+	// Registration runs asynchronously so Telegram message intake is never blocked
+	// by temporary upstream API failures. Retry stops on success or channel shutdown.
+	go func() {
+		attempt := 0
+		timer := time.NewTimer(0)
+		if !timer.Stop() {
+			select {
+			case <-timer.C:
+			default:
+			}
+		}
+		defer timer.Stop()
+		for {
+			err := register(regCtx, defs)
+			if err == nil {
+				logger.InfoCF("telegram", "Telegram commands registered", map[string]any{
+					"count": len(defs),
+				})
+				return
+			}
+
+			delay := commandRegistrationDelay(attempt)
+			logger.WarnCF("telegram", "Telegram command registration failed; will retry", map[string]any{
+				"error":       err.Error(),
+				"retry_after": delay.String(),
+			})
+			attempt++
+
+			if !timer.Stop() {
+				select {
+				case <-timer.C:
+				default:
+				}
+			}
+			timer.Reset(delay)
+
+			select {
+			case <-regCtx.Done():
+				return
+			case <-timer.C:
+			}
+		}
+	}()
+}
diff --git a/pkg/channels/telegram/command_registration_test.go b/pkg/channels/telegram/command_registration_test.go
new file mode 100644
index 000000000..26f891b2e
--- /dev/null
+++ b/pkg/channels/telegram/command_registration_test.go
@@ -0,0 +1,96 @@
+package telegram
+
+import (
+	"context"
+	"errors"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/commands"
+)
+
+func TestStartCommandRegistration_DoesNotBlock(t *testing.T) {
+	ch := &TelegramChannel{}
+	started := make(chan struct{}, 1)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	ch.registerFunc = func(context.Context, []commands.Definition) error {
+		started <- struct{}{}
+		return errors.New("temporary failure")
+	}
+
+	ch.startCommandRegistration(ctx, []commands.Definition{{Name: "help"}})
+
+	select {
+	case <-started:
+	case <-time.After(time.Second):
+		t.Fatal("registration did not start asynchronously")
+	}
+}
+
+func TestStartCommandRegistration_RetriesUntilSuccessThenStops(t *testing.T) {
+	ch := &TelegramChannel{}
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	origBackoff := commandRegistrationBackoff
+	commandRegistrationBackoff = []time.Duration{5 * time.Millisecond}
+	defer func() { commandRegistrationBackoff = origBackoff }()
+
+	var attempts atomic.Int32
+	ch.registerFunc = func(context.Context, []commands.Definition) error {
+		n := attempts.Add(1)
+		if n < 3 {
+			return errors.New("temporary failure")
+		}
+		return nil
+	}
+
+	ch.startCommandRegistration(ctx, []commands.Definition{{Name: "help", Description: "Help"}})
+
+	deadline := time.Now().Add(250 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		if attempts.Load() >= 3 {
+			break
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	if attempts.Load() < 3 {
+		t.Fatalf("expected at least 3 attempts, got %d", attempts.Load())
+	}
+
+	stable := attempts.Load()
+	time.Sleep(30 * time.Millisecond)
+	if attempts.Load() != stable {
+		t.Fatalf("expected retries to stop after success, got %d -> %d", stable, attempts.Load())
+	}
+}
+
+func TestStartCommandRegistration_StopsAfterCancel(t *testing.T) {
+	ch := &TelegramChannel{}
+	ctx, cancel := context.WithCancel(context.Background())
+
+	origBackoff := commandRegistrationBackoff
+	commandRegistrationBackoff = []time.Duration{5 * time.Millisecond}
+	defer func() { commandRegistrationBackoff = origBackoff }()
+	defer cancel()
+
+	var attempts atomic.Int32
+	ch.registerFunc = func(context.Context, []commands.Definition) error {
+		attempts.Add(1)
+		return errors.New("always fail")
+	}
+
+	ch.startCommandRegistration(ctx, []commands.Definition{{Name: "help", Description: "Help"}})
+
+	time.Sleep(20 * time.Millisecond)
+	cancel()
+	time.Sleep(20 * time.Millisecond) // allow in-flight attempt to settle
+	stable := attempts.Load()
+	time.Sleep(30 * time.Millisecond)
+	if attempts.Load() != stable {
+		t.Fatalf("expected retries to quiesce after cancel, got %d -> %d", stable, attempts.Load())
+	}
+}
diff --git a/pkg/channels/telegram/parse_markdown_to_md_v2.go b/pkg/channels/telegram/parse_markdown_to_md_v2.go
new file mode 100644
index 000000000..8cae312c5
--- /dev/null
+++ b/pkg/channels/telegram/parse_markdown_to_md_v2.go
@@ -0,0 +1,197 @@
+package telegram
+
+import (
+	"regexp"
+	"strings"
+)
+
+// mdV2SpecialChars are all characters that must be escaped in Telegram MarkdownV2
+var mdV2SpecialChars = map[rune]bool{
+	'*':  true,
+	'_':  true,
+	'[':  true,
+	']':  true,
+	'(':  true,
+	')':  true,
+	'~':  true,
+	'`':  true,
+	'>':  true,
+	'<':  true,
+	'#':  true,
+	'+':  true,
+	'-':  true,
+	'=':  true,
+	'|':  true,
+	'{':  true,
+	'}':  true,
+	'.':  true,
+	'!':  true,
+	'\\': true,
+}
+
+// entityPattern describes one Telegram MarkdownV2 inline entity type.
+type entityPattern struct {
+	re    *regexp.Regexp
+	open  string
+	close string
+}
+
+// allEntityPatterns lists every recognized entity in priority order
+// (longer / more-specific delimiters first so they win over shorter ones).
+// Each entry's regex is anchored to find the first occurrence in a string.
+var allEntityPatterns = []entityPattern{
+	// fenced code block — content is completely verbatim
+	{re: regexp.MustCompile("(?s)```(?:[\\w]*\\n)?[\\s\\S]*?```"), open: "```", close: "```"},
+	// inline code — content is completely verbatim
+	{re: regexp.MustCompile("`(?:[^`\\\n]|\\\\.)*`"), open: "`", close: "`"},
+	// expandable block-quote opener  **>…
+	{re: regexp.MustCompile(`(?m)\*\*>(?:[^\n]*)`), open: "**>", close: ""},
+	// block-quote line  >…
+	{re: regexp.MustCompile(`(?m)^>(?:[^\n]*)`), open: ">", close: ""},
+	// custom emoji / timestamp  ![…](…)   — must come before plain link
+	{re: regexp.MustCompile(`!\[[^\]]*\]\([^)]*\)`), open: "!", close: ""},
+	// inline URL / user mention  […](…)
+	{re: regexp.MustCompile(`\[[^\]]*\]\([^)]*\)`), open: "[", close: ""},
+	// spoiler  ||…||  — before single | so it wins
+	{re: regexp.MustCompile(`\|\|(?:[^|\\\n]|\\.)*\|\|`), open: "||", close: "||"},
+	// underline  __…__  — before single _ so it wins
+	{re: regexp.MustCompile(`__(?:[^_\\\n]|\\.)*__`), open: "__", close: "__"},
+	// bold  *…*
+	{re: regexp.MustCompile(`\*(?:[^*\\\n]|\\.)*\*`), open: "*", close: "*"},
+	// italic  _…_
+	{re: regexp.MustCompile(`_(?:[^_\\\n]|\\.)*_`), open: "_", close: "_"},
+	// strikethrough  ~…~
+	{re: regexp.MustCompile(`~(?:[^~\\\n]|\\.)*~`), open: "~", close: "~"},
+}
+
+// verbatimEntities are entity types whose inner content must never be
+// touched (code blocks, URLs, quotes, custom emoji).
+// Their content is passed through completely unchanged.
+var verbatimEntities = map[string]bool{
+	"```": true,
+	"`":   true,
+	"**>": true,
+	">":   true,
+	"!":   true,
+	"[":   true,
+}
+
+// markdownToTelegramMarkdownV2 converts a Markdown string into a string safe
+// for sending with Telegram's MarkdownV2 parse mode.
+//
+// Rules:
+//   - Markdown headings (# … ######) are converted to *bold*.
+//   - **bold** Markdown syntax is converted to *bold*.
+//   - Recognized Telegram MarkdownV2 entity spans are preserved; their inner
+//     content is processed recursively so that nested valid entities are kept
+//     intact while stray special characters are escaped.
+//   - All plain-text segments have their MarkdownV2 special characters escaped.
+//
+// Reference: https://core.telegram.org/bots/api#formatting-options
+func markdownToTelegramMarkdownV2(text string) string {
+	// 1. Convert Markdown headings → *escaped heading text*
+	text = reHeading.ReplaceAllStringFunc(text, func(match string) string {
+		sub := reHeading.FindStringSubmatch(match)
+		if len(sub) < 2 {
+			return match
+		}
+		// The heading content is fresh plain text — escape everything
+		// including * so the resulting *…* bold span stays valid.
+		return "*" + escapeMarkdownV2(sub[1]) + "*"
+	})
+
+	// 2. Convert **bold** → *bold*
+	text = reBoldStar.ReplaceAllString(text, "*$1*")
+
+	// 3. Recursively escape the full string.
+	return processText(text)
+}
+
+// processText walks `text`, finds the leftmost / longest matching entity,
+// escapes the gap before it, processes the entity (recursing into its inner
+// content when appropriate), then continues with the remainder.
+func processText(text string) string {
+	if text == "" {
+		return ""
+	}
+
+	// Find the leftmost match among all entity patterns.
+	bestStart := -1
+	bestEnd := -1
+	var bestPat *entityPattern
+
+	for i := range allEntityPatterns {
+		p := &allEntityPatterns[i]
+		loc := p.re.FindStringIndex(text)
+		if loc == nil {
+			continue
+		}
+		if bestStart == -1 || loc[0] < bestStart ||
+			(loc[0] == bestStart && (loc[1]-loc[0]) > (bestEnd-bestStart)) {
+			bestStart = loc[0]
+			bestEnd = loc[1]
+			bestPat = p
+		}
+	}
+
+	if bestPat == nil {
+		// No entity found — escape everything.
+		return escapeMarkdownV2(text)
+	}
+
+	var b strings.Builder
+
+	// Plain text before the entity.
+	if bestStart > 0 {
+		b.WriteString(escapeMarkdownV2(text[:bestStart]))
+	}
+
+	// The matched entity span.
+	matched := text[bestStart:bestEnd]
+
+	if verbatimEntities[bestPat.open] {
+		// Code blocks, URLs, quotes: pass through completely untouched.
+		b.WriteString(matched)
+	} else {
+		// Inline formatting (bold, italic, underline, strikethrough, spoiler):
+		// keep the delimiters and recursively process the inner content so that
+		// nested entities survive but stray specials get escaped.
+		openLen := len(bestPat.open)
+		closeLen := len(bestPat.close)
+		inner := matched[openLen : len(matched)-closeLen]
+
+		b.WriteString(bestPat.open)
+		b.WriteString(processText(inner))
+		b.WriteString(bestPat.close)
+	}
+
+	// Continue with the remainder of the string.
+	b.WriteString(processText(text[bestEnd:]))
+
+	return b.String()
+}
+
+// escapeMarkdownV2 escapes every MarkdownV2 special character in a plain-text
+// segment (i.e. a segment that is not part of any recognized entity).
+// Already-escaped sequences (backslash + char) are forwarded verbatim to avoid
+// double-escaping.
+func escapeMarkdownV2(s string) string {
+	var b strings.Builder
+	b.Grow(len(s) + 8)
+	runes := []rune(s)
+	for i := 0; i < len(runes); i++ {
+		ch := runes[i]
+		// Forward an existing escape sequence verbatim.
+		if ch == '\\' && i+1 < len(runes) {
+			b.WriteRune(ch)
+			b.WriteRune(runes[i+1])
+			i++
+			continue
+		}
+		if mdV2SpecialChars[ch] {
+			b.WriteByte('\\')
+		}
+		b.WriteRune(ch)
+	}
+	return b.String()
+}
diff --git a/pkg/channels/telegram/parse_markdown_to_md_v2_test.go b/pkg/channels/telegram/parse_markdown_to_md_v2_test.go
new file mode 100644
index 000000000..fd68a9b83
--- /dev/null
+++ b/pkg/channels/telegram/parse_markdown_to_md_v2_test.go
@@ -0,0 +1,68 @@
+package telegram
+
+import (
+	_ "embed"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+//go:embed testdata/md2_all_formats.txt
+var md2AllFormats string
+
+func Test_markdownToTelegramMarkdownV2(t *testing.T) {
+	cases := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{
+			name:     "heading -> bolding",
+			input:    `## HeadingH2 #`,
+			expected: "*HeadingH2 \\#*",
+		},
+		{
+			name:     "strikethrough",
+			input:    "~strikethroughMD~",
+			expected: "~strikethroughMD~",
+		},
+		{
+			name:     "inline URL",
+			input:    "[inline URL](http://www.example.com/)",
+			expected: "[inline URL](http://www.example.com/)",
+		},
+		{
+			name:     "all telegram formats",
+			input:    md2AllFormats,
+			expected: md2AllFormats,
+		},
+		{
+			name:     "empty",
+			input:    "",
+			expected: "",
+		},
+		{
+			name:     "one letter",
+			input:    "o",
+			expected: "o",
+		},
+		{
+			name:     "",
+			input:    "*Last update: ~10 24h*",
+			expected: "*Last update: \\~10 24h*",
+		},
+		{
+			name:     "",
+			input:    "<Market Capitalization>",
+			expected: "\\<Market Capitalization\\>",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			actual := markdownToTelegramMarkdownV2(tc.input)
+
+			require.EqualValues(t, tc.expected, actual)
+		})
+	}
+}
diff --git a/pkg/channels/telegram/parser_markdown_to_html.go b/pkg/channels/telegram/parser_markdown_to_html.go
new file mode 100644
index 000000000..bdaa51807
--- /dev/null
+++ b/pkg/channels/telegram/parser_markdown_to_html.go
@@ -0,0 +1,111 @@
+package telegram
+
+import (
+	"fmt"
+	"strings"
+)
+
+func markdownToTelegramHTML(text string) string {
+	if text == "" {
+		return ""
+	}
+
+	codeBlocks := extractCodeBlocks(text)
+	text = codeBlocks.text
+
+	inlineCodes := extractInlineCodes(text)
+	text = inlineCodes.text
+
+	text = reHeading.ReplaceAllString(text, "$1")
+
+	text = reBlockquote.ReplaceAllString(text, "$1")
+
+	text = escapeHTML(text)
+
+	text = reLink.ReplaceAllString(text, `<a href="$2">$1</a>`)
+
+	text = reBoldStar.ReplaceAllString(text, "<b>$1</b>")
+
+	text = reBoldUnder.ReplaceAllString(text, "<b>$1</b>")
+
+	text = reItalic.ReplaceAllStringFunc(text, func(s string) string {
+		match := reItalic.FindStringSubmatch(s)
+		if len(match) < 2 {
+			return s
+		}
+		return "<i>" + match[1] + "</i>"
+	})
+
+	text = reStrike.ReplaceAllString(text, "<s>$1</s>")
+
+	text = reListItem.ReplaceAllString(text, "• ")
+
+	for i, code := range inlineCodes.codes {
+		escaped := escapeHTML(code)
+		text = strings.ReplaceAll(text, fmt.Sprintf("\x00IC%d\x00", i), fmt.Sprintf("<code>%s</code>", escaped))
+	}
+
+	for i, code := range codeBlocks.codes {
+		escaped := escapeHTML(code)
+		text = strings.ReplaceAll(
+			text,
+			fmt.Sprintf("\x00CB%d\x00", i),
+			fmt.Sprintf("<pre><code>%s</code></pre>", escaped),
+		)
+	}
+
+	return text
+}
+
+type codeBlockMatch struct {
+	text  string
+	codes []string
+}
+
+func extractCodeBlocks(text string) codeBlockMatch {
+	matches := reCodeBlock.FindAllStringSubmatch(text, -1)
+
+	codes := make([]string, 0, len(matches))
+	for _, match := range matches {
+		codes = append(codes, match[1])
+	}
+
+	i := 0
+	text = reCodeBlock.ReplaceAllStringFunc(text, func(m string) string {
+		placeholder := fmt.Sprintf("\x00CB%d\x00", i)
+		i++
+		return placeholder
+	})
+
+	return codeBlockMatch{text: text, codes: codes}
+}
+
+type inlineCodeMatch struct {
+	text  string
+	codes []string
+}
+
+func extractInlineCodes(text string) inlineCodeMatch {
+	matches := reInlineCode.FindAllStringSubmatch(text, -1)
+
+	codes := make([]string, 0, len(matches))
+	for _, match := range matches {
+		codes = append(codes, match[1])
+	}
+
+	i := 0
+	text = reInlineCode.ReplaceAllStringFunc(text, func(m string) string {
+		placeholder := fmt.Sprintf("\x00IC%d\x00", i)
+		i++
+		return placeholder
+	})
+
+	return inlineCodeMatch{text: text, codes: codes}
+}
+
+func escapeHTML(text string) string {
+	text = strings.ReplaceAll(text, "&", "&amp;")
+	text = strings.ReplaceAll(text, "<", "&lt;")
+	text = strings.ReplaceAll(text, ">", "&gt;")
+	return text
+}
diff --git a/pkg/channels/telegram/telegram.go b/pkg/channels/telegram/telegram.go
index a11cf53b8..e7da1d615 100644
--- a/pkg/channels/telegram/telegram.go
+++ b/pkg/channels/telegram/telegram.go
@@ -2,22 +2,26 @@ package telegram
 
 import (
 	"context"
+	"crypto/rand"
+	"encoding/binary"
 	"fmt"
+	"io"
 	"net/http"
 	"net/url"
 	"os"
 	"regexp"
 	"strconv"
 	"strings"
+	"sync"
 	"time"
 
 	"github.com/mymmrac/telego"
-	"github.com/mymmrac/telego/telegohandler"
 	th "github.com/mymmrac/telego/telegohandler"
 	tu "github.com/mymmrac/telego/telegoutil"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/commands"
 	"github.com/sipeed/picoclaw/pkg/config"
 	"github.com/sipeed/picoclaw/pkg/identity"
 	"github.com/sipeed/picoclaw/pkg/logger"
@@ -26,7 +30,7 @@ import (
 )
 
 var (
-	reHeading    = regexp.MustCompile(`^#{1,6}\s+(.+)$`)
+	reHeading    = regexp.MustCompile(`(?m)^#{1,6}\s+([^\n]+)`)
 	reBlockquote = regexp.MustCompile(`^>\s*(.*)$`)
 	reLink       = regexp.MustCompile(`\[([^\]]+)\]\(([^)]+)\)`)
 	reBoldStar   = regexp.MustCompile(`\*\*(.+?)\*\*`)
@@ -40,13 +44,15 @@ var (
 
 type TelegramChannel struct {
 	*channels.BaseChannel
-	bot      *telego.Bot
-	bh       *telegohandler.BotHandler
-	commands TelegramCommander
-	config   *config.Config
-	chatIDs  map[string]int64
-	ctx      context.Context
-	cancel   context.CancelFunc
+	bot     *telego.Bot
+	bh      *th.BotHandler
+	config  *config.Config
+	chatIDs map[string]int64
+	ctx     context.Context
+	cancel  context.CancelFunc
+
+	registerFunc     func(context.Context, []commands.Definition) error
+	commandRegCancel context.CancelFunc
 }
 
 func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChannel, error) {
@@ -72,7 +78,12 @@ func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChann
 		}))
 	}
 
-	bot, err := telego.NewBot(telegramCfg.Token, opts...)
+	if baseURL := strings.TrimRight(strings.TrimSpace(telegramCfg.BaseURL), "/"); baseURL != "" {
+		opts = append(opts, telego.WithAPIServer(baseURL))
+	}
+	opts = append(opts, telego.WithLogger(logger.NewLogger("telego")))
+
+	bot, err := telego.NewBot(telegramCfg.Token(), opts...)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create telegram bot: %w", err)
 	}
@@ -82,14 +93,13 @@ func NewTelegramChannel(cfg *config.Config, bus *bus.MessageBus) (*TelegramChann
 		telegramCfg,
 		bus,
 		telegramCfg.AllowFrom,
-		channels.WithMaxMessageLength(4096),
+		channels.WithMaxMessageLength(4000),
 		channels.WithGroupTrigger(telegramCfg.GroupTrigger),
 		channels.WithReasoningChannelID(telegramCfg.ReasoningChannelID),
 	)
 
 	return &TelegramChannel{
 		BaseChannel: base,
-		commands:    NewTelegramCommands(bot, cfg),
 		bot:         bot,
 		config:      cfg,
 		chatIDs:     make(map[string]int64),
@@ -109,29 +119,13 @@ func (c *TelegramChannel) Start(ctx context.Context) error {
 		return fmt.Errorf("failed to start long polling: %w", err)
 	}
 
-	bh, err := telegohandler.NewBotHandler(c.bot, updates)
+	bh, err := th.NewBotHandler(c.bot, updates)
 	if err != nil {
 		c.cancel()
 		return fmt.Errorf("failed to create bot handler: %w", err)
 	}
 	c.bh = bh
 
-	bh.HandleMessage(func(ctx *th.Context, message telego.Message) error {
-		c.commands.Help(ctx, message)
-		return nil
-	}, th.CommandEqual("help"))
-	bh.HandleMessage(func(ctx *th.Context, message telego.Message) error {
-		return c.commands.Start(ctx, message)
-	}, th.CommandEqual("start"))
-
-	bh.HandleMessage(func(ctx *th.Context, message telego.Message) error {
-		return c.commands.Show(ctx, message)
-	}, th.CommandEqual("show"))
-
-	bh.HandleMessage(func(ctx *th.Context, message telego.Message) error {
-		return c.commands.List(ctx, message)
-	}, th.CommandEqual("list"))
-
 	bh.HandleMessage(func(ctx *th.Context, message telego.Message) error {
 		return c.handleMessage(ctx, &message)
 	}, th.AnyMessage())
@@ -141,7 +135,15 @@ func (c *TelegramChannel) Start(ctx context.Context) error {
 		"username": c.bot.Username(),
 	})
 
-	go bh.Start()
+	c.startCommandRegistration(c.ctx, commands.BuiltinDefinitions())
+
+	go func() {
+		if err = bh.Start(); err != nil {
+			logger.ErrorCF("telegram", "Bot handler failed", map[string]any{
+				"error": err.Error(),
+			})
+		}
+	}()
 
 	return nil
 }
@@ -152,13 +154,16 @@ func (c *TelegramChannel) Stop(ctx context.Context) error {
 
 	// Stop the bot handler
 	if c.bh != nil {
-		c.bh.Stop()
+		_ = c.bh.StopWithContext(ctx)
 	}
 
 	// Cancel our context (stops long polling)
 	if c.cancel != nil {
 		c.cancel()
 	}
+	if c.commandRegCancel != nil {
+		c.commandRegCancel()
+	}
 
 	return nil
 }
@@ -168,21 +173,129 @@ func (c *TelegramChannel) Send(ctx context.Context, msg bus.OutboundMessage) err
 		return channels.ErrNotRunning
 	}
 
-	chatID, err := parseChatID(msg.ChatID)
+	useMarkdownV2 := c.config.Channels.Telegram.UseMarkdownV2
+
+	chatID, threadID, err := parseTelegramChatID(msg.ChatID)
 	if err != nil {
 		return fmt.Errorf("invalid chat ID %s: %w", msg.ChatID, channels.ErrSendFailed)
 	}
 
-	htmlContent := markdownToTelegramHTML(msg.Content)
+	if msg.Content == "" {
+		return nil
+	}
 
-	// Typing/placeholder handled by Manager.preSend — just send the message
-	tgMsg := tu.Message(tu.ID(chatID), htmlContent)
-	tgMsg.ParseMode = telego.ModeHTML
+	// The Manager already splits messages to ≤4000 chars (WithMaxMessageLength),
+	// so msg.Content is guaranteed to be within that limit. We still need to
+	// check if HTML expansion pushes it beyond Telegram's 4096-char API limit.
+	replyToID := msg.ReplyToMessageID
+	queue := []string{msg.Content}
+	for len(queue) > 0 {
+		chunk := queue[0]
+		queue = queue[1:]
 
-	if _, err = c.bot.SendMessage(ctx, tgMsg); err != nil {
-		logger.ErrorCF("telegram", "HTML parse failed, falling back to plain text", map[string]any{
-			"error": err.Error(),
-		})
+		content := parseContent(chunk, useMarkdownV2)
+
+		if len([]rune(content)) > 4096 {
+			runeChunk := []rune(chunk)
+			ratio := float64(len(runeChunk)) / float64(len([]rune(content)))
+			smallerLen := int(float64(4096) * ratio * 0.95) // 5% safety margin
+
+			// Guarantee progress: if estimated length is >= chunk length, force it smaller
+			if smallerLen >= len(runeChunk) {
+				smallerLen = len(runeChunk) - 1
+			}
+
+			if smallerLen <= 0 {
+				if err := c.sendChunk(ctx, sendChunkParams{
+					chatID:        chatID,
+					threadID:      threadID,
+					content:       content,
+					replyToID:     replyToID,
+					mdFallback:    chunk,
+					useMarkdownV2: useMarkdownV2,
+				}); err != nil {
+					return err
+				}
+				replyToID = ""
+				continue
+			}
+
+			// Use the estimated smaller length as a guide for SplitMessage.
+			// SplitMessage will find natural break points (newlines/spaces) and respect code blocks.
+			subChunks := channels.SplitMessage(chunk, smallerLen)
+
+			// Safety fallback: If SplitMessage failed to shorten the chunk, force a manual hard split.
+			if len(subChunks) == 1 && subChunks[0] == chunk {
+				part1 := string(runeChunk[:smallerLen])
+				part2 := string(runeChunk[smallerLen:])
+				subChunks = []string{part1, part2}
+			}
+
+			// Filter out empty chunks to avoid sending empty messages to Telegram.
+			nonEmpty := make([]string, 0, len(subChunks))
+			for _, s := range subChunks {
+				if s != "" {
+					nonEmpty = append(nonEmpty, s)
+				}
+			}
+
+			// Push sub-chunks back to the front of the queue
+			queue = append(nonEmpty, queue...)
+			continue
+		}
+
+		if err := c.sendChunk(ctx, sendChunkParams{
+			chatID:        chatID,
+			threadID:      threadID,
+			content:       content,
+			replyToID:     replyToID,
+			mdFallback:    chunk,
+			useMarkdownV2: useMarkdownV2,
+		}); err != nil {
+			return err
+		}
+		// Only the first chunk should be a reply; subsequent chunks are normal messages.
+		replyToID = ""
+	}
+
+	return nil
+}
+
+type sendChunkParams struct {
+	chatID        int64
+	threadID      int
+	content       string
+	replyToID     string
+	mdFallback    string
+	useMarkdownV2 bool
+}
+
+// sendChunk sends a single HTML/MarkdownV2 message, falling back to the original
+// markdown as plain text on parse failure so users never see raw HTML/MarkdownV2 tags.
+func (c *TelegramChannel) sendChunk(
+	ctx context.Context,
+	params sendChunkParams,
+) error {
+	tgMsg := tu.Message(tu.ID(params.chatID), params.content)
+	tgMsg.MessageThreadID = params.threadID
+	if params.useMarkdownV2 {
+		tgMsg.WithParseMode(telego.ModeMarkdownV2)
+	} else {
+		tgMsg.WithParseMode(telego.ModeHTML)
+	}
+
+	if params.replyToID != "" {
+		if mid, parseErr := strconv.Atoi(params.replyToID); parseErr == nil {
+			tgMsg.ReplyParameters = &telego.ReplyParameters{
+				MessageID: mid,
+			}
+		}
+	}
+
+	if _, err := c.bot.SendMessage(ctx, tgMsg); err != nil {
+		logParseFailed(err, params.useMarkdownV2)
+
+		tgMsg.Text = params.mdFallback
 		tgMsg.ParseMode = ""
 		if _, err = c.bot.SendMessage(ctx, tgMsg); err != nil {
 			return fmt.Errorf("telegram send: %w", channels.ErrTemporary)
@@ -192,29 +305,44 @@ func (c *TelegramChannel) Send(ctx context.Context, msg bus.OutboundMessage) err
 	return nil
 }
 
+// maxTypingDuration limits how long the typing indicator can run.
+// Prevents endless typing when the LLM fails/hangs and preSend never invokes cancel.
+// Matches channels.Manager's typingStopTTL (5 min) so behavior is consistent.
+const maxTypingDuration = 5 * time.Minute
+
 // StartTyping implements channels.TypingCapable.
 // It sends ChatAction(typing) immediately and then repeats every 4 seconds
 // (Telegram's typing indicator expires after ~5s) in a background goroutine.
 // The returned stop function is idempotent and cancels the goroutine.
+// The goroutine also exits automatically after maxTypingDuration if cancel is
+// never called (e.g. when the LLM fails or times out without publishing).
 func (c *TelegramChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
-	cid, err := parseChatID(chatID)
+	cid, threadID, err := parseTelegramChatID(chatID)
 	if err != nil {
 		return func() {}, err
 	}
 
+	action := tu.ChatAction(tu.ID(cid), telego.ChatActionTyping)
+	action.MessageThreadID = threadID
+
 	// Send the first typing action immediately
-	_ = c.bot.SendChatAction(ctx, tu.ChatAction(tu.ID(cid), telego.ChatActionTyping))
+	_ = c.bot.SendChatAction(ctx, action)
 
 	typingCtx, cancel := context.WithCancel(ctx)
+	// Cap lifetime so the goroutine cannot run indefinitely if cancel is never called
+	maxCtx, maxCancel := context.WithTimeout(typingCtx, maxTypingDuration)
 	go func() {
+		defer maxCancel()
 		ticker := time.NewTicker(4 * time.Second)
 		defer ticker.Stop()
 		for {
 			select {
-			case <-typingCtx.Done():
+			case <-maxCtx.Done():
 				return
 			case <-ticker.C:
-				_ = c.bot.SendChatAction(typingCtx, tu.ChatAction(tu.ID(cid), telego.ChatActionTyping))
+				a := tu.ChatAction(tu.ID(cid), telego.ChatActionTyping)
+				a.MessageThreadID = threadID
+				_ = c.bot.SendChatAction(typingCtx, a)
 			}
 		}
 	}()
@@ -224,7 +352,8 @@ func (c *TelegramChannel) StartTyping(ctx context.Context, chatID string) (func(
 
 // EditMessage implements channels.MessageEditor.
 func (c *TelegramChannel) EditMessage(ctx context.Context, chatID string, messageID string, content string) error {
-	cid, err := parseChatID(chatID)
+	useMarkdownV2 := c.config.Channels.Telegram.UseMarkdownV2
+	cid, _, err := parseTelegramChatID(chatID)
 	if err != nil {
 		return err
 	}
@@ -232,13 +361,38 @@ func (c *TelegramChannel) EditMessage(ctx context.Context, chatID string, messag
 	if err != nil {
 		return err
 	}
-	htmlContent := markdownToTelegramHTML(content)
-	editMsg := tu.EditMessageText(tu.ID(cid), mid, htmlContent)
-	editMsg.ParseMode = telego.ModeHTML
+	parsedContent := parseContent(content, useMarkdownV2)
+	editMsg := tu.EditMessageText(tu.ID(cid), mid, parsedContent)
+	if useMarkdownV2 {
+		editMsg.WithParseMode(telego.ModeMarkdownV2)
+	} else {
+		editMsg.WithParseMode(telego.ModeHTML)
+	}
 	_, err = c.bot.EditMessageText(ctx, editMsg)
+	if err != nil {
+		logParseFailed(err, useMarkdownV2)
+		_, err = c.bot.EditMessageText(ctx, tu.EditMessageText(tu.ID(cid), mid, content))
+	}
+
 	return err
 }
 
+// DeleteMessage implements channels.MessageDeleter.
+func (c *TelegramChannel) DeleteMessage(ctx context.Context, chatID string, messageID string) error {
+	cid, _, err := parseTelegramChatID(chatID)
+	if err != nil {
+		return err
+	}
+	mid, err := strconv.Atoi(messageID)
+	if err != nil {
+		return err
+	}
+	return c.bot.DeleteMessage(ctx, &telego.DeleteMessageParams{
+		ChatID:    tu.ID(cid),
+		MessageID: mid,
+	})
+}
+
 // SendPlaceholder implements channels.PlaceholderCapable.
 // It sends a placeholder message (e.g. "Thinking... 💭") that will later be
 // edited to the actual response via EditMessage (channels.MessageEditor).
@@ -253,12 +407,14 @@ func (c *TelegramChannel) SendPlaceholder(ctx context.Context, chatID string) (s
 		text = "Thinking... 💭"
 	}
 
-	cid, err := parseChatID(chatID)
+	cid, threadID, err := parseTelegramChatID(chatID)
 	if err != nil {
 		return "", err
 	}
 
-	pMsg, err := c.bot.SendMessage(ctx, tu.Message(tu.ID(cid), text))
+	phMsg := tu.Message(tu.ID(cid), text)
+	phMsg.MessageThreadID = threadID
+	pMsg, err := c.bot.SendMessage(ctx, phMsg)
 	if err != nil {
 		return "", err
 	}
@@ -272,7 +428,7 @@ func (c *TelegramChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMe
 		return channels.ErrNotRunning
 	}
 
-	chatID, err := parseChatID(msg.ChatID)
+	chatID, threadID, err := parseTelegramChatID(msg.ChatID)
 	if err != nil {
 		return fmt.Errorf("invalid chat ID %s: %w", msg.ChatID, channels.ErrSendFailed)
 	}
@@ -304,30 +460,61 @@ func (c *TelegramChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMe
 		switch part.Type {
 		case "image":
 			params := &telego.SendPhotoParams{
-				ChatID:  tu.ID(chatID),
-				Photo:   telego.InputFile{File: file},
-				Caption: part.Caption,
+				ChatID:          tu.ID(chatID),
+				MessageThreadID: threadID,
+				Photo:           telego.InputFile{File: file},
+				Caption:         part.Caption,
 			}
 			_, err = c.bot.SendPhoto(ctx, params)
-		case "audio":
-			params := &telego.SendAudioParams{
-				ChatID:  tu.ID(chatID),
-				Audio:   telego.InputFile{File: file},
-				Caption: part.Caption,
+			if err != nil && strings.Contains(err.Error(), "PHOTO_INVALID_DIMENSIONS") {
+				if _, seekErr := file.Seek(0, io.SeekStart); seekErr != nil {
+					file.Close()
+					return fmt.Errorf("telegram rewind media after photo failure: %w", channels.ErrTemporary)
+				}
+
+				docParams := &telego.SendDocumentParams{
+					ChatID:          tu.ID(chatID),
+					MessageThreadID: threadID,
+					Document:        telego.InputFile{File: file},
+					Caption:         part.Caption,
+				}
+				_, err = c.bot.SendDocument(ctx, docParams)
+			}
+		case "audio":
+			// Send OGG files with "voice" in the filename as Telegram voice
+			// bubbles (SendVoice) instead of audio attachments (SendAudio).
+			fn := strings.ToLower(part.Filename)
+			if strings.Contains(fn, "voice") && (strings.HasSuffix(fn, ".ogg") || strings.HasSuffix(fn, ".oga")) {
+				vparams := &telego.SendVoiceParams{
+					ChatID:          tu.ID(chatID),
+					MessageThreadID: threadID,
+					Voice:           telego.InputFile{File: file},
+					Caption:         part.Caption,
+				}
+				_, err = c.bot.SendVoice(ctx, vparams)
+			} else {
+				params := &telego.SendAudioParams{
+					ChatID:          tu.ID(chatID),
+					MessageThreadID: threadID,
+					Audio:           telego.InputFile{File: file},
+					Caption:         part.Caption,
+				}
+				_, err = c.bot.SendAudio(ctx, params)
 			}
-			_, err = c.bot.SendAudio(ctx, params)
 		case "video":
 			params := &telego.SendVideoParams{
-				ChatID:  tu.ID(chatID),
-				Video:   telego.InputFile{File: file},
-				Caption: part.Caption,
+				ChatID:          tu.ID(chatID),
+				MessageThreadID: threadID,
+				Video:           telego.InputFile{File: file},
+				Caption:         part.Caption,
 			}
 			_, err = c.bot.SendVideo(ctx, params)
 		default: // "file" or unknown types
 			params := &telego.SendDocumentParams{
-				ChatID:   tu.ID(chatID),
-				Document: telego.InputFile{File: file},
-				Caption:  part.Caption,
+				ChatID:          tu.ID(chatID),
+				MessageThreadID: threadID,
+				Document:        telego.InputFile{File: file},
+				Caption:         part.Caption,
 			}
 			_, err = c.bot.SendDocument(ctx, params)
 		}
@@ -387,8 +574,9 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes
 	storeMedia := func(localPath, filename string) string {
 		if store := c.GetMediaStore(); store != nil {
 			ref, err := store.Store(localPath, media.MediaMeta{
-				Filename: filename,
-				Source:   "telegram",
+				Filename:      filename,
+				Source:        "telegram",
+				CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
 			}, scope)
 			if err == nil {
 				return ref
@@ -454,8 +642,12 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes
 		}
 	}
 
+	if content == "" && len(mediaPaths) == 0 {
+		return nil
+	}
+
 	if content == "" {
-		content = "[empty message]"
+		content = "[media only]"
 	}
 
 	// In group chats, apply unified group trigger filtering
@@ -471,19 +663,28 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes
 		content = cleaned
 	}
 
+	// For forum topics, embed the thread ID as "chatID/threadID" so replies
+	// route to the correct topic and each topic gets its own session.
+	// Only forum groups (IsForum) are handled; regular group reply threads
+	// must share one session per group.
+	compositeChatID := fmt.Sprintf("%d", chatID)
+	threadID := message.MessageThreadID
+	if message.Chat.IsForum && threadID != 0 {
+		compositeChatID = fmt.Sprintf("%d/%d", chatID, threadID)
+	}
+
 	logger.DebugCF("telegram", "Received message", map[string]any{
 		"sender_id": sender.CanonicalID,
-		"chat_id":   fmt.Sprintf("%d", chatID),
+		"chat_id":   compositeChatID,
+		"thread_id": threadID,
 		"preview":   utils.Truncate(content, 50),
 	})
 
-	// Placeholder is now auto-triggered by BaseChannel.HandleMessage via PlaceholderCapable
-
 	peerKind := "direct"
 	peerID := fmt.Sprintf("%d", user.ID)
 	if message.Chat.Type != "private" {
 		peerKind = "group"
-		peerID = fmt.Sprintf("%d", chatID)
+		peerID = compositeChatID
 	}
 
 	peer := bus.Peer{Kind: peerKind, ID: peerID}
@@ -496,11 +697,17 @@ func (c *TelegramChannel) handleMessage(ctx context.Context, message *telego.Mes
 		"is_group":   fmt.Sprintf("%t", message.Chat.Type != "private"),
 	}
 
+	// Set parent_peer metadata for per-topic agent binding.
+	if message.Chat.IsForum && threadID != 0 {
+		metadata["parent_peer_kind"] = "topic"
+		metadata["parent_peer_id"] = fmt.Sprintf("%d", threadID)
+	}
+
 	c.HandleMessage(c.ctx,
 		peer,
 		messageID,
 		platformID,
-		fmt.Sprintf("%d", chatID),
+		compositeChatID,
 		content,
 		mediaPaths,
 		metadata,
@@ -548,147 +755,77 @@ func (c *TelegramChannel) downloadFile(ctx context.Context, fileID, ext string)
 	return c.downloadFileWithInfo(file, ext)
 }
 
-func parseChatID(chatIDStr string) (int64, error) {
-	var id int64
-	_, err := fmt.Sscanf(chatIDStr, "%d", &id)
-	return id, err
-}
-
-func markdownToTelegramHTML(text string) string {
-	if text == "" {
-		return ""
+func parseContent(text string, useMarkdownV2 bool) string {
+	if useMarkdownV2 {
+		return markdownToTelegramMarkdownV2(text)
 	}
 
-	codeBlocks := extractCodeBlocks(text)
-	text = codeBlocks.text
+	return markdownToTelegramHTML(text)
+}
 
-	inlineCodes := extractInlineCodes(text)
-	text = inlineCodes.text
+// parseTelegramChatID splits "chatID/threadID" into its components.
+// Returns threadID=0 when no "/" is present (non-forum messages).
+func parseTelegramChatID(chatID string) (int64, int, error) {
+	idx := strings.Index(chatID, "/")
+	if idx == -1 {
+		cid, err := strconv.ParseInt(chatID, 10, 64)
+		return cid, 0, err
+	}
+	cid, err := strconv.ParseInt(chatID[:idx], 10, 64)
+	if err != nil {
+		return 0, 0, err
+	}
+	tid, err := strconv.Atoi(chatID[idx+1:])
+	if err != nil {
+		return 0, 0, fmt.Errorf("invalid thread ID in chat ID %q: %w", chatID, err)
+	}
+	return cid, tid, nil
+}
 
-	text = reHeading.ReplaceAllString(text, "$1")
-
-	text = reBlockquote.ReplaceAllString(text, "$1")
-
-	text = escapeHTML(text)
-
-	text = reLink.ReplaceAllString(text, `<a href="$2">$1</a>`)
-
-	text = reBoldStar.ReplaceAllString(text, "<b>$1</b>")
-
-	text = reBoldUnder.ReplaceAllString(text, "<b>$1</b>")
-
-	text = reItalic.ReplaceAllStringFunc(text, func(s string) string {
-		match := reItalic.FindStringSubmatch(s)
-		if len(match) < 2 {
-			return s
-		}
-		return "<i>" + match[1] + "</i>"
-	})
-
-	text = reStrike.ReplaceAllString(text, "<s>$1</s>")
-
-	text = reListItem.ReplaceAllString(text, "• ")
-
-	for i, code := range inlineCodes.codes {
-		escaped := escapeHTML(code)
-		text = strings.ReplaceAll(text, fmt.Sprintf("\x00IC%d\x00", i), fmt.Sprintf("<code>%s</code>", escaped))
+func logParseFailed(err error, useMarkdownV2 bool) {
+	parsingName := "HTML"
+	if useMarkdownV2 {
+		parsingName = "MarkdownV2"
 	}
 
-	for i, code := range codeBlocks.codes {
-		escaped := escapeHTML(code)
-		text = strings.ReplaceAll(
-			text,
-			fmt.Sprintf("\x00CB%d\x00", i),
-			fmt.Sprintf("<pre><code>%s</code></pre>", escaped),
-		)
-	}
-
-	return text
-}
-
-type codeBlockMatch struct {
-	text  string
-	codes []string
-}
-
-func extractCodeBlocks(text string) codeBlockMatch {
-	matches := reCodeBlock.FindAllStringSubmatch(text, -1)
-
-	codes := make([]string, 0, len(matches))
-	for _, match := range matches {
-		codes = append(codes, match[1])
-	}
-
-	i := 0
-	text = reCodeBlock.ReplaceAllStringFunc(text, func(m string) string {
-		placeholder := fmt.Sprintf("\x00CB%d\x00", i)
-		i++
-		return placeholder
-	})
-
-	return codeBlockMatch{text: text, codes: codes}
-}
-
-type inlineCodeMatch struct {
-	text  string
-	codes []string
-}
-
-func extractInlineCodes(text string) inlineCodeMatch {
-	matches := reInlineCode.FindAllStringSubmatch(text, -1)
-
-	codes := make([]string, 0, len(matches))
-	for _, match := range matches {
-		codes = append(codes, match[1])
-	}
-
-	i := 0
-	text = reInlineCode.ReplaceAllStringFunc(text, func(m string) string {
-		placeholder := fmt.Sprintf("\x00IC%d\x00", i)
-		i++
-		return placeholder
-	})
-
-	return inlineCodeMatch{text: text, codes: codes}
-}
-
-func escapeHTML(text string) string {
-	text = strings.ReplaceAll(text, "&", "&amp;")
-	text = strings.ReplaceAll(text, "<", "&lt;")
-	text = strings.ReplaceAll(text, ">", "&gt;")
-	return text
+	logger.ErrorCF("telegram",
+		fmt.Sprintf("%s parse failed, falling back to plain text", parsingName),
+		map[string]any{
+			"error": err.Error(),
+		},
+	)
 }
 
 // isBotMentioned checks if the bot is mentioned in the message via entities.
 func (c *TelegramChannel) isBotMentioned(message *telego.Message) bool {
-	botUsername := c.bot.Username()
-	if botUsername == "" {
+	text, entities := telegramEntityTextAndList(message)
+	if text == "" || len(entities) == 0 {
 		return false
 	}
 
-	entities := message.Entities
-	if entities == nil {
-		entities = message.CaptionEntities
+	botUsername := ""
+	if c.bot != nil {
+		botUsername = c.bot.Username()
 	}
+	runes := []rune(text)
 
 	for _, entity := range entities {
-		if entity.Type == "mention" {
-			// Extract the mention text from the message
-			text := message.Text
-			if text == "" {
-				text = message.Caption
-			}
-			runes := []rune(text)
-			end := entity.Offset + entity.Length
-			if end <= len(runes) {
-				mention := string(runes[entity.Offset:end])
-				if strings.EqualFold(mention, "@"+botUsername) {
-					return true
-				}
-			}
+		entityText, ok := telegramEntityText(runes, entity)
+		if !ok {
+			continue
 		}
-		if entity.Type == "text_mention" && entity.User != nil {
-			if entity.User.Username == botUsername {
+
+		switch entity.Type {
+		case telego.EntityTypeMention:
+			if botUsername != "" && strings.EqualFold(entityText, "@"+botUsername) {
+				return true
+			}
+		case telego.EntityTypeTextMention:
+			if botUsername != "" && entity.User != nil && strings.EqualFold(entity.User.Username, botUsername) {
+				return true
+			}
+		case telego.EntityTypeBotCommand:
+			if isBotCommandEntityForThisBot(entityText, botUsername) {
 				return true
 			}
 		}
@@ -696,6 +833,46 @@ func (c *TelegramChannel) isBotMentioned(message *telego.Message) bool {
 	return false
 }
 
+func telegramEntityTextAndList(message *telego.Message) (string, []telego.MessageEntity) {
+	if message.Text != "" {
+		return message.Text, message.Entities
+	}
+	return message.Caption, message.CaptionEntities
+}
+
+func telegramEntityText(runes []rune, entity telego.MessageEntity) (string, bool) {
+	if entity.Offset < 0 || entity.Length <= 0 {
+		return "", false
+	}
+	end := entity.Offset + entity.Length
+	if entity.Offset >= len(runes) || end > len(runes) {
+		return "", false
+	}
+	return string(runes[entity.Offset:end]), true
+}
+
+func isBotCommandEntityForThisBot(entityText, botUsername string) bool {
+	if !strings.HasPrefix(entityText, "/") {
+		return false
+	}
+	command := strings.TrimPrefix(entityText, "/")
+	if command == "" {
+		return false
+	}
+
+	at := strings.IndexRune(command, '@')
+	if at == -1 {
+		// A bare /command delivered to this bot is intended for this bot.
+		return true
+	}
+
+	mentionUsername := command[at+1:]
+	if mentionUsername == "" || botUsername == "" {
+		return false
+	}
+	return strings.EqualFold(mentionUsername, botUsername)
+}
+
 // stripBotMention removes the @bot mention from the content.
 func (c *TelegramChannel) stripBotMention(content string) string {
 	botUsername := c.bot.Username()
@@ -707,3 +884,107 @@ func (c *TelegramChannel) stripBotMention(content string) string {
 	content = re.ReplaceAllString(content, "")
 	return strings.TrimSpace(content)
 }
+
+// BeginStream implements channels.StreamingCapable.
+func (c *TelegramChannel) BeginStream(ctx context.Context, chatID string) (channels.Streamer, error) {
+	if !c.config.Channels.Telegram.Streaming.Enabled {
+		return nil, fmt.Errorf("streaming disabled in config")
+	}
+
+	cid, _, err := parseTelegramChatID(chatID)
+	if err != nil {
+		return nil, err
+	}
+
+	streamCfg := c.config.Channels.Telegram.Streaming
+	return &telegramStreamer{
+		bot:              c.bot,
+		chatID:           cid,
+		draftID:          cryptoRandInt(),
+		throttleInterval: time.Duration(streamCfg.ThrottleSeconds) * time.Second,
+		minGrowth:        streamCfg.MinGrowthChars,
+	}, nil
+}
+
+// telegramStreamer streams partial LLM output via Telegram's sendMessageDraft API.
+// On first API error (e.g. bot lacks forum mode), it silently degrades: Update
+// becomes a no-op, while Finalize still delivers the final message.
+type telegramStreamer struct {
+	bot              *telego.Bot
+	chatID           int64
+	draftID          int
+	throttleInterval time.Duration
+	minGrowth        int
+	lastLen          int
+	lastAt           time.Time
+	failed           bool
+	mu               sync.Mutex
+}
+
+func (s *telegramStreamer) Update(ctx context.Context, content string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.failed {
+		return nil
+	}
+
+	// Throttle: skip if not enough time or content has passed
+	now := time.Now()
+	growth := len(content) - s.lastLen
+	if s.lastLen > 0 && now.Sub(s.lastAt) < s.throttleInterval && growth < s.minGrowth {
+		return nil
+	}
+
+	htmlContent := markdownToTelegramHTML(content)
+
+	err := s.bot.SendMessageDraft(ctx, &telego.SendMessageDraftParams{
+		ChatID:    s.chatID,
+		DraftID:   s.draftID,
+		Text:      htmlContent,
+		ParseMode: telego.ModeHTML,
+	})
+	if err != nil {
+		// First error → degrade silently (e.g. no forum mode)
+		logger.WarnCF("telegram", "sendMessageDraft failed, disabling streaming", map[string]any{
+			"error": err.Error(),
+		})
+		s.failed = true
+		return nil // don't propagate — Finalize will still deliver
+	}
+
+	s.lastLen = len(content)
+	s.lastAt = now
+	return nil
+}
+
+func (s *telegramStreamer) Finalize(ctx context.Context, content string) error {
+	htmlContent := markdownToTelegramHTML(content)
+	tgMsg := tu.Message(tu.ID(s.chatID), htmlContent)
+	tgMsg.ParseMode = telego.ModeHTML
+
+	if _, err := s.bot.SendMessage(ctx, tgMsg); err != nil {
+		// Fallback to plain text
+		tgMsg.ParseMode = ""
+		if _, err = s.bot.SendMessage(ctx, tgMsg); err != nil {
+			logger.ErrorCF("telegram", "Finalize failed after HTML and plain-text attempts", map[string]any{
+				"chat_id": s.chatID,
+				"error":   err.Error(),
+				"len":     len(content),
+			})
+			return fmt.Errorf("telegram finalize: %w", err)
+		}
+	}
+	return nil
+}
+
+func (s *telegramStreamer) Cancel(ctx context.Context) {
+	// Draft auto-expires on Telegram's side; nothing to clean up.
+}
+
+// cryptoRandInt returns a non-zero random int using crypto/rand.
+func cryptoRandInt() int {
+	var b [4]byte
+	_, _ = rand.Read(b[:])
+	return int(binary.BigEndian.Uint32(b[:])) | 1 // ensure non-zero
+}
diff --git a/pkg/channels/telegram/telegram_commands.go b/pkg/channels/telegram/telegram_commands.go
deleted file mode 100644
index 496fc5e4f..000000000
--- a/pkg/channels/telegram/telegram_commands.go
+++ /dev/null
@@ -1,156 +0,0 @@
-package telegram
-
-import (
-	"context"
-	"fmt"
-	"strings"
-
-	"github.com/mymmrac/telego"
-
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-type TelegramCommander interface {
-	Help(ctx context.Context, message telego.Message) error
-	Start(ctx context.Context, message telego.Message) error
-	Show(ctx context.Context, message telego.Message) error
-	List(ctx context.Context, message telego.Message) error
-}
-
-type cmd struct {
-	bot    *telego.Bot
-	config *config.Config
-}
-
-func NewTelegramCommands(bot *telego.Bot, cfg *config.Config) TelegramCommander {
-	return &cmd{
-		bot:    bot,
-		config: cfg,
-	}
-}
-
-func commandArgs(text string) string {
-	parts := strings.SplitN(text, " ", 2)
-	if len(parts) < 2 {
-		return ""
-	}
-	return strings.TrimSpace(parts[1])
-}
-
-func (c *cmd) Help(ctx context.Context, message telego.Message) error {
-	msg := `/start - Start the bot
-/help - Show this help message
-/show [model|channel] - Show current configuration
-/list [models|channels] - List available options
-	`
-	_, err := c.bot.SendMessage(ctx, &telego.SendMessageParams{
-		ChatID: telego.ChatID{ID: message.Chat.ID},
-		Text:   msg,
-		ReplyParameters: &telego.ReplyParameters{
-			MessageID: message.MessageID,
-		},
-	})
-	return err
-}
-
-func (c *cmd) Start(ctx context.Context, message telego.Message) error {
-	_, err := c.bot.SendMessage(ctx, &telego.SendMessageParams{
-		ChatID: telego.ChatID{ID: message.Chat.ID},
-		Text:   "Hello! I am PicoClaw 🦞",
-		ReplyParameters: &telego.ReplyParameters{
-			MessageID: message.MessageID,
-		},
-	})
-	return err
-}
-
-func (c *cmd) Show(ctx context.Context, message telego.Message) error {
-	args := commandArgs(message.Text)
-	if args == "" {
-		_, err := c.bot.SendMessage(ctx, &telego.SendMessageParams{
-			ChatID: telego.ChatID{ID: message.Chat.ID},
-			Text:   "Usage: /show [model|channel]",
-			ReplyParameters: &telego.ReplyParameters{
-				MessageID: message.MessageID,
-			},
-		})
-		return err
-	}
-
-	var response string
-	switch args {
-	case "model":
-		response = fmt.Sprintf("Current Model: %s (Provider: %s)",
-			c.config.Agents.Defaults.GetModelName(),
-			c.config.Agents.Defaults.Provider)
-	case "channel":
-		response = "Current Channel: telegram"
-	default:
-		response = fmt.Sprintf("Unknown parameter: %s. Try 'model' or 'channel'.", args)
-	}
-
-	_, err := c.bot.SendMessage(ctx, &telego.SendMessageParams{
-		ChatID: telego.ChatID{ID: message.Chat.ID},
-		Text:   response,
-		ReplyParameters: &telego.ReplyParameters{
-			MessageID: message.MessageID,
-		},
-	})
-	return err
-}
-
-func (c *cmd) List(ctx context.Context, message telego.Message) error {
-	args := commandArgs(message.Text)
-	if args == "" {
-		_, err := c.bot.SendMessage(ctx, &telego.SendMessageParams{
-			ChatID: telego.ChatID{ID: message.Chat.ID},
-			Text:   "Usage: /list [models|channels]",
-			ReplyParameters: &telego.ReplyParameters{
-				MessageID: message.MessageID,
-			},
-		})
-		return err
-	}
-
-	var response string
-	switch args {
-	case "models":
-		provider := c.config.Agents.Defaults.Provider
-		if provider == "" {
-			provider = "configured default"
-		}
-		response = fmt.Sprintf("Configured Model: %s\nProvider: %s\n\nTo change models, update config.json",
-			c.config.Agents.Defaults.GetModelName(), provider)
-
-	case "channels":
-		var enabled []string
-		if c.config.Channels.Telegram.Enabled {
-			enabled = append(enabled, "telegram")
-		}
-		if c.config.Channels.WhatsApp.Enabled {
-			enabled = append(enabled, "whatsapp")
-		}
-		if c.config.Channels.Feishu.Enabled {
-			enabled = append(enabled, "feishu")
-		}
-		if c.config.Channels.Discord.Enabled {
-			enabled = append(enabled, "discord")
-		}
-		if c.config.Channels.Slack.Enabled {
-			enabled = append(enabled, "slack")
-		}
-		response = fmt.Sprintf("Enabled Channels:\n- %s", strings.Join(enabled, "\n- "))
-
-	default:
-		response = fmt.Sprintf("Unknown parameter: %s. Try 'models' or 'channels'.", args)
-	}
-
-	_, err := c.bot.SendMessage(ctx, &telego.SendMessageParams{
-		ChatID: telego.ChatID{ID: message.Chat.ID},
-		Text:   response,
-		ReplyParameters: &telego.ReplyParameters{
-			MessageID: message.MessageID,
-		},
-	})
-	return err
-}
diff --git a/pkg/channels/telegram/telegram_dispatch_test.go b/pkg/channels/telegram/telegram_dispatch_test.go
new file mode 100644
index 000000000..0eb1de5ea
--- /dev/null
+++ b/pkg/channels/telegram/telegram_dispatch_test.go
@@ -0,0 +1,48 @@
+package telegram
+
+import (
+	"context"
+	"testing"
+
+	"github.com/mymmrac/telego"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+)
+
+func TestHandleMessage_DoesNotConsumeGenericCommandsLocally(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	ch := &TelegramChannel{
+		BaseChannel: channels.NewBaseChannel("telegram", nil, messageBus, nil),
+		chatIDs:     make(map[string]int64),
+		ctx:         context.Background(),
+	}
+
+	msg := &telego.Message{
+		Text:      "/new",
+		MessageID: 9,
+		Chat: telego.Chat{
+			ID:   123,
+			Type: "private",
+		},
+		From: &telego.User{
+			ID:        42,
+			FirstName: "Alice",
+		},
+	}
+
+	if err := ch.handleMessage(context.Background(), msg); err != nil {
+		t.Fatalf("handleMessage error: %v", err)
+	}
+
+	inbound, ok := <-messageBus.InboundChan()
+	if !ok {
+		t.Fatal("expected inbound message to be forwarded")
+	}
+	if inbound.Channel != "telegram" {
+		t.Fatalf("channel=%q", inbound.Channel)
+	}
+	if inbound.Content != "/new" {
+		t.Fatalf("content=%q", inbound.Content)
+	}
+}
diff --git a/pkg/channels/telegram/telegram_group_command_filter_test.go b/pkg/channels/telegram/telegram_group_command_filter_test.go
new file mode 100644
index 000000000..614b2ca7f
--- /dev/null
+++ b/pkg/channels/telegram/telegram_group_command_filter_test.go
@@ -0,0 +1,149 @@
+package telegram
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/mymmrac/telego"
+	ta "github.com/mymmrac/telego/telegoapi"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+type getMeCaller struct {
+	username string
+}
+
+func (c getMeCaller) Call(_ context.Context, url string, _ *ta.RequestData) (*ta.Response, error) {
+	if strings.HasSuffix(url, "/getMe") {
+		result := fmt.Sprintf(`{"id":1,"is_bot":true,"first_name":"bot","username":%q}`, c.username)
+		return &ta.Response{Ok: true, Result: []byte(result)}, nil
+	}
+	return &ta.Response{Ok: true, Result: []byte("true")}, nil
+}
+
+func newTestTelegramBot(t *testing.T, username string) *telego.Bot {
+	t.Helper()
+
+	token := "123456:" + strings.Repeat("a", 35)
+	bot, err := telego.NewBot(token,
+		telego.WithAPICaller(getMeCaller{username: username}),
+		telego.WithDiscardLogger(),
+	)
+	if err != nil {
+		t.Fatalf("NewBot error: %v", err)
+	}
+	return bot
+}
+
+func newGroupMentionOnlyChannel(t *testing.T, botUsername string) (*TelegramChannel, *bus.MessageBus) {
+	t.Helper()
+
+	messageBus := bus.NewMessageBus()
+	ch := &TelegramChannel{
+		BaseChannel: channels.NewBaseChannel("telegram", nil, messageBus, nil,
+			channels.WithGroupTrigger(config.GroupTriggerConfig{MentionOnly: true}),
+		),
+		bot:     newTestTelegramBot(t, botUsername),
+		chatIDs: make(map[string]int64),
+		ctx:     context.Background(),
+	}
+	return ch, messageBus
+}
+
+func TestHandleMessage_GroupMentionOnly_BotCommandEntity(t *testing.T) {
+	tests := []struct {
+		name          string
+		text          string
+		wantForwarded bool
+		wantContent   string
+	}{
+		{
+			name:          "command with bot username",
+			text:          "/new@testbot",
+			wantForwarded: true,
+			wantContent:   "/new",
+		},
+		{
+			name:          "bare command",
+			text:          "/new",
+			wantForwarded: true,
+			wantContent:   "/new",
+		},
+		{
+			name:          "command for another bot",
+			text:          "/new@otherbot",
+			wantForwarded: false,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			ch, messageBus := newGroupMentionOnlyChannel(t, "testbot")
+
+			msg := &telego.Message{
+				Text: tc.text,
+				Entities: []telego.MessageEntity{{
+					Type:   telego.EntityTypeBotCommand,
+					Offset: 0,
+					Length: len([]rune(tc.text)),
+				}},
+				MessageID: 42,
+				Chat: telego.Chat{
+					ID:   123,
+					Type: "group",
+				},
+				From: &telego.User{
+					ID:        7,
+					FirstName: "Alice",
+				},
+			}
+
+			if err := ch.handleMessage(context.Background(), msg); err != nil {
+				t.Fatalf("handleMessage error: %v", err)
+			}
+
+			ctx, cancel := context.WithTimeout(context.Background(), 200*time.Microsecond)
+			defer cancel()
+			select {
+			case <-ctx.Done():
+				if tc.wantForwarded {
+					t.Fatal("timeout waiting for message to be forwarded")
+					return
+				}
+			case inbound, ok := <-messageBus.InboundChan():
+				if tc.wantForwarded {
+					if !ok {
+						t.Fatal("expected inbound message to be forwarded")
+					}
+					if inbound.Content != tc.wantContent {
+						t.Fatalf("content=%q want=%q", inbound.Content, tc.wantContent)
+					}
+					return
+				}
+			}
+		})
+	}
+}
+
+func TestIsBotMentioned_MentionEntityUnaffected(t *testing.T) {
+	ch, _ := newGroupMentionOnlyChannel(t, "testbot")
+
+	msg := &telego.Message{
+		Text: "@testbot hello",
+		Entities: []telego.MessageEntity{{
+			Type:   telego.EntityTypeMention,
+			Offset: 0,
+			Length: len("@testbot"),
+		}},
+	}
+
+	if !ch.isBotMentioned(msg) {
+		t.Fatal("expected mention entity to be treated as bot mention")
+	}
+}
diff --git a/pkg/channels/telegram/telegram_test.go b/pkg/channels/telegram/telegram_test.go
new file mode 100644
index 000000000..fd189d9a7
--- /dev/null
+++ b/pkg/channels/telegram/telegram_test.go
@@ -0,0 +1,675 @@
+package telegram
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/mymmrac/telego"
+	ta "github.com/mymmrac/telego/telegoapi"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+const testToken = "1234567890:aaaabbbbaaaabbbbaaaabbbbaaaabbbbccc"
+
+// stubCaller implements ta.Caller for testing.
+type stubCaller struct {
+	calls  []stubCall
+	callFn func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error)
+}
+
+type stubCall struct {
+	URL  string
+	Data *ta.RequestData
+}
+
+func (s *stubCaller) Call(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+	s.calls = append(s.calls, stubCall{URL: url, Data: data})
+	return s.callFn(ctx, url, data)
+}
+
+// stubConstructor implements ta.RequestConstructor for testing.
+type stubConstructor struct{}
+
+type multipartCall struct {
+	Parameters map[string]string
+	FileSizes  map[string]int
+}
+
+func (s *stubConstructor) JSONRequest(parameters any) (*ta.RequestData, error) {
+	b, err := json.Marshal(parameters)
+	if err != nil {
+		return nil, err
+	}
+	return &ta.RequestData{
+		ContentType: "application/json",
+		BodyRaw:     b,
+	}, nil
+}
+
+func (s *stubConstructor) MultipartRequest(
+	parameters map[string]string,
+	files map[string]ta.NamedReader,
+) (*ta.RequestData, error) {
+	return &ta.RequestData{}, nil
+}
+
+type multipartRecordingConstructor struct {
+	stubConstructor
+	calls []multipartCall
+}
+
+func (s *multipartRecordingConstructor) MultipartRequest(
+	parameters map[string]string,
+	files map[string]ta.NamedReader,
+) (*ta.RequestData, error) {
+	call := multipartCall{
+		Parameters: make(map[string]string, len(parameters)),
+		FileSizes:  make(map[string]int, len(files)),
+	}
+	for k, v := range parameters {
+		call.Parameters[k] = v
+	}
+	for field, file := range files {
+		if file == nil {
+			continue
+		}
+		data, err := io.ReadAll(file)
+		if err != nil {
+			return nil, err
+		}
+		call.FileSizes[field] = len(data)
+	}
+	s.calls = append(s.calls, call)
+	return &ta.RequestData{}, nil
+}
+
+// successResponse returns a ta.Response that telego will treat as a successful SendMessage.
+func successResponse(t *testing.T) *ta.Response {
+	t.Helper()
+	msg := &telego.Message{MessageID: 1}
+	b, err := json.Marshal(msg)
+	require.NoError(t, err)
+	return &ta.Response{Ok: true, Result: b}
+}
+
+// newTestChannel creates a TelegramChannel with a mocked bot for unit testing.
+func newTestChannel(t *testing.T, caller *stubCaller) *TelegramChannel {
+	return newTestChannelWithConstructor(t, caller, &stubConstructor{})
+}
+
+func newTestChannelWithConstructor(
+	t *testing.T,
+	caller *stubCaller,
+	constructor ta.RequestConstructor,
+) *TelegramChannel {
+	t.Helper()
+
+	bot, err := telego.NewBot(testToken,
+		telego.WithAPICaller(caller),
+		telego.WithRequestConstructor(constructor),
+		telego.WithDiscardLogger(),
+	)
+	require.NoError(t, err)
+
+	base := channels.NewBaseChannel("telegram", nil, nil, nil,
+		channels.WithMaxMessageLength(4000),
+	)
+	base.SetRunning(true)
+
+	return &TelegramChannel{
+		BaseChannel: base,
+		bot:         bot,
+		chatIDs:     make(map[string]int64),
+		config:      config.DefaultConfig(),
+	}
+}
+
+func TestSendMedia_ImageFallbacksToDocumentOnInvalidDimensions(t *testing.T) {
+	constructor := &multipartRecordingConstructor{}
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			switch {
+			case strings.Contains(url, "sendPhoto"):
+				return nil, errors.New(`api: 400 "Bad Request: PHOTO_INVALID_DIMENSIONS"`)
+			case strings.Contains(url, "sendDocument"):
+				return successResponse(t), nil
+			default:
+				t.Fatalf("unexpected API call: %s", url)
+				return nil, nil
+			}
+		},
+	}
+	ch := newTestChannelWithConstructor(t, caller, constructor)
+
+	store := media.NewFileMediaStore()
+	ch.SetMediaStore(store)
+
+	tmpDir := t.TempDir()
+	localPath := filepath.Join(tmpDir, "woodstock-en-10s.png")
+	content := []byte("fake-png-content")
+	require.NoError(t, os.WriteFile(localPath, content, 0o644))
+
+	ref, err := store.Store(
+		localPath,
+		media.MediaMeta{Filename: "woodstock-en-10s.png", ContentType: "image/png"},
+		"scope-1",
+	)
+	require.NoError(t, err)
+
+	err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "12345",
+		Parts: []bus.MediaPart{{
+			Type:    "image",
+			Ref:     ref,
+			Caption: "caption",
+		}},
+	})
+
+	require.NoError(t, err)
+	require.Len(t, caller.calls, 2)
+	assert.Contains(t, caller.calls[0].URL, "sendPhoto")
+	assert.Contains(t, caller.calls[1].URL, "sendDocument")
+	require.Len(t, constructor.calls, 2)
+	assert.Equal(t, len(content), constructor.calls[0].FileSizes["photo"])
+	assert.Equal(t, len(content), constructor.calls[1].FileSizes["document"])
+	assert.Equal(t, "caption", constructor.calls[1].Parameters["caption"])
+}
+
+func TestSendMedia_ImageNonDimensionErrorDoesNotFallback(t *testing.T) {
+	constructor := &multipartRecordingConstructor{}
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return nil, errors.New("api: 500 \"server exploded\"")
+		},
+	}
+	ch := newTestChannelWithConstructor(t, caller, constructor)
+
+	store := media.NewFileMediaStore()
+	ch.SetMediaStore(store)
+
+	tmpDir := t.TempDir()
+	localPath := filepath.Join(tmpDir, "image.png")
+	require.NoError(t, os.WriteFile(localPath, []byte("fake-png-content"), 0o644))
+
+	ref, err := store.Store(localPath, media.MediaMeta{Filename: "image.png", ContentType: "image/png"}, "scope-1")
+	require.NoError(t, err)
+
+	err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		ChatID: "12345",
+		Parts: []bus.MediaPart{{
+			Type: "image",
+			Ref:  ref,
+		}},
+	})
+
+	require.Error(t, err)
+	assert.ErrorIs(t, err, channels.ErrTemporary)
+	require.Len(t, caller.calls, 1)
+	assert.Contains(t, caller.calls[0].URL, "sendPhoto")
+	require.Len(t, constructor.calls, 1)
+	assert.NotContains(t, caller.calls[0].URL, "sendDocument")
+}
+
+func TestSend_EmptyContent(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			t.Fatal("SendMessage should not be called for empty content")
+			return nil, nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: "",
+	})
+
+	assert.NoError(t, err)
+	assert.Empty(t, caller.calls, "no API calls should be made for empty content")
+}
+
+func TestSend_ShortMessage_SingleCall(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return successResponse(t), nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: "Hello, world!",
+	})
+
+	assert.NoError(t, err)
+	assert.Len(t, caller.calls, 1, "short message should result in exactly one SendMessage call")
+}
+
+func TestSend_LongMessage_SingleCall(t *testing.T) {
+	// With WithMaxMessageLength(4000), the Manager pre-splits messages before
+	// they reach Send(). A message at exactly 4000 chars should go through
+	// as a single SendMessage call (no re-split needed since HTML expansion
+	// won't exceed 4096 for plain text).
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return successResponse(t), nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	longContent := strings.Repeat("a", 4000)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: longContent,
+	})
+
+	assert.NoError(t, err)
+	assert.Len(t, caller.calls, 1, "pre-split message within limit should result in one SendMessage call")
+}
+
+func TestSend_HTMLFallback_PerChunk(t *testing.T) {
+	callCount := 0
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			callCount++
+			// Fail on odd calls (HTML attempt), succeed on even calls (plain text fallback)
+			if callCount%2 == 1 {
+				return nil, errors.New("Bad Request: can't parse entities")
+			}
+			return successResponse(t), nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: "Hello **world**",
+	})
+
+	assert.NoError(t, err)
+	// One short message → 1 HTML attempt (fail) + 1 plain text fallback (success) = 2 calls
+	assert.Equal(t, 2, len(caller.calls), "should have HTML attempt + plain text fallback")
+}
+
+func TestSend_HTMLFallback_BothFail(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return nil, errors.New("send failed")
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: "Hello",
+	})
+
+	assert.Error(t, err)
+	assert.True(t, errors.Is(err, channels.ErrTemporary), "error should wrap ErrTemporary")
+	assert.Equal(t, 2, len(caller.calls), "should have HTML attempt + plain text attempt")
+}
+
+func TestSend_LongMessage_HTMLFallback_StopsOnError(t *testing.T) {
+	// With a long message that gets split into 2 chunks, if both HTML and
+	// plain text fail on the first chunk, Send should return early.
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return nil, errors.New("send failed")
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	longContent := strings.Repeat("x", 4001)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: longContent,
+	})
+
+	assert.Error(t, err)
+	// Should fail on the first chunk (2 calls: HTML + fallback), never reaching the second chunk.
+	assert.Equal(t, 2, len(caller.calls), "should stop after first chunk fails both HTML and plain text")
+}
+
+func TestSend_MarkdownShortButHTMLLong_MultipleCalls(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return successResponse(t), nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	// Create markdown whose length is <= 4000 but whose HTML expansion is much longer.
+	// "**a** " (6 chars) becomes "<b>a</b> " (9 chars) in HTML, so repeating it many times
+	// yields HTML that exceeds Telegram's limit while markdown stays within it.
+	markdownContent := strings.Repeat("**a** ", 600) // 3600 chars markdown, HTML ~5400+ chars
+	assert.LessOrEqual(t, len([]rune(markdownContent)), 4000, "markdown content must not exceed chunk size")
+
+	htmlExpanded := markdownToTelegramHTML(markdownContent)
+	assert.Greater(
+		t, len([]rune(htmlExpanded)), 4096,
+		"HTML expansion must exceed Telegram limit for this test to be meaningful",
+	)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: markdownContent,
+	})
+
+	assert.NoError(t, err)
+	assert.Greater(
+		t, len(caller.calls), 1,
+		"markdown-short but HTML-long message should be split into multiple SendMessage calls",
+	)
+}
+
+func TestSend_HTMLOverflow_WordBoundary(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return successResponse(t), nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	// We want to force a split near index ~2600 while keeping markdown length <= 4000.
+	// Prefix of 430 bold units (6 chars each) = 2580 chars.
+	// Expansion per unit is +3 chars when converted to HTML, so 2580 + 430*3 = 3870.
+	prefix := strings.Repeat("**a** ", 430)
+	targetWord := "TARGETWORDTHATSTAYSTOGETHER"
+	// Suffix of 230 bold units (6 chars each) = 1380 chars.
+	// Total markdown length: 2580 (prefix) + 27 (target word) + 1380 (suffix) = 3987 <= 4000.
+	// HTML expansion adds ~3 chars per bold unit: (430 + 230)*3 = 1980 extra chars,
+	// so total HTML length comfortably exceeds 4096.
+	suffix := strings.Repeat(" **b**", 230)
+	content := prefix + targetWord + suffix
+
+	// Ensure the test content matches the intended boundary conditions.
+	assert.LessOrEqual(t, len([]rune(content)), 4000, "markdown content must not exceed chunk size for this test")
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "123456",
+		Content: content,
+	})
+
+	assert.NoError(t, err)
+
+	foundFullWord := false
+	for i, call := range caller.calls {
+		var params map[string]any
+		err := json.Unmarshal(call.Data.BodyRaw, &params)
+		require.NoError(t, err)
+		text, _ := params["text"].(string)
+
+		hasWord := strings.Contains(text, targetWord)
+		t.Logf("Chunk %d length: %d, contains target word: %v", i, len(text), hasWord)
+
+		if hasWord {
+			foundFullWord = true
+			break
+		}
+	}
+
+	assert.True(t, foundFullWord, "The target word should not be split between chunks")
+}
+
+func TestSend_NotRunning(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			t.Fatal("should not be called")
+			return nil, nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+	ch.SetRunning(false)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "12345",
+		Content: "Hello",
+	})
+
+	assert.ErrorIs(t, err, channels.ErrNotRunning)
+	assert.Empty(t, caller.calls)
+}
+
+func TestSend_InvalidChatID(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			t.Fatal("should not be called")
+			return nil, nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "not-a-number",
+		Content: "Hello",
+	})
+
+	assert.Error(t, err)
+	assert.True(t, errors.Is(err, channels.ErrSendFailed), "error should wrap ErrSendFailed")
+	assert.Empty(t, caller.calls)
+}
+
+func TestParseTelegramChatID_Plain(t *testing.T) {
+	cid, tid, err := parseTelegramChatID("12345")
+	assert.NoError(t, err)
+	assert.Equal(t, int64(12345), cid)
+	assert.Equal(t, 0, tid)
+}
+
+func TestParseTelegramChatID_NegativeGroup(t *testing.T) {
+	cid, tid, err := parseTelegramChatID("-1001234567890")
+	assert.NoError(t, err)
+	assert.Equal(t, int64(-1001234567890), cid)
+	assert.Equal(t, 0, tid)
+}
+
+func TestParseTelegramChatID_WithThreadID(t *testing.T) {
+	cid, tid, err := parseTelegramChatID("-1001234567890/42")
+	assert.NoError(t, err)
+	assert.Equal(t, int64(-1001234567890), cid)
+	assert.Equal(t, 42, tid)
+}
+
+func TestParseTelegramChatID_GeneralTopic(t *testing.T) {
+	cid, tid, err := parseTelegramChatID("-100123/1")
+	assert.NoError(t, err)
+	assert.Equal(t, int64(-100123), cid)
+	assert.Equal(t, 1, tid)
+}
+
+func TestParseTelegramChatID_Invalid(t *testing.T) {
+	_, _, err := parseTelegramChatID("not-a-number")
+	assert.Error(t, err)
+}
+
+func TestParseTelegramChatID_InvalidThreadID(t *testing.T) {
+	_, _, err := parseTelegramChatID("-100123/not-a-thread")
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "invalid thread ID")
+}
+
+func TestSend_WithForumThreadID(t *testing.T) {
+	caller := &stubCaller{
+		callFn: func(ctx context.Context, url string, data *ta.RequestData) (*ta.Response, error) {
+			return successResponse(t), nil
+		},
+	}
+	ch := newTestChannel(t, caller)
+
+	err := ch.Send(context.Background(), bus.OutboundMessage{
+		ChatID:  "-1001234567890/42",
+		Content: "Hello from topic",
+	})
+
+	assert.NoError(t, err)
+	assert.Len(t, caller.calls, 1)
+}
+
+func TestHandleMessage_ForumTopic_SetsMetadata(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	ch := &TelegramChannel{
+		BaseChannel: channels.NewBaseChannel("telegram", nil, messageBus, nil),
+		chatIDs:     make(map[string]int64),
+		ctx:         context.Background(),
+	}
+
+	msg := &telego.Message{
+		Text:            "hello from topic",
+		MessageID:       10,
+		MessageThreadID: 42,
+		Chat: telego.Chat{
+			ID:      -1001234567890,
+			Type:    "supergroup",
+			IsForum: true,
+		},
+		From: &telego.User{
+			ID:        7,
+			FirstName: "Alice",
+		},
+	}
+
+	err := ch.handleMessage(context.Background(), msg)
+	require.NoError(t, err)
+
+	inbound, ok := <-messageBus.InboundChan()
+	require.True(t, ok, "expected inbound message")
+
+	// Composite chatID should include thread ID
+	assert.Equal(t, "-1001234567890/42", inbound.ChatID)
+
+	// Peer ID should include thread ID for session key isolation
+	assert.Equal(t, "group", inbound.Peer.Kind)
+	assert.Equal(t, "-1001234567890/42", inbound.Peer.ID)
+
+	// Parent peer metadata should be set for agent binding
+	assert.Equal(t, "topic", inbound.Metadata["parent_peer_kind"])
+	assert.Equal(t, "42", inbound.Metadata["parent_peer_id"])
+}
+
+func TestHandleMessage_NoForum_NoThreadMetadata(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	ch := &TelegramChannel{
+		BaseChannel: channels.NewBaseChannel("telegram", nil, messageBus, nil),
+		chatIDs:     make(map[string]int64),
+		ctx:         context.Background(),
+	}
+
+	msg := &telego.Message{
+		Text:      "regular group message",
+		MessageID: 11,
+		Chat: telego.Chat{
+			ID:   -100999,
+			Type: "group",
+		},
+		From: &telego.User{
+			ID:        8,
+			FirstName: "Bob",
+		},
+	}
+
+	err := ch.handleMessage(context.Background(), msg)
+	require.NoError(t, err)
+
+	inbound, ok := <-messageBus.InboundChan()
+	require.True(t, ok)
+
+	// Plain chatID without thread suffix
+	assert.Equal(t, "-100999", inbound.ChatID)
+
+	// Peer ID should be raw chat ID (no thread suffix)
+	assert.Equal(t, "group", inbound.Peer.Kind)
+	assert.Equal(t, "-100999", inbound.Peer.ID)
+
+	// No parent peer metadata
+	assert.Empty(t, inbound.Metadata["parent_peer_kind"])
+	assert.Empty(t, inbound.Metadata["parent_peer_id"])
+}
+
+func TestHandleMessage_ReplyThread_NonForum_NoIsolation(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	ch := &TelegramChannel{
+		BaseChannel: channels.NewBaseChannel("telegram", nil, messageBus, nil),
+		chatIDs:     make(map[string]int64),
+		ctx:         context.Background(),
+	}
+
+	// In regular groups, reply threads set MessageThreadID to the original
+	// message ID. This should NOT trigger per-thread session isolation.
+	msg := &telego.Message{
+		Text:            "reply in thread",
+		MessageID:       20,
+		MessageThreadID: 15,
+		Chat: telego.Chat{
+			ID:      -100999,
+			Type:    "supergroup",
+			IsForum: false,
+		},
+		From: &telego.User{
+			ID:        9,
+			FirstName: "Carol",
+		},
+	}
+
+	err := ch.handleMessage(context.Background(), msg)
+	require.NoError(t, err)
+
+	inbound, ok := <-messageBus.InboundChan()
+	require.True(t, ok)
+
+	// chatID should NOT include thread suffix for non-forum groups
+	assert.Equal(t, "-100999", inbound.ChatID)
+
+	// Peer ID should be raw chat ID (shared session for whole group)
+	assert.Equal(t, "group", inbound.Peer.Kind)
+	assert.Equal(t, "-100999", inbound.Peer.ID)
+
+	// No parent peer metadata
+	assert.Empty(t, inbound.Metadata["parent_peer_kind"])
+	assert.Empty(t, inbound.Metadata["parent_peer_id"])
+}
+
+func TestHandleMessage_EmptyContent_Ignored(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	ch := &TelegramChannel{
+		BaseChannel: channels.NewBaseChannel("telegram", nil, messageBus, nil),
+		chatIDs:     make(map[string]int64),
+		ctx:         context.Background(),
+	}
+
+	// Service message with no text/caption/media (like ForumTopicCreated)
+	msg := &telego.Message{
+		MessageID: 123,
+		Chat: telego.Chat{
+			ID:   456,
+			Type: "group",
+		},
+		From: &telego.User{
+			ID:        789,
+			FirstName: "User",
+		},
+	}
+
+	err := ch.handleMessage(context.Background(), msg)
+	require.NoError(t, err)
+
+	// Should NOT publish to message bus
+	select {
+	case <-messageBus.InboundChan():
+		t.Fatal("Empty message should not be published to message bus")
+	default:
+	}
+}
diff --git a/pkg/channels/telegram/testdata/md2_all_formats.txt b/pkg/channels/telegram/testdata/md2_all_formats.txt
new file mode 100644
index 000000000..f78fcc72f
--- /dev/null
+++ b/pkg/channels/telegram/testdata/md2_all_formats.txt
@@ -0,0 +1,31 @@
+*bold \*text*
+_italic \*text_
+__underline__
+~strikethrough~
+||spoiler||
+*bold _italic bold ~italic bold strikethrough ||italic bold strikethrough spoiler||~ __underline italic bold___ bold*
+[inline URL](http://www.example.com/)
+[inline mention of a user](tg://user?id=123456789)
+![👍](tg://emoji?id=5368324170671202286)
+![22:45 tomorrow](tg://time?unix=1647531900&format=wDT)
+![22:45 tomorrow](tg://time?unix=1647531900&format=t)
+![22:45 tomorrow](tg://time?unix=1647531900&format=r)
+![22:45 tomorrow](tg://time?unix=1647531900)
+`inline fixed-width code`
+```
+pre-formatted fixed-width code block
+```
+```python
+pre-formatted fixed-width code block written in the Python programming language
+```
+>Block quotation started
+>Block quotation continued
+>Block quotation continued
+>Block quotation continued
+>The last line of the block quotation
+**>The expandable block quotation started right after the previous block quotation
+>It is separated from the previous block quotation by an empty bold entity
+>Expandable block quotation continued
+>Hidden by default part of the expandable block quotation started
+>Expandable block quotation continued
+>The last line of the expandable block quotation with the expandability mark||
diff --git a/pkg/channels/wecom/app.go b/pkg/channels/wecom/app.go
deleted file mode 100644
index 292a71fd2..000000000
--- a/pkg/channels/wecom/app.go
+++ /dev/null
@@ -1,794 +0,0 @@
-package wecom
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"encoding/xml"
-	"fmt"
-	"io"
-	"mime/multipart"
-	"net/http"
-	"net/url"
-	"os"
-	"path/filepath"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/sipeed/picoclaw/pkg/bus"
-	"github.com/sipeed/picoclaw/pkg/channels"
-	"github.com/sipeed/picoclaw/pkg/config"
-	"github.com/sipeed/picoclaw/pkg/identity"
-	"github.com/sipeed/picoclaw/pkg/logger"
-	"github.com/sipeed/picoclaw/pkg/utils"
-)
-
-const (
-	wecomAPIBase = "https://qyapi.weixin.qq.com"
-)
-
-// WeComAppChannel implements the Channel interface for WeCom App (企业微信自建应用)
-type WeComAppChannel struct {
-	*channels.BaseChannel
-	config        config.WeComAppConfig
-	client        *http.Client
-	accessToken   string
-	tokenExpiry   time.Time
-	tokenMu       sync.RWMutex
-	ctx           context.Context
-	cancel        context.CancelFunc
-	processedMsgs map[string]bool // Message deduplication: msg_id -> processed
-	msgMu         sync.RWMutex
-}
-
-// WeComXMLMessage represents the XML message structure from WeCom
-type WeComXMLMessage struct {
-	XMLName      xml.Name `xml:"xml"`
-	ToUserName   string   `xml:"ToUserName"`
-	FromUserName string   `xml:"FromUserName"`
-	CreateTime   int64    `xml:"CreateTime"`
-	MsgType      string   `xml:"MsgType"`
-	Content      string   `xml:"Content"`
-	MsgId        int64    `xml:"MsgId"`
-	AgentID      int64    `xml:"AgentID"`
-	PicUrl       string   `xml:"PicUrl"`
-	MediaId      string   `xml:"MediaId"`
-	Format       string   `xml:"Format"`
-	ThumbMediaId string   `xml:"ThumbMediaId"`
-	LocationX    float64  `xml:"Location_X"`
-	LocationY    float64  `xml:"Location_Y"`
-	Scale        int      `xml:"Scale"`
-	Label        string   `xml:"Label"`
-	Title        string   `xml:"Title"`
-	Description  string   `xml:"Description"`
-	Url          string   `xml:"Url"`
-	Event        string   `xml:"Event"`
-	EventKey     string   `xml:"EventKey"`
-}
-
-// WeComTextMessage represents text message for sending
-type WeComTextMessage struct {
-	ToUser  string `json:"touser"`
-	MsgType string `json:"msgtype"`
-	AgentID int64  `json:"agentid"`
-	Text    struct {
-		Content string `json:"content"`
-	} `json:"text"`
-	Safe int `json:"safe,omitempty"`
-}
-
-// WeComMarkdownMessage represents markdown message for sending
-type WeComMarkdownMessage struct {
-	ToUser   string `json:"touser"`
-	MsgType  string `json:"msgtype"`
-	AgentID  int64  `json:"agentid"`
-	Markdown struct {
-		Content string `json:"content"`
-	} `json:"markdown"`
-}
-
-// WeComImageMessage represents image message for sending
-type WeComImageMessage struct {
-	ToUser  string `json:"touser"`
-	MsgType string `json:"msgtype"`
-	AgentID int64  `json:"agentid"`
-	Image   struct {
-		MediaID string `json:"media_id"`
-	} `json:"image"`
-}
-
-// WeComAccessTokenResponse represents the access token API response
-type WeComAccessTokenResponse struct {
-	ErrCode     int    `json:"errcode"`
-	ErrMsg      string `json:"errmsg"`
-	AccessToken string `json:"access_token"`
-	ExpiresIn   int    `json:"expires_in"`
-}
-
-// WeComSendMessageResponse represents the send message API response
-type WeComSendMessageResponse struct {
-	ErrCode      int    `json:"errcode"`
-	ErrMsg       string `json:"errmsg"`
-	InvalidUser  string `json:"invaliduser"`
-	InvalidParty string `json:"invalidparty"`
-	InvalidTag   string `json:"invalidtag"`
-}
-
-// PKCS7Padding adds PKCS7 padding
-type PKCS7Padding struct{}
-
-// NewWeComAppChannel creates a new WeCom App channel instance
-func NewWeComAppChannel(cfg config.WeComAppConfig, messageBus *bus.MessageBus) (*WeComAppChannel, error) {
-	if cfg.CorpID == "" || cfg.CorpSecret == "" || cfg.AgentID == 0 {
-		return nil, fmt.Errorf("wecom_app corp_id, corp_secret and agent_id are required")
-	}
-
-	base := channels.NewBaseChannel("wecom_app", cfg, messageBus, cfg.AllowFrom,
-		channels.WithMaxMessageLength(2048),
-		channels.WithGroupTrigger(cfg.GroupTrigger),
-		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
-	)
-
-	// Client timeout must be >= the configured ReplyTimeout so the
-	// per-request context deadline is always the effective limit.
-	clientTimeout := 30 * time.Second
-	if d := time.Duration(cfg.ReplyTimeout) * time.Second; d > clientTimeout {
-		clientTimeout = d
-	}
-
-	ctx, cancel := context.WithCancel(context.Background())
-	return &WeComAppChannel{
-		BaseChannel:   base,
-		config:        cfg,
-		client:        &http.Client{Timeout: clientTimeout},
-		ctx:           ctx,
-		cancel:        cancel,
-		processedMsgs: make(map[string]bool),
-	}, nil
-}
-
-// Name returns the channel name
-func (c *WeComAppChannel) Name() string {
-	return "wecom_app"
-}
-
-// Start initializes the WeCom App channel
-func (c *WeComAppChannel) Start(ctx context.Context) error {
-	logger.InfoC("wecom_app", "Starting WeCom App channel...")
-
-	// Cancel the context created in the constructor to avoid a resource leak.
-	if c.cancel != nil {
-		c.cancel()
-	}
-	c.ctx, c.cancel = context.WithCancel(ctx)
-
-	// Get initial access token
-	if err := c.refreshAccessToken(); err != nil {
-		logger.WarnCF("wecom_app", "Failed to get initial access token", map[string]any{
-			"error": err.Error(),
-		})
-	}
-
-	// Start token refresh goroutine
-	go c.tokenRefreshLoop()
-
-	c.SetRunning(true)
-	logger.InfoC("wecom_app", "WeCom App channel started")
-
-	return nil
-}
-
-// Stop gracefully stops the WeCom App channel
-func (c *WeComAppChannel) Stop(ctx context.Context) error {
-	logger.InfoC("wecom_app", "Stopping WeCom App channel...")
-
-	if c.cancel != nil {
-		c.cancel()
-	}
-
-	c.SetRunning(false)
-	logger.InfoC("wecom_app", "WeCom App channel stopped")
-	return nil
-}
-
-// Send sends a message to WeCom user proactively using access token
-func (c *WeComAppChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
-	if !c.IsRunning() {
-		return channels.ErrNotRunning
-	}
-
-	accessToken := c.getAccessToken()
-	if accessToken == "" {
-		return fmt.Errorf("no valid access token available")
-	}
-
-	logger.DebugCF("wecom_app", "Sending message", map[string]any{
-		"chat_id": msg.ChatID,
-		"preview": utils.Truncate(msg.Content, 100),
-	})
-
-	return c.sendTextMessage(ctx, accessToken, msg.ChatID, msg.Content)
-}
-
-// SendMedia implements the channels.MediaSender interface.
-func (c *WeComAppChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
-	if !c.IsRunning() {
-		return channels.ErrNotRunning
-	}
-
-	accessToken := c.getAccessToken()
-	if accessToken == "" {
-		return fmt.Errorf("no valid access token available: %w", channels.ErrTemporary)
-	}
-
-	store := c.GetMediaStore()
-	if store == nil {
-		return fmt.Errorf("no media store available: %w", channels.ErrSendFailed)
-	}
-
-	for _, part := range msg.Parts {
-		localPath, err := store.Resolve(part.Ref)
-		if err != nil {
-			logger.ErrorCF("wecom_app", "Failed to resolve media ref", map[string]any{
-				"ref":   part.Ref,
-				"error": err.Error(),
-			})
-			continue
-		}
-
-		// Map part type to WeCom media type
-		var mediaType string
-		switch part.Type {
-		case "image":
-			mediaType = "image"
-		case "audio":
-			mediaType = "voice"
-		case "video":
-			mediaType = "video"
-		default:
-			mediaType = "file"
-		}
-
-		// Upload media to get media_id
-		mediaID, err := c.uploadMedia(ctx, accessToken, mediaType, localPath)
-		if err != nil {
-			logger.ErrorCF("wecom_app", "Failed to upload media", map[string]any{
-				"type":  mediaType,
-				"error": err.Error(),
-			})
-			// Fallback: send caption as text
-			if part.Caption != "" {
-				_ = c.sendTextMessage(ctx, accessToken, msg.ChatID, part.Caption)
-			}
-			continue
-		}
-
-		// Send media message using the media_id
-		if mediaType == "image" {
-			err = c.sendImageMessage(ctx, accessToken, msg.ChatID, mediaID)
-		} else {
-			// For non-image types, send as text fallback with caption
-			caption := part.Caption
-			if caption == "" {
-				caption = fmt.Sprintf("[%s: %s]", part.Type, part.Filename)
-			}
-			err = c.sendTextMessage(ctx, accessToken, msg.ChatID, caption)
-		}
-
-		if err != nil {
-			return err
-		}
-	}
-
-	return nil
-}
-
-// uploadMedia uploads a local file to WeCom temporary media storage.
-func (c *WeComAppChannel) uploadMedia(ctx context.Context, accessToken, mediaType, localPath string) (string, error) {
-	apiURL := fmt.Sprintf("%s/cgi-bin/media/upload?access_token=%s&type=%s",
-		wecomAPIBase, url.QueryEscape(accessToken), url.QueryEscape(mediaType))
-
-	file, err := os.Open(localPath)
-	if err != nil {
-		return "", fmt.Errorf("failed to open file: %w", err)
-	}
-	defer file.Close()
-
-	body := &bytes.Buffer{}
-	writer := multipart.NewWriter(body)
-
-	filename := filepath.Base(localPath)
-	formFile, err := writer.CreateFormFile("media", filename)
-	if err != nil {
-		return "", fmt.Errorf("failed to create form file: %w", err)
-	}
-
-	if _, err = io.Copy(formFile, file); err != nil {
-		return "", fmt.Errorf("failed to copy file content: %w", err)
-	}
-	writer.Close()
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, apiURL, body)
-	if err != nil {
-		return "", fmt.Errorf("failed to create request: %w", err)
-	}
-	req.Header.Set("Content-Type", writer.FormDataContentType())
-
-	resp, err := c.client.Do(req)
-	if err != nil {
-		return "", channels.ClassifyNetError(err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		respBody, _ := io.ReadAll(resp.Body)
-		return "", channels.ClassifySendError(resp.StatusCode, fmt.Errorf("wecom upload error: %s", string(respBody)))
-	}
-
-	var result struct {
-		ErrCode int    `json:"errcode"`
-		ErrMsg  string `json:"errmsg"`
-		MediaID string `json:"media_id"`
-	}
-	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
-		return "", fmt.Errorf("failed to parse upload response: %w", err)
-	}
-
-	if result.ErrCode != 0 {
-		return "", fmt.Errorf("upload API error: %s (code: %d)", result.ErrMsg, result.ErrCode)
-	}
-
-	return result.MediaID, nil
-}
-
-// sendImageMessage sends an image message using a media_id.
-func (c *WeComAppChannel) sendImageMessage(ctx context.Context, accessToken, userID, mediaID string) error {
-	apiURL := fmt.Sprintf("%s/cgi-bin/message/send?access_token=%s", wecomAPIBase, accessToken)
-
-	msg := WeComImageMessage{
-		ToUser:  userID,
-		MsgType: "image",
-		AgentID: c.config.AgentID,
-	}
-	msg.Image.MediaID = mediaID
-
-	jsonData, err := json.Marshal(msg)
-	if err != nil {
-		return fmt.Errorf("failed to marshal message: %w", err)
-	}
-
-	timeout := c.config.ReplyTimeout
-	if timeout <= 0 {
-		timeout = 5
-	}
-
-	reqCtx, cancel := context.WithTimeout(ctx, time.Duration(timeout)*time.Second)
-	defer cancel()
-
-	req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, apiURL, bytes.NewBuffer(jsonData))
-	if err != nil {
-		return fmt.Errorf("failed to create request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-
-	resp, err := c.client.Do(req)
-	if err != nil {
-		return channels.ClassifyNetError(err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		respBody, _ := io.ReadAll(resp.Body)
-		return channels.ClassifySendError(resp.StatusCode, fmt.Errorf("wecom_app API error: %s", string(respBody)))
-	}
-
-	respBody, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return fmt.Errorf("failed to read response: %w", err)
-	}
-
-	var sendResp WeComSendMessageResponse
-	if err := json.Unmarshal(respBody, &sendResp); err != nil {
-		return fmt.Errorf("failed to parse response: %w", err)
-	}
-
-	if sendResp.ErrCode != 0 {
-		return fmt.Errorf("API error: %s (code: %d)", sendResp.ErrMsg, sendResp.ErrCode)
-	}
-
-	return nil
-}
-
-// WebhookPath returns the path for registering on the shared HTTP server.
-func (c *WeComAppChannel) WebhookPath() string {
-	if c.config.WebhookPath != "" {
-		return c.config.WebhookPath
-	}
-	return "/webhook/wecom-app"
-}
-
-// ServeHTTP implements http.Handler for the shared HTTP server.
-func (c *WeComAppChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	c.handleWebhook(w, r)
-}
-
-// HealthPath returns the health check endpoint path.
-func (c *WeComAppChannel) HealthPath() string {
-	return "/health/wecom-app"
-}
-
-// HealthHandler handles health check requests.
-func (c *WeComAppChannel) HealthHandler(w http.ResponseWriter, r *http.Request) {
-	c.handleHealth(w, r)
-}
-
-// handleWebhook handles incoming webhook requests from WeCom
-func (c *WeComAppChannel) handleWebhook(w http.ResponseWriter, r *http.Request) {
-	ctx := r.Context()
-
-	// Log all incoming requests for debugging
-	logger.DebugCF("wecom_app", "Received webhook request", map[string]any{
-		"method": r.Method,
-		"url":    r.URL.String(),
-		"path":   r.URL.Path,
-		"query":  r.URL.RawQuery,
-	})
-
-	if r.Method == http.MethodGet {
-		// Handle verification request
-		c.handleVerification(ctx, w, r)
-		return
-	}
-
-	if r.Method == http.MethodPost {
-		// Handle message callback
-		c.handleMessageCallback(ctx, w, r)
-		return
-	}
-
-	logger.WarnCF("wecom_app", "Method not allowed", map[string]any{
-		"method": r.Method,
-	})
-	http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
-}
-
-// handleVerification handles the URL verification request from WeCom
-func (c *WeComAppChannel) handleVerification(ctx context.Context, w http.ResponseWriter, r *http.Request) {
-	query := r.URL.Query()
-	msgSignature := query.Get("msg_signature")
-	timestamp := query.Get("timestamp")
-	nonce := query.Get("nonce")
-	echostr := query.Get("echostr")
-
-	logger.DebugCF("wecom_app", "Handling verification request", map[string]any{
-		"msg_signature": msgSignature,
-		"timestamp":     timestamp,
-		"nonce":         nonce,
-		"echostr":       echostr,
-		"corp_id":       c.config.CorpID,
-	})
-
-	if msgSignature == "" || timestamp == "" || nonce == "" || echostr == "" {
-		logger.ErrorC("wecom_app", "Missing parameters in verification request")
-		http.Error(w, "Missing parameters", http.StatusBadRequest)
-		return
-	}
-
-	// Verify signature
-	if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, echostr) {
-		logger.WarnCF("wecom_app", "Signature verification failed", map[string]any{
-			"token":         c.config.Token,
-			"msg_signature": msgSignature,
-			"timestamp":     timestamp,
-			"nonce":         nonce,
-		})
-		http.Error(w, "Invalid signature", http.StatusForbidden)
-		return
-	}
-
-	logger.DebugC("wecom_app", "Signature verification passed")
-
-	// Decrypt echostr with CorpID verification
-	// For WeCom App (自建应用), receiveid should be corp_id
-	logger.DebugCF("wecom_app", "Attempting to decrypt echostr", map[string]any{
-		"encoding_aes_key": c.config.EncodingAESKey,
-		"corp_id":          c.config.CorpID,
-	})
-	decryptedEchoStr, err := decryptMessageWithVerify(echostr, c.config.EncodingAESKey, c.config.CorpID)
-	if err != nil {
-		logger.ErrorCF("wecom_app", "Failed to decrypt echostr", map[string]any{
-			"error":            err.Error(),
-			"encoding_aes_key": c.config.EncodingAESKey,
-			"corp_id":          c.config.CorpID,
-		})
-		http.Error(w, "Decryption failed", http.StatusInternalServerError)
-		return
-	}
-
-	logger.DebugCF("wecom_app", "Successfully decrypted echostr", map[string]any{
-		"decrypted": decryptedEchoStr,
-	})
-
-	// Remove BOM and whitespace as per WeCom documentation
-	// The response must be plain text without quotes, BOM, or newlines
-	decryptedEchoStr = strings.TrimSpace(decryptedEchoStr)
-	decryptedEchoStr = strings.TrimPrefix(decryptedEchoStr, "\xef\xbb\xbf") // Remove UTF-8 BOM
-	w.Write([]byte(decryptedEchoStr))
-}
-
-// handleMessageCallback handles incoming messages from WeCom
-func (c *WeComAppChannel) handleMessageCallback(ctx context.Context, w http.ResponseWriter, r *http.Request) {
-	query := r.URL.Query()
-	msgSignature := query.Get("msg_signature")
-	timestamp := query.Get("timestamp")
-	nonce := query.Get("nonce")
-
-	if msgSignature == "" || timestamp == "" || nonce == "" {
-		http.Error(w, "Missing parameters", http.StatusBadRequest)
-		return
-	}
-
-	// Read request body
-	body, err := io.ReadAll(r.Body)
-	if err != nil {
-		http.Error(w, "Failed to read body", http.StatusBadRequest)
-		return
-	}
-	defer r.Body.Close()
-
-	// Parse XML to get encrypted message
-	var encryptedMsg struct {
-		XMLName    xml.Name `xml:"xml"`
-		ToUserName string   `xml:"ToUserName"`
-		Encrypt    string   `xml:"Encrypt"`
-		AgentID    string   `xml:"AgentID"`
-	}
-
-	if err = xml.Unmarshal(body, &encryptedMsg); err != nil {
-		logger.ErrorCF("wecom_app", "Failed to parse XML", map[string]any{
-			"error": err.Error(),
-		})
-		http.Error(w, "Invalid XML", http.StatusBadRequest)
-		return
-	}
-
-	// Verify signature
-	if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
-		logger.WarnC("wecom_app", "Message signature verification failed")
-		http.Error(w, "Invalid signature", http.StatusForbidden)
-		return
-	}
-
-	// Decrypt message with CorpID verification
-	// For WeCom App (自建应用), receiveid should be corp_id
-	decryptedMsg, err := decryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, c.config.CorpID)
-	if err != nil {
-		logger.ErrorCF("wecom_app", "Failed to decrypt message", map[string]any{
-			"error": err.Error(),
-		})
-		http.Error(w, "Decryption failed", http.StatusInternalServerError)
-		return
-	}
-
-	// Parse decrypted XML message
-	var msg WeComXMLMessage
-	if err := xml.Unmarshal([]byte(decryptedMsg), &msg); err != nil {
-		logger.ErrorCF("wecom_app", "Failed to parse decrypted message", map[string]any{
-			"error": err.Error(),
-		})
-		http.Error(w, "Invalid message format", http.StatusBadRequest)
-		return
-	}
-
-	// Process the message with the channel's long-lived context (not the HTTP
-	// request context, which is canceled as soon as we return the response).
-	go c.processMessage(c.ctx, msg)
-
-	// Return success response immediately
-	// WeCom App requires response within configured timeout (default 5 seconds)
-	w.Write([]byte("success"))
-}
-
-// processMessage processes the received message
-func (c *WeComAppChannel) processMessage(ctx context.Context, msg WeComXMLMessage) {
-	// Skip non-text messages for now (can be extended)
-	if msg.MsgType != "text" && msg.MsgType != "image" && msg.MsgType != "voice" {
-		logger.DebugCF("wecom_app", "Skipping non-supported message type", map[string]any{
-			"msg_type": msg.MsgType,
-		})
-		return
-	}
-
-	// Message deduplication: Use msg_id to prevent duplicate processing
-	// As per WeCom documentation, use msg_id for deduplication
-	msgID := fmt.Sprintf("%d", msg.MsgId)
-	c.msgMu.Lock()
-	if c.processedMsgs[msgID] {
-		c.msgMu.Unlock()
-		logger.DebugCF("wecom_app", "Skipping duplicate message", map[string]any{
-			"msg_id": msgID,
-		})
-		return
-	}
-	c.processedMsgs[msgID] = true
-	// Clean up old messages while still holding the lock to avoid a data race
-	// on len(). Reset the map but re-insert the current msgID so it remains
-	// deduplicated.
-	if len(c.processedMsgs) > 1000 {
-		c.processedMsgs = make(map[string]bool)
-		c.processedMsgs[msgID] = true
-	}
-	c.msgMu.Unlock()
-
-	senderID := msg.FromUserName
-	chatID := senderID // WeCom App uses user ID as chat ID for direct messages
-
-	// Build metadata
-	// WeCom App only supports direct messages (private chat)
-	peer := bus.Peer{Kind: "direct", ID: senderID}
-	messageID := fmt.Sprintf("%d", msg.MsgId)
-
-	metadata := map[string]string{
-		"msg_type":    msg.MsgType,
-		"msg_id":      fmt.Sprintf("%d", msg.MsgId),
-		"agent_id":    fmt.Sprintf("%d", msg.AgentID),
-		"platform":    "wecom_app",
-		"media_id":    msg.MediaId,
-		"create_time": fmt.Sprintf("%d", msg.CreateTime),
-	}
-
-	content := msg.Content
-
-	logger.DebugCF("wecom_app", "Received message", map[string]any{
-		"sender_id": senderID,
-		"msg_type":  msg.MsgType,
-		"preview":   utils.Truncate(content, 50),
-	})
-
-	// Build sender info
-	appSender := bus.SenderInfo{
-		Platform:    "wecom",
-		PlatformID:  senderID,
-		CanonicalID: identity.BuildCanonicalID("wecom", senderID),
-	}
-
-	// Handle the message through the base channel
-	c.HandleMessage(ctx, peer, messageID, senderID, chatID, content, nil, metadata, appSender)
-}
-
-// tokenRefreshLoop periodically refreshes the access token
-func (c *WeComAppChannel) tokenRefreshLoop() {
-	ticker := time.NewTicker(5 * time.Minute)
-	defer ticker.Stop()
-
-	for {
-		select {
-		case <-c.ctx.Done():
-			return
-		case <-ticker.C:
-			if err := c.refreshAccessToken(); err != nil {
-				logger.ErrorCF("wecom_app", "Failed to refresh access token", map[string]any{
-					"error": err.Error(),
-				})
-			}
-		}
-	}
-}
-
-// refreshAccessToken gets a new access token from WeCom API
-func (c *WeComAppChannel) refreshAccessToken() error {
-	apiURL := fmt.Sprintf("%s/cgi-bin/gettoken?corpid=%s&corpsecret=%s",
-		wecomAPIBase, url.QueryEscape(c.config.CorpID), url.QueryEscape(c.config.CorpSecret))
-
-	resp, err := http.Get(apiURL)
-	if err != nil {
-		return fmt.Errorf("failed to request access token: %w", err)
-	}
-	defer resp.Body.Close()
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return fmt.Errorf("failed to read response: %w", err)
-	}
-
-	var tokenResp WeComAccessTokenResponse
-	if err := json.Unmarshal(body, &tokenResp); err != nil {
-		return fmt.Errorf("failed to parse response: %w", err)
-	}
-
-	if tokenResp.ErrCode != 0 {
-		return fmt.Errorf("API error: %s (code: %d)", tokenResp.ErrMsg, tokenResp.ErrCode)
-	}
-
-	c.tokenMu.Lock()
-	c.accessToken = tokenResp.AccessToken
-	c.tokenExpiry = time.Now().Add(time.Duration(tokenResp.ExpiresIn-300) * time.Second) // Refresh 5 minutes early
-	c.tokenMu.Unlock()
-
-	logger.DebugC("wecom_app", "Access token refreshed successfully")
-	return nil
-}
-
-// getAccessToken returns the current valid access token
-func (c *WeComAppChannel) getAccessToken() string {
-	c.tokenMu.RLock()
-	defer c.tokenMu.RUnlock()
-
-	if time.Now().After(c.tokenExpiry) {
-		return ""
-	}
-
-	return c.accessToken
-}
-
-// sendTextMessage sends a text message to a user
-func (c *WeComAppChannel) sendTextMessage(ctx context.Context, accessToken, userID, content string) error {
-	apiURL := fmt.Sprintf("%s/cgi-bin/message/send?access_token=%s", wecomAPIBase, accessToken)
-
-	msg := WeComTextMessage{
-		ToUser:  userID,
-		MsgType: "text",
-		AgentID: c.config.AgentID,
-	}
-	msg.Text.Content = content
-
-	jsonData, err := json.Marshal(msg)
-	if err != nil {
-		return fmt.Errorf("failed to marshal message: %w", err)
-	}
-
-	// Use configurable timeout (default 5 seconds)
-	timeout := c.config.ReplyTimeout
-	if timeout <= 0 {
-		timeout = 5
-	}
-
-	reqCtx, cancel := context.WithTimeout(ctx, time.Duration(timeout)*time.Second)
-	defer cancel()
-
-	req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, apiURL, bytes.NewBuffer(jsonData))
-	if err != nil {
-		return fmt.Errorf("failed to create request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-
-	resp, err := c.client.Do(req)
-	if err != nil {
-		return channels.ClassifyNetError(err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(resp.Body)
-		return channels.ClassifySendError(resp.StatusCode, fmt.Errorf("wecom_app API error: %s", string(body)))
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return fmt.Errorf("failed to read response: %w", err)
-	}
-
-	var sendResp WeComSendMessageResponse
-	if err := json.Unmarshal(body, &sendResp); err != nil {
-		return fmt.Errorf("failed to parse response: %w", err)
-	}
-
-	if sendResp.ErrCode != 0 {
-		return fmt.Errorf("API error: %s (code: %d)", sendResp.ErrMsg, sendResp.ErrCode)
-	}
-
-	return nil
-}
-
-// handleHealth handles health check requests
-func (c *WeComAppChannel) handleHealth(w http.ResponseWriter, r *http.Request) {
-	status := map[string]any{
-		"status":    "ok",
-		"running":   c.IsRunning(),
-		"has_token": c.getAccessToken() != "",
-	}
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(status)
-}
diff --git a/pkg/channels/wecom/app_test.go b/pkg/channels/wecom/app_test.go
deleted file mode 100644
index 0d15e955b..000000000
--- a/pkg/channels/wecom/app_test.go
+++ /dev/null
@@ -1,1123 +0,0 @@
-package wecom
-
-import (
-	"bytes"
-	"context"
-	"crypto/aes"
-	"crypto/cipher"
-	"crypto/sha1"
-	"encoding/base64"
-	"encoding/binary"
-	"encoding/json"
-	"encoding/xml"
-	"fmt"
-	"net/http"
-	"net/http/httptest"
-	"sort"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/sipeed/picoclaw/pkg/bus"
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-// generateTestAESKeyApp generates a valid test AES key for WeCom App
-func generateTestAESKeyApp() string {
-	// AES key needs to be 32 bytes (256 bits) for AES-256
-	key := make([]byte, 32)
-	for i := range key {
-		key[i] = byte(i + 1)
-	}
-	// Return base64 encoded key without padding
-	return base64.StdEncoding.EncodeToString(key)[:43]
-}
-
-// encryptTestMessageApp encrypts a message for testing WeCom App
-func encryptTestMessageApp(message, aesKey string) (string, error) {
-	// Decode AES key
-	key, err := base64.StdEncoding.DecodeString(aesKey + "=")
-	if err != nil {
-		return "", err
-	}
-
-	// Prepare message: random(16) + msg_len(4) + msg + corp_id
-	random := make([]byte, 0, 16)
-	for i := range 16 {
-		random = append(random, byte(i+1))
-	}
-
-	msgBytes := []byte(message)
-	corpID := []byte("test_corp_id")
-
-	msgLen := uint32(len(msgBytes))
-	lenBytes := make([]byte, 4)
-	binary.BigEndian.PutUint32(lenBytes, msgLen)
-
-	plainText := append(random, lenBytes...)
-	plainText = append(plainText, msgBytes...)
-	plainText = append(plainText, corpID...)
-
-	// PKCS7 padding
-	blockSize := aes.BlockSize
-	padding := blockSize - len(plainText)%blockSize
-	padText := bytes.Repeat([]byte{byte(padding)}, padding)
-	plainText = append(plainText, padText...)
-
-	// Encrypt
-	block, err := aes.NewCipher(key)
-	if err != nil {
-		return "", err
-	}
-
-	mode := cipher.NewCBCEncrypter(block, key[:aes.BlockSize])
-	cipherText := make([]byte, len(plainText))
-	mode.CryptBlocks(cipherText, plainText)
-
-	return base64.StdEncoding.EncodeToString(cipherText), nil
-}
-
-// generateSignatureApp generates a signature for testing WeCom App
-func generateSignatureApp(token, timestamp, nonce, msgEncrypt string) string {
-	params := []string{token, timestamp, nonce, msgEncrypt}
-	sort.Strings(params)
-	str := strings.Join(params, "")
-	hash := sha1.Sum([]byte(str))
-	return fmt.Sprintf("%x", hash)
-}
-
-func TestNewWeComAppChannel(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-
-	t.Run("missing corp_id", func(t *testing.T) {
-		cfg := config.WeComAppConfig{
-			CorpID:     "",
-			CorpSecret: "test_secret",
-			AgentID:    1000002,
-		}
-		_, err := NewWeComAppChannel(cfg, msgBus)
-		if err == nil {
-			t.Error("expected error for missing corp_id, got nil")
-		}
-	})
-
-	t.Run("missing corp_secret", func(t *testing.T) {
-		cfg := config.WeComAppConfig{
-			CorpID:     "test_corp_id",
-			CorpSecret: "",
-			AgentID:    1000002,
-		}
-		_, err := NewWeComAppChannel(cfg, msgBus)
-		if err == nil {
-			t.Error("expected error for missing corp_secret, got nil")
-		}
-	})
-
-	t.Run("missing agent_id", func(t *testing.T) {
-		cfg := config.WeComAppConfig{
-			CorpID:     "test_corp_id",
-			CorpSecret: "test_secret",
-			AgentID:    0,
-		}
-		_, err := NewWeComAppChannel(cfg, msgBus)
-		if err == nil {
-			t.Error("expected error for missing agent_id, got nil")
-		}
-	})
-
-	t.Run("valid config", func(t *testing.T) {
-		cfg := config.WeComAppConfig{
-			CorpID:     "test_corp_id",
-			CorpSecret: "test_secret",
-			AgentID:    1000002,
-			AllowFrom:  []string{"user1", "user2"},
-		}
-		ch, err := NewWeComAppChannel(cfg, msgBus)
-		if err != nil {
-			t.Fatalf("unexpected error: %v", err)
-		}
-		if ch.Name() != "wecom_app" {
-			t.Errorf("Name() = %q, want %q", ch.Name(), "wecom_app")
-		}
-		if ch.IsRunning() {
-			t.Error("new channel should not be running")
-		}
-	})
-}
-
-func TestWeComAppChannelIsAllowed(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-
-	t.Run("empty allowlist allows all", func(t *testing.T) {
-		cfg := config.WeComAppConfig{
-			CorpID:     "test_corp_id",
-			CorpSecret: "test_secret",
-			AgentID:    1000002,
-			AllowFrom:  []string{},
-		}
-		ch, _ := NewWeComAppChannel(cfg, msgBus)
-		if !ch.IsAllowed("any_user") {
-			t.Error("empty allowlist should allow all users")
-		}
-	})
-
-	t.Run("allowlist restricts users", func(t *testing.T) {
-		cfg := config.WeComAppConfig{
-			CorpID:     "test_corp_id",
-			CorpSecret: "test_secret",
-			AgentID:    1000002,
-			AllowFrom:  []string{"allowed_user"},
-		}
-		ch, _ := NewWeComAppChannel(cfg, msgBus)
-		if !ch.IsAllowed("allowed_user") {
-			t.Error("allowed user should pass allowlist check")
-		}
-		if ch.IsAllowed("blocked_user") {
-			t.Error("non-allowed user should be blocked")
-		}
-	})
-}
-
-func TestWeComAppVerifySignature(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	cfg := config.WeComAppConfig{
-		CorpID:     "test_corp_id",
-		CorpSecret: "test_secret",
-		AgentID:    1000002,
-		Token:      "test_token",
-	}
-	ch, _ := NewWeComAppChannel(cfg, msgBus)
-
-	t.Run("valid signature", func(t *testing.T) {
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		msgEncrypt := "test_message"
-		expectedSig := generateSignatureApp("test_token", timestamp, nonce, msgEncrypt)
-
-		if !verifySignature(ch.config.Token, expectedSig, timestamp, nonce, msgEncrypt) {
-			t.Error("valid signature should pass verification")
-		}
-	})
-
-	t.Run("invalid signature", func(t *testing.T) {
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		msgEncrypt := "test_message"
-
-		if verifySignature(ch.config.Token, "invalid_sig", timestamp, nonce, msgEncrypt) {
-			t.Error("invalid signature should fail verification")
-		}
-	})
-
-	t.Run("empty token skips verification", func(t *testing.T) {
-		cfgEmpty := config.WeComAppConfig{
-			CorpID:     "test_corp_id",
-			CorpSecret: "test_secret",
-			AgentID:    1000002,
-			Token:      "",
-		}
-		chEmpty, _ := NewWeComAppChannel(cfgEmpty, msgBus)
-
-		if !verifySignature(chEmpty.config.Token, "any_sig", "any_ts", "any_nonce", "any_msg") {
-			t.Error("empty token should skip verification and return true")
-		}
-	})
-}
-
-func TestWeComAppDecryptMessage(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-
-	t.Run("decrypt without AES key", func(t *testing.T) {
-		cfg := config.WeComAppConfig{
-			CorpID:         "test_corp_id",
-			CorpSecret:     "test_secret",
-			AgentID:        1000002,
-			EncodingAESKey: "",
-		}
-		ch, _ := NewWeComAppChannel(cfg, msgBus)
-
-		// Without AES key, message should be base64 decoded only
-		plainText := "hello world"
-		encoded := base64.StdEncoding.EncodeToString([]byte(plainText))
-
-		result, err := decryptMessage(encoded, ch.config.EncodingAESKey)
-		if err != nil {
-			t.Fatalf("unexpected error: %v", err)
-		}
-		if result != plainText {
-			t.Errorf("decryptMessage() = %q, want %q", result, plainText)
-		}
-	})
-
-	t.Run("decrypt with AES key", func(t *testing.T) {
-		aesKey := generateTestAESKeyApp()
-		cfg := config.WeComAppConfig{
-			CorpID:         "test_corp_id",
-			CorpSecret:     "test_secret",
-			AgentID:        1000002,
-			EncodingAESKey: aesKey,
-		}
-		ch, _ := NewWeComAppChannel(cfg, msgBus)
-
-		originalMsg := "<xml><Content>Hello</Content></xml>"
-		encrypted, err := encryptTestMessageApp(originalMsg, aesKey)
-		if err != nil {
-			t.Fatalf("failed to encrypt test message: %v", err)
-		}
-
-		result, err := decryptMessage(encrypted, ch.config.EncodingAESKey)
-		if err != nil {
-			t.Fatalf("unexpected error: %v", err)
-		}
-		if result != originalMsg {
-			t.Errorf("WeComDecryptMessage() = %q, want %q", result, originalMsg)
-		}
-	})
-
-	t.Run("invalid base64", func(t *testing.T) {
-		cfg := config.WeComAppConfig{
-			CorpID:         "test_corp_id",
-			CorpSecret:     "test_secret",
-			AgentID:        1000002,
-			EncodingAESKey: "",
-		}
-		ch, _ := NewWeComAppChannel(cfg, msgBus)
-
-		_, err := decryptMessage("invalid_base64!!!", ch.config.EncodingAESKey)
-		if err == nil {
-			t.Error("expected error for invalid base64, got nil")
-		}
-	})
-
-	t.Run("invalid AES key", func(t *testing.T) {
-		cfg := config.WeComAppConfig{
-			CorpID:         "test_corp_id",
-			CorpSecret:     "test_secret",
-			AgentID:        1000002,
-			EncodingAESKey: "invalid_key",
-		}
-		ch, _ := NewWeComAppChannel(cfg, msgBus)
-
-		_, err := decryptMessage(base64.StdEncoding.EncodeToString([]byte("test")), ch.config.EncodingAESKey)
-		if err == nil {
-			t.Error("expected error for invalid AES key, got nil")
-		}
-	})
-
-	t.Run("ciphertext too short", func(t *testing.T) {
-		aesKey := generateTestAESKeyApp()
-		cfg := config.WeComAppConfig{
-			CorpID:         "test_corp_id",
-			CorpSecret:     "test_secret",
-			AgentID:        1000002,
-			EncodingAESKey: aesKey,
-		}
-		ch, _ := NewWeComAppChannel(cfg, msgBus)
-
-		// Encrypt a very short message that results in ciphertext less than block size
-		shortData := make([]byte, 8)
-		_, err := decryptMessage(base64.StdEncoding.EncodeToString(shortData), ch.config.EncodingAESKey)
-		if err == nil {
-			t.Error("expected error for short ciphertext, got nil")
-		}
-	})
-}
-
-func TestWeComAppPKCS7Unpad(t *testing.T) {
-	tests := []struct {
-		name     string
-		input    []byte
-		expected []byte
-	}{
-		{
-			name:     "empty input",
-			input:    []byte{},
-			expected: []byte{},
-		},
-		{
-			name:     "valid padding 3 bytes",
-			input:    append([]byte("hello"), bytes.Repeat([]byte{3}, 3)...),
-			expected: []byte("hello"),
-		},
-		{
-			name:     "valid padding 16 bytes (full block)",
-			input:    append([]byte("123456789012345"), bytes.Repeat([]byte{16}, 16)...),
-			expected: []byte("123456789012345"),
-		},
-		{
-			name:     "invalid padding larger than data",
-			input:    []byte{20},
-			expected: nil, // should return error
-		},
-		{
-			name:     "invalid padding zero",
-			input:    append([]byte("test"), byte(0)),
-			expected: nil, // should return error
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result, err := pkcs7Unpad(tt.input)
-			if tt.expected == nil {
-				// This case should return an error
-				if err == nil {
-					t.Errorf("pkcs7Unpad() expected error for invalid padding, got result: %v", result)
-				}
-				return
-			}
-			if err != nil {
-				t.Errorf("pkcs7Unpad() unexpected error: %v", err)
-				return
-			}
-			if !bytes.Equal(result, tt.expected) {
-				t.Errorf("pkcs7Unpad() = %v, want %v", result, tt.expected)
-			}
-		})
-	}
-}
-
-func TestWeComAppHandleVerification(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	aesKey := generateTestAESKeyApp()
-	cfg := config.WeComAppConfig{
-		CorpID:         "test_corp_id",
-		CorpSecret:     "test_secret",
-		AgentID:        1000002,
-		Token:          "test_token",
-		EncodingAESKey: aesKey,
-	}
-	ch, _ := NewWeComAppChannel(cfg, msgBus)
-
-	t.Run("valid verification request", func(t *testing.T) {
-		echostr := "test_echostr_123"
-		encryptedEchostr, _ := encryptTestMessageApp(echostr, aesKey)
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		signature := generateSignatureApp("test_token", timestamp, nonce, encryptedEchostr)
-
-		req := httptest.NewRequest(
-			http.MethodGet,
-			"/webhook/wecom-app?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce+"&echostr="+encryptedEchostr,
-			nil,
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleVerification(context.Background(), w, req)
-
-		if w.Code != http.StatusOK {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
-		}
-		if w.Body.String() != echostr {
-			t.Errorf("response body = %q, want %q", w.Body.String(), echostr)
-		}
-	})
-
-	t.Run("missing parameters", func(t *testing.T) {
-		req := httptest.NewRequest(http.MethodGet, "/webhook/wecom-app?msg_signature=sig&timestamp=ts", nil)
-		w := httptest.NewRecorder()
-
-		ch.handleVerification(context.Background(), w, req)
-
-		if w.Code != http.StatusBadRequest {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusBadRequest)
-		}
-	})
-
-	t.Run("invalid signature", func(t *testing.T) {
-		echostr := "test_echostr"
-		encryptedEchostr, _ := encryptTestMessageApp(echostr, aesKey)
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-
-		req := httptest.NewRequest(
-			http.MethodGet,
-			"/webhook/wecom-app?msg_signature=invalid_sig&timestamp="+timestamp+"&nonce="+nonce+"&echostr="+encryptedEchostr,
-			nil,
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleVerification(context.Background(), w, req)
-
-		if w.Code != http.StatusForbidden {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusForbidden)
-		}
-	})
-}
-
-func TestWeComAppHandleMessageCallback(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	aesKey := generateTestAESKeyApp()
-	cfg := config.WeComAppConfig{
-		CorpID:         "test_corp_id",
-		CorpSecret:     "test_secret",
-		AgentID:        1000002,
-		Token:          "test_token",
-		EncodingAESKey: aesKey,
-	}
-	ch, _ := NewWeComAppChannel(cfg, msgBus)
-
-	t.Run("valid message callback", func(t *testing.T) {
-		// Create XML message
-		xmlMsg := WeComXMLMessage{
-			ToUserName:   "corp_id",
-			FromUserName: "user123",
-			CreateTime:   1234567890,
-			MsgType:      "text",
-			Content:      "Hello World",
-			MsgId:        123456,
-			AgentID:      1000002,
-		}
-		xmlData, _ := xml.Marshal(xmlMsg)
-
-		// Encrypt message
-		encrypted, _ := encryptTestMessageApp(string(xmlData), aesKey)
-
-		// Create encrypted XML wrapper
-		encryptedWrapper := struct {
-			XMLName xml.Name `xml:"xml"`
-			Encrypt string   `xml:"Encrypt"`
-		}{
-			Encrypt: encrypted,
-		}
-		wrapperData, _ := xml.Marshal(encryptedWrapper)
-
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		signature := generateSignatureApp("test_token", timestamp, nonce, encrypted)
-
-		req := httptest.NewRequest(
-			http.MethodPost,
-			"/webhook/wecom-app?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce,
-			bytes.NewReader(wrapperData),
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleMessageCallback(context.Background(), w, req)
-
-		if w.Code != http.StatusOK {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
-		}
-		if w.Body.String() != "success" {
-			t.Errorf("response body = %q, want %q", w.Body.String(), "success")
-		}
-	})
-
-	t.Run("missing parameters", func(t *testing.T) {
-		req := httptest.NewRequest(http.MethodPost, "/webhook/wecom-app?msg_signature=sig", nil)
-		w := httptest.NewRecorder()
-
-		ch.handleMessageCallback(context.Background(), w, req)
-
-		if w.Code != http.StatusBadRequest {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusBadRequest)
-		}
-	})
-
-	t.Run("invalid XML", func(t *testing.T) {
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		signature := generateSignatureApp("test_token", timestamp, nonce, "")
-
-		req := httptest.NewRequest(
-			http.MethodPost,
-			"/webhook/wecom-app?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce,
-			strings.NewReader("invalid xml"),
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleMessageCallback(context.Background(), w, req)
-
-		if w.Code != http.StatusBadRequest {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusBadRequest)
-		}
-	})
-
-	t.Run("invalid signature", func(t *testing.T) {
-		encryptedWrapper := struct {
-			XMLName xml.Name `xml:"xml"`
-			Encrypt string   `xml:"Encrypt"`
-		}{
-			Encrypt: "encrypted_data",
-		}
-		wrapperData, _ := xml.Marshal(encryptedWrapper)
-
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-
-		req := httptest.NewRequest(
-			http.MethodPost,
-			"/webhook/wecom-app?msg_signature=invalid_sig&timestamp="+timestamp+"&nonce="+nonce,
-			bytes.NewReader(wrapperData),
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleMessageCallback(context.Background(), w, req)
-
-		if w.Code != http.StatusForbidden {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusForbidden)
-		}
-	})
-}
-
-func TestWeComAppProcessMessage(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	cfg := config.WeComAppConfig{
-		CorpID:     "test_corp_id",
-		CorpSecret: "test_secret",
-		AgentID:    1000002,
-	}
-	ch, _ := NewWeComAppChannel(cfg, msgBus)
-
-	t.Run("process text message", func(t *testing.T) {
-		msg := WeComXMLMessage{
-			ToUserName:   "corp_id",
-			FromUserName: "user123",
-			CreateTime:   1234567890,
-			MsgType:      "text",
-			Content:      "Hello World",
-			MsgId:        123456,
-			AgentID:      1000002,
-		}
-
-		// Should not panic
-		ch.processMessage(context.Background(), msg)
-	})
-
-	t.Run("process image message", func(t *testing.T) {
-		msg := WeComXMLMessage{
-			ToUserName:   "corp_id",
-			FromUserName: "user123",
-			CreateTime:   1234567890,
-			MsgType:      "image",
-			PicUrl:       "https://example.com/image.jpg",
-			MediaId:      "media_123",
-			MsgId:        123456,
-			AgentID:      1000002,
-		}
-
-		// Should not panic
-		ch.processMessage(context.Background(), msg)
-	})
-
-	t.Run("process voice message", func(t *testing.T) {
-		msg := WeComXMLMessage{
-			ToUserName:   "corp_id",
-			FromUserName: "user123",
-			CreateTime:   1234567890,
-			MsgType:      "voice",
-			MediaId:      "media_123",
-			Format:       "amr",
-			MsgId:        123456,
-			AgentID:      1000002,
-		}
-
-		// Should not panic
-		ch.processMessage(context.Background(), msg)
-	})
-
-	t.Run("skip unsupported message type", func(t *testing.T) {
-		msg := WeComXMLMessage{
-			ToUserName:   "corp_id",
-			FromUserName: "user123",
-			CreateTime:   1234567890,
-			MsgType:      "video",
-			MsgId:        123456,
-			AgentID:      1000002,
-		}
-
-		// Should not panic
-		ch.processMessage(context.Background(), msg)
-	})
-
-	t.Run("process event message", func(t *testing.T) {
-		msg := WeComXMLMessage{
-			ToUserName:   "corp_id",
-			FromUserName: "user123",
-			CreateTime:   1234567890,
-			MsgType:      "event",
-			Event:        "subscribe",
-			MsgId:        123456,
-			AgentID:      1000002,
-		}
-
-		// Should not panic
-		ch.processMessage(context.Background(), msg)
-	})
-}
-
-func TestWeComAppHandleWebhook(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	cfg := config.WeComAppConfig{
-		CorpID:     "test_corp_id",
-		CorpSecret: "test_secret",
-		AgentID:    1000002,
-		Token:      "test_token",
-	}
-	ch, _ := NewWeComAppChannel(cfg, msgBus)
-
-	t.Run("GET request calls verification", func(t *testing.T) {
-		echostr := "test_echostr"
-		encoded := base64.StdEncoding.EncodeToString([]byte(echostr))
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		signature := generateSignatureApp("test_token", timestamp, nonce, encoded)
-
-		req := httptest.NewRequest(
-			http.MethodGet,
-			"/webhook/wecom-app?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce+"&echostr="+encoded,
-			nil,
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleWebhook(w, req)
-
-		if w.Code != http.StatusOK {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
-		}
-	})
-
-	t.Run("POST request calls message callback", func(t *testing.T) {
-		encryptedWrapper := struct {
-			XMLName xml.Name `xml:"xml"`
-			Encrypt string   `xml:"Encrypt"`
-		}{
-			Encrypt: base64.StdEncoding.EncodeToString([]byte("test")),
-		}
-		wrapperData, _ := xml.Marshal(encryptedWrapper)
-
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		signature := generateSignatureApp("test_token", timestamp, nonce, encryptedWrapper.Encrypt)
-
-		req := httptest.NewRequest(
-			http.MethodPost,
-			"/webhook/wecom-app?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce,
-			bytes.NewReader(wrapperData),
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleWebhook(w, req)
-
-		// Should not be method not allowed
-		if w.Code == http.StatusMethodNotAllowed {
-			t.Error("POST request should not return Method Not Allowed")
-		}
-	})
-
-	t.Run("unsupported method", func(t *testing.T) {
-		req := httptest.NewRequest(http.MethodPut, "/webhook/wecom-app", nil)
-		w := httptest.NewRecorder()
-
-		ch.handleWebhook(w, req)
-
-		if w.Code != http.StatusMethodNotAllowed {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusMethodNotAllowed)
-		}
-	})
-}
-
-func TestWeComAppHandleHealth(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	cfg := config.WeComAppConfig{
-		CorpID:     "test_corp_id",
-		CorpSecret: "test_secret",
-		AgentID:    1000002,
-	}
-	ch, _ := NewWeComAppChannel(cfg, msgBus)
-
-	req := httptest.NewRequest(http.MethodGet, "/health/wecom-app", nil)
-	w := httptest.NewRecorder()
-
-	ch.handleHealth(w, req)
-
-	if w.Code != http.StatusOK {
-		t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
-	}
-
-	contentType := w.Header().Get("Content-Type")
-	if contentType != "application/json" {
-		t.Errorf("Content-Type = %q, want %q", contentType, "application/json")
-	}
-
-	body := w.Body.String()
-	if !strings.Contains(body, "status") || !strings.Contains(body, "running") || !strings.Contains(body, "has_token") {
-		t.Errorf("response body should contain status, running, and has_token fields, got: %s", body)
-	}
-}
-
-func TestWeComAppAccessToken(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	cfg := config.WeComAppConfig{
-		CorpID:     "test_corp_id",
-		CorpSecret: "test_secret",
-		AgentID:    1000002,
-	}
-	ch, _ := NewWeComAppChannel(cfg, msgBus)
-
-	t.Run("get empty access token initially", func(t *testing.T) {
-		token := ch.getAccessToken()
-		if token != "" {
-			t.Errorf("getAccessToken() = %q, want empty string", token)
-		}
-	})
-
-	t.Run("set and get access token", func(t *testing.T) {
-		ch.tokenMu.Lock()
-		ch.accessToken = "test_token_123"
-		ch.tokenExpiry = time.Now().Add(1 * time.Hour)
-		ch.tokenMu.Unlock()
-
-		token := ch.getAccessToken()
-		if token != "test_token_123" {
-			t.Errorf("getAccessToken() = %q, want %q", token, "test_token_123")
-		}
-	})
-
-	t.Run("expired token returns empty", func(t *testing.T) {
-		ch.tokenMu.Lock()
-		ch.accessToken = "expired_token"
-		ch.tokenExpiry = time.Now().Add(-1 * time.Hour)
-		ch.tokenMu.Unlock()
-
-		token := ch.getAccessToken()
-		if token != "" {
-			t.Errorf("getAccessToken() = %q, want empty string for expired token", token)
-		}
-	})
-}
-
-func TestWeComAppMessageStructures(t *testing.T) {
-	t.Run("WeComTextMessage structure", func(t *testing.T) {
-		msg := WeComTextMessage{
-			ToUser:  "user123",
-			MsgType: "text",
-			AgentID: 1000002,
-		}
-		msg.Text.Content = "Hello World"
-
-		if msg.ToUser != "user123" {
-			t.Errorf("ToUser = %q, want %q", msg.ToUser, "user123")
-		}
-		if msg.MsgType != "text" {
-			t.Errorf("MsgType = %q, want %q", msg.MsgType, "text")
-		}
-		if msg.AgentID != 1000002 {
-			t.Errorf("AgentID = %d, want %d", msg.AgentID, 1000002)
-		}
-		if msg.Text.Content != "Hello World" {
-			t.Errorf("Text.Content = %q, want %q", msg.Text.Content, "Hello World")
-		}
-
-		// Test JSON marshaling
-		jsonData, err := json.Marshal(msg)
-		if err != nil {
-			t.Fatalf("failed to marshal JSON: %v", err)
-		}
-
-		var unmarshaled WeComTextMessage
-		err = json.Unmarshal(jsonData, &unmarshaled)
-		if err != nil {
-			t.Fatalf("failed to unmarshal JSON: %v", err)
-		}
-
-		if unmarshaled.ToUser != msg.ToUser {
-			t.Errorf("JSON round-trip failed for ToUser")
-		}
-	})
-
-	t.Run("WeComMarkdownMessage structure", func(t *testing.T) {
-		msg := WeComMarkdownMessage{
-			ToUser:  "user123",
-			MsgType: "markdown",
-			AgentID: 1000002,
-		}
-		msg.Markdown.Content = "# Hello\nWorld"
-
-		if msg.Markdown.Content != "# Hello\nWorld" {
-			t.Errorf("Markdown.Content = %q, want %q", msg.Markdown.Content, "# Hello\nWorld")
-		}
-
-		// Test JSON marshaling
-		jsonData, err := json.Marshal(msg)
-		if err != nil {
-			t.Fatalf("failed to marshal JSON: %v", err)
-		}
-
-		if !bytes.Contains(jsonData, []byte("markdown")) {
-			t.Error("JSON should contain 'markdown' field")
-		}
-	})
-
-	t.Run("WeComImageMessage structure", func(t *testing.T) {
-		msg := WeComImageMessage{
-			ToUser:  "user123",
-			MsgType: "image",
-			AgentID: 1000002,
-		}
-		msg.Image.MediaID = "media_123456"
-
-		if msg.Image.MediaID != "media_123456" {
-			t.Errorf("Image.MediaID = %q, want %q", msg.Image.MediaID, "media_123456")
-		}
-		if msg.ToUser != "user123" {
-			t.Errorf("ToUser = %q, want %q", msg.ToUser, "user123")
-		}
-		if msg.MsgType != "image" {
-			t.Errorf("MsgType = %q, want %q", msg.MsgType, "image")
-		}
-		if msg.AgentID != 1000002 {
-			t.Errorf("AgentID = %d, want %d", msg.AgentID, 1000002)
-		}
-	})
-
-	t.Run("WeComAccessTokenResponse structure", func(t *testing.T) {
-		jsonData := `{
-			"errcode": 0,
-			"errmsg": "ok",
-			"access_token": "test_access_token",
-			"expires_in": 7200
-		}`
-
-		var resp WeComAccessTokenResponse
-		err := json.Unmarshal([]byte(jsonData), &resp)
-		if err != nil {
-			t.Fatalf("failed to unmarshal JSON: %v", err)
-		}
-
-		if resp.ErrCode != 0 {
-			t.Errorf("ErrCode = %d, want %d", resp.ErrCode, 0)
-		}
-		if resp.ErrMsg != "ok" {
-			t.Errorf("ErrMsg = %q, want %q", resp.ErrMsg, "ok")
-		}
-		if resp.AccessToken != "test_access_token" {
-			t.Errorf("AccessToken = %q, want %q", resp.AccessToken, "test_access_token")
-		}
-		if resp.ExpiresIn != 7200 {
-			t.Errorf("ExpiresIn = %d, want %d", resp.ExpiresIn, 7200)
-		}
-	})
-
-	t.Run("WeComSendMessageResponse structure", func(t *testing.T) {
-		jsonData := `{
-			"errcode": 0,
-			"errmsg": "ok",
-			"invaliduser": "",
-			"invalidparty": "",
-			"invalidtag": ""
-		}`
-
-		var resp WeComSendMessageResponse
-		err := json.Unmarshal([]byte(jsonData), &resp)
-		if err != nil {
-			t.Fatalf("failed to unmarshal JSON: %v", err)
-		}
-
-		if resp.ErrCode != 0 {
-			t.Errorf("ErrCode = %d, want %d", resp.ErrCode, 0)
-		}
-		if resp.ErrMsg != "ok" {
-			t.Errorf("ErrMsg = %q, want %q", resp.ErrMsg, "ok")
-		}
-	})
-}
-
-func TestWeComAppXMLMessageStructure(t *testing.T) {
-	xmlData := `<?xml version="1.0"?>
-<xml>
-	<ToUserName><![CDATA[corp_id]]></ToUserName>
-	<FromUserName><![CDATA[user123]]></FromUserName>
-	<CreateTime>1234567890</CreateTime>
-	<MsgType><![CDATA[text]]></MsgType>
-	<Content><![CDATA[Hello World]]></Content>
-	<MsgId>1234567890123456</MsgId>
-	<AgentID>1000002</AgentID>
-</xml>`
-
-	var msg WeComXMLMessage
-	err := xml.Unmarshal([]byte(xmlData), &msg)
-	if err != nil {
-		t.Fatalf("failed to unmarshal XML: %v", err)
-	}
-
-	if msg.ToUserName != "corp_id" {
-		t.Errorf("ToUserName = %q, want %q", msg.ToUserName, "corp_id")
-	}
-	if msg.FromUserName != "user123" {
-		t.Errorf("FromUserName = %q, want %q", msg.FromUserName, "user123")
-	}
-	if msg.CreateTime != 1234567890 {
-		t.Errorf("CreateTime = %d, want %d", msg.CreateTime, 1234567890)
-	}
-	if msg.MsgType != "text" {
-		t.Errorf("MsgType = %q, want %q", msg.MsgType, "text")
-	}
-	if msg.Content != "Hello World" {
-		t.Errorf("Content = %q, want %q", msg.Content, "Hello World")
-	}
-	if msg.MsgId != 1234567890123456 {
-		t.Errorf("MsgId = %d, want %d", msg.MsgId, 1234567890123456)
-	}
-	if msg.AgentID != 1000002 {
-		t.Errorf("AgentID = %d, want %d", msg.AgentID, 1000002)
-	}
-}
-
-func TestWeComAppXMLMessageImage(t *testing.T) {
-	xmlData := `<?xml version="1.0"?>
-<xml>
-	<ToUserName><![CDATA[corp_id]]></ToUserName>
-	<FromUserName><![CDATA[user123]]></FromUserName>
-	<CreateTime>1234567890</CreateTime>
-	<MsgType><![CDATA[image]]></MsgType>
-	<PicUrl><![CDATA[https://example.com/image.jpg]]></PicUrl>
-	<MediaId><![CDATA[media_123]]></MediaId>
-	<MsgId>1234567890123456</MsgId>
-	<AgentID>1000002</AgentID>
-</xml>`
-
-	var msg WeComXMLMessage
-	err := xml.Unmarshal([]byte(xmlData), &msg)
-	if err != nil {
-		t.Fatalf("failed to unmarshal XML: %v", err)
-	}
-
-	if msg.MsgType != "image" {
-		t.Errorf("MsgType = %q, want %q", msg.MsgType, "image")
-	}
-	if msg.PicUrl != "https://example.com/image.jpg" {
-		t.Errorf("PicUrl = %q, want %q", msg.PicUrl, "https://example.com/image.jpg")
-	}
-	if msg.MediaId != "media_123" {
-		t.Errorf("MediaId = %q, want %q", msg.MediaId, "media_123")
-	}
-}
-
-func TestWeComAppXMLMessageVoice(t *testing.T) {
-	xmlData := `<?xml version="1.0"?>
-<xml>
-	<ToUserName><![CDATA[corp_id]]></ToUserName>
-	<FromUserName><![CDATA[user123]]></FromUserName>
-	<CreateTime>1234567890</CreateTime>
-	<MsgType><![CDATA[voice]]></MsgType>
-	<MediaId><![CDATA[media_123]]></MediaId>
-	<Format><![CDATA[amr]]></Format>
-	<MsgId>1234567890123456</MsgId>
-	<AgentID>1000002</AgentID>
-</xml>`
-
-	var msg WeComXMLMessage
-	err := xml.Unmarshal([]byte(xmlData), &msg)
-	if err != nil {
-		t.Fatalf("failed to unmarshal XML: %v", err)
-	}
-
-	if msg.MsgType != "voice" {
-		t.Errorf("MsgType = %q, want %q", msg.MsgType, "voice")
-	}
-	if msg.Format != "amr" {
-		t.Errorf("Format = %q, want %q", msg.Format, "amr")
-	}
-}
-
-func TestWeComAppXMLMessageLocation(t *testing.T) {
-	xmlData := `<?xml version="1.0"?>
-<xml>
-	<ToUserName><![CDATA[corp_id]]></ToUserName>
-	<FromUserName><![CDATA[user123]]></FromUserName>
-	<CreateTime>1234567890</CreateTime>
-	<MsgType><![CDATA[location]]></MsgType>
-	<Location_X>39.9042</Location_X>
-	<Location_Y>116.4074</Location_Y>
-	<Scale>16</Scale>
-	<Label><![CDATA[Beijing]]></Label>
-	<MsgId>1234567890123456</MsgId>
-	<AgentID>1000002</AgentID>
-</xml>`
-
-	var msg WeComXMLMessage
-	err := xml.Unmarshal([]byte(xmlData), &msg)
-	if err != nil {
-		t.Fatalf("failed to unmarshal XML: %v", err)
-	}
-
-	if msg.MsgType != "location" {
-		t.Errorf("MsgType = %q, want %q", msg.MsgType, "location")
-	}
-	if msg.LocationX != 39.9042 {
-		t.Errorf("LocationX = %f, want %f", msg.LocationX, 39.9042)
-	}
-	if msg.LocationY != 116.4074 {
-		t.Errorf("LocationY = %f, want %f", msg.LocationY, 116.4074)
-	}
-	if msg.Scale != 16 {
-		t.Errorf("Scale = %d, want %d", msg.Scale, 16)
-	}
-	if msg.Label != "Beijing" {
-		t.Errorf("Label = %q, want %q", msg.Label, "Beijing")
-	}
-}
-
-func TestWeComAppXMLMessageLink(t *testing.T) {
-	xmlData := `<?xml version="1.0"?>
-<xml>
-	<ToUserName><![CDATA[corp_id]]></ToUserName>
-	<FromUserName><![CDATA[user123]]></FromUserName>
-	<CreateTime>1234567890</CreateTime>
-	<MsgType><![CDATA[link]]></MsgType>
-	<Title><![CDATA[Link Title]]></Title>
-	<Description><![CDATA[Link Description]]></Description>
-	<Url><![CDATA[https://example.com]]></Url>
-	<MsgId>1234567890123456</MsgId>
-	<AgentID>1000002</AgentID>
-</xml>`
-
-	var msg WeComXMLMessage
-	err := xml.Unmarshal([]byte(xmlData), &msg)
-	if err != nil {
-		t.Fatalf("failed to unmarshal XML: %v", err)
-	}
-
-	if msg.MsgType != "link" {
-		t.Errorf("MsgType = %q, want %q", msg.MsgType, "link")
-	}
-	if msg.Title != "Link Title" {
-		t.Errorf("Title = %q, want %q", msg.Title, "Link Title")
-	}
-	if msg.Description != "Link Description" {
-		t.Errorf("Description = %q, want %q", msg.Description, "Link Description")
-	}
-	if msg.Url != "https://example.com" {
-		t.Errorf("Url = %q, want %q", msg.Url, "https://example.com")
-	}
-}
-
-func TestWeComAppXMLMessageEvent(t *testing.T) {
-	xmlData := `<?xml version="1.0"?>
-<xml>
-	<ToUserName><![CDATA[corp_id]]></ToUserName>
-	<FromUserName><![CDATA[user123]]></FromUserName>
-	<CreateTime>1234567890</CreateTime>
-	<MsgType><![CDATA[event]]></MsgType>
-	<Event><![CDATA[subscribe]]></Event>
-	<EventKey><![CDATA[event_key_123]]></EventKey>
-	<AgentID>1000002</AgentID>
-</xml>`
-
-	var msg WeComXMLMessage
-	err := xml.Unmarshal([]byte(xmlData), &msg)
-	if err != nil {
-		t.Fatalf("failed to unmarshal XML: %v", err)
-	}
-
-	if msg.MsgType != "event" {
-		t.Errorf("MsgType = %q, want %q", msg.MsgType, "event")
-	}
-	if msg.Event != "subscribe" {
-		t.Errorf("Event = %q, want %q", msg.Event, "subscribe")
-	}
-	if msg.EventKey != "event_key_123" {
-		t.Errorf("EventKey = %q, want %q", msg.EventKey, "event_key_123")
-	}
-}
diff --git a/pkg/channels/wecom/bot.go b/pkg/channels/wecom/bot.go
deleted file mode 100644
index 0d0426c0d..000000000
--- a/pkg/channels/wecom/bot.go
+++ /dev/null
@@ -1,503 +0,0 @@
-package wecom
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"encoding/xml"
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-	"sync"
-	"time"
-
-	"github.com/sipeed/picoclaw/pkg/bus"
-	"github.com/sipeed/picoclaw/pkg/channels"
-	"github.com/sipeed/picoclaw/pkg/config"
-	"github.com/sipeed/picoclaw/pkg/identity"
-	"github.com/sipeed/picoclaw/pkg/logger"
-	"github.com/sipeed/picoclaw/pkg/utils"
-)
-
-// WeComBotChannel implements the Channel interface for WeCom Bot (企业微信智能机器人)
-// Uses webhook callback mode - simpler than WeCom App but only supports passive replies
-type WeComBotChannel struct {
-	*channels.BaseChannel
-	config        config.WeComConfig
-	client        *http.Client
-	ctx           context.Context
-	cancel        context.CancelFunc
-	processedMsgs map[string]bool // Message deduplication: msg_id -> processed
-	msgMu         sync.RWMutex
-}
-
-// WeComBotMessage represents the JSON message structure from WeCom Bot (AIBOT)
-type WeComBotMessage struct {
-	MsgID    string `json:"msgid"`
-	AIBotID  string `json:"aibotid"`
-	ChatID   string `json:"chatid"`   // Session ID, only present for group chats
-	ChatType string `json:"chattype"` // "single" for DM, "group" for group chat
-	From     struct {
-		UserID string `json:"userid"`
-	} `json:"from"`
-	ResponseURL string `json:"response_url"`
-	MsgType     string `json:"msgtype"` // text, image, voice, file, mixed
-	Text        struct {
-		Content string `json:"content"`
-	} `json:"text"`
-	Image struct {
-		URL string `json:"url"`
-	} `json:"image"`
-	Voice struct {
-		Content string `json:"content"` // Voice to text content
-	} `json:"voice"`
-	File struct {
-		URL string `json:"url"`
-	} `json:"file"`
-	Mixed struct {
-		MsgItem []struct {
-			MsgType string `json:"msgtype"`
-			Text    struct {
-				Content string `json:"content"`
-			} `json:"text"`
-			Image struct {
-				URL string `json:"url"`
-			} `json:"image"`
-		} `json:"msg_item"`
-	} `json:"mixed"`
-	Quote struct {
-		MsgType string `json:"msgtype"`
-		Text    struct {
-			Content string `json:"content"`
-		} `json:"text"`
-	} `json:"quote"`
-}
-
-// WeComBotReplyMessage represents the reply message structure
-type WeComBotReplyMessage struct {
-	MsgType string `json:"msgtype"`
-	Text    struct {
-		Content string `json:"content"`
-	} `json:"text,omitempty"`
-}
-
-// NewWeComBotChannel creates a new WeCom Bot channel instance
-func NewWeComBotChannel(cfg config.WeComConfig, messageBus *bus.MessageBus) (*WeComBotChannel, error) {
-	if cfg.Token == "" || cfg.WebhookURL == "" {
-		return nil, fmt.Errorf("wecom token and webhook_url are required")
-	}
-
-	base := channels.NewBaseChannel("wecom", cfg, messageBus, cfg.AllowFrom,
-		channels.WithMaxMessageLength(2048),
-		channels.WithGroupTrigger(cfg.GroupTrigger),
-		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
-	)
-
-	// Client timeout must be >= the configured ReplyTimeout so the
-	// per-request context deadline is always the effective limit.
-	clientTimeout := 30 * time.Second
-	if d := time.Duration(cfg.ReplyTimeout) * time.Second; d > clientTimeout {
-		clientTimeout = d
-	}
-
-	ctx, cancel := context.WithCancel(context.Background())
-	return &WeComBotChannel{
-		BaseChannel:   base,
-		config:        cfg,
-		client:        &http.Client{Timeout: clientTimeout},
-		ctx:           ctx,
-		cancel:        cancel,
-		processedMsgs: make(map[string]bool),
-	}, nil
-}
-
-// Name returns the channel name
-func (c *WeComBotChannel) Name() string {
-	return "wecom"
-}
-
-// Start initializes the WeCom Bot channel
-func (c *WeComBotChannel) Start(ctx context.Context) error {
-	logger.InfoC("wecom", "Starting WeCom Bot channel...")
-
-	// Cancel the context created in the constructor to avoid a resource leak.
-	if c.cancel != nil {
-		c.cancel()
-	}
-	c.ctx, c.cancel = context.WithCancel(ctx)
-
-	c.SetRunning(true)
-	logger.InfoC("wecom", "WeCom Bot channel started")
-
-	return nil
-}
-
-// Stop gracefully stops the WeCom Bot channel
-func (c *WeComBotChannel) Stop(ctx context.Context) error {
-	logger.InfoC("wecom", "Stopping WeCom Bot channel...")
-
-	if c.cancel != nil {
-		c.cancel()
-	}
-
-	c.SetRunning(false)
-	logger.InfoC("wecom", "WeCom Bot channel stopped")
-	return nil
-}
-
-// Send sends a message to WeCom user via webhook API
-// Note: WeCom Bot can only reply within the configured timeout (default 5 seconds) of receiving a message
-// For delayed responses, we use the webhook URL
-func (c *WeComBotChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
-	if !c.IsRunning() {
-		return channels.ErrNotRunning
-	}
-
-	logger.DebugCF("wecom", "Sending message via webhook", map[string]any{
-		"chat_id": msg.ChatID,
-		"preview": utils.Truncate(msg.Content, 100),
-	})
-
-	return c.sendWebhookReply(ctx, msg.ChatID, msg.Content)
-}
-
-// WebhookPath returns the path for registering on the shared HTTP server.
-func (c *WeComBotChannel) WebhookPath() string {
-	if c.config.WebhookPath != "" {
-		return c.config.WebhookPath
-	}
-	return "/webhook/wecom"
-}
-
-// ServeHTTP implements http.Handler for the shared HTTP server.
-func (c *WeComBotChannel) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	c.handleWebhook(w, r)
-}
-
-// HealthPath returns the health check endpoint path.
-func (c *WeComBotChannel) HealthPath() string {
-	return "/health/wecom"
-}
-
-// HealthHandler handles health check requests.
-func (c *WeComBotChannel) HealthHandler(w http.ResponseWriter, r *http.Request) {
-	c.handleHealth(w, r)
-}
-
-// handleWebhook handles incoming webhook requests from WeCom
-func (c *WeComBotChannel) handleWebhook(w http.ResponseWriter, r *http.Request) {
-	ctx := r.Context()
-
-	if r.Method == http.MethodGet {
-		// Handle verification request
-		c.handleVerification(ctx, w, r)
-		return
-	}
-
-	if r.Method == http.MethodPost {
-		// Handle message callback
-		c.handleMessageCallback(ctx, w, r)
-		return
-	}
-
-	http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
-}
-
-// handleVerification handles the URL verification request from WeCom
-func (c *WeComBotChannel) handleVerification(ctx context.Context, w http.ResponseWriter, r *http.Request) {
-	query := r.URL.Query()
-	msgSignature := query.Get("msg_signature")
-	timestamp := query.Get("timestamp")
-	nonce := query.Get("nonce")
-	echostr := query.Get("echostr")
-
-	if msgSignature == "" || timestamp == "" || nonce == "" || echostr == "" {
-		http.Error(w, "Missing parameters", http.StatusBadRequest)
-		return
-	}
-
-	// Verify signature
-	if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, echostr) {
-		logger.WarnC("wecom", "Signature verification failed")
-		http.Error(w, "Invalid signature", http.StatusForbidden)
-		return
-	}
-
-	// Decrypt echostr
-	// For AIBOT (智能机器人), receiveid should be empty string ""
-	// Reference: https://developer.work.weixin.qq.com/document/path/101033
-	decryptedEchoStr, err := decryptMessageWithVerify(echostr, c.config.EncodingAESKey, "")
-	if err != nil {
-		logger.ErrorCF("wecom", "Failed to decrypt echostr", map[string]any{
-			"error": err.Error(),
-		})
-		http.Error(w, "Decryption failed", http.StatusInternalServerError)
-		return
-	}
-
-	// Remove BOM and whitespace as per WeCom documentation
-	// The response must be plain text without quotes, BOM, or newlines
-	decryptedEchoStr = strings.TrimSpace(decryptedEchoStr)
-	decryptedEchoStr = strings.TrimPrefix(decryptedEchoStr, "\xef\xbb\xbf") // Remove UTF-8 BOM
-	w.Write([]byte(decryptedEchoStr))
-}
-
-// handleMessageCallback handles incoming messages from WeCom
-func (c *WeComBotChannel) handleMessageCallback(ctx context.Context, w http.ResponseWriter, r *http.Request) {
-	query := r.URL.Query()
-	msgSignature := query.Get("msg_signature")
-	timestamp := query.Get("timestamp")
-	nonce := query.Get("nonce")
-
-	if msgSignature == "" || timestamp == "" || nonce == "" {
-		http.Error(w, "Missing parameters", http.StatusBadRequest)
-		return
-	}
-
-	// Read request body
-	body, err := io.ReadAll(r.Body)
-	if err != nil {
-		http.Error(w, "Failed to read body", http.StatusBadRequest)
-		return
-	}
-	defer r.Body.Close()
-
-	// Parse XML to get encrypted message
-	var encryptedMsg struct {
-		XMLName    xml.Name `xml:"xml"`
-		ToUserName string   `xml:"ToUserName"`
-		Encrypt    string   `xml:"Encrypt"`
-		AgentID    string   `xml:"AgentID"`
-	}
-
-	if err = xml.Unmarshal(body, &encryptedMsg); err != nil {
-		logger.ErrorCF("wecom", "Failed to parse XML", map[string]any{
-			"error": err.Error(),
-		})
-		http.Error(w, "Invalid XML", http.StatusBadRequest)
-		return
-	}
-
-	// Verify signature
-	if !verifySignature(c.config.Token, msgSignature, timestamp, nonce, encryptedMsg.Encrypt) {
-		logger.WarnC("wecom", "Message signature verification failed")
-		http.Error(w, "Invalid signature", http.StatusForbidden)
-		return
-	}
-
-	// Decrypt message
-	// For AIBOT (智能机器人), receiveid should be empty string ""
-	// Reference: https://developer.work.weixin.qq.com/document/path/101033
-	decryptedMsg, err := decryptMessageWithVerify(encryptedMsg.Encrypt, c.config.EncodingAESKey, "")
-	if err != nil {
-		logger.ErrorCF("wecom", "Failed to decrypt message", map[string]any{
-			"error": err.Error(),
-		})
-		http.Error(w, "Decryption failed", http.StatusInternalServerError)
-		return
-	}
-
-	// Parse decrypted JSON message (AIBOT uses JSON format)
-	var msg WeComBotMessage
-	if err := json.Unmarshal([]byte(decryptedMsg), &msg); err != nil {
-		logger.ErrorCF("wecom", "Failed to parse decrypted message", map[string]any{
-			"error": err.Error(),
-		})
-		http.Error(w, "Invalid message format", http.StatusBadRequest)
-		return
-	}
-
-	// Process the message with the channel's long-lived context (not the HTTP
-	// request context, which is canceled as soon as we return the response).
-	go c.processMessage(c.ctx, msg)
-
-	// Return success response immediately
-	// WeCom Bot requires response within configured timeout (default 5 seconds)
-	w.Write([]byte("success"))
-}
-
-// processMessage processes the received message
-func (c *WeComBotChannel) processMessage(ctx context.Context, msg WeComBotMessage) {
-	// Skip unsupported message types
-	if msg.MsgType != "text" && msg.MsgType != "image" && msg.MsgType != "voice" && msg.MsgType != "file" &&
-		msg.MsgType != "mixed" {
-		logger.DebugCF("wecom", "Skipping non-supported message type", map[string]any{
-			"msg_type": msg.MsgType,
-		})
-		return
-	}
-
-	// Message deduplication: Use msg_id to prevent duplicate processing
-	msgID := msg.MsgID
-	c.msgMu.Lock()
-	if c.processedMsgs[msgID] {
-		c.msgMu.Unlock()
-		logger.DebugCF("wecom", "Skipping duplicate message", map[string]any{
-			"msg_id": msgID,
-		})
-		return
-	}
-	c.processedMsgs[msgID] = true
-	// Clean up old messages while still holding the lock to avoid a data race
-	// on len(). Reset the map but re-insert the current msgID so it remains
-	// deduplicated.
-	if len(c.processedMsgs) > 1000 {
-		c.processedMsgs = make(map[string]bool)
-		c.processedMsgs[msgID] = true
-	}
-	c.msgMu.Unlock()
-
-	senderID := msg.From.UserID
-
-	// Determine if this is a group chat or direct message
-	// ChatType: "single" for DM, "group" for group chat
-	isGroupChat := msg.ChatType == "group"
-
-	var chatID, peerKind, peerID string
-	if isGroupChat {
-		// Group chat: use ChatID as chatID and peer_id
-		chatID = msg.ChatID
-		peerKind = "group"
-		peerID = msg.ChatID
-	} else {
-		// Direct message: use senderID as chatID and peer_id
-		chatID = senderID
-		peerKind = "direct"
-		peerID = senderID
-	}
-
-	// Extract content based on message type
-	var content string
-	switch msg.MsgType {
-	case "text":
-		content = msg.Text.Content
-	case "voice":
-		content = msg.Voice.Content // Voice to text content
-	case "mixed":
-		// For mixed messages, concatenate text items
-		for _, item := range msg.Mixed.MsgItem {
-			if item.MsgType == "text" {
-				content += item.Text.Content
-			}
-		}
-	case "image", "file":
-		// For image and file, we don't have text content
-		content = ""
-	}
-
-	// Build metadata
-	peer := bus.Peer{Kind: peerKind, ID: peerID}
-
-	// In group chats, apply unified group trigger filtering
-	if isGroupChat {
-		respond, cleaned := c.ShouldRespondInGroup(false, content)
-		if !respond {
-			return
-		}
-		content = cleaned
-	}
-
-	metadata := map[string]string{
-		"msg_type":     msg.MsgType,
-		"msg_id":       msg.MsgID,
-		"platform":     "wecom",
-		"response_url": msg.ResponseURL,
-	}
-	if isGroupChat {
-		metadata["chat_id"] = msg.ChatID
-		metadata["sender_id"] = senderID
-	}
-
-	logger.DebugCF("wecom", "Received message", map[string]any{
-		"sender_id":     senderID,
-		"msg_type":      msg.MsgType,
-		"peer_kind":     peerKind,
-		"is_group_chat": isGroupChat,
-		"preview":       utils.Truncate(content, 50),
-	})
-
-	// Build sender info
-	sender := bus.SenderInfo{
-		Platform:    "wecom",
-		PlatformID:  senderID,
-		CanonicalID: identity.BuildCanonicalID("wecom", senderID),
-	}
-
-	if !c.IsAllowedSender(sender) {
-		return
-	}
-
-	// Handle the message through the base channel
-	c.HandleMessage(ctx, peer, msg.MsgID, senderID, chatID, content, nil, metadata, sender)
-}
-
-// sendWebhookReply sends a reply using the webhook URL
-func (c *WeComBotChannel) sendWebhookReply(ctx context.Context, userID, content string) error {
-	reply := WeComBotReplyMessage{
-		MsgType: "text",
-	}
-	reply.Text.Content = content
-
-	jsonData, err := json.Marshal(reply)
-	if err != nil {
-		return fmt.Errorf("failed to marshal reply: %w", err)
-	}
-
-	// Use configurable timeout (default 5 seconds)
-	timeout := c.config.ReplyTimeout
-	if timeout <= 0 {
-		timeout = 5
-	}
-
-	reqCtx, cancel := context.WithTimeout(ctx, time.Duration(timeout)*time.Second)
-	defer cancel()
-
-	req, err := http.NewRequestWithContext(reqCtx, http.MethodPost, c.config.WebhookURL, bytes.NewBuffer(jsonData))
-	if err != nil {
-		return fmt.Errorf("failed to create request: %w", err)
-	}
-	req.Header.Set("Content-Type", "application/json")
-
-	resp, err := c.client.Do(req)
-	if err != nil {
-		return channels.ClassifyNetError(err)
-	}
-	defer resp.Body.Close()
-
-	if resp.StatusCode != http.StatusOK {
-		body, _ := io.ReadAll(resp.Body)
-		return channels.ClassifySendError(resp.StatusCode, fmt.Errorf("webhook API error: %s", string(body)))
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return fmt.Errorf("failed to read response: %w", err)
-	}
-
-	// Check response
-	var result struct {
-		ErrCode int    `json:"errcode"`
-		ErrMsg  string `json:"errmsg"`
-	}
-	if err := json.Unmarshal(body, &result); err != nil {
-		return fmt.Errorf("failed to parse response: %w", err)
-	}
-
-	if result.ErrCode != 0 {
-		return fmt.Errorf("webhook API error: %s (code: %d)", result.ErrMsg, result.ErrCode)
-	}
-
-	return nil
-}
-
-// handleHealth handles health check requests
-func (c *WeComBotChannel) handleHealth(w http.ResponseWriter, r *http.Request) {
-	status := map[string]any{
-		"status":  "ok",
-		"running": c.IsRunning(),
-	}
-
-	w.Header().Set("Content-Type", "application/json")
-	json.NewEncoder(w).Encode(status)
-}
diff --git a/pkg/channels/wecom/bot_test.go b/pkg/channels/wecom/bot_test.go
deleted file mode 100644
index 97b503ce8..000000000
--- a/pkg/channels/wecom/bot_test.go
+++ /dev/null
@@ -1,782 +0,0 @@
-package wecom
-
-import (
-	"bytes"
-	"context"
-	"crypto/aes"
-	"crypto/cipher"
-	"crypto/sha1"
-	"encoding/base64"
-	"encoding/binary"
-	"encoding/json"
-	"encoding/xml"
-	"fmt"
-	"net/http"
-	"net/http/httptest"
-	"sort"
-	"strings"
-	"testing"
-
-	"github.com/sipeed/picoclaw/pkg/bus"
-	"github.com/sipeed/picoclaw/pkg/config"
-)
-
-// generateTestAESKey generates a valid test AES key
-func generateTestAESKey() string {
-	// AES key needs to be 32 bytes (256 bits) for AES-256
-	key := make([]byte, 32)
-	for i := range key {
-		key[i] = byte(i)
-	}
-	// Return base64 encoded key without padding
-	return base64.StdEncoding.EncodeToString(key)[:43]
-}
-
-// encryptTestMessage encrypts a message for testing (AIBOT JSON format)
-func encryptTestMessage(message, aesKey string) (string, error) {
-	// Decode AES key
-	key, err := base64.StdEncoding.DecodeString(aesKey + "=")
-	if err != nil {
-		return "", err
-	}
-
-	// Prepare message: random(16) + msg_len(4) + msg + receiveid
-	random := make([]byte, 0, 16)
-	for i := range 16 {
-		random = append(random, byte(i))
-	}
-
-	msgBytes := []byte(message)
-	receiveID := []byte("test_aibot_id")
-
-	msgLen := uint32(len(msgBytes))
-	lenBytes := make([]byte, 4)
-	binary.BigEndian.PutUint32(lenBytes, msgLen)
-
-	plainText := append(random, lenBytes...)
-	plainText = append(plainText, msgBytes...)
-	plainText = append(plainText, receiveID...)
-
-	// PKCS7 padding
-	blockSize := aes.BlockSize
-	padding := blockSize - len(plainText)%blockSize
-	padText := bytes.Repeat([]byte{byte(padding)}, padding)
-	plainText = append(plainText, padText...)
-
-	// Encrypt
-	block, err := aes.NewCipher(key)
-	if err != nil {
-		return "", err
-	}
-
-	mode := cipher.NewCBCEncrypter(block, key[:aes.BlockSize])
-	cipherText := make([]byte, len(plainText))
-	mode.CryptBlocks(cipherText, plainText)
-
-	return base64.StdEncoding.EncodeToString(cipherText), nil
-}
-
-// generateSignature generates a signature for testing
-func generateSignature(token, timestamp, nonce, msgEncrypt string) string {
-	params := []string{token, timestamp, nonce, msgEncrypt}
-	sort.Strings(params)
-	str := strings.Join(params, "")
-	hash := sha1.Sum([]byte(str))
-	return fmt.Sprintf("%x", hash)
-}
-
-func TestNewWeComBotChannel(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-
-	t.Run("missing token", func(t *testing.T) {
-		cfg := config.WeComConfig{
-			Token:      "",
-			WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-		}
-		_, err := NewWeComBotChannel(cfg, msgBus)
-		if err == nil {
-			t.Error("expected error for missing token, got nil")
-		}
-	})
-
-	t.Run("missing webhook_url", func(t *testing.T) {
-		cfg := config.WeComConfig{
-			Token:      "test_token",
-			WebhookURL: "",
-		}
-		_, err := NewWeComBotChannel(cfg, msgBus)
-		if err == nil {
-			t.Error("expected error for missing webhook_url, got nil")
-		}
-	})
-
-	t.Run("valid config", func(t *testing.T) {
-		cfg := config.WeComConfig{
-			Token:      "test_token",
-			WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			AllowFrom:  []string{"user1", "user2"},
-		}
-		ch, err := NewWeComBotChannel(cfg, msgBus)
-		if err != nil {
-			t.Fatalf("unexpected error: %v", err)
-		}
-		if ch.Name() != "wecom" {
-			t.Errorf("Name() = %q, want %q", ch.Name(), "wecom")
-		}
-		if ch.IsRunning() {
-			t.Error("new channel should not be running")
-		}
-	})
-}
-
-func TestWeComBotChannelIsAllowed(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-
-	t.Run("empty allowlist allows all", func(t *testing.T) {
-		cfg := config.WeComConfig{
-			Token:      "test_token",
-			WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			AllowFrom:  []string{},
-		}
-		ch, _ := NewWeComBotChannel(cfg, msgBus)
-		if !ch.IsAllowed("any_user") {
-			t.Error("empty allowlist should allow all users")
-		}
-	})
-
-	t.Run("allowlist restricts users", func(t *testing.T) {
-		cfg := config.WeComConfig{
-			Token:      "test_token",
-			WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			AllowFrom:  []string{"allowed_user"},
-		}
-		ch, _ := NewWeComBotChannel(cfg, msgBus)
-		if !ch.IsAllowed("allowed_user") {
-			t.Error("allowed user should pass allowlist check")
-		}
-		if ch.IsAllowed("blocked_user") {
-			t.Error("non-allowed user should be blocked")
-		}
-	})
-}
-
-func TestWeComBotVerifySignature(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	cfg := config.WeComConfig{
-		Token:      "test_token",
-		WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-	}
-	ch, _ := NewWeComBotChannel(cfg, msgBus)
-
-	t.Run("valid signature", func(t *testing.T) {
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		msgEncrypt := "test_message"
-		expectedSig := generateSignature("test_token", timestamp, nonce, msgEncrypt)
-
-		if !verifySignature(ch.config.Token, expectedSig, timestamp, nonce, msgEncrypt) {
-			t.Error("valid signature should pass verification")
-		}
-	})
-
-	t.Run("invalid signature", func(t *testing.T) {
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		msgEncrypt := "test_message"
-
-		if verifySignature(ch.config.Token, "invalid_sig", timestamp, nonce, msgEncrypt) {
-			t.Error("invalid signature should fail verification")
-		}
-	})
-
-	t.Run("empty token skips verification", func(t *testing.T) {
-		// Create a channel manually with empty token to test the behavior
-		cfgEmpty := config.WeComConfig{
-			Token:      "",
-			WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-		}
-		chEmpty := &WeComBotChannel{
-			config: cfgEmpty,
-		}
-
-		if !verifySignature(chEmpty.config.Token, "any_sig", "any_ts", "any_nonce", "any_msg") {
-			t.Error("empty token should skip verification and return true")
-		}
-	})
-}
-
-func TestWeComBotDecryptMessage(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-
-	t.Run("decrypt without AES key", func(t *testing.T) {
-		cfg := config.WeComConfig{
-			Token:          "test_token",
-			WebhookURL:     "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			EncodingAESKey: "",
-		}
-		ch, _ := NewWeComBotChannel(cfg, msgBus)
-
-		// Without AES key, message should be base64 decoded only
-		plainText := "hello world"
-		encoded := base64.StdEncoding.EncodeToString([]byte(plainText))
-
-		result, err := decryptMessage(encoded, ch.config.EncodingAESKey)
-		if err != nil {
-			t.Fatalf("unexpected error: %v", err)
-		}
-		if result != plainText {
-			t.Errorf("decryptMessage() = %q, want %q", result, plainText)
-		}
-	})
-
-	t.Run("decrypt with AES key", func(t *testing.T) {
-		aesKey := generateTestAESKey()
-		cfg := config.WeComConfig{
-			Token:          "test_token",
-			WebhookURL:     "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			EncodingAESKey: aesKey,
-		}
-		ch, _ := NewWeComBotChannel(cfg, msgBus)
-
-		originalMsg := "<xml><Content>Hello</Content></xml>"
-		encrypted, err := encryptTestMessage(originalMsg, aesKey)
-		if err != nil {
-			t.Fatalf("failed to encrypt test message: %v", err)
-		}
-
-		result, err := decryptMessage(encrypted, ch.config.EncodingAESKey)
-		if err != nil {
-			t.Fatalf("unexpected error: %v", err)
-		}
-		if result != originalMsg {
-			t.Errorf("WeComDecryptMessage() = %q, want %q", result, originalMsg)
-		}
-	})
-
-	t.Run("invalid base64", func(t *testing.T) {
-		cfg := config.WeComConfig{
-			Token:          "test_token",
-			WebhookURL:     "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			EncodingAESKey: "",
-		}
-		ch, _ := NewWeComBotChannel(cfg, msgBus)
-
-		_, err := decryptMessage("invalid_base64!!!", ch.config.EncodingAESKey)
-		if err == nil {
-			t.Error("expected error for invalid base64, got nil")
-		}
-	})
-
-	t.Run("invalid AES key", func(t *testing.T) {
-		cfg := config.WeComConfig{
-			Token:          "test_token",
-			WebhookURL:     "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			EncodingAESKey: "invalid_key",
-		}
-		ch, _ := NewWeComBotChannel(cfg, msgBus)
-
-		_, err := decryptMessage(base64.StdEncoding.EncodeToString([]byte("test")), ch.config.EncodingAESKey)
-		if err == nil {
-			t.Error("expected error for invalid AES key, got nil")
-		}
-	})
-}
-
-func TestWeComBotPKCS7Unpad(t *testing.T) {
-	tests := []struct {
-		name     string
-		input    []byte
-		expected []byte
-	}{
-		{
-			name:     "empty input",
-			input:    []byte{},
-			expected: []byte{},
-		},
-		{
-			name:     "valid padding 3 bytes",
-			input:    append([]byte("hello"), bytes.Repeat([]byte{3}, 3)...),
-			expected: []byte("hello"),
-		},
-		{
-			name:     "valid padding 16 bytes (full block)",
-			input:    append([]byte("123456789012345"), bytes.Repeat([]byte{16}, 16)...),
-			expected: []byte("123456789012345"),
-		},
-		{
-			name:     "invalid padding larger than data",
-			input:    []byte{20},
-			expected: nil, // should return error
-		},
-		{
-			name:     "invalid padding zero",
-			input:    append([]byte("test"), byte(0)),
-			expected: nil, // should return error
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result, err := pkcs7Unpad(tt.input)
-			if tt.expected == nil {
-				// This case should return an error
-				if err == nil {
-					t.Errorf("pkcs7Unpad() expected error for invalid padding, got result: %v", result)
-				}
-				return
-			}
-			if err != nil {
-				t.Errorf("pkcs7Unpad() unexpected error: %v", err)
-				return
-			}
-			if !bytes.Equal(result, tt.expected) {
-				t.Errorf("pkcs7Unpad() = %v, want %v", result, tt.expected)
-			}
-		})
-	}
-}
-
-func TestWeComBotHandleVerification(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	aesKey := generateTestAESKey()
-	cfg := config.WeComConfig{
-		Token:          "test_token",
-		EncodingAESKey: aesKey,
-		WebhookURL:     "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-	}
-	ch, _ := NewWeComBotChannel(cfg, msgBus)
-
-	t.Run("valid verification request", func(t *testing.T) {
-		echostr := "test_echostr_123"
-		encryptedEchostr, _ := encryptTestMessage(echostr, aesKey)
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		signature := generateSignature("test_token", timestamp, nonce, encryptedEchostr)
-
-		req := httptest.NewRequest(
-			http.MethodGet,
-			"/webhook/wecom?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce+"&echostr="+encryptedEchostr,
-			nil,
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleVerification(context.Background(), w, req)
-
-		if w.Code != http.StatusOK {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
-		}
-		if w.Body.String() != echostr {
-			t.Errorf("response body = %q, want %q", w.Body.String(), echostr)
-		}
-	})
-
-	t.Run("missing parameters", func(t *testing.T) {
-		req := httptest.NewRequest(http.MethodGet, "/webhook/wecom?msg_signature=sig&timestamp=ts", nil)
-		w := httptest.NewRecorder()
-
-		ch.handleVerification(context.Background(), w, req)
-
-		if w.Code != http.StatusBadRequest {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusBadRequest)
-		}
-	})
-
-	t.Run("invalid signature", func(t *testing.T) {
-		echostr := "test_echostr"
-		encryptedEchostr, _ := encryptTestMessage(echostr, aesKey)
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-
-		req := httptest.NewRequest(
-			http.MethodGet,
-			"/webhook/wecom?msg_signature=invalid_sig&timestamp="+timestamp+"&nonce="+nonce+"&echostr="+encryptedEchostr,
-			nil,
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleVerification(context.Background(), w, req)
-
-		if w.Code != http.StatusForbidden {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusForbidden)
-		}
-	})
-}
-
-func TestWeComBotHandleMessageCallback(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	aesKey := generateTestAESKey()
-	cfg := config.WeComConfig{
-		Token:          "test_token",
-		EncodingAESKey: aesKey,
-		WebhookURL:     "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-	}
-	ch, _ := NewWeComBotChannel(cfg, msgBus)
-
-	t.Run("valid direct message callback", func(t *testing.T) {
-		// Create JSON message for direct chat (single)
-		jsonMsg := `{
-			"msgid": "test_msg_id_123",
-			"aibotid": "test_aibot_id",
-			"chattype": "single",
-			"from": {"userid": "user123"},
-			"response_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			"msgtype": "text",
-			"text": {"content": "Hello World"}
-		}`
-
-		// Encrypt message
-		encrypted, _ := encryptTestMessage(jsonMsg, aesKey)
-
-		// Create encrypted XML wrapper
-		encryptedWrapper := struct {
-			XMLName xml.Name `xml:"xml"`
-			Encrypt string   `xml:"Encrypt"`
-		}{
-			Encrypt: encrypted,
-		}
-		wrapperData, _ := xml.Marshal(encryptedWrapper)
-
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		signature := generateSignature("test_token", timestamp, nonce, encrypted)
-
-		req := httptest.NewRequest(
-			http.MethodPost,
-			"/webhook/wecom?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce,
-			bytes.NewReader(wrapperData),
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleMessageCallback(context.Background(), w, req)
-
-		if w.Code != http.StatusOK {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
-		}
-		if w.Body.String() != "success" {
-			t.Errorf("response body = %q, want %q", w.Body.String(), "success")
-		}
-	})
-
-	t.Run("valid group message callback", func(t *testing.T) {
-		// Create JSON message for group chat
-		jsonMsg := `{
-			"msgid": "test_msg_id_456",
-			"aibotid": "test_aibot_id",
-			"chatid": "group_chat_id_123",
-			"chattype": "group",
-			"from": {"userid": "user456"},
-			"response_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			"msgtype": "text",
-			"text": {"content": "Hello Group"}
-		}`
-
-		// Encrypt message
-		encrypted, _ := encryptTestMessage(jsonMsg, aesKey)
-
-		// Create encrypted XML wrapper
-		encryptedWrapper := struct {
-			XMLName xml.Name `xml:"xml"`
-			Encrypt string   `xml:"Encrypt"`
-		}{
-			Encrypt: encrypted,
-		}
-		wrapperData, _ := xml.Marshal(encryptedWrapper)
-
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		signature := generateSignature("test_token", timestamp, nonce, encrypted)
-
-		req := httptest.NewRequest(
-			http.MethodPost,
-			"/webhook/wecom?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce,
-			bytes.NewReader(wrapperData),
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleMessageCallback(context.Background(), w, req)
-
-		if w.Code != http.StatusOK {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
-		}
-		if w.Body.String() != "success" {
-			t.Errorf("response body = %q, want %q", w.Body.String(), "success")
-		}
-	})
-
-	t.Run("missing parameters", func(t *testing.T) {
-		req := httptest.NewRequest(http.MethodPost, "/webhook/wecom?msg_signature=sig", nil)
-		w := httptest.NewRecorder()
-
-		ch.handleMessageCallback(context.Background(), w, req)
-
-		if w.Code != http.StatusBadRequest {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusBadRequest)
-		}
-	})
-
-	t.Run("invalid XML", func(t *testing.T) {
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		signature := generateSignature("test_token", timestamp, nonce, "")
-
-		req := httptest.NewRequest(
-			http.MethodPost,
-			"/webhook/wecom?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce,
-			strings.NewReader("invalid xml"),
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleMessageCallback(context.Background(), w, req)
-
-		if w.Code != http.StatusBadRequest {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusBadRequest)
-		}
-	})
-
-	t.Run("invalid signature", func(t *testing.T) {
-		encryptedWrapper := struct {
-			XMLName xml.Name `xml:"xml"`
-			Encrypt string   `xml:"Encrypt"`
-		}{
-			Encrypt: "encrypted_data",
-		}
-		wrapperData, _ := xml.Marshal(encryptedWrapper)
-
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-
-		req := httptest.NewRequest(
-			http.MethodPost,
-			"/webhook/wecom?msg_signature=invalid_sig&timestamp="+timestamp+"&nonce="+nonce,
-			bytes.NewReader(wrapperData),
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleMessageCallback(context.Background(), w, req)
-
-		if w.Code != http.StatusForbidden {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusForbidden)
-		}
-	})
-}
-
-func TestWeComBotProcessMessage(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	cfg := config.WeComConfig{
-		Token:      "test_token",
-		WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-	}
-	ch, _ := NewWeComBotChannel(cfg, msgBus)
-
-	t.Run("process direct text message", func(t *testing.T) {
-		msg := WeComBotMessage{
-			MsgID:       "test_msg_id_123",
-			AIBotID:     "test_aibot_id",
-			ChatType:    "single",
-			ResponseURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			MsgType:     "text",
-		}
-		msg.From.UserID = "user123"
-		msg.Text.Content = "Hello World"
-
-		// Should not panic
-		ch.processMessage(context.Background(), msg)
-	})
-
-	t.Run("process group text message", func(t *testing.T) {
-		msg := WeComBotMessage{
-			MsgID:       "test_msg_id_456",
-			AIBotID:     "test_aibot_id",
-			ChatID:      "group_chat_id_123",
-			ChatType:    "group",
-			ResponseURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			MsgType:     "text",
-		}
-		msg.From.UserID = "user456"
-		msg.Text.Content = "Hello Group"
-
-		// Should not panic
-		ch.processMessage(context.Background(), msg)
-	})
-
-	t.Run("process voice message", func(t *testing.T) {
-		msg := WeComBotMessage{
-			MsgID:       "test_msg_id_789",
-			AIBotID:     "test_aibot_id",
-			ChatType:    "single",
-			ResponseURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			MsgType:     "voice",
-		}
-		msg.From.UserID = "user123"
-		msg.Voice.Content = "Voice message text"
-
-		// Should not panic
-		ch.processMessage(context.Background(), msg)
-	})
-
-	t.Run("skip unsupported message type", func(t *testing.T) {
-		msg := WeComBotMessage{
-			MsgID:       "test_msg_id_000",
-			AIBotID:     "test_aibot_id",
-			ChatType:    "single",
-			ResponseURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-			MsgType:     "video",
-		}
-		msg.From.UserID = "user123"
-
-		// Should not panic
-		ch.processMessage(context.Background(), msg)
-	})
-}
-
-func TestWeComBotHandleWebhook(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	cfg := config.WeComConfig{
-		Token:      "test_token",
-		WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-	}
-	ch, _ := NewWeComBotChannel(cfg, msgBus)
-
-	t.Run("GET request calls verification", func(t *testing.T) {
-		echostr := "test_echostr"
-		encoded := base64.StdEncoding.EncodeToString([]byte(echostr))
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		signature := generateSignature("test_token", timestamp, nonce, encoded)
-
-		req := httptest.NewRequest(
-			http.MethodGet,
-			"/webhook/wecom?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce+"&echostr="+encoded,
-			nil,
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleWebhook(w, req)
-
-		if w.Code != http.StatusOK {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
-		}
-	})
-
-	t.Run("POST request calls message callback", func(t *testing.T) {
-		encryptedWrapper := struct {
-			XMLName xml.Name `xml:"xml"`
-			Encrypt string   `xml:"Encrypt"`
-		}{
-			Encrypt: base64.StdEncoding.EncodeToString([]byte("test")),
-		}
-		wrapperData, _ := xml.Marshal(encryptedWrapper)
-
-		timestamp := "1234567890"
-		nonce := "test_nonce"
-		signature := generateSignature("test_token", timestamp, nonce, encryptedWrapper.Encrypt)
-
-		req := httptest.NewRequest(
-			http.MethodPost,
-			"/webhook/wecom?msg_signature="+signature+"&timestamp="+timestamp+"&nonce="+nonce,
-			bytes.NewReader(wrapperData),
-		)
-		w := httptest.NewRecorder()
-
-		ch.handleWebhook(w, req)
-
-		// Should not be method not allowed
-		if w.Code == http.StatusMethodNotAllowed {
-			t.Error("POST request should not return Method Not Allowed")
-		}
-	})
-
-	t.Run("unsupported method", func(t *testing.T) {
-		req := httptest.NewRequest(http.MethodPut, "/webhook/wecom", nil)
-		w := httptest.NewRecorder()
-
-		ch.handleWebhook(w, req)
-
-		if w.Code != http.StatusMethodNotAllowed {
-			t.Errorf("status code = %d, want %d", w.Code, http.StatusMethodNotAllowed)
-		}
-	})
-}
-
-func TestWeComBotHandleHealth(t *testing.T) {
-	msgBus := bus.NewMessageBus()
-	cfg := config.WeComConfig{
-		Token:      "test_token",
-		WebhookURL: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-	}
-	ch, _ := NewWeComBotChannel(cfg, msgBus)
-
-	req := httptest.NewRequest(http.MethodGet, "/health/wecom", nil)
-	w := httptest.NewRecorder()
-
-	ch.handleHealth(w, req)
-
-	if w.Code != http.StatusOK {
-		t.Errorf("status code = %d, want %d", w.Code, http.StatusOK)
-	}
-
-	contentType := w.Header().Get("Content-Type")
-	if contentType != "application/json" {
-		t.Errorf("Content-Type = %q, want %q", contentType, "application/json")
-	}
-
-	body := w.Body.String()
-	if !strings.Contains(body, "status") || !strings.Contains(body, "running") {
-		t.Errorf("response body should contain status and running fields, got: %s", body)
-	}
-}
-
-func TestWeComBotReplyMessage(t *testing.T) {
-	msg := WeComBotReplyMessage{
-		MsgType: "text",
-	}
-	msg.Text.Content = "Hello World"
-
-	if msg.MsgType != "text" {
-		t.Errorf("MsgType = %q, want %q", msg.MsgType, "text")
-	}
-	if msg.Text.Content != "Hello World" {
-		t.Errorf("Text.Content = %q, want %q", msg.Text.Content, "Hello World")
-	}
-}
-
-func TestWeComBotMessageStructure(t *testing.T) {
-	jsonData := `{
-		"msgid": "test_msg_id_123",
-		"aibotid": "test_aibot_id",
-		"chatid": "group_chat_id_123",
-		"chattype": "group",
-		"from": {"userid": "user123"},
-		"response_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=test",
-		"msgtype": "text",
-		"text": {"content": "Hello World"}
-	}`
-
-	var msg WeComBotMessage
-	err := json.Unmarshal([]byte(jsonData), &msg)
-	if err != nil {
-		t.Fatalf("failed to unmarshal JSON: %v", err)
-	}
-
-	if msg.MsgID != "test_msg_id_123" {
-		t.Errorf("MsgID = %q, want %q", msg.MsgID, "test_msg_id_123")
-	}
-	if msg.AIBotID != "test_aibot_id" {
-		t.Errorf("AIBotID = %q, want %q", msg.AIBotID, "test_aibot_id")
-	}
-	if msg.ChatID != "group_chat_id_123" {
-		t.Errorf("ChatID = %q, want %q", msg.ChatID, "group_chat_id_123")
-	}
-	if msg.ChatType != "group" {
-		t.Errorf("ChatType = %q, want %q", msg.ChatType, "group")
-	}
-	if msg.From.UserID != "user123" {
-		t.Errorf("From.UserID = %q, want %q", msg.From.UserID, "user123")
-	}
-	if msg.MsgType != "text" {
-		t.Errorf("MsgType = %q, want %q", msg.MsgType, "text")
-	}
-	if msg.Text.Content != "Hello World" {
-		t.Errorf("Text.Content = %q, want %q", msg.Text.Content, "Hello World")
-	}
-}
diff --git a/pkg/channels/wecom/common.go b/pkg/channels/wecom/common.go
deleted file mode 100644
index 39a27d04c..000000000
--- a/pkg/channels/wecom/common.go
+++ /dev/null
@@ -1,134 +0,0 @@
-package wecom
-
-import (
-	"crypto/aes"
-	"crypto/cipher"
-	"crypto/sha1"
-	"encoding/base64"
-	"encoding/binary"
-	"fmt"
-	"sort"
-	"strings"
-)
-
-// blockSize is the PKCS7 block size used by WeCom (32)
-const blockSize = 32
-
-// verifySignature verifies the message signature for WeCom
-// This is a common function used by both WeCom Bot and WeCom App
-func verifySignature(token, msgSignature, timestamp, nonce, msgEncrypt string) bool {
-	if token == "" {
-		return true // Skip verification if token is not set
-	}
-
-	// Sort parameters
-	params := []string{token, timestamp, nonce, msgEncrypt}
-	sort.Strings(params)
-
-	// Concatenate
-	str := strings.Join(params, "")
-
-	// SHA1 hash
-	hash := sha1.Sum([]byte(str))
-	expectedSignature := fmt.Sprintf("%x", hash)
-
-	return expectedSignature == msgSignature
-}
-
-// decryptMessage decrypts the encrypted message using AES
-// For AIBOT, receiveid should be the aibotid; for other apps, it should be corp_id
-func decryptMessage(encryptedMsg, encodingAESKey string) (string, error) {
-	return decryptMessageWithVerify(encryptedMsg, encodingAESKey, "")
-}
-
-// decryptMessageWithVerify decrypts the encrypted message and optionally verifies receiveid
-// receiveid: for AIBOT use aibotid, for WeCom App use corp_id. If empty, skip verification.
-func decryptMessageWithVerify(encryptedMsg, encodingAESKey, receiveid string) (string, error) {
-	if encodingAESKey == "" {
-		// No encryption, return as is (base64 decode)
-		decoded, err := base64.StdEncoding.DecodeString(encryptedMsg)
-		if err != nil {
-			return "", err
-		}
-		return string(decoded), nil
-	}
-
-	// Decode AES key (base64)
-	aesKey, err := base64.StdEncoding.DecodeString(encodingAESKey + "=")
-	if err != nil {
-		return "", fmt.Errorf("failed to decode AES key: %w", err)
-	}
-
-	// Decode encrypted message
-	cipherText, err := base64.StdEncoding.DecodeString(encryptedMsg)
-	if err != nil {
-		return "", fmt.Errorf("failed to decode message: %w", err)
-	}
-
-	// AES decrypt
-	block, err := aes.NewCipher(aesKey)
-	if err != nil {
-		return "", fmt.Errorf("failed to create cipher: %w", err)
-	}
-
-	if len(cipherText) < aes.BlockSize {
-		return "", fmt.Errorf("ciphertext too short")
-	}
-
-	// IV is the first 16 bytes of AESKey
-	iv := aesKey[:aes.BlockSize]
-	mode := cipher.NewCBCDecrypter(block, iv)
-	plainText := make([]byte, len(cipherText))
-	mode.CryptBlocks(plainText, cipherText)
-
-	// Remove PKCS7 padding
-	plainText, err = pkcs7Unpad(plainText)
-	if err != nil {
-		return "", fmt.Errorf("failed to unpad: %w", err)
-	}
-
-	// Parse message structure
-	// Format: random(16) + msg_len(4) + msg + receiveid
-	if len(plainText) < 20 {
-		return "", fmt.Errorf("decrypted message too short")
-	}
-
-	msgLen := binary.BigEndian.Uint32(plainText[16:20])
-	if int(msgLen) > len(plainText)-20 {
-		return "", fmt.Errorf("invalid message length")
-	}
-
-	msg := plainText[20 : 20+msgLen]
-
-	// Verify receiveid if provided
-	if receiveid != "" && len(plainText) > 20+int(msgLen) {
-		actualReceiveID := string(plainText[20+msgLen:])
-		if actualReceiveID != receiveid {
-			return "", fmt.Errorf("receiveid mismatch: expected %s, got %s", receiveid, actualReceiveID)
-		}
-	}
-
-	return string(msg), nil
-}
-
-// pkcs7Unpad removes PKCS7 padding with validation
-func pkcs7Unpad(data []byte) ([]byte, error) {
-	if len(data) == 0 {
-		return data, nil
-	}
-	padding := int(data[len(data)-1])
-	// WeCom uses 32-byte block size for PKCS7 padding
-	if padding == 0 || padding > blockSize {
-		return nil, fmt.Errorf("invalid padding size: %d", padding)
-	}
-	if padding > len(data) {
-		return nil, fmt.Errorf("padding size larger than data")
-	}
-	// Verify all padding bytes
-	for i := range padding {
-		if data[len(data)-1-i] != byte(padding) {
-			return nil, fmt.Errorf("invalid padding byte at position %d", i)
-		}
-	}
-	return data[:len(data)-padding], nil
-}
diff --git a/pkg/channels/wecom/init.go b/pkg/channels/wecom/init.go
index 3ef1ecdf3..3aad84d42 100644
--- a/pkg/channels/wecom/init.go
+++ b/pkg/channels/wecom/init.go
@@ -8,9 +8,6 @@ import (
 
 func init() {
 	channels.RegisterFactory("wecom", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
-		return NewWeComBotChannel(cfg.Channels.WeCom, b)
-	})
-	channels.RegisterFactory("wecom_app", func(cfg *config.Config, b *bus.MessageBus) (channels.Channel, error) {
-		return NewWeComAppChannel(cfg.Channels.WeComApp, b)
+		return NewChannel(cfg.Channels.WeCom, b)
 	})
 }
diff --git a/pkg/channels/wecom/media.go b/pkg/channels/wecom/media.go
new file mode 100644
index 000000000..974a3bf4d
--- /dev/null
+++ b/pkg/channels/wecom/media.go
@@ -0,0 +1,802 @@
+package wecom
+
+import (
+	"context"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/md5"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"mime"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/h2non/filetype"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+const (
+	wecomOutboundMediaMaxBytes = 20 << 20
+	wecomOutboundImageMaxBytes = 2 << 20
+	wecomOutboundVoiceMaxBytes = 2 << 20
+	wecomOutboundVideoMaxBytes = 10 << 20
+	wecomUploadChunkMaxBytes   = 512 << 10
+	wecomUploadMaxChunks       = 100
+	wecomUploadMinBytes        = 5
+)
+
+type wecomOutboundMedia struct {
+	MsgType     string
+	MediaID     string
+	Title       string
+	Description string
+}
+
+func (m *wecomOutboundMedia) respondBody() wecomRespondMsgBody {
+	body := wecomRespondMsgBody{MsgType: m.MsgType}
+	switch m.MsgType {
+	case "file":
+		body.File = &wecomMediaRefContent{MediaID: m.MediaID}
+	case "image":
+		body.Image = &wecomMediaRefContent{MediaID: m.MediaID}
+	case "voice":
+		body.Voice = &wecomMediaRefContent{MediaID: m.MediaID}
+	case "video":
+		body.Video = &wecomVideoContent{
+			MediaID:     m.MediaID,
+			Title:       m.Title,
+			Description: m.Description,
+		}
+	}
+	return body
+}
+
+func (m *wecomOutboundMedia) sendBody(chatID string, chatType uint32) wecomSendMsgBody {
+	body := wecomSendMsgBody{
+		ChatID:   chatID,
+		ChatType: chatType,
+		MsgType:  m.MsgType,
+	}
+	switch m.MsgType {
+	case "file":
+		body.File = &wecomMediaRefContent{MediaID: m.MediaID}
+	case "image":
+		body.Image = &wecomMediaRefContent{MediaID: m.MediaID}
+	case "voice":
+		body.Voice = &wecomMediaRefContent{MediaID: m.MediaID}
+	case "video":
+		body.Video = &wecomVideoContent{
+			MediaID:     m.MediaID,
+			Title:       m.Title,
+			Description: m.Description,
+		}
+	}
+	return body
+}
+
+func decodeMediaAESKey(value string) ([]byte, error) {
+	if value == "" {
+		return nil, nil
+	}
+	key, err := base64.StdEncoding.DecodeString(value)
+	if err == nil && len(key) == 32 {
+		return key, nil
+	}
+	key, err = base64.StdEncoding.DecodeString(value + "=")
+	if err != nil {
+		return nil, fmt.Errorf("decode AES key: %w", err)
+	}
+	if len(key) != 32 {
+		return nil, fmt.Errorf("invalid AES key length %d", len(key))
+	}
+	return key, nil
+}
+
+func decryptAESCBC(key, ciphertext []byte) ([]byte, error) {
+	if len(ciphertext) == 0 {
+		return nil, fmt.Errorf("ciphertext is empty")
+	}
+	if len(ciphertext)%aes.BlockSize != 0 {
+		return nil, fmt.Errorf("ciphertext length %d is not a multiple of block size", len(ciphertext))
+	}
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, fmt.Errorf("create cipher: %w", err)
+	}
+	plaintext := make([]byte, len(ciphertext))
+	iv := key[:aes.BlockSize]
+	cipher.NewCBCDecrypter(block, iv).CryptBlocks(plaintext, ciphertext)
+	return pkcs7Unpad(plaintext)
+}
+
+func pkcs7Unpad(data []byte) ([]byte, error) {
+	if len(data) == 0 {
+		return nil, fmt.Errorf("empty plaintext")
+	}
+	padding := int(data[len(data)-1])
+	if padding == 0 || padding > 32 || padding > len(data) {
+		return nil, fmt.Errorf("invalid padding size %d", padding)
+	}
+	for i := 0; i < padding; i++ {
+		if data[len(data)-1-i] != byte(padding) {
+			return nil, fmt.Errorf("invalid padding byte")
+		}
+	}
+	return data[:len(data)-padding], nil
+}
+
+func inferMediaExt(contentType, fallback string) string {
+	contentType = normalizeWeComContentType(contentType)
+	switch contentType {
+	case "image/jpeg", "image/jpg":
+		return ".jpg"
+	case "image/png":
+		return ".png"
+	case "image/gif":
+		return ".gif"
+	case "image/webp":
+		return ".webp"
+	case "application/pdf":
+		return ".pdf"
+	case "video/mp4":
+		return ".mp4"
+	default:
+		return fallback
+	}
+}
+
+func normalizeWeComContentType(value string) string {
+	value = strings.ToLower(strings.TrimSpace(value))
+	if idx := strings.Index(value, ";"); idx >= 0 {
+		value = strings.TrimSpace(value[:idx])
+	}
+	return value
+}
+
+func isGenericWeComContentType(value string) bool {
+	switch normalizeWeComContentType(value) {
+	case "", "application/octet-stream", "binary/octet-stream", "application/unknown", "application/binary":
+		return true
+	default:
+		return false
+	}
+}
+
+func sanitizeWeComFilename(name string) string {
+	name = filepath.Base(strings.TrimSpace(name))
+	if name == "." || name == "/" || name == "" {
+		return ""
+	}
+	return name
+}
+
+func candidateWeComFilename(resourceURL, contentDisposition, fallbackName string) string {
+	if _, params, err := mime.ParseMediaType(contentDisposition); err == nil {
+		if name := sanitizeWeComFilename(params["filename"]); name != "" {
+			return name
+		}
+		if name := sanitizeWeComFilename(params["filename*"]); name != "" {
+			return name
+		}
+	}
+
+	if parsed, err := url.Parse(resourceURL); err == nil {
+		query := parsed.Query()
+		for _, key := range []string{"filename", "file_name", "name"} {
+			if name := sanitizeWeComFilename(query.Get(key)); name != "" {
+				return name
+			}
+		}
+		if name := sanitizeWeComFilename(parsed.Path); name != "" {
+			return name
+		}
+	}
+
+	return sanitizeWeComFilename(fallbackName)
+}
+
+func detectWeComFiletype(data []byte) (string, string) {
+	kind, err := filetype.Match(data)
+	if err != nil || kind == filetype.Unknown {
+		return "", ""
+	}
+	ext := ""
+	if kind.Extension != "" {
+		ext = "." + strings.ToLower(kind.Extension)
+	}
+	return normalizeWeComContentType(kind.MIME.Value), ext
+}
+
+func detectWeComMediaMetadata(
+	data []byte,
+	fallbackName, fallbackContentType, resourceURL, contentDisposition string,
+) (string, string) {
+	filename := candidateWeComFilename(resourceURL, contentDisposition, fallbackName)
+	if filename == "" {
+		filename = "media"
+	}
+
+	ext := strings.ToLower(filepath.Ext(filename))
+	contentType := normalizeWeComContentType(fallbackContentType)
+	detectedType, detectedExt := detectWeComFiletype(data)
+
+	if ext != "" && isGenericWeComContentType(contentType) {
+		if byExt := normalizeWeComContentType(mime.TypeByExtension(ext)); byExt != "" {
+			contentType = byExt
+		}
+	}
+
+	if detectedType != "" {
+		switch {
+		case contentType == "":
+			contentType = detectedType
+		case isGenericWeComContentType(contentType):
+			contentType = detectedType
+		case strings.HasPrefix(detectedType, "image/") && !strings.HasPrefix(contentType, "image/"):
+			contentType = detectedType
+		case strings.HasPrefix(detectedType, "audio/") && !strings.HasPrefix(contentType, "audio/"):
+			contentType = detectedType
+		case strings.HasPrefix(detectedType, "video/") && !strings.HasPrefix(contentType, "video/"):
+			contentType = detectedType
+		}
+	}
+
+	if contentType == "" && ext != "" {
+		contentType = normalizeWeComContentType(mime.TypeByExtension(ext))
+	}
+	if contentType == "" {
+		contentType = normalizeWeComContentType(http.DetectContentType(data))
+	}
+
+	if ext == "" {
+		ext = detectedExt
+	}
+	if ext == "" && contentType != "" {
+		if exts, err := mime.ExtensionsByType(contentType); err == nil && len(exts) > 0 {
+			ext = strings.ToLower(exts[0])
+		}
+	}
+
+	if filepath.Ext(filename) == "" && ext != "" {
+		filename += ext
+	}
+	return filename, contentType
+}
+
+func (c *WeComChannel) storeRemoteMedia(
+	ctx context.Context,
+	scope, msgID, resourceURL, aesKey, fallbackExt string,
+) (string, error) {
+	store := c.GetMediaStore()
+	if store == nil {
+		return "", fmt.Errorf("no media store available")
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, resourceURL, nil)
+	if err != nil {
+		return "", fmt.Errorf("create request: %w", err)
+	}
+	resp, err := c.mediaClient.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("download media: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("download media returned HTTP %d", resp.StatusCode)
+	}
+
+	data, err := io.ReadAll(io.LimitReader(resp.Body, wecomOutboundMediaMaxBytes+1))
+	if err != nil {
+		return "", fmt.Errorf("read media: %w", err)
+	}
+	if len(data) > wecomOutboundMediaMaxBytes {
+		return "", fmt.Errorf("media too large")
+	}
+
+	if aesKey != "" {
+		key, keyErr := decodeMediaAESKey(aesKey)
+		if keyErr != nil {
+			return "", keyErr
+		}
+		data, err = decryptAESCBC(key, data)
+		if err != nil {
+			return "", fmt.Errorf("decrypt media: %w", err)
+		}
+	}
+
+	filename, contentType := detectWeComMediaMetadata(
+		data,
+		msgID+fallbackExt,
+		resp.Header.Get("Content-Type"),
+		resourceURL,
+		resp.Header.Get("Content-Disposition"),
+	)
+	ext := filepath.Ext(filename)
+	if ext == "" {
+		ext = inferMediaExt(contentType, fallbackExt)
+	}
+	mediaDir := filepath.Join(os.TempDir(), "picoclaw_media")
+	if mkdirErr := os.MkdirAll(mediaDir, 0o700); mkdirErr != nil {
+		return "", fmt.Errorf("mkdir media dir: %w", mkdirErr)
+	}
+	tmpFile, err := os.CreateTemp(mediaDir, msgID+"-*"+ext)
+	if err != nil {
+		return "", fmt.Errorf("create temp file: %w", err)
+	}
+	tmpPath := tmpFile.Name()
+	if _, writeErr := tmpFile.Write(data); writeErr != nil {
+		tmpFile.Close()
+		_ = os.Remove(tmpPath)
+		return "", fmt.Errorf("write temp file: %w", writeErr)
+	}
+	if closeErr := tmpFile.Close(); closeErr != nil {
+		_ = os.Remove(tmpPath)
+		return "", fmt.Errorf("close temp file: %w", closeErr)
+	}
+
+	ref, err := store.Store(tmpPath, media.MediaMeta{
+		Filename:      filename,
+		ContentType:   contentType,
+		Source:        "wecom",
+		CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
+	}, scope)
+	if err != nil {
+		_ = os.Remove(tmpPath)
+		return "", err
+	}
+	return ref, nil
+}
+
+func detectLocalWeComContentType(localPath, hint string) string {
+	contentType := normalizeWeComContentType(hint)
+	if !isGenericWeComContentType(contentType) {
+		return contentType
+	}
+
+	if kind, err := filetype.MatchFile(localPath); err == nil && kind != filetype.Unknown {
+		return normalizeWeComContentType(kind.MIME.Value)
+	}
+
+	if ext := strings.ToLower(filepath.Ext(localPath)); ext != "" {
+		if byExt := normalizeWeComContentType(mime.TypeByExtension(ext)); byExt != "" {
+			return byExt
+		}
+	}
+
+	file, err := os.Open(localPath)
+	if err != nil {
+		return contentType
+	}
+	defer file.Close()
+
+	buf := make([]byte, 512)
+	n, err := file.Read(buf)
+	if err != nil && err != io.EOF {
+		return contentType
+	}
+	if n == 0 {
+		return contentType
+	}
+	return normalizeWeComContentType(http.DetectContentType(buf[:n]))
+}
+
+func writeWeComTempFile(prefix, filename string, data []byte) (string, error) {
+	mediaDir := filepath.Join(os.TempDir(), "picoclaw_media")
+	if err := os.MkdirAll(mediaDir, 0o700); err != nil {
+		return "", fmt.Errorf("mkdir media dir: %w", err)
+	}
+
+	ext := strings.ToLower(filepath.Ext(filename))
+	tmpFile, err := os.CreateTemp(mediaDir, prefix+"-*"+ext)
+	if err != nil {
+		return "", fmt.Errorf("create temp file: %w", err)
+	}
+	tmpPath := tmpFile.Name()
+
+	if _, err := tmpFile.Write(data); err != nil {
+		_ = tmpFile.Close()
+		_ = os.Remove(tmpPath)
+		return "", fmt.Errorf("write temp file: %w", err)
+	}
+	if err := tmpFile.Close(); err != nil {
+		_ = os.Remove(tmpPath)
+		return "", fmt.Errorf("close temp file: %w", err)
+	}
+	return tmpPath, nil
+}
+
+func (c *WeComChannel) downloadRemoteMediaToTemp(
+	ctx context.Context,
+	resourceURL, fallbackName string,
+) (string, string, string, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, resourceURL, nil)
+	if err != nil {
+		return "", "", "", fmt.Errorf("create request: %w", err)
+	}
+
+	resp, err := c.mediaClient.Do(req)
+	if err != nil {
+		return "", "", "", fmt.Errorf("download media: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
+		return "", "", "", fmt.Errorf("download media returned HTTP %d: %s", resp.StatusCode, string(body))
+	}
+
+	data, err := io.ReadAll(io.LimitReader(resp.Body, wecomOutboundMediaMaxBytes+1))
+	if err != nil {
+		return "", "", "", fmt.Errorf("read media: %w", err)
+	}
+	if len(data) > wecomOutboundMediaMaxBytes {
+		return "", "", "", fmt.Errorf("media too large")
+	}
+
+	filename, contentType := detectWeComMediaMetadata(
+		data,
+		fallbackName,
+		resp.Header.Get("Content-Type"),
+		resourceURL,
+		resp.Header.Get("Content-Disposition"),
+	)
+	tmpPath, err := writeWeComTempFile("wecom-outbound", filename, data)
+	if err != nil {
+		return "", "", "", err
+	}
+	return tmpPath, filename, contentType, nil
+}
+
+func (c *WeComChannel) resolveOutboundPart(
+	ctx context.Context,
+	part bus.MediaPart,
+) (string, string, string, func(), error) {
+	cleanup := func() {}
+	filename := sanitizeWeComFilename(part.Filename)
+	contentType := normalizeWeComContentType(part.ContentType)
+	ref := strings.TrimSpace(part.Ref)
+
+	switch {
+	case ref == "":
+		return "", filename, contentType, cleanup, nil
+
+	case strings.HasPrefix(ref, "http://") || strings.HasPrefix(ref, "https://"):
+		localPath, name, ct, err := c.downloadRemoteMediaToTemp(ctx, ref, filename)
+		if err != nil {
+			return "", "", "", cleanup, err
+		}
+		return localPath, name, ct, func() { _ = os.Remove(localPath) }, nil
+
+	case strings.HasPrefix(ref, "media://"):
+		store := c.GetMediaStore()
+		if store == nil {
+			return "", "", "", cleanup, fmt.Errorf("no media store available")
+		}
+
+		localPath, meta, err := store.ResolveWithMeta(ref)
+		if err != nil {
+			return "", "", "", cleanup, err
+		}
+		if filename == "" {
+			filename = sanitizeWeComFilename(meta.Filename)
+		}
+		if contentType == "" {
+			contentType = normalizeWeComContentType(meta.ContentType)
+		}
+		if strings.HasPrefix(localPath, "http://") || strings.HasPrefix(localPath, "https://") {
+			tmpPath, name, ct, err := c.downloadRemoteMediaToTemp(ctx, localPath, filename)
+			if err != nil {
+				return "", "", "", cleanup, err
+			}
+			return tmpPath, name, ct, func() { _ = os.Remove(tmpPath) }, nil
+		}
+		if _, err := os.Stat(localPath); err != nil {
+			return "", "", "", cleanup, err
+		}
+		if filename == "" {
+			filename = sanitizeWeComFilename(filepath.Base(localPath))
+		}
+		if contentType == "" {
+			contentType = detectLocalWeComContentType(localPath, "")
+		}
+		return localPath, filename, contentType, cleanup, nil
+
+	case strings.HasPrefix(ref, "file://"):
+		u, err := url.Parse(ref)
+		if err != nil {
+			return "", "", "", cleanup, err
+		}
+		localPath := u.Path
+		if _, err := os.Stat(localPath); err != nil {
+			return "", "", "", cleanup, err
+		}
+		if filename == "" {
+			filename = sanitizeWeComFilename(filepath.Base(localPath))
+		}
+		if contentType == "" {
+			contentType = detectLocalWeComContentType(localPath, "")
+		}
+		return localPath, filename, contentType, cleanup, nil
+
+	default:
+		if _, err := os.Stat(ref); err != nil {
+			return "", "", "", cleanup, err
+		}
+		if filename == "" {
+			filename = sanitizeWeComFilename(filepath.Base(ref))
+		}
+		if contentType == "" {
+			contentType = detectLocalWeComContentType(ref, "")
+		}
+		return ref, filename, contentType, cleanup, nil
+	}
+}
+
+func canWeComSendImage(contentType, ext string, size int64) bool {
+	if size > wecomOutboundImageMaxBytes {
+		return false
+	}
+	switch normalizeWeComContentType(contentType) {
+	case "image/jpeg", "image/jpg", "image/png", "image/gif":
+		return true
+	}
+	switch strings.ToLower(ext) {
+	case ".jpg", ".jpeg", ".png", ".gif":
+		return true
+	default:
+		return false
+	}
+}
+
+func canWeComSendVoice(contentType, ext string, size int64) bool {
+	if size > wecomOutboundVoiceMaxBytes {
+		return false
+	}
+	contentType = normalizeWeComContentType(contentType)
+	return strings.Contains(contentType, "amr") || strings.EqualFold(ext, ".amr")
+}
+
+func canWeComSendVideo(contentType, ext string, size int64) bool {
+	if size > wecomOutboundVideoMaxBytes {
+		return false
+	}
+	return normalizeWeComContentType(contentType) == "video/mp4" || strings.EqualFold(ext, ".mp4")
+}
+
+func outboundWeComMediaKind(partType, filename, contentType string, size int64) string {
+	if size < wecomUploadMinBytes {
+		return ""
+	}
+
+	partType = strings.ToLower(strings.TrimSpace(partType))
+	contentType = normalizeWeComContentType(contentType)
+	ext := strings.ToLower(filepath.Ext(filename))
+
+	if partType == "file" {
+		if size <= wecomOutboundMediaMaxBytes {
+			return "file"
+		}
+		return ""
+	}
+
+	if (partType == "image" || partType == "") && canWeComSendImage(contentType, ext, size) {
+		return "image"
+	}
+	if (partType == "audio" || partType == "voice" || partType == "") && canWeComSendVoice(contentType, ext, size) {
+		return "voice"
+	}
+	if (partType == "video" || partType == "") && canWeComSendVideo(contentType, ext, size) {
+		return "video"
+	}
+	if size <= wecomOutboundMediaMaxBytes {
+		return "file"
+	}
+	return ""
+}
+
+func trimWeComBytes(value string, limit int) string {
+	value = strings.TrimSpace(value)
+	if limit <= 0 || len(value) <= limit {
+		return value
+	}
+	size := 0
+	var out strings.Builder
+	for _, r := range value {
+		width := len(string(r))
+		if size+width > limit {
+			break
+		}
+		size += width
+		out.WriteRune(r)
+	}
+	return out.String()
+}
+
+func ensureWeComOutboundFilename(filename, localPath, contentType string) string {
+	filename = sanitizeWeComFilename(filename)
+	if filename == "" {
+		filename = sanitizeWeComFilename(filepath.Base(localPath))
+	}
+	if filename == "" {
+		filename = "media"
+	}
+	if filepath.Ext(filename) == "" {
+		fallbackExt := inferMediaExt(contentType, strings.ToLower(filepath.Ext(localPath)))
+		if fallbackExt != "" {
+			filename += fallbackExt
+		}
+	}
+	filename = trimWeComBytes(filename, 256)
+	if filename == "" {
+		return "media"
+	}
+	return filename
+}
+
+func buildWeComVideoContent(mediaID, filename, description string) *wecomVideoContent {
+	title := strings.TrimSuffix(filename, filepath.Ext(filename))
+	title = trimWeComBytes(title, 64)
+	if title == "" {
+		title = "video"
+	}
+	description = trimWeComBytes(description, 512)
+	return &wecomVideoContent{
+		MediaID:     mediaID,
+		Title:       title,
+		Description: description,
+	}
+}
+
+func decodeWeComEnvelopeBody[T any](env wecomEnvelope) (T, error) {
+	var out T
+	if len(env.Body) == 0 {
+		return out, fmt.Errorf("wecom response body is empty")
+	}
+	if err := json.Unmarshal(env.Body, &out); err != nil {
+		return out, fmt.Errorf("decode wecom response body: %w", err)
+	}
+	return out, nil
+}
+
+func (c *WeComChannel) uploadOutboundMedia(
+	ctx context.Context,
+	localPath, filename, contentType string,
+	part bus.MediaPart,
+) (*wecomOutboundMedia, error) {
+	_ = ctx
+
+	contentType = detectLocalWeComContentType(localPath, contentType)
+	filename = ensureWeComOutboundFilename(filename, localPath, contentType)
+
+	data, err := os.ReadFile(localPath)
+	if err != nil {
+		return nil, fmt.Errorf("read media file: %w", err)
+	}
+	size := int64(len(data))
+	kind := outboundWeComMediaKind(part.Type, filename, contentType, size)
+	if kind == "" {
+		return nil, fmt.Errorf("unsupported wecom media type or size for %q", filename)
+	}
+
+	totalChunks := (len(data) + wecomUploadChunkMaxBytes - 1) / wecomUploadChunkMaxBytes
+	if totalChunks <= 0 || totalChunks > wecomUploadMaxChunks {
+		return nil, fmt.Errorf("wecom upload requires 1-%d chunks, got %d", wecomUploadMaxChunks, totalChunks)
+	}
+
+	sum := md5.Sum(data)
+	initEnv, err := c.sendCommandAck(wecomCommand{
+		Cmd:     wecomCmdUploadMediaInit,
+		Headers: wecomHeaders{ReqID: randomID(10)},
+		Body: wecomUploadMediaInitBody{
+			Type:        kind,
+			Filename:    filename,
+			TotalSize:   size,
+			TotalChunks: totalChunks,
+			MD5:         hex.EncodeToString(sum[:]),
+		},
+	}, wecomUploadTimeout)
+	if err != nil {
+		return nil, err
+	}
+	initResp, err := decodeWeComEnvelopeBody[wecomUploadMediaInitResponse](initEnv)
+	if err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(initResp.UploadID) == "" {
+		return nil, fmt.Errorf("wecom upload init returned empty upload_id")
+	}
+
+	for idx, offset := 0, 0; offset < len(data); idx, offset = idx+1, offset+wecomUploadChunkMaxBytes {
+		end := offset + wecomUploadChunkMaxBytes
+		if end > len(data) {
+			end = len(data)
+		}
+		sendErr := c.sendCommand(wecomCommand{
+			Cmd:     wecomCmdUploadMediaChunk,
+			Headers: wecomHeaders{ReqID: randomID(10)},
+			Body: wecomUploadMediaChunkBody{
+				UploadID:   initResp.UploadID,
+				ChunkIndex: idx,
+				Base64Data: base64.StdEncoding.EncodeToString(data[offset:end]),
+			},
+		}, wecomUploadTimeout)
+		if sendErr != nil {
+			return nil, sendErr
+		}
+	}
+
+	finishEnv, err := c.sendCommandAck(wecomCommand{
+		Cmd:     wecomCmdUploadMediaEnd,
+		Headers: wecomHeaders{ReqID: randomID(10)},
+		Body: wecomUploadMediaFinishBody{
+			UploadID: initResp.UploadID,
+		},
+	}, wecomUploadTimeout)
+	if err != nil {
+		return nil, err
+	}
+	finishResp, err := decodeWeComEnvelopeBody[wecomUploadMediaFinishResponse](finishEnv)
+	if err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(finishResp.MediaID) == "" {
+		return nil, fmt.Errorf("wecom upload finish returned empty media_id")
+	}
+
+	uploaded := &wecomOutboundMedia{
+		MsgType: kind,
+		MediaID: finishResp.MediaID,
+	}
+	if kind == "video" {
+		video := buildWeComVideoContent(finishResp.MediaID, filename, part.Caption)
+		uploaded.Title = video.Title
+		uploaded.Description = video.Description
+	}
+	return uploaded, nil
+}
+
+func fallbackWeComMediaText(part bus.MediaPart, kind, filename string) string {
+	var lines []string
+	if caption := strings.TrimSpace(part.Caption); caption != "" {
+		lines = append(lines, caption)
+	}
+
+	label := kind
+	if label == "" {
+		label = "media"
+	}
+	if filename != "" {
+		lines = append(lines, fmt.Sprintf("[%s: %s]", label, filename))
+	} else {
+		lines = append(lines, fmt.Sprintf("[%s attachment]", label))
+	}
+
+	ref := strings.TrimSpace(part.Ref)
+	if strings.HasPrefix(ref, "http://") || strings.HasPrefix(ref, "https://") {
+		lines = append(lines, ref)
+	}
+
+	return strings.Join(lines, "\n")
+}
+
+func (c *WeComChannel) resolveMediaRoute(chatID string) (wecomTurn, uint32, bool) {
+	if turn, ok := c.getTurn(chatID); ok {
+		if time.Since(turn.CreatedAt) <= wecomStreamMaxDuration {
+			return turn, turn.ChatType, true
+		}
+		c.deleteTurn(chatID)
+	}
+	if route, ok := c.routes.Get(chatID); ok {
+		return wecomTurn{ChatID: route.ChatID, ChatType: route.ChatType}, route.ChatType, false
+	}
+	return wecomTurn{ChatID: chatID}, 0, false
+}
diff --git a/pkg/channels/wecom/media_test.go b/pkg/channels/wecom/media_test.go
new file mode 100644
index 000000000..d5307e5d2
--- /dev/null
+++ b/pkg/channels/wecom/media_test.go
@@ -0,0 +1,180 @@
+package wecom
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"io"
+	"net/http"
+	"strings"
+	"testing"
+
+	basechannels "github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+func TestStoreRemoteMedia_DetectsJPEGContentTypeFromBody(t *testing.T) {
+	t.Parallel()
+
+	const jpegBase64 = "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAP//////////////////////////////////////////////////////////////////////////////////////" +
+		"//////////////////////////////////////////////////////////////////////////////////////////////2wBDAf//////////////////////////////////////////////////////////////////////////////////////" +
+		"//////////////////////////////////////////////////////////////////////////////////////////////wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAb/xAAVEQEBAAAAAAAAAAAAAAAAAAAABf/aAAwDAQACEAMQAAAB6A//xAAVEAEBAAAAAAAAAAAAAAAAAAAAEf/aAAgBAQABBQJf/8QAFBEBAAAAAAAAAAAAAAAAAAAAEP/aAAgBAwEBPwF//8QAFBEBAAAAAAAAAAAAAAAAAAAAEP/aAAgBAgEBPwF//8QAFBABAAAAAAAAAAAAAAAAAAAAEP/aAAgBAQAGPwJf/8QAFBABAAAAAAAAAAAAAAAAAAAAEP/aAAgBAQABPyFf/9k="
+
+	jpegData := decodeTestBase64(t, jpegBase64)
+	store := media.NewFileMediaStore()
+	ch := &WeComChannel{
+		BaseChannel: basechannels.NewBaseChannel("wecom", nil, nil, nil),
+		mediaClient: &http.Client{
+			Transport: roundTripFunc(func(*http.Request) (*http.Response, error) {
+				return &http.Response{
+					StatusCode: http.StatusOK,
+					Header:     http.Header{"Content-Type": []string{"application/octet-stream"}},
+					Body:       io.NopCloser(bytes.NewReader(jpegData)),
+				}, nil
+			}),
+		},
+	}
+	ch.SetMediaStore(store)
+
+	ref, err := ch.storeRemoteMedia(context.Background(), "test-scope", "msg-1", "https://wecom.example/media", "", "")
+	if err != nil {
+		t.Fatalf("storeRemoteMedia returned error: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = store.ReleaseAll("test-scope")
+	})
+
+	_, meta, err := store.ResolveWithMeta(ref)
+	if err != nil {
+		t.Fatalf("resolve media ref: %v", err)
+	}
+	if meta.ContentType != "image/jpeg" {
+		t.Fatalf("expected image/jpeg content type, got %q", meta.ContentType)
+	}
+	if !strings.HasSuffix(meta.Filename, ".jpg") && !strings.HasSuffix(meta.Filename, ".jpeg") {
+		t.Fatalf("expected jpeg filename, got %q", meta.Filename)
+	}
+}
+
+func TestDetectWeComMediaMetadata_UsesFallbackExtensionWhenBodyUnknown(t *testing.T) {
+	t.Parallel()
+
+	filename, contentType := detectWeComMediaMetadata([]byte("not a real image"), "msg-2.pdf", "", "", "")
+	if filename != "msg-2.pdf" {
+		t.Fatalf("expected fallback filename to be preserved, got %q", filename)
+	}
+	if contentType != "application/pdf" {
+		t.Fatalf("expected application/pdf from fallback extension, got %q", contentType)
+	}
+}
+
+func TestStoreRemoteMedia_PreservesSuffixFromURL(t *testing.T) {
+	t.Parallel()
+
+	docxLikeData := []byte("PK\x03\x04fake office payload")
+	store := media.NewFileMediaStore()
+	ch := &WeComChannel{
+		BaseChannel: basechannels.NewBaseChannel("wecom", nil, nil, nil),
+		mediaClient: &http.Client{
+			Transport: roundTripFunc(func(*http.Request) (*http.Response, error) {
+				return &http.Response{
+					StatusCode: http.StatusOK,
+					Header:     http.Header{"Content-Type": []string{"application/octet-stream"}},
+					Body:       io.NopCloser(bytes.NewReader(docxLikeData)),
+				}, nil
+			}),
+		},
+	}
+	ch.SetMediaStore(store)
+
+	ref, err := ch.storeRemoteMedia(
+		context.Background(),
+		"test-scope",
+		"msg-docx",
+		"https://wecom.example/media/report.docx?signature=1",
+		"",
+		".bin",
+	)
+	if err != nil {
+		t.Fatalf("storeRemoteMedia returned error: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = store.ReleaseAll("test-scope")
+	})
+
+	localPath, meta, err := store.ResolveWithMeta(ref)
+	if err != nil {
+		t.Fatalf("resolve media ref: %v", err)
+	}
+	if !strings.HasSuffix(meta.Filename, ".docx") {
+		t.Fatalf("expected docx filename, got %q", meta.Filename)
+	}
+	if !strings.HasSuffix(strings.ToLower(localPath), ".docx") {
+		t.Fatalf("expected docx temp path, got %q", localPath)
+	}
+}
+
+func TestStoreRemoteMedia_PreservesSuffixFromContentDisposition(t *testing.T) {
+	t.Parallel()
+
+	pptxLikeData := []byte("PK\x03\x04fake office payload")
+	store := media.NewFileMediaStore()
+	ch := &WeComChannel{
+		BaseChannel: basechannels.NewBaseChannel("wecom", nil, nil, nil),
+		mediaClient: &http.Client{
+			Transport: roundTripFunc(func(*http.Request) (*http.Response, error) {
+				return &http.Response{
+					StatusCode: http.StatusOK,
+					Header: http.Header{
+						"Content-Type":        []string{"application/octet-stream"},
+						"Content-Disposition": []string{`attachment; filename="slides.pptx"`},
+					},
+					Body: io.NopCloser(bytes.NewReader(pptxLikeData)),
+				}, nil
+			}),
+		},
+	}
+	ch.SetMediaStore(store)
+
+	ref, err := ch.storeRemoteMedia(
+		context.Background(),
+		"test-scope",
+		"msg-pptx",
+		"https://wecom.example/media/download",
+		"",
+		".bin",
+	)
+	if err != nil {
+		t.Fatalf("storeRemoteMedia returned error: %v", err)
+	}
+	t.Cleanup(func() {
+		_ = store.ReleaseAll("test-scope")
+	})
+
+	localPath, meta, err := store.ResolveWithMeta(ref)
+	if err != nil {
+		t.Fatalf("resolve media ref: %v", err)
+	}
+	if !strings.HasSuffix(meta.Filename, ".pptx") {
+		t.Fatalf("expected pptx filename, got %q", meta.Filename)
+	}
+	if !strings.HasSuffix(strings.ToLower(localPath), ".pptx") {
+		t.Fatalf("expected pptx temp path, got %q", localPath)
+	}
+}
+
+func decodeTestBase64(t *testing.T, value string) []byte {
+	t.Helper()
+
+	data, err := io.ReadAll(base64.NewDecoder(base64.StdEncoding, strings.NewReader(value)))
+	if err != nil {
+		t.Fatalf("decode base64 fixture: %v", err)
+	}
+	return data
+}
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}
diff --git a/pkg/channels/wecom/protocol.go b/pkg/channels/wecom/protocol.go
new file mode 100644
index 000000000..f42ce3bf4
--- /dev/null
+++ b/pkg/channels/wecom/protocol.go
@@ -0,0 +1,173 @@
+package wecom
+
+import "encoding/json"
+
+const (
+	wecomDefaultWebSocketURL = "wss://openws.work.weixin.qq.com"
+	wecomCmdSubscribe        = "aibot_subscribe"
+	wecomCmdPing             = "ping"
+	wecomCmdMsgCallback      = "aibot_msg_callback"
+	wecomCmdEventCallback    = "aibot_event_callback"
+	wecomCmdRespondMsg       = "aibot_respond_msg"
+	wecomCmdSendMsg          = "aibot_send_msg"
+	wecomCmdUploadMediaInit  = "aibot_upload_media_init"
+	wecomCmdUploadMediaChunk = "aibot_upload_media_chunk"
+	wecomCmdUploadMediaEnd   = "aibot_upload_media_finish"
+)
+
+type wecomEnvelope struct {
+	Cmd     string          `json:"cmd,omitempty"`
+	Headers wecomHeaders    `json:"headers"`
+	Body    json.RawMessage `json:"body,omitempty"`
+	ErrCode int             `json:"errcode,omitempty"`
+	ErrMsg  string          `json:"errmsg,omitempty"`
+}
+
+type wecomHeaders struct {
+	ReqID string `json:"req_id,omitempty"`
+}
+
+type wecomCommand struct {
+	Cmd     string       `json:"cmd"`
+	Headers wecomHeaders `json:"headers"`
+	Body    any          `json:"body,omitempty"`
+}
+
+type wecomSendMsgBody struct {
+	ChatID       string                `json:"chatid"`
+	ChatType     uint32                `json:"chat_type,omitempty"`
+	MsgType      string                `json:"msgtype"`
+	Markdown     *wecomMarkdownContent `json:"markdown,omitempty"`
+	File         *wecomMediaRefContent `json:"file,omitempty"`
+	Image        *wecomMediaRefContent `json:"image,omitempty"`
+	Voice        *wecomMediaRefContent `json:"voice,omitempty"`
+	Video        *wecomVideoContent    `json:"video,omitempty"`
+	TemplateCard map[string]any        `json:"template_card,omitempty"`
+}
+
+type wecomRespondMsgBody struct {
+	MsgType      string                `json:"msgtype"`
+	Stream       *wecomStreamContent   `json:"stream,omitempty"`
+	Markdown     *wecomMarkdownContent `json:"markdown,omitempty"`
+	File         *wecomMediaRefContent `json:"file,omitempty"`
+	Image        *wecomMediaRefContent `json:"image,omitempty"`
+	Voice        *wecomMediaRefContent `json:"voice,omitempty"`
+	Video        *wecomVideoContent    `json:"video,omitempty"`
+	TemplateCard map[string]any        `json:"template_card,omitempty"`
+}
+
+type wecomStreamContent struct {
+	ID      string `json:"id"`
+	Finish  bool   `json:"finish"`
+	Content string `json:"content,omitempty"`
+}
+
+type wecomMarkdownContent struct {
+	Content string `json:"content"`
+}
+
+type wecomMediaRefContent struct {
+	MediaID string `json:"media_id"`
+}
+
+type wecomVideoContent struct {
+	MediaID     string `json:"media_id"`
+	Title       string `json:"title,omitempty"`
+	Description string `json:"description,omitempty"`
+}
+
+type wecomUploadMediaInitBody struct {
+	Type        string `json:"type"`
+	Filename    string `json:"filename"`
+	TotalSize   int64  `json:"total_size"`
+	TotalChunks int    `json:"total_chunks"`
+	MD5         string `json:"md5,omitempty"`
+}
+
+type wecomUploadMediaInitResponse struct {
+	UploadID string `json:"upload_id"`
+}
+
+type wecomUploadMediaChunkBody struct {
+	UploadID   string `json:"upload_id"`
+	ChunkIndex int    `json:"chunk_index"`
+	Base64Data string `json:"base64_data"`
+}
+
+type wecomUploadMediaFinishBody struct {
+	UploadID string `json:"upload_id"`
+}
+
+type wecomUploadMediaFinishResponse struct {
+	Type      string          `json:"type"`
+	MediaID   string          `json:"media_id"`
+	CreatedAt json.RawMessage `json:"created_at"`
+}
+
+type wecomIncomingMessage struct {
+	MsgID    string `json:"msgid"`
+	AIBotID  string `json:"aibotid"`
+	ChatID   string `json:"chatid,omitempty"`
+	ChatType string `json:"chattype,omitempty"`
+	From     struct {
+		UserID string `json:"userid"`
+	} `json:"from"`
+	MsgType string `json:"msgtype"`
+	Text    *struct {
+		Content string `json:"content"`
+	} `json:"text,omitempty"`
+	Image *struct {
+		URL    string `json:"url"`
+		AESKey string `json:"aeskey,omitempty"`
+	} `json:"image,omitempty"`
+	File *struct {
+		URL    string `json:"url"`
+		AESKey string `json:"aeskey,omitempty"`
+	} `json:"file,omitempty"`
+	Video *struct {
+		URL    string `json:"url"`
+		AESKey string `json:"aeskey,omitempty"`
+	} `json:"video,omitempty"`
+	Voice *struct {
+		Content string `json:"content"`
+	} `json:"voice,omitempty"`
+	Mixed *struct {
+		MsgItem []struct {
+			MsgType string `json:"msgtype"`
+			Text    *struct {
+				Content string `json:"content"`
+			} `json:"text,omitempty"`
+			Image *struct {
+				URL    string `json:"url"`
+				AESKey string `json:"aeskey,omitempty"`
+			} `json:"image,omitempty"`
+			File *struct {
+				URL    string `json:"url"`
+				AESKey string `json:"aeskey,omitempty"`
+			} `json:"file,omitempty"`
+		} `json:"msg_item"`
+	} `json:"mixed,omitempty"`
+	Quote *struct {
+		MsgType string `json:"msgtype"`
+		Text    *struct {
+			Content string `json:"content"`
+		} `json:"text,omitempty"`
+	} `json:"quote,omitempty"`
+	Event *struct {
+		EventType string `json:"eventtype"`
+	} `json:"event,omitempty"`
+}
+
+func incomingChatID(msg wecomIncomingMessage) string {
+	if msg.ChatID != "" {
+		return msg.ChatID
+	}
+	return msg.From.UserID
+}
+
+func incomingChatTypeCode(kind string) uint32 {
+	if kind == "group" {
+		return 2
+	}
+	return 1
+}
diff --git a/pkg/channels/wecom/reqid_store.go b/pkg/channels/wecom/reqid_store.go
new file mode 100644
index 000000000..59e64e63d
--- /dev/null
+++ b/pkg/channels/wecom/reqid_store.go
@@ -0,0 +1,113 @@
+package wecom
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+)
+
+type wecomRoute struct {
+	ReqID     string    `json:"req_id"`
+	ChatID    string    `json:"chat_id"`
+	ChatType  uint32    `json:"chat_type"`
+	ExpiresAt time.Time `json:"expires_at"`
+}
+
+type reqIDStore struct {
+	mu     sync.Mutex
+	path   string
+	routes map[string]wecomRoute
+}
+
+func newReqIDStore(path string) *reqIDStore {
+	if path == "" {
+		path = defaultReqIDStorePath()
+	}
+	s := &reqIDStore{
+		path:   path,
+		routes: make(map[string]wecomRoute),
+	}
+	_ = s.load()
+	return s
+}
+
+func defaultReqIDStorePath() string {
+	if home, err := os.UserHomeDir(); err == nil && home != "" {
+		return filepath.Join(home, ".picoclaw", "wecom", "reqid-store.json")
+	}
+	return filepath.Join(os.TempDir(), "picoclaw-wecom-reqid-store.json")
+}
+
+func (s *reqIDStore) Put(chatID, reqID string, chatType uint32, ttl time.Duration) error {
+	if reqID == "" || chatID == "" {
+		return nil
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.deleteExpiredLocked(time.Now())
+	s.routes[chatID] = wecomRoute{
+		ReqID:     reqID,
+		ChatID:    chatID,
+		ChatType:  chatType,
+		ExpiresAt: time.Now().Add(ttl),
+	}
+	return s.saveLocked()
+}
+
+func (s *reqIDStore) Get(chatID string) (wecomRoute, bool) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.deleteExpiredLocked(time.Now())
+	route, ok := s.routes[chatID]
+	return route, ok
+}
+
+func (s *reqIDStore) Delete(chatID string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	delete(s.routes, chatID)
+	return s.saveLocked()
+}
+
+func (s *reqIDStore) load() error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	data, err := os.ReadFile(s.path)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return nil
+		}
+		return err
+	}
+
+	var routes map[string]wecomRoute
+	if err := json.Unmarshal(data, &routes); err != nil {
+		return err
+	}
+	s.routes = routes
+	s.deleteExpiredLocked(time.Now())
+	return nil
+}
+
+func (s *reqIDStore) deleteExpiredLocked(now time.Time) {
+	for chatID, route := range s.routes {
+		if !route.ExpiresAt.IsZero() && now.After(route.ExpiresAt) {
+			delete(s.routes, chatID)
+		}
+	}
+}
+
+func (s *reqIDStore) saveLocked() error {
+	if err := os.MkdirAll(filepath.Dir(s.path), 0o700); err != nil {
+		return err
+	}
+	data, err := json.MarshalIndent(s.routes, "", "  ")
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(s.path, data, 0o600)
+}
diff --git a/pkg/channels/wecom/reqid_store_test.go b/pkg/channels/wecom/reqid_store_test.go
new file mode 100644
index 000000000..e68e82500
--- /dev/null
+++ b/pkg/channels/wecom/reqid_store_test.go
@@ -0,0 +1,24 @@
+package wecom
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestReqIDStorePersistsRoutes(t *testing.T) {
+	storePath := filepath.Join(t.TempDir(), "reqids.json")
+	store := newReqIDStore(storePath)
+	if err := store.Put("chat-1", "req-1", 2, time.Hour); err != nil {
+		t.Fatalf("Put() error = %v", err)
+	}
+
+	reloaded := newReqIDStore(storePath)
+	route, ok := reloaded.Get("chat-1")
+	if !ok {
+		t.Fatal("expected persisted route to be loaded")
+	}
+	if route.ChatID != "chat-1" || route.ReqID != "req-1" || route.ChatType != 2 {
+		t.Fatalf("loaded route = %+v", route)
+	}
+}
diff --git a/pkg/channels/wecom/wecom.go b/pkg/channels/wecom/wecom.go
new file mode 100644
index 000000000..26e971921
--- /dev/null
+++ b/pkg/channels/wecom/wecom.go
@@ -0,0 +1,970 @@
+package wecom
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/json"
+	"fmt"
+	"math/big"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/gorilla/websocket"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/identity"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+const (
+	wecomConnectTimeout    = 15 * time.Second
+	wecomCommandTimeout    = 10 * time.Second
+	wecomUploadTimeout     = 30 * time.Second
+	wecomHeartbeatInterval = 30 * time.Second
+	wecomStreamMaxDuration = 5*time.Minute + 30*time.Second
+	wecomStreamMinInterval = 500 * time.Millisecond
+	wecomRouteTTL          = 30 * time.Minute
+	wecomMediaTimeout      = 30 * time.Second
+	wecomRecentMessageMax  = 1000
+)
+
+type WeComChannel struct {
+	*channels.BaseChannel
+	config config.WeComConfig
+
+	ctx    context.Context
+	cancel context.CancelFunc
+
+	conn   *websocket.Conn
+	connMu sync.Mutex
+
+	pendingMu sync.Mutex
+	pending   map[string]chan wecomEnvelope
+
+	turnsMu sync.Mutex
+	turns   map[string][]wecomTurn
+
+	recent      *recentMessageSet
+	routes      *reqIDStore
+	mediaClient *http.Client
+	commandSend func(wecomCommand, time.Duration) (wecomEnvelope, error)
+}
+
+type wecomTurn struct {
+	ReqID     string
+	ChatID    string
+	ChatType  uint32
+	StreamID  string
+	CreatedAt time.Time
+}
+
+type wecomStreamer struct {
+	channel *WeComChannel
+	chatID  string
+	turn    wecomTurn
+
+	mu         sync.Mutex
+	closed     bool
+	lastSentAt time.Time
+	content    string
+}
+
+type recentMessageSet struct {
+	mu   sync.Mutex
+	seen map[string]struct{}
+	ring []string
+	idx  int
+}
+
+func newRecentMessageSet(capacity int) *recentMessageSet {
+	if capacity <= 0 {
+		capacity = wecomRecentMessageMax
+	}
+	return &recentMessageSet{
+		seen: make(map[string]struct{}, capacity),
+		ring: make([]string, capacity),
+	}
+}
+
+func (s *recentMessageSet) Mark(id string) bool {
+	if id == "" {
+		return true
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if _, ok := s.seen[id]; ok {
+		return false
+	}
+	if old := s.ring[s.idx]; old != "" {
+		delete(s.seen, old)
+	}
+	s.ring[s.idx] = id
+	s.idx = (s.idx + 1) % len(s.ring)
+	s.seen[id] = struct{}{}
+	return true
+}
+
+func NewChannel(cfg config.WeComConfig, messageBus *bus.MessageBus) (*WeComChannel, error) {
+	if cfg.BotID == "" || cfg.Secret() == "" {
+		return nil, fmt.Errorf("wecom bot_id and secret are required")
+	}
+	if cfg.WebSocketURL == "" {
+		cfg.WebSocketURL = wecomDefaultWebSocketURL
+	}
+
+	base := channels.NewBaseChannel(
+		"wecom",
+		cfg,
+		messageBus,
+		cfg.AllowFrom,
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
+
+	ch := &WeComChannel{
+		BaseChannel: base,
+		config:      cfg,
+		pending:     make(map[string]chan wecomEnvelope),
+		turns:       make(map[string][]wecomTurn),
+		recent:      newRecentMessageSet(wecomRecentMessageMax),
+		routes:      newReqIDStore(""),
+		mediaClient: &http.Client{Timeout: wecomMediaTimeout},
+	}
+	ch.SetOwner(ch)
+	return ch, nil
+}
+
+func (c *WeComChannel) Name() string { return "wecom" }
+
+func (c *WeComChannel) Start(ctx context.Context) error {
+	logger.InfoC("wecom", "Starting WeCom channel...")
+	c.ctx, c.cancel = context.WithCancel(ctx)
+	c.SetRunning(true)
+	go c.connectLoop()
+	return nil
+}
+
+func (c *WeComChannel) Stop(_ context.Context) error {
+	logger.InfoC("wecom", "Stopping WeCom channel...")
+	if c.cancel != nil {
+		c.cancel()
+	}
+	c.connMu.Lock()
+	if c.conn != nil {
+		_ = c.conn.Close()
+		c.conn = nil
+	}
+	c.connMu.Unlock()
+	c.clearTurns()
+	c.SetRunning(false)
+	return nil
+}
+
+func (c *WeComChannel) BeginStream(_ context.Context, chatID string) (channels.Streamer, error) {
+	if !c.IsRunning() {
+		return nil, channels.ErrNotRunning
+	}
+
+	turn, ok := c.getTurn(chatID)
+	if !ok {
+		return nil, fmt.Errorf("wecom streaming unavailable: no active turn")
+	}
+	if time.Since(turn.CreatedAt) > wecomStreamMaxDuration {
+		c.consumeTurn(chatID, turn)
+		return nil, fmt.Errorf("wecom streaming unavailable: turn expired")
+	}
+
+	return &wecomStreamer{
+		channel: c,
+		chatID:  chatID,
+		turn:    turn,
+	}, nil
+}
+
+func (c *WeComChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+	content := strings.TrimSpace(msg.Content)
+	if content == "" {
+		return nil
+	}
+
+	if turn, ok := c.getTurn(msg.ChatID); ok {
+		if time.Since(turn.CreatedAt) <= wecomStreamMaxDuration {
+			if err := c.sendStreamReply(turn, content); err == nil {
+				c.consumeTurn(msg.ChatID, turn)
+				return nil
+			}
+		}
+		c.consumeTurn(msg.ChatID, turn)
+	}
+
+	if route, ok := c.routes.Get(msg.ChatID); ok {
+		if err := c.sendActivePush(route.ChatID, route.ChatType, content); err != nil {
+			return err
+		}
+		return nil
+	}
+
+	if err := c.sendActivePush(msg.ChatID, 0, content); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (c *WeComChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+
+	route, chatType, hasTurn := c.resolveMediaRoute(msg.ChatID)
+	chatID := route.ChatID
+	if chatID == "" {
+		chatID = msg.ChatID
+	}
+
+	for _, part := range msg.Parts {
+		if strings.TrimSpace(part.Ref) == "" {
+			if caption := strings.TrimSpace(part.Caption); caption != "" {
+				if err := c.sendActivePush(chatID, chatType, caption); err != nil {
+					return err
+				}
+			}
+			continue
+		}
+
+		localPath, filename, contentType, cleanup, err := c.resolveOutboundPart(ctx, part)
+		if err != nil {
+			return fmt.Errorf("wecom resolve media %q: %v: %w", part.Ref, err, channels.ErrSendFailed)
+		}
+
+		func() {
+			if cleanup != nil {
+				defer cleanup()
+			}
+
+			uploaded, uploadErr := c.uploadOutboundMedia(ctx, localPath, filename, contentType, part)
+			if uploadErr != nil {
+				logger.WarnCF("wecom", "Falling back to placeholder after media upload failure", map[string]any{
+					"chat_id":      chatID,
+					"ref":          part.Ref,
+					"filename":     filename,
+					"content_type": contentType,
+					"error":        uploadErr.Error(),
+				})
+				if hasTurn {
+					if finishErr := c.sendStreamChunk(route, true, ""); finishErr != nil {
+						err = finishErr
+						return
+					}
+					c.deleteTurn(msg.ChatID)
+					hasTurn = false
+				}
+				err = c.sendActivePush(chatID, chatType, fallbackWeComMediaText(part, "", filename))
+				return
+			}
+
+			if hasTurn {
+				err = c.sendTurnMedia(route, uploaded)
+				c.deleteTurn(msg.ChatID)
+				hasTurn = false
+			} else {
+				err = c.sendActiveMedia(chatID, chatType, uploaded)
+			}
+			if err != nil {
+				return
+			}
+			if caption := strings.TrimSpace(part.Caption); caption != "" {
+				err = c.sendActivePush(chatID, chatType, caption)
+			}
+		}()
+		if err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (c *WeComChannel) connectLoop() {
+	backoff := time.Second
+	for {
+		select {
+		case <-c.ctx.Done():
+			return
+		default:
+		}
+
+		if err := c.runConnection(); err != nil {
+			logger.WarnCF("wecom", "WeCom connection lost", map[string]any{
+				"error":   err.Error(),
+				"backoff": backoff.String(),
+			})
+			select {
+			case <-time.After(backoff):
+			case <-c.ctx.Done():
+				return
+			}
+			if backoff < time.Minute {
+				backoff *= 2
+				if backoff > time.Minute {
+					backoff = time.Minute
+				}
+			}
+			continue
+		}
+		return
+	}
+}
+
+func (c *WeComChannel) runConnection() error {
+	dialCtx, cancel := context.WithTimeout(c.ctx, wecomConnectTimeout)
+	defer cancel()
+
+	conn, resp, err := websocket.DefaultDialer.DialContext(dialCtx, c.config.WebSocketURL, nil)
+	if resp != nil {
+		_ = resp.Body.Close()
+	}
+	if err != nil {
+		return fmt.Errorf("%w: %v", channels.ErrTemporary, err)
+	}
+
+	c.connMu.Lock()
+	c.conn = conn
+	c.connMu.Unlock()
+	defer func() {
+		c.connMu.Lock()
+		if c.conn == conn {
+			c.conn = nil
+		}
+		c.connMu.Unlock()
+		_ = conn.Close()
+		c.clearTurns()
+	}()
+
+	readErrCh := make(chan error, 1)
+	go func() {
+		readErrCh <- c.readLoop(conn)
+	}()
+
+	if writeErr := c.writeAndWait(conn, wecomCommand{
+		Cmd:     wecomCmdSubscribe,
+		Headers: wecomHeaders{ReqID: randomID(10)},
+		Body: map[string]string{
+			"bot_id": c.config.BotID,
+			"secret": c.config.Secret(),
+		},
+	}, wecomCommandTimeout); writeErr != nil {
+		return writeErr
+	}
+
+	heartbeatDone := make(chan struct{})
+	go func() {
+		defer close(heartbeatDone)
+		c.heartbeatLoop(conn)
+	}()
+
+	err = <-readErrCh
+	_ = conn.Close()
+	<-heartbeatDone
+	return err
+}
+
+func (c *WeComChannel) heartbeatLoop(conn *websocket.Conn) {
+	ticker := time.NewTicker(wecomHeartbeatInterval)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ticker.C:
+			if err := c.writeAndWait(conn, wecomCommand{
+				Cmd:     wecomCmdPing,
+				Headers: wecomHeaders{ReqID: randomID(10)},
+			}, wecomCommandTimeout); err != nil {
+				logger.WarnCF("wecom", "Heartbeat failed", map[string]any{"error": err.Error()})
+				_ = conn.Close()
+				return
+			}
+		case <-c.ctx.Done():
+			return
+		}
+	}
+}
+
+func (c *WeComChannel) readLoop(conn *websocket.Conn) error {
+	for {
+		_, raw, err := conn.ReadMessage()
+		if err != nil {
+			select {
+			case <-c.ctx.Done():
+				return nil
+			default:
+				return fmt.Errorf("%w: %v", channels.ErrTemporary, err)
+			}
+		}
+
+		var env wecomEnvelope
+		if err := json.Unmarshal(raw, &env); err != nil {
+			logger.WarnCF("wecom", "Failed to parse WebSocket message", map[string]any{"error": err.Error()})
+			continue
+		}
+
+		if env.Cmd == "" && env.Headers.ReqID != "" {
+			c.pendingMu.Lock()
+			ch, ok := c.pending[env.Headers.ReqID]
+			if ok {
+				delete(c.pending, env.Headers.ReqID)
+			}
+			c.pendingMu.Unlock()
+			if ok {
+				ch <- env
+			}
+			continue
+		}
+
+		go c.handleEnvelope(env)
+	}
+}
+
+func (c *WeComChannel) handleEnvelope(env wecomEnvelope) {
+	switch env.Cmd {
+	case wecomCmdMsgCallback:
+		c.handleMessageCallback(env)
+	case wecomCmdEventCallback:
+		c.handleEventCallback(env)
+	default:
+		logger.DebugCF("wecom", "Ignoring unsupported WeCom command", map[string]any{"cmd": env.Cmd})
+	}
+}
+
+func (c *WeComChannel) handleEventCallback(env wecomEnvelope) {
+	var msg wecomIncomingMessage
+	if err := json.Unmarshal(env.Body, &msg); err != nil {
+		logger.WarnCF("wecom", "Failed to parse WeCom event callback", map[string]any{"error": err.Error()})
+	}
+}
+
+func (c *WeComChannel) handleMessageCallback(env wecomEnvelope) {
+	var msg wecomIncomingMessage
+	if err := json.Unmarshal(env.Body, &msg); err != nil {
+		logger.WarnCF("wecom", "Failed to parse WeCom message callback", map[string]any{"error": err.Error()})
+		return
+	}
+	if !c.recent.Mark(msg.MsgID) {
+		return
+	}
+
+	reqID := env.Headers.ReqID
+	if reqID == "" {
+		logger.WarnC("wecom", "WeCom message callback missing req_id")
+		return
+	}
+	if msg.Event != nil && msg.Event.EventType != "" {
+		return
+	}
+
+	if err := c.dispatchIncoming(reqID, msg); err != nil {
+		logger.WarnCF("wecom", "Failed to dispatch WeCom message", map[string]any{
+			"req_id": reqID,
+			"error":  err.Error(),
+		})
+		_ = c.respondImmediate(reqID, "The WeCom message could not be processed.")
+	}
+}
+
+func (c *WeComChannel) dispatchIncoming(reqID string, msg wecomIncomingMessage) error {
+	senderID := msg.From.UserID
+	if senderID == "" {
+		senderID = "unknown"
+	}
+	actualChatID := incomingChatID(msg)
+	chatType := incomingChatTypeCode(msg.ChatType)
+	peerKind := "direct"
+	if msg.ChatType == "group" {
+		peerKind = "group"
+	}
+
+	sender := bus.SenderInfo{
+		Platform:    "wecom",
+		PlatformID:  senderID,
+		CanonicalID: identity.BuildCanonicalID("wecom", senderID),
+		DisplayName: senderID,
+	}
+
+	var (
+		content   string
+		quoteText string
+		mediaRefs []string
+		err       error
+	)
+	scope := channels.BuildMediaScope("wecom", actualChatID, msg.MsgID)
+	switch msg.MsgType {
+	case "text":
+		if msg.Text != nil {
+			content = strings.TrimSpace(msg.Text.Content)
+		}
+	case "voice":
+		if msg.Voice != nil {
+			content = strings.TrimSpace(msg.Voice.Content)
+		}
+	case "image":
+		content = "[image]"
+		mediaRefs, err = c.collectSingleMedia(c.ctx, scope, msg.MsgID, &mediaPayload{
+			url:    msg.Image.URL,
+			aesKey: msg.Image.AESKey,
+		}, "image", ".jpg")
+	case "file":
+		content = "[file]"
+		mediaRefs, err = c.collectSingleMedia(c.ctx, scope, msg.MsgID, &mediaPayload{
+			url:    msg.File.URL,
+			aesKey: msg.File.AESKey,
+		}, "file", ".bin")
+	case "video":
+		content = "[video]"
+		mediaRefs, err = c.collectSingleMedia(c.ctx, scope, msg.MsgID, &mediaPayload{
+			url:    msg.Video.URL,
+			aesKey: msg.Video.AESKey,
+		}, "video", ".mp4")
+	case "mixed":
+		content, mediaRefs, err = c.collectMixedMedia(c.ctx, scope, msg)
+	default:
+		return c.respondImmediate(reqID, "Unsupported WeCom message type: "+msg.MsgType)
+	}
+	if err != nil {
+		return err
+	}
+	if msg.Quote != nil && msg.Quote.Text != nil {
+		quoteText = strings.TrimSpace(msg.Quote.Text.Content)
+		if content == "" {
+			content = quoteText
+		}
+	}
+	if content == "" && len(mediaRefs) == 0 {
+		return c.respondImmediate(reqID, "The WeCom message did not contain usable content.")
+	}
+
+	turn := wecomTurn{
+		ReqID:     reqID,
+		ChatID:    actualChatID,
+		ChatType:  chatType,
+		StreamID:  randomID(10),
+		CreatedAt: time.Now(),
+	}
+	c.queueTurn(actualChatID, turn)
+	if err := c.routes.Put(actualChatID, reqID, chatType, wecomRouteTTL); err != nil {
+		logger.WarnCF("wecom", "Failed to persist req_id route", map[string]any{
+			"chat_id": actualChatID,
+			"req_id":  reqID,
+			"error":   err.Error(),
+		})
+	}
+
+	opening := ""
+	if c.config.SendThinkingMessage {
+		opening = "Processing..."
+	}
+	if err := c.sendStreamChunk(turn, false, opening); err != nil {
+		return err
+	}
+
+	peer := bus.Peer{Kind: peerKind, ID: actualChatID}
+	metadata := map[string]string{
+		"channel":   "wecom",
+		"req_id":    reqID,
+		"chat_id":   actualChatID,
+		"chat_type": msg.ChatType,
+		"msg_id":    msg.MsgID,
+		"msg_type":  msg.MsgType,
+	}
+	if quoteText != "" {
+		metadata["quote_text"] = quoteText
+	}
+
+	c.HandleMessage(c.ctx, peer, msg.MsgID, senderID, actualChatID, content, mediaRefs, metadata, sender)
+	return nil
+}
+
+func (c *WeComChannel) collectSingleMedia(
+	ctx context.Context,
+	scope, msgID string,
+	payload interface {
+		GetURL() string
+		GetAESKey() string
+	},
+	label, fallbackExt string,
+) ([]string, error) {
+	if payload == nil || payload.GetURL() == "" {
+		return nil, fmt.Errorf("%s payload is empty", label)
+	}
+	ref, err := c.storeRemoteMedia(ctx, scope, msgID, payload.GetURL(), payload.GetAESKey(), fallbackExt)
+	if err != nil {
+		return nil, err
+	}
+	return []string{ref}, nil
+}
+
+type mediaPayload struct {
+	url    string
+	aesKey string
+}
+
+func (p *mediaPayload) GetURL() string    { return p.url }
+func (p *mediaPayload) GetAESKey() string { return p.aesKey }
+
+func (c *WeComChannel) collectMixedMedia(
+	ctx context.Context,
+	scope string,
+	msg wecomIncomingMessage,
+) (string, []string, error) {
+	if msg.Mixed == nil {
+		return "", nil, fmt.Errorf("mixed message is empty")
+	}
+
+	var textParts []string
+	var refs []string
+	for idx, item := range msg.Mixed.MsgItem {
+		switch item.MsgType {
+		case "text":
+			if item.Text != nil && strings.TrimSpace(item.Text.Content) != "" {
+				textParts = append(textParts, strings.TrimSpace(item.Text.Content))
+			}
+		case "image":
+			if item.Image != nil && item.Image.URL != "" {
+				ref, err := c.storeRemoteMedia(
+					ctx,
+					scope,
+					fmt.Sprintf("%s-%d", msg.MsgID, idx),
+					item.Image.URL,
+					item.Image.AESKey,
+					".jpg",
+				)
+				if err != nil {
+					return "", nil, err
+				}
+				refs = append(refs, ref)
+			}
+		case "file":
+			if item.File != nil && item.File.URL != "" {
+				ref, err := c.storeRemoteMedia(
+					ctx,
+					scope,
+					fmt.Sprintf("%s-%d", msg.MsgID, idx),
+					item.File.URL,
+					item.File.AESKey,
+					".bin",
+				)
+				if err != nil {
+					return "", nil, err
+				}
+				refs = append(refs, ref)
+			}
+		}
+	}
+
+	content := strings.Join(textParts, "\n")
+	if content == "" && len(refs) > 0 {
+		content = "[media]"
+	}
+	return content, refs, nil
+}
+
+func (c *WeComChannel) respondImmediate(reqID, content string) error {
+	turn := wecomTurn{
+		ReqID:     reqID,
+		StreamID:  randomID(10),
+		CreatedAt: time.Now(),
+	}
+	return c.sendStreamChunk(turn, true, content)
+}
+
+func (c *WeComChannel) sendStreamReply(turn wecomTurn, content string) error {
+	return c.sendStreamChunk(turn, true, content)
+}
+
+func (c *WeComChannel) sendStreamChunk(turn wecomTurn, finish bool, content string) error {
+	return c.sendCommand(wecomCommand{
+		Cmd:     wecomCmdRespondMsg,
+		Headers: wecomHeaders{ReqID: turn.ReqID},
+		Body: wecomRespondMsgBody{
+			MsgType: "stream",
+			Stream: &wecomStreamContent{
+				ID:      turn.StreamID,
+				Finish:  finish,
+				Content: content,
+			},
+		},
+	}, wecomCommandTimeout)
+}
+
+func (c *WeComChannel) sendTurnMedia(turn wecomTurn, uploaded *wecomOutboundMedia) error {
+	if uploaded == nil {
+		return fmt.Errorf("wecom outbound media is nil: %w", channels.ErrSendFailed)
+	}
+	if err := c.sendCommand(wecomCommand{
+		Cmd:     wecomCmdRespondMsg,
+		Headers: wecomHeaders{ReqID: turn.ReqID},
+		Body:    uploaded.respondBody(),
+	}, wecomCommandTimeout); err != nil {
+		return err
+	}
+	return c.sendStreamChunk(turn, true, "")
+}
+
+func (c *WeComChannel) sendActivePush(chatID string, chatType uint32, content string) error {
+	if strings.TrimSpace(chatID) == "" {
+		return fmt.Errorf("empty chat ID: %w", channels.ErrSendFailed)
+	}
+	return c.sendCommand(wecomCommand{
+		Cmd:     wecomCmdSendMsg,
+		Headers: wecomHeaders{ReqID: randomID(10)},
+		Body: wecomSendMsgBody{
+			ChatID:   chatID,
+			ChatType: chatType,
+			MsgType:  "markdown",
+			Markdown: &wecomMarkdownContent{Content: content},
+		},
+	}, wecomCommandTimeout)
+}
+
+func (c *WeComChannel) sendActiveMedia(chatID string, chatType uint32, uploaded *wecomOutboundMedia) error {
+	if strings.TrimSpace(chatID) == "" {
+		return fmt.Errorf("empty chat ID: %w", channels.ErrSendFailed)
+	}
+	if uploaded == nil {
+		return fmt.Errorf("wecom outbound media is nil: %w", channels.ErrSendFailed)
+	}
+	return c.sendCommand(wecomCommand{
+		Cmd:     wecomCmdSendMsg,
+		Headers: wecomHeaders{ReqID: randomID(10)},
+		Body:    uploaded.sendBody(chatID, chatType),
+	}, wecomCommandTimeout)
+}
+
+func (c *WeComChannel) sendCommand(cmd wecomCommand, timeout time.Duration) error {
+	_, err := c.sendCommandAck(cmd, timeout)
+	return err
+}
+
+func (c *WeComChannel) sendCommandAck(cmd wecomCommand, timeout time.Duration) (wecomEnvelope, error) {
+	if c.commandSend != nil {
+		return c.commandSend(cmd, timeout)
+	}
+	return c.writeCurrentAck(cmd, timeout)
+}
+
+func (c *WeComChannel) writeCurrentAck(cmd wecomCommand, timeout time.Duration) (wecomEnvelope, error) {
+	c.connMu.Lock()
+	conn := c.conn
+	c.connMu.Unlock()
+	if conn == nil {
+		return wecomEnvelope{}, fmt.Errorf("wecom websocket not connected: %w", channels.ErrTemporary)
+	}
+	return c.writeAndWaitAck(conn, cmd, timeout)
+}
+
+func (c *WeComChannel) writeAndWait(conn *websocket.Conn, cmd wecomCommand, timeout time.Duration) error {
+	_, err := c.writeAndWaitAck(conn, cmd, timeout)
+	return err
+}
+
+func (c *WeComChannel) writeAndWaitAck(
+	conn *websocket.Conn,
+	cmd wecomCommand,
+	timeout time.Duration,
+) (wecomEnvelope, error) {
+	if cmd.Headers.ReqID == "" {
+		cmd.Headers.ReqID = randomID(10)
+	}
+	waitCh := make(chan wecomEnvelope, 1)
+	c.pendingMu.Lock()
+	c.pending[cmd.Headers.ReqID] = waitCh
+	c.pendingMu.Unlock()
+	defer func() {
+		c.pendingMu.Lock()
+		delete(c.pending, cmd.Headers.ReqID)
+		c.pendingMu.Unlock()
+	}()
+
+	data, err := json.Marshal(cmd)
+	if err != nil {
+		return wecomEnvelope{}, fmt.Errorf("%w: %v", channels.ErrSendFailed, err)
+	}
+	c.connMu.Lock()
+	err = conn.WriteMessage(websocket.TextMessage, data)
+	c.connMu.Unlock()
+	if err != nil {
+		return wecomEnvelope{}, fmt.Errorf("%w: %v", channels.ErrTemporary, err)
+	}
+
+	timer := time.NewTimer(timeout)
+	defer timer.Stop()
+	select {
+	case env := <-waitCh:
+		if env.ErrCode != 0 {
+			return wecomEnvelope{}, fmt.Errorf(
+				"%w: wecom errcode=%d errmsg=%s",
+				channels.ErrTemporary,
+				env.ErrCode,
+				env.ErrMsg,
+			)
+		}
+		return env, nil
+	case <-timer.C:
+		return wecomEnvelope{}, fmt.Errorf("%w: timeout waiting for WeCom ack", channels.ErrTemporary)
+	case <-c.ctx.Done():
+		return wecomEnvelope{}, c.ctx.Err()
+	}
+}
+
+func (c *WeComChannel) getTurn(chatID string) (wecomTurn, bool) {
+	c.turnsMu.Lock()
+	defer c.turnsMu.Unlock()
+	queue := c.turns[chatID]
+	if len(queue) == 0 {
+		return wecomTurn{}, false
+	}
+	return queue[0], true
+}
+
+func (c *WeComChannel) deleteTurn(chatID string) {
+	c.turnsMu.Lock()
+	defer c.turnsMu.Unlock()
+	queue := c.turns[chatID]
+	if len(queue) <= 1 {
+		delete(c.turns, chatID)
+		return
+	}
+	c.turns[chatID] = queue[1:]
+}
+
+func (c *WeComChannel) queueTurn(chatID string, turn wecomTurn) {
+	c.turnsMu.Lock()
+	defer c.turnsMu.Unlock()
+	c.turns[chatID] = append(c.turns[chatID], turn)
+}
+
+func (c *WeComChannel) consumeTurn(chatID string, turn wecomTurn) bool {
+	c.turnsMu.Lock()
+	defer c.turnsMu.Unlock()
+
+	queue := c.turns[chatID]
+	if len(queue) == 0 {
+		return false
+	}
+	current := queue[0]
+	if current.ReqID != turn.ReqID || current.StreamID != turn.StreamID {
+		return false
+	}
+	if len(queue) == 1 {
+		delete(c.turns, chatID)
+		return true
+	}
+	c.turns[chatID] = queue[1:]
+	return true
+}
+
+func (c *WeComChannel) clearTurns() {
+	c.turnsMu.Lock()
+	c.turns = make(map[string][]wecomTurn)
+	c.turnsMu.Unlock()
+}
+
+func randomID(n int) string {
+	const alphabet = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+	if n <= 0 {
+		n = 10
+	}
+	buf := make([]byte, n)
+	for i := range buf {
+		v, _ := rand.Int(rand.Reader, big.NewInt(int64(len(alphabet))))
+		buf[i] = alphabet[v.Int64()]
+	}
+	return string(buf)
+}
+
+func (s *wecomStreamer) Update(ctx context.Context, content string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.closed {
+		return nil
+	}
+	if err := s.validateActiveTurn(); err != nil {
+		return err
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+
+	if !s.lastSentAt.IsZero() {
+		wait := time.Until(s.lastSentAt.Add(wecomStreamMinInterval))
+		if wait > 0 {
+			timer := time.NewTimer(wait)
+			defer timer.Stop()
+			select {
+			case <-ctx.Done():
+				return ctx.Err()
+			case <-timer.C:
+			}
+		}
+	}
+
+	if err := s.channel.sendStreamChunk(s.turn, false, content); err != nil {
+		return err
+	}
+	s.content = content
+	s.lastSentAt = time.Now()
+	return nil
+}
+
+func (s *wecomStreamer) Finalize(ctx context.Context, content string) error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.closed {
+		return nil
+	}
+	if err := s.validateActiveTurn(); err != nil {
+		return err
+	}
+	if err := ctx.Err(); err != nil {
+		return err
+	}
+	if err := s.channel.sendStreamChunk(s.turn, true, content); err != nil {
+		return err
+	}
+
+	s.content = content
+	s.closed = true
+	s.channel.consumeTurn(s.chatID, s.turn)
+	return nil
+}
+
+func (s *wecomStreamer) Cancel(_ context.Context) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	if s.closed {
+		return
+	}
+	if s.validateActiveTurn() == nil {
+		_ = s.channel.sendStreamChunk(s.turn, true, s.content)
+		s.channel.consumeTurn(s.chatID, s.turn)
+	}
+	s.closed = true
+}
+
+func (s *wecomStreamer) validateActiveTurn() error {
+	if time.Since(s.turn.CreatedAt) > wecomStreamMaxDuration {
+		s.channel.consumeTurn(s.chatID, s.turn)
+		return fmt.Errorf("wecom streaming unavailable: turn expired")
+	}
+	current, ok := s.channel.getTurn(s.chatID)
+	if !ok || current.ReqID != s.turn.ReqID || current.StreamID != s.turn.StreamID {
+		return fmt.Errorf("wecom streaming unavailable: turn no longer active")
+	}
+	return nil
+}
diff --git a/pkg/channels/wecom/wecom_test.go b/pkg/channels/wecom/wecom_test.go
new file mode 100644
index 000000000..c7a4adfc0
--- /dev/null
+++ b/pkg/channels/wecom/wecom_test.go
@@ -0,0 +1,660 @@
+package wecom
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+func TestDispatchIncoming_UsesActualChatIDAndStoresReqIDRoute(t *testing.T) {
+	t.Parallel()
+
+	messageBus := bus.NewMessageBus()
+	ch := newTestWeComChannel(t, messageBus)
+
+	var commands []wecomCommand
+	ch.commandSend = func(cmd wecomCommand, _ time.Duration) (wecomEnvelope, error) {
+		commands = append(commands, cmd)
+		return wecomTestAck(nil), nil
+	}
+
+	msg := wecomIncomingMessage{
+		MsgID:    "msg-1",
+		ChatID:   "chat-1",
+		ChatType: "direct",
+		MsgType:  "text",
+		Text: &struct {
+			Content string `json:"content"`
+		}{Content: "hello"},
+	}
+	msg.From.UserID = "user-1"
+
+	if err := ch.dispatchIncoming("req-1", msg); err != nil {
+		t.Fatalf("dispatchIncoming() error = %v", err)
+	}
+
+	select {
+	case inbound := <-messageBus.InboundChan():
+		if inbound.ChatID != "chat-1" {
+			t.Fatalf("inbound ChatID = %q, want chat-1", inbound.ChatID)
+		}
+		if inbound.MessageID != "msg-1" {
+			t.Fatalf("inbound MessageID = %q, want msg-1", inbound.MessageID)
+		}
+		if inbound.Peer.ID != "chat-1" {
+			t.Fatalf("inbound Peer.ID = %q, want chat-1", inbound.Peer.ID)
+		}
+		if inbound.Metadata["req_id"] != "req-1" {
+			t.Fatalf("inbound req_id = %q, want req-1", inbound.Metadata["req_id"])
+		}
+	default:
+		t.Fatal("expected inbound message to be published")
+	}
+
+	turn, ok := ch.getTurn("chat-1")
+	if !ok {
+		t.Fatal("expected queued turn for chat-1")
+	}
+	if turn.ReqID != "req-1" {
+		t.Fatalf("turn.ReqID = %q, want req-1", turn.ReqID)
+	}
+
+	route, ok := ch.routes.Get("chat-1")
+	if !ok {
+		t.Fatal("expected persisted route for chat-1")
+	}
+	if route.ReqID != "req-1" || route.ChatType != 1 {
+		t.Fatalf("route = %+v", route)
+	}
+
+	if len(commands) != 1 {
+		t.Fatalf("expected 1 opening command, got %d", len(commands))
+	}
+	if commands[0].Cmd != wecomCmdRespondMsg {
+		t.Fatalf("opening command = %q, want %q", commands[0].Cmd, wecomCmdRespondMsg)
+	}
+	if commands[0].Headers.ReqID != "req-1" {
+		t.Fatalf("opening req_id = %q, want req-1", commands[0].Headers.ReqID)
+	}
+}
+
+func TestNewChannel_DoesNotRegisterMessageSplitLimit(t *testing.T) {
+	t.Parallel()
+
+	ch := newTestWeComChannel(t, bus.NewMessageBus())
+	if got := ch.MaxMessageLength(); got != 0 {
+		t.Fatalf("MaxMessageLength() = %d, want 0", got)
+	}
+}
+
+func TestBeginStream_UpdateAndFinalize(t *testing.T) {
+	t.Parallel()
+
+	ch := newTestWeComChannel(t, bus.NewMessageBus())
+	ch.SetRunning(true)
+	ch.queueTurn("chat-1", wecomTurn{
+		ReqID:     "req-1",
+		ChatID:    "chat-1",
+		ChatType:  1,
+		StreamID:  "stream-1",
+		CreatedAt: time.Now(),
+	})
+
+	var commands []wecomCommand
+	ch.commandSend = func(cmd wecomCommand, _ time.Duration) (wecomEnvelope, error) {
+		commands = append(commands, cmd)
+		return wecomTestAck(nil), nil
+	}
+
+	streamer, err := ch.BeginStream(context.Background(), "chat-1")
+	if err != nil {
+		t.Fatalf("BeginStream() error = %v", err)
+	}
+	if err := streamer.Update(context.Background(), "draft"); err != nil {
+		t.Fatalf("Update() error = %v", err)
+	}
+	if err := streamer.Finalize(context.Background(), "final"); err != nil {
+		t.Fatalf("Finalize() error = %v", err)
+	}
+
+	if len(commands) != 2 {
+		t.Fatalf("expected 2 commands, got %d", len(commands))
+	}
+	for i, wantFinish := range []bool{false, true} {
+		if commands[i].Cmd != wecomCmdRespondMsg {
+			t.Fatalf("command[%d].Cmd = %q, want %q", i, commands[i].Cmd, wecomCmdRespondMsg)
+		}
+		body, ok := commands[i].Body.(wecomRespondMsgBody)
+		if !ok {
+			t.Fatalf("command[%d] body type = %T", i, commands[i].Body)
+		}
+		if body.Stream == nil {
+			t.Fatalf("command[%d] missing stream body", i)
+		}
+		if body.Stream.ID != "stream-1" {
+			t.Fatalf("command[%d] stream id = %q, want stream-1", i, body.Stream.ID)
+		}
+		if body.Stream.Finish != wantFinish {
+			t.Fatalf("command[%d] finish = %v, want %v", i, body.Stream.Finish, wantFinish)
+		}
+	}
+	if body := commands[0].Body.(wecomRespondMsgBody); body.Stream.Content != "draft" {
+		t.Fatalf("update content = %q, want draft", body.Stream.Content)
+	}
+	if body := commands[1].Body.(wecomRespondMsgBody); body.Stream.Content != "final" {
+		t.Fatalf("final content = %q, want final", body.Stream.Content)
+	}
+	if _, ok := ch.getTurn("chat-1"); ok {
+		t.Fatal("expected turn to be consumed after Finalize")
+	}
+}
+
+func TestSend_StreamFailureFallsBackToActualChatID(t *testing.T) {
+	t.Parallel()
+
+	ch := newTestWeComChannel(t, bus.NewMessageBus())
+	ch.SetRunning(true)
+	ch.queueTurn("chat-1", wecomTurn{
+		ReqID:     "req-1",
+		ChatID:    "chat-1",
+		ChatType:  1,
+		StreamID:  "stream-1",
+		CreatedAt: time.Now(),
+	})
+	ch.queueTurn("chat-1", wecomTurn{
+		ReqID:     "req-2",
+		ChatID:    "chat-1",
+		ChatType:  1,
+		StreamID:  "stream-2",
+		CreatedAt: time.Now(),
+	})
+	if err := ch.routes.Put("chat-1", "req-2", 1, time.Hour); err != nil {
+		t.Fatalf("Put() error = %v", err)
+	}
+
+	var commands []wecomCommand
+	ch.commandSend = func(cmd wecomCommand, _ time.Duration) (wecomEnvelope, error) {
+		commands = append(commands, cmd)
+		if len(commands) == 1 && cmd.Cmd == wecomCmdRespondMsg {
+			return wecomEnvelope{}, errors.New("stream send failed")
+		}
+		return wecomTestAck(nil), nil
+	}
+
+	if err := ch.Send(context.Background(), bus.OutboundMessage{
+		Channel: "wecom",
+		ChatID:  "chat-1",
+		Content: "hello",
+	}); err != nil {
+		t.Fatalf("Send() error = %v", err)
+	}
+
+	if len(commands) != 2 {
+		t.Fatalf("expected 2 commands, got %d", len(commands))
+	}
+	if commands[0].Cmd != wecomCmdRespondMsg || commands[0].Headers.ReqID != "req-1" {
+		t.Fatalf("first command = %+v", commands[0])
+	}
+	if commands[1].Cmd != wecomCmdSendMsg {
+		t.Fatalf("second command = %q, want %q", commands[1].Cmd, wecomCmdSendMsg)
+	}
+	body, ok := commands[1].Body.(wecomSendMsgBody)
+	if !ok {
+		t.Fatalf("unexpected send body type %T", commands[1].Body)
+	}
+	if body.ChatID != "chat-1" {
+		t.Fatalf("send chatid = %q, want chat-1", body.ChatID)
+	}
+	if body.ChatType != 1 {
+		t.Fatalf("send chat_type = %d, want 1", body.ChatType)
+	}
+
+	nextTurn, ok := ch.getTurn("chat-1")
+	if !ok {
+		t.Fatal("expected second turn to remain queued")
+	}
+	if nextTurn.ReqID != "req-2" {
+		t.Fatalf("next queued req_id = %q, want req-2", nextTurn.ReqID)
+	}
+}
+
+func TestSend_DoesNotSplitStreamReply(t *testing.T) {
+	t.Parallel()
+
+	ch := newTestWeComChannel(t, bus.NewMessageBus())
+	ch.SetRunning(true)
+	ch.queueTurn("chat-1", wecomTurn{
+		ReqID:     "req-1",
+		ChatID:    "chat-1",
+		ChatType:  1,
+		StreamID:  "stream-1",
+		CreatedAt: time.Now(),
+	})
+
+	var commands []wecomCommand
+	ch.commandSend = func(cmd wecomCommand, _ time.Duration) (wecomEnvelope, error) {
+		commands = append(commands, cmd)
+		return wecomTestAck(nil), nil
+	}
+
+	content := strings.Repeat("\u4e2d", 30000)
+	if err := ch.Send(context.Background(), bus.OutboundMessage{
+		Channel: "wecom",
+		ChatID:  "chat-1",
+		Content: content,
+	}); err != nil {
+		t.Fatalf("Send() error = %v", err)
+	}
+
+	if len(commands) != 1 {
+		t.Fatalf("expected 1 stream command, got %d", len(commands))
+	}
+	body, ok := commands[0].Body.(wecomRespondMsgBody)
+	if !ok {
+		t.Fatalf("unexpected body type %T", commands[0].Body)
+	}
+	if body.Stream == nil || !body.Stream.Finish {
+		t.Fatalf("stream body = %+v", body.Stream)
+	}
+	if body.Stream.Content != content {
+		t.Fatalf("stream content length = %d, want %d", len(body.Stream.Content), len(content))
+	}
+}
+
+func TestSend_DoesNotSplitActivePush(t *testing.T) {
+	t.Parallel()
+
+	ch := newTestWeComChannel(t, bus.NewMessageBus())
+	ch.SetRunning(true)
+
+	var commands []wecomCommand
+	ch.commandSend = func(cmd wecomCommand, _ time.Duration) (wecomEnvelope, error) {
+		commands = append(commands, cmd)
+		return wecomTestAck(nil), nil
+	}
+
+	content := strings.Repeat("a", 30000)
+	if err := ch.Send(context.Background(), bus.OutboundMessage{
+		Channel: "wecom",
+		ChatID:  "chat-1",
+		Content: content,
+	}); err != nil {
+		t.Fatalf("Send() error = %v", err)
+	}
+
+	if len(commands) != 1 {
+		t.Fatalf("expected 1 send command, got %d", len(commands))
+	}
+	if commands[0].Cmd != wecomCmdSendMsg {
+		t.Fatalf("command = %q, want %q", commands[0].Cmd, wecomCmdSendMsg)
+	}
+	body, ok := commands[0].Body.(wecomSendMsgBody)
+	if !ok {
+		t.Fatalf("unexpected body type %T", commands[0].Body)
+	}
+	if body.Markdown == nil || body.Markdown.Content != content {
+		t.Fatalf("markdown content length = %d, want %d", len(body.Markdown.Content), len(content))
+	}
+}
+
+func TestSendMedia_SendsActiveImage(t *testing.T) {
+	t.Parallel()
+
+	ch := newTestWeComChannel(t, bus.NewMessageBus())
+	ch.SetRunning(true)
+
+	store := media.NewFileMediaStore()
+	ch.SetMediaStore(store)
+
+	imageData := wecomTestJPEGData(t)
+	imagePath := filepath.Join(t.TempDir(), "photo.jpg")
+	if err := os.WriteFile(imagePath, imageData, 0o600); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+	ref, err := store.Store(imagePath, media.MediaMeta{
+		Filename:      "photo.jpg",
+		ContentType:   "image/jpeg",
+		Source:        "test",
+		CleanupPolicy: media.CleanupPolicyForgetOnly,
+	}, "scope-1")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	var commands []wecomCommand
+	ch.commandSend = func(cmd wecomCommand, _ time.Duration) (wecomEnvelope, error) {
+		commands = append(commands, cmd)
+		switch cmd.Cmd {
+		case wecomCmdUploadMediaInit:
+			return wecomTestAck(wecomUploadMediaInitResponse{UploadID: "upload-1"}), nil
+		case wecomCmdUploadMediaEnd:
+			return wecomTestAck(wecomUploadMediaFinishResponse{
+				Type:    "image",
+				MediaID: "media-1",
+			}), nil
+		default:
+			return wecomTestAck(nil), nil
+		}
+	}
+
+	err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		Channel: "wecom",
+		ChatID:  "chat-1",
+		Parts: []bus.MediaPart{{
+			Ref:         ref,
+			Type:        "image",
+			Filename:    "photo.jpg",
+			ContentType: "image/jpeg",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+
+	if len(commands) != 4 {
+		t.Fatalf("expected 4 commands, got %d", len(commands))
+	}
+	if commands[0].Cmd != wecomCmdUploadMediaInit {
+		t.Fatalf("first command = %q, want %q", commands[0].Cmd, wecomCmdUploadMediaInit)
+	}
+	initBody, ok := commands[0].Body.(wecomUploadMediaInitBody)
+	if !ok {
+		t.Fatalf("unexpected init body type %T", commands[0].Body)
+	}
+	if initBody.Type != "image" || initBody.Filename != "photo.jpg" || initBody.TotalChunks != 1 {
+		t.Fatalf("init body = %+v", initBody)
+	}
+	if commands[1].Cmd != wecomCmdUploadMediaChunk {
+		t.Fatalf("second command = %q, want %q", commands[1].Cmd, wecomCmdUploadMediaChunk)
+	}
+	chunkBody, ok := commands[1].Body.(wecomUploadMediaChunkBody)
+	if !ok {
+		t.Fatalf("unexpected chunk body type %T", commands[1].Body)
+	}
+	if chunkBody.UploadID != "upload-1" || chunkBody.ChunkIndex != 0 || chunkBody.Base64Data == "" {
+		t.Fatalf("chunk body = %+v", chunkBody)
+	}
+	if commands[2].Cmd != wecomCmdUploadMediaEnd {
+		t.Fatalf("third command = %q, want %q", commands[2].Cmd, wecomCmdUploadMediaEnd)
+	}
+	if commands[3].Cmd != wecomCmdSendMsg {
+		t.Fatalf("fourth command = %q, want %q", commands[3].Cmd, wecomCmdSendMsg)
+	}
+
+	body, ok := commands[3].Body.(wecomSendMsgBody)
+	if !ok {
+		t.Fatalf("unexpected send body type %T", commands[3].Body)
+	}
+	if body.MsgType != "image" || body.Image == nil {
+		t.Fatalf("send body = %+v", body)
+	}
+	if body.ChatID != "chat-1" {
+		t.Fatalf("send chatid = %q, want chat-1", body.ChatID)
+	}
+	if body.Image.MediaID != "media-1" {
+		t.Fatalf("image media_id = %q, want media-1", body.Image.MediaID)
+	}
+}
+
+func TestSendMedia_UsesTurnImageAndFinishesStream(t *testing.T) {
+	t.Parallel()
+
+	ch := newTestWeComChannel(t, bus.NewMessageBus())
+	ch.SetRunning(true)
+
+	store := media.NewFileMediaStore()
+	ch.SetMediaStore(store)
+
+	imageData := wecomTestJPEGData(t)
+	imagePath := filepath.Join(t.TempDir(), "reply.jpg")
+	if err := os.WriteFile(imagePath, imageData, 0o600); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+	ref, err := store.Store(imagePath, media.MediaMeta{
+		Filename:      "reply.jpg",
+		ContentType:   "image/jpeg",
+		Source:        "test",
+		CleanupPolicy: media.CleanupPolicyForgetOnly,
+	}, "scope-2")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	ch.queueTurn("chat-1", wecomTurn{
+		ReqID:     "req-1",
+		ChatID:    "chat-1",
+		ChatType:  1,
+		StreamID:  "stream-1",
+		CreatedAt: time.Now(),
+	})
+	putErr := ch.routes.Put("chat-1", "req-1", 1, time.Hour)
+	if putErr != nil {
+		t.Fatalf("Put() error = %v", putErr)
+	}
+
+	var commands []wecomCommand
+	ch.commandSend = func(cmd wecomCommand, _ time.Duration) (wecomEnvelope, error) {
+		commands = append(commands, cmd)
+		switch cmd.Cmd {
+		case wecomCmdUploadMediaInit:
+			return wecomTestAck(wecomUploadMediaInitResponse{UploadID: "upload-2"}), nil
+		case wecomCmdUploadMediaEnd:
+			return wecomTestAck(wecomUploadMediaFinishResponse{
+				Type:    "image",
+				MediaID: "media-2",
+			}), nil
+		default:
+			return wecomTestAck(nil), nil
+		}
+	}
+
+	err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		Channel: "wecom",
+		ChatID:  "chat-1",
+		Parts: []bus.MediaPart{{
+			Ref:         ref,
+			Type:        "image",
+			Filename:    "reply.jpg",
+			ContentType: "image/jpeg",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+
+	if len(commands) != 5 {
+		t.Fatalf("expected 5 commands, got %d", len(commands))
+	}
+	if commands[0].Cmd != wecomCmdUploadMediaInit {
+		t.Fatalf("first command = %+v", commands[0])
+	}
+	if commands[1].Cmd != wecomCmdUploadMediaChunk {
+		t.Fatalf("second command = %+v", commands[1])
+	}
+	if commands[2].Cmd != wecomCmdUploadMediaEnd {
+		t.Fatalf("third command = %+v", commands[2])
+	}
+	if commands[3].Cmd != wecomCmdRespondMsg || commands[3].Headers.ReqID != "req-1" {
+		t.Fatalf("fourth command = %+v", commands[3])
+	}
+	if commands[4].Cmd != wecomCmdRespondMsg || commands[4].Headers.ReqID != "req-1" {
+		t.Fatalf("fifth command = %+v", commands[4])
+	}
+
+	imageBody, ok := commands[3].Body.(wecomRespondMsgBody)
+	if !ok {
+		t.Fatalf("unexpected image body type %T", commands[3].Body)
+	}
+	if imageBody.MsgType != "image" || imageBody.Image == nil {
+		t.Fatalf("image body = %+v", imageBody)
+	}
+	if imageBody.Image.MediaID != "media-2" {
+		t.Fatalf("image media_id = %q, want media-2", imageBody.Image.MediaID)
+	}
+
+	streamBody, ok := commands[4].Body.(wecomRespondMsgBody)
+	if !ok {
+		t.Fatalf("unexpected finish body type %T", commands[4].Body)
+	}
+	if streamBody.MsgType != "stream" || streamBody.Stream == nil || !streamBody.Stream.Finish {
+		t.Fatalf("finish body = %+v", streamBody)
+	}
+
+	if _, ok := ch.getTurn("chat-1"); ok {
+		t.Fatal("expected turn to be removed after media send")
+	}
+}
+
+func TestSendMedia_SendsActiveFile(t *testing.T) {
+	t.Parallel()
+
+	ch := newTestWeComChannel(t, bus.NewMessageBus())
+	ch.SetRunning(true)
+
+	store := media.NewFileMediaStore()
+	ch.SetMediaStore(store)
+
+	filePath := filepath.Join(t.TempDir(), "report.pdf")
+	if err := os.WriteFile(filePath, []byte("%PDF-1.4"), 0o600); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+	ref, err := store.Store(filePath, media.MediaMeta{
+		Filename:      "report.pdf",
+		ContentType:   "application/pdf",
+		Source:        "test",
+		CleanupPolicy: media.CleanupPolicyForgetOnly,
+	}, "scope-3")
+	if err != nil {
+		t.Fatalf("Store() error = %v", err)
+	}
+
+	var commands []wecomCommand
+	ch.commandSend = func(cmd wecomCommand, _ time.Duration) (wecomEnvelope, error) {
+		commands = append(commands, cmd)
+		switch cmd.Cmd {
+		case wecomCmdUploadMediaInit:
+			return wecomTestAck(wecomUploadMediaInitResponse{UploadID: "upload-3"}), nil
+		case wecomCmdUploadMediaEnd:
+			return wecomTestAck(wecomUploadMediaFinishResponse{
+				Type:    "file",
+				MediaID: "media-3",
+			}), nil
+		default:
+			return wecomTestAck(nil), nil
+		}
+	}
+
+	err = ch.SendMedia(context.Background(), bus.OutboundMediaMessage{
+		Channel: "wecom",
+		ChatID:  "chat-2",
+		Parts: []bus.MediaPart{{
+			Ref:         ref,
+			Type:        "file",
+			Filename:    "report.pdf",
+			ContentType: "application/pdf",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("SendMedia() error = %v", err)
+	}
+
+	if len(commands) != 4 {
+		t.Fatalf("expected 4 commands, got %d", len(commands))
+	}
+	if commands[0].Cmd != wecomCmdUploadMediaInit {
+		t.Fatalf("first command = %q, want %q", commands[0].Cmd, wecomCmdUploadMediaInit)
+	}
+	initBody, ok := commands[0].Body.(wecomUploadMediaInitBody)
+	if !ok {
+		t.Fatalf("unexpected init body type %T", commands[0].Body)
+	}
+	if initBody.Type != "file" || initBody.Filename != "report.pdf" {
+		t.Fatalf("init body = %+v", initBody)
+	}
+	if commands[1].Cmd != wecomCmdUploadMediaChunk {
+		t.Fatalf("second command = %q, want %q", commands[1].Cmd, wecomCmdUploadMediaChunk)
+	}
+	if commands[2].Cmd != wecomCmdUploadMediaEnd {
+		t.Fatalf("third command = %q, want %q", commands[2].Cmd, wecomCmdUploadMediaEnd)
+	}
+	if commands[3].Cmd != wecomCmdSendMsg {
+		t.Fatalf("fourth command = %q, want %q", commands[3].Cmd, wecomCmdSendMsg)
+	}
+
+	body, ok := commands[3].Body.(wecomSendMsgBody)
+	if !ok {
+		t.Fatalf("unexpected body type %T", commands[3].Body)
+	}
+	if body.MsgType != "file" || body.File == nil {
+		t.Fatalf("body = %+v", body)
+	}
+	if body.File.MediaID != "media-3" {
+		t.Fatalf("file media_id = %q, want media-3", body.File.MediaID)
+	}
+}
+
+func newTestWeComChannel(t *testing.T, messageBus *bus.MessageBus) *WeComChannel {
+	t.Helper()
+
+	cfg := config.WeComConfig{BotID: "bot-1"}
+	cfg.SetSecret("secret-1")
+	ch, err := NewChannel(cfg, messageBus)
+	if err != nil {
+		t.Fatalf("NewChannel() error = %v", err)
+	}
+	ch.ctx = context.Background()
+	ch.routes = newReqIDStore(filepath.Join(t.TempDir(), "reqids.json"))
+	return ch
+}
+
+func wecomTestJPEGData(t *testing.T) []byte {
+	t.Helper()
+
+	const jpegBase64 = "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAP//////////////////////////////////////////////////////////////////////////////////////" +
+		"//////////////////////////////////////////////////////////////////////////////////////////////2wBDAf//////////////////////////////////////////////////////////////////////////////////////" +
+		"//////////////////////////////////////////////////////////////////////////////////////////////wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAb/xAAVEQEBAAAAAAAAAAAAAAAAAAAABf/aAAwDAQACEAMQAAAB6A//xAAVEAEBAAAAAAAAAAAAAAAAAAAAEf/aAAgBAQABBQJf/8QAFBEBAAAAAAAAAAAAAAAAAAAAEP/aAAgBAwEBPwF//8QAFBEBAAAAAAAAAAAAAAAAAAAAEP/aAAgBAgEBPwF//8QAFBABAAAAAAAAAAAAAAAAAAAAEP/aAAgBAQAGPwJf/8QAFBABAAAAAAAAAAAAAAAAAAAAEP/aAAgBAQABPyFf/9k="
+
+	return decodeTestBase64(t, jpegBase64)
+}
+
+func TestDecodeWeComUploadFinish_AcceptsNumericCreatedAt(t *testing.T) {
+	t.Parallel()
+
+	resp, err := decodeWeComEnvelopeBody[wecomUploadMediaFinishResponse](wecomEnvelope{
+		Body: json.RawMessage(`{"type":"file","media_id":"media-1","created_at":1380000000}`),
+	})
+	if err != nil {
+		t.Fatalf("decodeWeComEnvelopeBody() error = %v", err)
+	}
+	if resp.Type != "file" || resp.MediaID != "media-1" {
+		t.Fatalf("response = %+v", resp)
+	}
+	if string(resp.CreatedAt) != "1380000000" {
+		t.Fatalf("created_at = %s, want 1380000000", string(resp.CreatedAt))
+	}
+}
+
+func wecomTestAck(body any) wecomEnvelope {
+	var raw []byte
+	if body != nil {
+		encoded, err := json.Marshal(body)
+		if err != nil {
+			panic(err)
+		}
+		raw = encoded
+	}
+	return wecomEnvelope{
+		ErrCode: 0,
+		ErrMsg:  "ok",
+		Body:    raw,
+	}
+}
diff --git a/pkg/channels/weixin/api.go b/pkg/channels/weixin/api.go
new file mode 100644
index 000000000..7f9b3b5c6
--- /dev/null
+++ b/pkg/channels/weixin/api.go
@@ -0,0 +1,241 @@
+package weixin
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"path"
+)
+
+type ApiClient struct {
+	BaseURL    string
+	Token      string
+	HttpClient *http.Client
+}
+
+func NewApiClient(baseURL, token string, proxy string) (*ApiClient, error) {
+	if baseURL == "" {
+		baseURL = "https://ilinkai.weixin.qq.com/"
+	}
+
+	client := &http.Client{
+		// Default timeout; will be overridden per context
+	}
+
+	if proxy != "" {
+		proxyURL, err := url.Parse(proxy)
+		if err != nil {
+			return nil, fmt.Errorf("invalid proxy URL %q: %w", proxy, err)
+		}
+
+		// Clone the default transport so we preserve all default settings (TLS, HTTP/2, timeouts, keep-alives)
+		if defaultTransport, ok := http.DefaultTransport.(*http.Transport); ok {
+			transport := defaultTransport.Clone()
+			transport.Proxy = http.ProxyURL(proxyURL)
+			client.Transport = transport
+		} else {
+			// Fallback: preserve previous behavior if DefaultTransport is not the expected type
+			client.Transport = &http.Transport{
+				Proxy: http.ProxyURL(proxyURL),
+			}
+		}
+	}
+
+	return &ApiClient{
+		BaseURL:    baseURL,
+		Token:      token,
+		HttpClient: client,
+	}, nil
+}
+
+func randomWechatUIN() string {
+	var b [4]byte
+	_, _ = rand.Read(b[:])
+	uint32Val := binary.BigEndian.Uint32(b[:])
+	return base64.StdEncoding.EncodeToString([]byte(fmt.Sprintf("%d", uint32Val)))
+}
+
+func (c *ApiClient) post(ctx context.Context, endpoint string, body any, responseObj any) error {
+	u, err := url.Parse(c.BaseURL)
+	if err != nil {
+		return err
+	}
+	u.Path = path.Join(u.Path, endpoint)
+
+	jsonData, err := json.Marshal(body)
+	if err != nil {
+		return fmt.Errorf("failed to marshal request body: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", u.String(), bytes.NewBuffer(jsonData))
+	if err != nil {
+		return fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+	if endpoint == "ilink/bot/get_bot_qrcode" || endpoint == "ilink/bot/get_qrcode_status" {
+		// QR routes have different headers sometimes, but let's stick to base ones
+		if endpoint == "ilink/bot/get_qrcode_status" {
+			// Use direct map assignment to send exact header name the Tencent API expects
+			req.Header["iLink-App-ClientVersion"] = []string{"1"}
+		}
+	} else {
+		req.Header["AuthorizationType"] = []string{"ilink_bot_token"}
+		req.Header["X-WECHAT-UIN"] = []string{randomWechatUIN()}
+		if c.Token != "" {
+			req.Header.Set("Authorization", "Bearer "+c.Token)
+		}
+	}
+
+	resp, err := c.HttpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("http POST %s failed: %w", endpoint, err)
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return fmt.Errorf("failed to read response body: %w", err)
+	}
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("http %d %s: %s", resp.StatusCode, resp.Status, string(respBody))
+	}
+
+	if responseObj != nil {
+		if err := json.Unmarshal(respBody, responseObj); err != nil {
+			return fmt.Errorf("failed to unmarshal response: %w, body: %s", err, string(respBody))
+		}
+	}
+
+	return nil
+}
+
+func (c *ApiClient) GetUpdates(ctx context.Context, req GetUpdatesReq) (*GetUpdatesResp, error) {
+	req.BaseInfo = BaseInfo{ChannelVersion: "1.0.2"}
+	var resp GetUpdatesResp
+	err := c.post(ctx, "ilink/bot/getupdates", req, &resp)
+	if err != nil {
+		return nil, err
+	}
+	return &resp, nil
+}
+
+func (c *ApiClient) SendMessage(ctx context.Context, req SendMessageReq) (*SendMessageResp, error) {
+	req.BaseInfo = BaseInfo{ChannelVersion: "1.0.2"}
+	var resp SendMessageResp
+	if err := c.post(ctx, "ilink/bot/sendmessage", req, &resp); err != nil {
+		return nil, err
+	}
+	return &resp, nil
+}
+
+func (c *ApiClient) GetUploadUrl(ctx context.Context, req GetUploadUrlReq) (*GetUploadUrlResp, error) {
+	req.BaseInfo = BaseInfo{ChannelVersion: "1.0.2"}
+	var resp GetUploadUrlResp
+	err := c.post(ctx, "ilink/bot/getuploadurl", req, &resp)
+	if err != nil {
+		return nil, err
+	}
+	return &resp, nil
+}
+
+func (c *ApiClient) GetConfig(ctx context.Context, req GetConfigReq) (*GetConfigResp, error) {
+	req.BaseInfo = BaseInfo{ChannelVersion: "1.0.2"}
+	var resp GetConfigResp
+	if err := c.post(ctx, "ilink/bot/getconfig", req, &resp); err != nil {
+		return nil, err
+	}
+	return &resp, nil
+}
+
+func (c *ApiClient) SendTyping(ctx context.Context, req SendTypingReq) (*SendTypingResp, error) {
+	req.BaseInfo = BaseInfo{ChannelVersion: "1.0.2"}
+	var resp SendTypingResp
+	if err := c.post(ctx, "ilink/bot/sendtyping", req, &resp); err != nil {
+		return nil, err
+	}
+	return &resp, nil
+}
+
+func (c *ApiClient) GetQRCode(ctx context.Context, botType string) (*QRCodeResponse, error) {
+	// get_bot_qrcode is GET, not POST
+	u, err := url.Parse(c.BaseURL)
+	if err != nil {
+		return nil, err
+	}
+	u.Path = path.Join(u.Path, "ilink/bot/get_bot_qrcode")
+	q := u.Query()
+	q.Set("bot_type", botType)
+	u.RawQuery = q.Encode()
+
+	req, err := http.NewRequestWithContext(ctx, "GET", u.String(), nil)
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := c.HttpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("get_bot_qrcode failed: %d %s", resp.StatusCode, string(respBody))
+	}
+
+	var qrcodeResp QRCodeResponse
+	if err := json.Unmarshal(respBody, &qrcodeResp); err != nil {
+		return nil, err
+	}
+	return &qrcodeResp, nil
+}
+
+func (c *ApiClient) GetQRCodeStatus(ctx context.Context, qrcode string) (*StatusResponse, error) {
+	// get_qrcode_status is GET
+	u, err := url.Parse(c.BaseURL)
+	if err != nil {
+		return nil, err
+	}
+	u.Path = path.Join(u.Path, "ilink/bot/get_qrcode_status")
+	q := u.Query()
+	q.Set("qrcode", qrcode)
+	u.RawQuery = q.Encode()
+
+	req, err := http.NewRequestWithContext(ctx, "GET", u.String(), nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header["iLink-App-ClientVersion"] = []string{"1"}
+
+	resp, err := c.HttpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("get_qrcode_status failed: %d %s", resp.StatusCode, string(respBody))
+	}
+
+	var statusResp StatusResponse
+	if err := json.Unmarshal(respBody, &statusResp); err != nil {
+		return nil, err
+	}
+	return &statusResp, nil
+}
diff --git a/pkg/channels/weixin/auth.go b/pkg/channels/weixin/auth.go
new file mode 100644
index 000000000..52ec2a6df
--- /dev/null
+++ b/pkg/channels/weixin/auth.go
@@ -0,0 +1,111 @@
+package weixin
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/mdp/qrterminal/v3"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// AuthFlowOpts configures the interactive QR login flow.
+type AuthFlowOpts struct {
+	BaseURL string
+	BotType string
+	Timeout time.Duration
+	Proxy   string
+}
+
+// PerformLoginInteractive starts the Weixin QR login flow and blocks until login is successful or times out.
+// It prints a QR code to the terminal for the user to scan.
+// Returns the BotToken, UserID, AccountID, and BaseUrl on success.
+func PerformLoginInteractive(
+	ctx context.Context,
+	opts AuthFlowOpts,
+) (botToken, userID, accountID, baseUrl string, err error) {
+	if opts.BaseURL == "" {
+		opts.BaseURL = "https://ilinkai.weixin.qq.com/"
+	}
+	if opts.BotType == "" {
+		opts.BotType = "3" // Default iLink Bot Type
+	}
+	if opts.Timeout == 0 {
+		opts.Timeout = 5 * time.Minute
+	}
+
+	api, err := NewApiClient(opts.BaseURL, "", opts.Proxy)
+	if err != nil {
+		return "", "", "", "", fmt.Errorf("failed to create api client: %w", err)
+	}
+
+	logger.InfoC("weixin", "Requesting Weixin QR code...")
+	qrResp, err := api.GetQRCode(ctx, opts.BotType)
+	if err != nil {
+		return "", "", "", "", fmt.Errorf("failed to get qrcode: %w", err)
+	}
+
+	fmt.Println("\n=======================================================")
+	fmt.Println("Please scan the following QR code with WeChat to login:")
+	fmt.Println("=======================================================")
+	fmt.Println()
+
+	// Create Small QR
+	qrconfig := qrterminal.Config{
+		Level:      qrterminal.L,
+		Writer:     os.Stdout,
+		HalfBlocks: true,
+	}
+	qrterminal.GenerateWithConfig(qrResp.QrcodeImgContent, qrconfig)
+
+	fmt.Printf("\nQR Code Link: %s\n\n", qrResp.QrcodeImgContent)
+	fmt.Println("Waiting for scan...")
+
+	timeoutCtx, cancel := context.WithTimeout(ctx, opts.Timeout)
+	defer cancel()
+
+	pollTicker := time.NewTicker(2 * time.Second)
+	defer pollTicker.Stop()
+
+	scannedPrinted := false
+
+	for {
+		select {
+		case <-timeoutCtx.Done():
+			return "", "", "", "", fmt.Errorf("login timeout")
+		case <-pollTicker.C:
+			statusResp, err := api.GetQRCodeStatus(timeoutCtx, qrResp.Qrcode)
+			if err != nil {
+				// Long poll timeout or temporary error
+				continue
+			}
+
+			switch statusResp.Status {
+			case "wait":
+				// still waiting
+			case "scaned":
+				if !scannedPrinted {
+					fmt.Println("👀 QR Code scanned! Please confirm login on your WeChat app...")
+					scannedPrinted = true
+				}
+			case "confirmed":
+				if statusResp.BotToken == "" || statusResp.IlinkBotID == "" {
+					return "", "", "", "", fmt.Errorf("login confirmed but missing bot_token or ilink_bot_id")
+				}
+				logger.InfoCF("weixin", "Login successful", map[string]any{
+					"account_id": statusResp.IlinkBotID,
+				})
+
+				return statusResp.BotToken, statusResp.IlinkUserID, statusResp.IlinkBotID, statusResp.Baseurl, nil
+			case "expired":
+				return "", "", "", "", fmt.Errorf("qrcode expired, please try again")
+			default:
+				logger.WarnCF("weixin", "Unknown QR code status", map[string]any{
+					"status": statusResp.Status,
+				})
+			}
+		}
+	}
+}
diff --git a/pkg/channels/weixin/media.go b/pkg/channels/weixin/media.go
new file mode 100644
index 000000000..72af27438
--- /dev/null
+++ b/pkg/channels/weixin/media.go
@@ -0,0 +1,1038 @@
+package weixin
+
+import (
+	"bytes"
+	"context"
+	"crypto/aes"
+	"crypto/md5"
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/hex"
+	"fmt"
+	"io"
+	"mime"
+	"net/http"
+	"net/url"
+	"os"
+	"os/exec"
+	"path"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/h2non/filetype"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	basechannels "github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+const (
+	weixinMediaMaxBytes         = 100 << 20
+	weixinTypingKeepAlive       = 5 * time.Second
+	weixinUploadRetryMax        = 3
+	weixinVoiceTranscodeTimeout = 15 * time.Second
+)
+
+type uploadedFileInfo struct {
+	downloadParam string
+	aesKeyHex     string
+	fileSize      int64
+	cipherSize    int64
+	filename      string
+}
+
+func pkcs7Pad(src []byte, blockSize int) []byte {
+	padding := blockSize - len(src)%blockSize
+	if padding == 0 {
+		padding = blockSize
+	}
+	out := make([]byte, len(src)+padding)
+	copy(out, src)
+	for i := len(src); i < len(out); i++ {
+		out[i] = byte(padding)
+	}
+	return out
+}
+
+func pkcs7Unpad(src []byte, blockSize int) ([]byte, error) {
+	if len(src) == 0 || len(src)%blockSize != 0 {
+		return nil, fmt.Errorf("invalid padded data size %d", len(src))
+	}
+	padding := int(src[len(src)-1])
+	if padding <= 0 || padding > blockSize || padding > len(src) {
+		return nil, fmt.Errorf("invalid padding size %d", padding)
+	}
+	for i := len(src) - padding; i < len(src); i++ {
+		if src[i] != byte(padding) {
+			return nil, fmt.Errorf("invalid padding content")
+		}
+	}
+	return src[:len(src)-padding], nil
+}
+
+func encryptAESECB(plaintext, key []byte) ([]byte, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+	padded := pkcs7Pad(plaintext, block.BlockSize())
+	out := make([]byte, len(padded))
+	for i := 0; i < len(padded); i += block.BlockSize() {
+		block.Encrypt(out[i:i+block.BlockSize()], padded[i:i+block.BlockSize()])
+	}
+	return out, nil
+}
+
+func decryptAESECB(ciphertext, key []byte) ([]byte, error) {
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+	if len(ciphertext)%block.BlockSize() != 0 {
+		return nil, fmt.Errorf("invalid ciphertext size %d", len(ciphertext))
+	}
+	out := make([]byte, len(ciphertext))
+	for i := 0; i < len(ciphertext); i += block.BlockSize() {
+		block.Decrypt(out[i:i+block.BlockSize()], ciphertext[i:i+block.BlockSize()])
+	}
+	return pkcs7Unpad(out, block.BlockSize())
+}
+
+func parseWeixinMediaAESKey(aesKeyBase64 string) ([]byte, error) {
+	decoded, err := base64.StdEncoding.DecodeString(aesKeyBase64)
+	if err != nil {
+		return nil, err
+	}
+	if len(decoded) == 16 {
+		return decoded, nil
+	}
+	if len(decoded) == 32 {
+		if raw, err := hex.DecodeString(string(decoded)); err == nil && len(raw) == 16 {
+			return raw, nil
+		}
+	}
+	return nil, fmt.Errorf("unsupported aes_key length %d", len(decoded))
+}
+
+func imageAESKey(img *ImageItem) ([]byte, bool, error) {
+	if img == nil {
+		return nil, false, nil
+	}
+	if img.Aeskey != "" {
+		raw, err := hex.DecodeString(img.Aeskey)
+		if err != nil {
+			return nil, false, err
+		}
+		return raw, true, nil
+	}
+	if img.Media != nil && img.Media.AesKey != "" {
+		raw, err := parseWeixinMediaAESKey(img.Media.AesKey)
+		if err != nil {
+			return nil, false, err
+		}
+		return raw, true, nil
+	}
+	return nil, false, nil
+}
+
+func genericMediaAESKey(mediaRef *CDNMedia) ([]byte, error) {
+	if mediaRef == nil || mediaRef.AesKey == "" {
+		return nil, fmt.Errorf("missing aes_key")
+	}
+	return parseWeixinMediaAESKey(mediaRef.AesKey)
+}
+
+func aesEcbPaddedSize(size int64) int64 {
+	return (size/16 + 1) * 16
+}
+
+func randomHex(n int) (string, error) {
+	buf := make([]byte, n)
+	if _, err := rand.Read(buf); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(buf), nil
+}
+
+func buildCDNDownloadURL(base, encryptedQueryParam string) string {
+	return strings.TrimRight(base, "/") +
+		"/download?encrypted_query_param=" + url.QueryEscape(encryptedQueryParam)
+}
+
+func buildCDNUploadURL(base, uploadParam, filekey string) string {
+	return strings.TrimRight(base, "/") +
+		"/upload?encrypted_query_param=" + url.QueryEscape(uploadParam) +
+		"&filekey=" + url.QueryEscape(filekey)
+}
+
+func (c *WeixinChannel) downloadCDNBuffer(ctx context.Context, encryptedQueryParam string) ([]byte, error) {
+	req, err := http.NewRequestWithContext(
+		ctx,
+		http.MethodGet,
+		buildCDNDownloadURL(c.cdnBaseURL(), encryptedQueryParam),
+		nil,
+	)
+	if err != nil {
+		return nil, err
+	}
+	resp, err := c.api.HttpClient.Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
+		return nil, fmt.Errorf("cdn download HTTP %d: %s", resp.StatusCode, string(body))
+	}
+
+	data, err := io.ReadAll(io.LimitReader(resp.Body, weixinMediaMaxBytes+1))
+	if err != nil {
+		return nil, err
+	}
+	if len(data) > weixinMediaMaxBytes {
+		return nil, fmt.Errorf("cdn media too large: %d bytes", len(data))
+	}
+	return data, nil
+}
+
+func (c *WeixinChannel) downloadAndDecryptCDNBuffer(
+	ctx context.Context,
+	encryptedQueryParam string,
+	key []byte,
+) ([]byte, error) {
+	data, err := c.downloadCDNBuffer(ctx, encryptedQueryParam)
+	if err != nil {
+		return nil, err
+	}
+	if len(key) == 0 {
+		return data, nil
+	}
+	return decryptAESECB(data, key)
+}
+
+func detectMediaMetadata(data []byte, fallbackName, fallbackContentType string) (string, string) {
+	contentType := strings.TrimSpace(fallbackContentType)
+	ext := filepath.Ext(fallbackName)
+	if kind, err := filetype.Match(data); err == nil && kind != filetype.Unknown {
+		contentType = kind.MIME.Value
+		if kind.Extension != "" {
+			ext = "." + kind.Extension
+		}
+	}
+	if contentType == "" && ext != "" {
+		contentType = mime.TypeByExtension(strings.ToLower(ext))
+	}
+	if contentType == "" {
+		contentType = http.DetectContentType(data)
+	}
+	if ext == "" && contentType != "" {
+		if exts, err := mime.ExtensionsByType(contentType); err == nil && len(exts) > 0 {
+			ext = exts[0]
+		}
+	}
+
+	filename := sanitizeFilename(fallbackName)
+	if filename == "" {
+		filename = "media"
+	}
+	if filepath.Ext(filename) == "" && ext != "" {
+		filename += ext
+	}
+	return filename, contentType
+}
+
+func sanitizeFilename(name string) string {
+	name = filepath.Base(strings.TrimSpace(name))
+	if name == "." || name == "/" || name == "" {
+		return ""
+	}
+	return name
+}
+
+func writeManagedTempFile(prefix, filename string, data []byte) (string, error) {
+	if err := os.MkdirAll(media.TempDir(), 0o700); err != nil {
+		return "", err
+	}
+	pattern := prefix + "-*"
+	if ext := filepath.Ext(filename); ext != "" {
+		pattern += ext
+	}
+	f, err := os.CreateTemp(media.TempDir(), pattern)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+	if _, err := f.Write(data); err != nil {
+		os.Remove(f.Name())
+		return "", err
+	}
+	return f.Name(), nil
+}
+
+func (c *WeixinChannel) storeInboundBytes(
+	chatID,
+	messageID,
+	filename,
+	contentType string,
+	data []byte,
+) (string, error) {
+	store := c.GetMediaStore()
+	if store == nil {
+		return "", fmt.Errorf("no media store available")
+	}
+	filename, contentType = detectMediaMetadata(data, filename, contentType)
+	tmpPath, err := writeManagedTempFile("weixin-inbound", filename, data)
+	if err != nil {
+		return "", err
+	}
+	ref, err := store.Store(tmpPath, media.MediaMeta{
+		Filename:      filename,
+		ContentType:   contentType,
+		Source:        "weixin",
+		CleanupPolicy: media.CleanupPolicyDeleteOnCleanup,
+	}, basechannels.BuildMediaScope("weixin", chatID, messageID))
+	if err != nil {
+		os.Remove(tmpPath)
+		return "", err
+	}
+	return ref, nil
+}
+
+func isDownloadableMediaItem(item *MessageItem) bool {
+	if item == nil {
+		return false
+	}
+
+	switch item.Type {
+	case MessageItemTypeImage:
+		return item.ImageItem != nil && item.ImageItem.Media != nil && item.ImageItem.Media.EncryptQueryParam != ""
+	case MessageItemTypeVideo:
+		return item.VideoItem != nil && item.VideoItem.Media != nil && item.VideoItem.Media.EncryptQueryParam != ""
+	case MessageItemTypeFile:
+		return item.FileItem != nil && item.FileItem.Media != nil && item.FileItem.Media.EncryptQueryParam != ""
+	case MessageItemTypeVoice:
+		return item.VoiceItem != nil &&
+			item.VoiceItem.Media != nil &&
+			item.VoiceItem.Media.EncryptQueryParam != "" &&
+			strings.TrimSpace(item.VoiceItem.Text) == ""
+	default:
+		return false
+	}
+}
+
+func selectInboundMediaItem(msg WeixinMessage) *MessageItem {
+	priorities := []int{
+		MessageItemTypeImage,
+		MessageItemTypeVideo,
+		MessageItemTypeFile,
+		MessageItemTypeVoice,
+	}
+
+	for _, want := range priorities {
+		for i := range msg.ItemList {
+			item := &msg.ItemList[i]
+			if item.Type == want && isDownloadableMediaItem(item) {
+				return item
+			}
+		}
+	}
+
+	for i := range msg.ItemList {
+		item := &msg.ItemList[i]
+		if item.Type != MessageItemTypeText || item.RefMsg == nil || item.RefMsg.MessageItem == nil {
+			continue
+		}
+		if isDownloadableMediaItem(item.RefMsg.MessageItem) {
+			return item.RefMsg.MessageItem
+		}
+	}
+
+	return nil
+}
+
+func tryTranscodeSilkToWAV(ctx context.Context, silk []byte) ([]byte, error) {
+	decoders := []struct {
+		name string
+		args func(inputPath, outputPath string) []string
+	}{
+		{
+			name: "silk_v3_decoder",
+			args: func(inputPath, outputPath string) []string { return []string{inputPath, outputPath, "24000"} },
+		},
+		{
+			name: "silk_decoder",
+			args: func(inputPath, outputPath string) []string { return []string{inputPath, outputPath, "24000"} },
+		},
+		{
+			name: "ffmpeg",
+			args: func(inputPath, outputPath string) []string {
+				return []string{"-y", "-i", inputPath, outputPath}
+			},
+		},
+	}
+
+	for _, decoder := range decoders {
+		bin, err := exec.LookPath(decoder.name)
+		if err != nil {
+			continue
+		}
+
+		tmpIn, err := writeManagedTempFile("weixin-voice", "voice.silk", silk)
+		if err != nil {
+			return nil, err
+		}
+		tmpOut := filepath.Join(media.TempDir(), "weixin-voice-"+uuid.New().String()+".wav")
+		wav, ok := func() ([]byte, bool) {
+			defer os.Remove(tmpIn)
+			defer os.Remove(tmpOut)
+
+			runCtx, cancel := context.WithTimeout(ctx, weixinVoiceTranscodeTimeout)
+			cmd := exec.CommandContext(runCtx, bin, decoder.args(tmpIn, tmpOut)...)
+			out, runErr := cmd.CombinedOutput()
+			cancel()
+			if runErr != nil {
+				logger.DebugCF("weixin", "SILK transcode command failed", map[string]any{
+					"decoder": decoder.name,
+					"error":   runErr.Error(),
+					"output":  strings.TrimSpace(string(out)),
+				})
+				return nil, false
+			}
+
+			wav, readErr := os.ReadFile(tmpOut)
+			if readErr != nil {
+				logger.DebugCF("weixin", "Failed to read transcoded WAV", map[string]any{
+					"decoder": decoder.name,
+					"error":   readErr.Error(),
+				})
+				return nil, false
+			}
+			return wav, len(wav) > 0
+		}()
+		if ok {
+			return wav, nil
+		}
+	}
+
+	return nil, fmt.Errorf("no SILK decoder available")
+}
+
+func (c *WeixinChannel) downloadMediaFromItem(
+	ctx context.Context,
+	chatID,
+	messageID string,
+	item *MessageItem,
+) (string, error) {
+	if item == nil {
+		return "", nil
+	}
+
+	switch item.Type {
+	case MessageItemTypeImage:
+		key, ok, err := imageAESKey(item.ImageItem)
+		if err != nil {
+			return "", err
+		}
+		data, err := c.downloadAndDecryptCDNBuffer(ctx, item.ImageItem.Media.EncryptQueryParam, func() []byte {
+			if ok {
+				return key
+			}
+			return nil
+		}())
+		if err != nil {
+			return "", err
+		}
+		return c.storeInboundBytes(chatID, messageID, "image", "", data)
+
+	case MessageItemTypeVoice:
+		key, err := genericMediaAESKey(item.VoiceItem.Media)
+		if err != nil {
+			return "", err
+		}
+		silk, err := c.downloadAndDecryptCDNBuffer(ctx, item.VoiceItem.Media.EncryptQueryParam, key)
+		if err != nil {
+			return "", err
+		}
+		if wav, err := tryTranscodeSilkToWAV(ctx, silk); err == nil && len(wav) > 0 {
+			return c.storeInboundBytes(chatID, messageID, "voice.wav", "audio/wav", wav)
+		}
+		return c.storeInboundBytes(chatID, messageID, "voice.silk", "audio/silk", silk)
+
+	case MessageItemTypeFile:
+		key, err := genericMediaAESKey(item.FileItem.Media)
+		if err != nil {
+			return "", err
+		}
+		data, err := c.downloadAndDecryptCDNBuffer(ctx, item.FileItem.Media.EncryptQueryParam, key)
+		if err != nil {
+			return "", err
+		}
+		filename := item.FileItem.FileName
+		if filename == "" {
+			filename = "file.bin"
+		}
+		contentType := mime.TypeByExtension(strings.ToLower(filepath.Ext(filename)))
+		return c.storeInboundBytes(chatID, messageID, filename, contentType, data)
+
+	case MessageItemTypeVideo:
+		key, err := genericMediaAESKey(item.VideoItem.Media)
+		if err != nil {
+			return "", err
+		}
+		data, err := c.downloadAndDecryptCDNBuffer(ctx, item.VideoItem.Media.EncryptQueryParam, key)
+		if err != nil {
+			return "", err
+		}
+		return c.storeInboundBytes(chatID, messageID, "video.mp4", "video/mp4", data)
+	}
+
+	return "", nil
+}
+
+func outboundMediaKind(partType, filename, contentType string) int {
+	switch strings.ToLower(strings.TrimSpace(partType)) {
+	case "image":
+		return UploadMediaTypeImage
+	case "video":
+		return UploadMediaTypeVideo
+	}
+
+	ct := strings.ToLower(contentType)
+	switch {
+	case strings.HasPrefix(ct, "image/"):
+		return UploadMediaTypeImage
+	case strings.HasPrefix(ct, "video/"):
+		return UploadMediaTypeVideo
+	default:
+		return UploadMediaTypeFile
+	}
+}
+
+func detectLocalContentType(localPath, hintContentType string) string {
+	if strings.TrimSpace(hintContentType) != "" {
+		return hintContentType
+	}
+	if kind, err := filetype.MatchFile(localPath); err == nil && kind != filetype.Unknown {
+		return kind.MIME.Value
+	}
+	if ext := filepath.Ext(localPath); ext != "" {
+		if ct := mime.TypeByExtension(strings.ToLower(ext)); ct != "" {
+			return ct
+		}
+	}
+	return "application/octet-stream"
+}
+
+func downloadFilenameFromURL(rawURL, fallback string) string {
+	if fallback = sanitizeFilename(fallback); fallback != "" {
+		return fallback
+	}
+	parsed, err := url.Parse(rawURL)
+	if err == nil {
+		if base := sanitizeFilename(path.Base(parsed.Path)); base != "" {
+			return base
+		}
+	}
+	return "remote-media"
+}
+
+func (c *WeixinChannel) downloadRemoteMediaToTemp(
+	ctx context.Context,
+	rawURL,
+	fallbackName string,
+) (string, string, string, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
+	if err != nil {
+		return "", "", "", err
+	}
+	resp, err := c.api.HttpClient.Do(req)
+	if err != nil {
+		return "", "", "", err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
+		return "", "", "", fmt.Errorf("remote media HTTP %d: %s", resp.StatusCode, string(body))
+	}
+
+	data, err := io.ReadAll(io.LimitReader(resp.Body, weixinMediaMaxBytes+1))
+	if err != nil {
+		return "", "", "", err
+	}
+	if len(data) > weixinMediaMaxBytes {
+		return "", "", "", fmt.Errorf("remote media too large: %d bytes", len(data))
+	}
+
+	filename, contentType := detectMediaMetadata(
+		data,
+		downloadFilenameFromURL(rawURL, fallbackName),
+		resp.Header.Get("Content-Type"),
+	)
+	tmpPath, err := writeManagedTempFile("weixin-remote", filename, data)
+	if err != nil {
+		return "", "", "", err
+	}
+	return tmpPath, filename, contentType, nil
+}
+
+func (c *WeixinChannel) resolveOutboundPart(
+	ctx context.Context,
+	part bus.MediaPart,
+) (string, string, string, func(), error) {
+	cleanup := func() {}
+	filename := sanitizeFilename(part.Filename)
+	contentType := strings.TrimSpace(part.ContentType)
+
+	switch {
+	case strings.HasPrefix(part.Ref, "http://") || strings.HasPrefix(part.Ref, "https://"):
+		localPath, name, ct, err := c.downloadRemoteMediaToTemp(ctx, part.Ref, filename)
+		if err != nil {
+			return "", "", "", cleanup, err
+		}
+		return localPath, name, ct, func() { os.Remove(localPath) }, nil
+
+	case strings.HasPrefix(part.Ref, "media://"):
+		store := c.GetMediaStore()
+		if store == nil {
+			return "", "", "", cleanup, fmt.Errorf("no media store available")
+		}
+		localPath, meta, err := store.ResolveWithMeta(part.Ref)
+		if err != nil {
+			return "", "", "", cleanup, err
+		}
+		if filename == "" {
+			filename = sanitizeFilename(meta.Filename)
+		}
+		if contentType == "" {
+			contentType = meta.ContentType
+		}
+		if strings.HasPrefix(localPath, "http://") || strings.HasPrefix(localPath, "https://") {
+			tmpPath, name, ct, err := c.downloadRemoteMediaToTemp(ctx, localPath, filename)
+			if err != nil {
+				return "", "", "", cleanup, err
+			}
+			return tmpPath, name, ct, func() { os.Remove(tmpPath) }, nil
+		}
+		if filename == "" {
+			filename = sanitizeFilename(filepath.Base(localPath))
+		}
+		if contentType == "" {
+			contentType = detectLocalContentType(localPath, "")
+		}
+		return localPath, filename, contentType, cleanup, nil
+
+	case strings.HasPrefix(part.Ref, "file://"):
+		u, err := url.Parse(part.Ref)
+		if err != nil {
+			return "", "", "", cleanup, err
+		}
+		localPath := u.Path
+		if filename == "" {
+			filename = sanitizeFilename(filepath.Base(localPath))
+		}
+		if contentType == "" {
+			contentType = detectLocalContentType(localPath, "")
+		}
+		return localPath, filename, contentType, cleanup, nil
+
+	default:
+		localPath := part.Ref
+		if filename == "" {
+			filename = sanitizeFilename(filepath.Base(localPath))
+		}
+		if contentType == "" {
+			contentType = detectLocalContentType(localPath, "")
+		}
+		return localPath, filename, contentType, cleanup, nil
+	}
+}
+
+func (c *WeixinChannel) uploadLocalFile(
+	ctx context.Context,
+	localPath,
+	filename,
+	toUserID string,
+	mediaType int,
+) (*uploadedFileInfo, error) {
+	data, err := os.ReadFile(localPath)
+	if err != nil {
+		return nil, err
+	}
+	if len(data) > weixinMediaMaxBytes {
+		return nil, fmt.Errorf("media too large: %d bytes", len(data))
+	}
+
+	filekey, err := randomHex(16)
+	if err != nil {
+		return nil, err
+	}
+	aesKey := make([]byte, 16)
+	if _, readErr := rand.Read(aesKey); readErr != nil {
+		return nil, readErr
+	}
+	aesKeyHex := hex.EncodeToString(aesKey)
+	rawMD5 := md5.Sum(data)
+
+	resp, err := c.api.GetUploadUrl(ctx, GetUploadUrlReq{
+		Filekey:     filekey,
+		MediaType:   mediaType,
+		ToUserID:    toUserID,
+		Rawsize:     int64(len(data)),
+		RawfileMD5:  hex.EncodeToString(rawMD5[:]),
+		Filesize:    aesEcbPaddedSize(int64(len(data))),
+		NoNeedThumb: true,
+		Aeskey:      aesKeyHex,
+	})
+	if err != nil {
+		return nil, err
+	}
+	if resp == nil {
+		return nil, fmt.Errorf("getuploadurl returned nil response")
+	}
+	if resp.Ret != 0 || resp.Errcode != 0 {
+		if isSessionExpiredStatus(resp.Ret, resp.Errcode) {
+			c.pauseSession("getuploadurl", resp.Ret, resp.Errcode, resp.Errmsg)
+		}
+		return nil, fmt.Errorf("getuploadurl failed: ret=%d errcode=%d errmsg=%s", resp.Ret, resp.Errcode, resp.Errmsg)
+	}
+	if strings.TrimSpace(resp.UploadParam) == "" {
+		return nil, fmt.Errorf("getuploadurl returned empty upload_param")
+	}
+
+	downloadParam, err := c.uploadBufferToCDN(ctx, data, resp.UploadParam, filekey, aesKey)
+	if err != nil {
+		return nil, err
+	}
+
+	return &uploadedFileInfo{
+		downloadParam: downloadParam,
+		aesKeyHex:     aesKeyHex,
+		fileSize:      int64(len(data)),
+		cipherSize:    aesEcbPaddedSize(int64(len(data))),
+		filename:      filename,
+	}, nil
+}
+
+func (c *WeixinChannel) uploadBufferToCDN(
+	ctx context.Context,
+	plaintext []byte,
+	uploadParam,
+	filekey string,
+	aesKey []byte,
+) (string, error) {
+	ciphertext, err := encryptAESECB(plaintext, aesKey)
+	if err != nil {
+		return "", err
+	}
+
+	uploadURL := buildCDNUploadURL(c.cdnBaseURL(), uploadParam, filekey)
+	var lastErr error
+
+	for attempt := 1; attempt <= weixinUploadRetryMax; attempt++ {
+		req, reqErr := http.NewRequestWithContext(ctx, http.MethodPost, uploadURL, bytes.NewReader(ciphertext))
+		if reqErr != nil {
+			return "", reqErr
+		}
+		req.Header.Set("Content-Type", "application/octet-stream")
+
+		resp, doErr := c.api.HttpClient.Do(req)
+		if doErr != nil {
+			lastErr = doErr
+		} else {
+			func() {
+				defer resp.Body.Close()
+				if resp.StatusCode >= 400 && resp.StatusCode < 500 {
+					body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
+					lastErr = fmt.Errorf(
+						"cdn upload client error %d: %s",
+						resp.StatusCode,
+						strings.TrimSpace(string(body)),
+					)
+					return
+				}
+				if resp.StatusCode != http.StatusOK {
+					body, _ := io.ReadAll(io.LimitReader(resp.Body, 1024))
+					lastErr = fmt.Errorf(
+						"cdn upload server error %d: %s",
+						resp.StatusCode,
+						strings.TrimSpace(string(body)),
+					)
+					return
+				}
+				if encrypted := strings.TrimSpace(resp.Header.Get("X-Encrypted-Param")); encrypted != "" {
+					lastErr = nil
+					uploadParam = encrypted
+					return
+				}
+				lastErr = fmt.Errorf("cdn upload missing x-encrypted-param header")
+			}()
+		}
+
+		if lastErr == nil {
+			return uploadParam, nil
+		}
+		if strings.Contains(lastErr.Error(), "client error") || attempt == weixinUploadRetryMax {
+			break
+		}
+	}
+
+	return "", lastErr
+}
+
+func (c *WeixinChannel) sendMessageItem(
+	ctx context.Context,
+	toUserID,
+	contextToken string,
+	item MessageItem,
+) error {
+	resp, err := c.api.SendMessage(ctx, SendMessageReq{
+		Msg: WeixinMessage{
+			ToUserID:     toUserID,
+			ClientID:     "picoclaw-" + uuid.New().String(),
+			MessageType:  MessageTypeBot,
+			MessageState: MessageStateFinish,
+			ItemList:     []MessageItem{item},
+			ContextToken: contextToken,
+		},
+	})
+	if err != nil {
+		return err
+	}
+	if resp == nil {
+		return fmt.Errorf("sendmessage returned nil response")
+	}
+	if resp.Ret != 0 || resp.Errcode != 0 {
+		if isSessionExpiredStatus(resp.Ret, resp.Errcode) {
+			c.pauseSession("sendmessage", resp.Ret, resp.Errcode, resp.Errmsg)
+		}
+		return fmt.Errorf("sendmessage failed: ret=%d errcode=%d errmsg=%s", resp.Ret, resp.Errcode, resp.Errmsg)
+	}
+	return nil
+}
+
+func (c *WeixinChannel) sendTextMessage(
+	ctx context.Context,
+	toUserID,
+	contextToken,
+	text string,
+) error {
+	if strings.TrimSpace(text) == "" {
+		return nil
+	}
+	return c.sendMessageItem(ctx, toUserID, contextToken, MessageItem{
+		Type: MessageItemTypeText,
+		TextItem: &TextItem{
+			Text: text,
+		},
+	})
+}
+
+func encodeWeixinOutboundAESKey(aesKeyHex string) string {
+	return base64.StdEncoding.EncodeToString([]byte(aesKeyHex))
+}
+
+func (c *WeixinChannel) sendUploadedMedia(
+	ctx context.Context,
+	toUserID,
+	contextToken,
+	caption string,
+	mediaType int,
+	uploaded *uploadedFileInfo,
+) error {
+	if err := c.sendTextMessage(ctx, toUserID, contextToken, caption); err != nil {
+		return err
+	}
+
+	mediaRef := &CDNMedia{
+		EncryptQueryParam: uploaded.downloadParam,
+		AesKey:            encodeWeixinOutboundAESKey(uploaded.aesKeyHex),
+		EncryptType:       1,
+	}
+
+	switch mediaType {
+	case UploadMediaTypeImage:
+		return c.sendMessageItem(ctx, toUserID, contextToken, MessageItem{
+			Type: MessageItemTypeImage,
+			ImageItem: &ImageItem{
+				Media:   mediaRef,
+				MidSize: uploaded.cipherSize,
+			},
+		})
+
+	case UploadMediaTypeVideo:
+		return c.sendMessageItem(ctx, toUserID, contextToken, MessageItem{
+			Type: MessageItemTypeVideo,
+			VideoItem: &VideoItem{
+				Media:     mediaRef,
+				VideoSize: uploaded.cipherSize,
+			},
+		})
+
+	default:
+		return c.sendMessageItem(ctx, toUserID, contextToken, MessageItem{
+			Type: MessageItemTypeFile,
+			FileItem: &FileItem{
+				Media:    mediaRef,
+				FileName: uploaded.filename,
+				Len:      fmt.Sprintf("%d", uploaded.fileSize),
+			},
+		})
+	}
+}
+
+func (c *WeixinChannel) sendTypingStatus(
+	ctx context.Context,
+	chatID,
+	typingTicket string,
+	status int,
+) error {
+	resp, err := c.api.SendTyping(ctx, SendTypingReq{
+		IlinkUserID:  chatID,
+		TypingTicket: typingTicket,
+		Status:       status,
+	})
+	if err != nil {
+		return err
+	}
+	if resp == nil {
+		return fmt.Errorf("sendtyping returned nil response")
+	}
+	if resp.Ret != 0 || resp.Errcode != 0 {
+		if isSessionExpiredStatus(resp.Ret, resp.Errcode) {
+			c.pauseSession("sendtyping", resp.Ret, resp.Errcode, resp.Errmsg)
+		}
+		return fmt.Errorf("sendtyping failed: ret=%d errcode=%d errmsg=%s", resp.Ret, resp.Errcode, resp.Errmsg)
+	}
+	return nil
+}
+
+// StartTyping implements channels.TypingCapable.
+func (c *WeixinChannel) StartTyping(ctx context.Context, chatID string) (func(), error) {
+	if strings.TrimSpace(chatID) == "" {
+		return func() {}, nil
+	}
+	if c.remainingPause() > 0 {
+		return func() {}, nil
+	}
+
+	ticket, err := c.getTypingTicket(ctx, chatID)
+	if err != nil {
+		if ticket == "" {
+			return func() {}, err
+		}
+		logger.DebugCF("weixin", "GetConfig refresh failed; using cached typing ticket", map[string]any{
+			"chat_id": chatID,
+			"error":   err.Error(),
+		})
+	}
+	if ticket == "" {
+		return func() {}, nil
+	}
+
+	typingCtx, cancel := context.WithCancel(ctx)
+	var once sync.Once
+	stop := func() {
+		once.Do(func() {
+			cancel()
+			stopCtx, stopCancel := context.WithTimeout(context.Background(), 5*time.Second)
+			defer stopCancel()
+			if err := c.sendTypingStatus(stopCtx, chatID, ticket, TypingStatusCancel); err != nil {
+				logger.DebugCF("weixin", "Failed to cancel typing indicator", map[string]any{
+					"chat_id": chatID,
+					"error":   err.Error(),
+				})
+			}
+		})
+	}
+
+	if err := c.sendTypingStatus(typingCtx, chatID, ticket, TypingStatusTyping); err != nil {
+		stop()
+		return func() {}, err
+	}
+
+	ticker := time.NewTicker(weixinTypingKeepAlive)
+	go func() {
+		defer ticker.Stop()
+		for {
+			select {
+			case <-typingCtx.Done():
+				return
+			case <-ticker.C:
+				if err := c.sendTypingStatus(typingCtx, chatID, ticket, TypingStatusTyping); err != nil {
+					logger.DebugCF("weixin", "Failed to refresh typing indicator", map[string]any{
+						"chat_id": chatID,
+						"error":   err.Error(),
+					})
+				}
+			}
+		}
+	}()
+
+	return stop, nil
+}
+
+// SendMedia implements channels.MediaSender.
+func (c *WeixinChannel) SendMedia(ctx context.Context, msg bus.OutboundMediaMessage) error {
+	if !c.IsRunning() {
+		return basechannels.ErrNotRunning
+	}
+	if err := c.ensureSessionActive(); err != nil {
+		return err
+	}
+
+	contextToken := ""
+	if v, ok := c.contextTokens.Load(msg.ChatID); ok {
+		contextToken, _ = v.(string)
+	}
+	if contextToken == "" {
+		return fmt.Errorf(
+			"weixin send media: missing context token for chat %s: %w",
+			msg.ChatID,
+			basechannels.ErrSendFailed,
+		)
+	}
+
+	for _, part := range msg.Parts {
+		localPath, filename, contentType, cleanup, err := c.resolveOutboundPart(ctx, part)
+		if err != nil {
+			logger.ErrorCF("weixin", "Failed to resolve outbound media", map[string]any{
+				"chat_id": msg.ChatID,
+				"ref":     part.Ref,
+				"error":   err.Error(),
+			})
+			return fmt.Errorf("weixin send media: %w", basechannels.ErrSendFailed)
+		}
+		func() {
+			if cleanup != nil {
+				defer cleanup()
+			}
+
+			kind := outboundMediaKind(part.Type, filename, contentType)
+			uploaded, uploadErr := c.uploadLocalFile(ctx, localPath, filename, msg.ChatID, kind)
+			if uploadErr != nil {
+				err = uploadErr
+				return
+			}
+			err = c.sendUploadedMedia(ctx, msg.ChatID, contextToken, part.Caption, kind, uploaded)
+		}()
+		if err != nil {
+			logger.ErrorCF("weixin", "Failed to send outbound media", map[string]any{
+				"chat_id": msg.ChatID,
+				"ref":     part.Ref,
+				"error":   err.Error(),
+			})
+			if c.remainingPause() > 0 {
+				return fmt.Errorf("weixin send media: %w", basechannels.ErrSendFailed)
+			}
+			return fmt.Errorf("weixin send media: %w", basechannels.ErrTemporary)
+		}
+	}
+
+	return nil
+}
diff --git a/pkg/channels/weixin/state.go b/pkg/channels/weixin/state.go
new file mode 100644
index 000000000..9672e614d
--- /dev/null
+++ b/pkg/channels/weixin/state.go
@@ -0,0 +1,226 @@
+package weixin
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	basechannels "github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/fileutil"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+const (
+	weixinDefaultCDNBaseURL    = "https://novac2c.cdn.weixin.qq.com/c2c"
+	weixinConfigCacheTTL       = 24 * time.Hour
+	weixinConfigRetryInitial   = 2 * time.Second
+	weixinConfigRetryMax       = time.Hour
+	weixinSessionPauseDuration = time.Hour
+	weixinSessionExpiredCode   = -14
+)
+
+type typingTicketCacheEntry struct {
+	ticket      string
+	nextFetchAt time.Time
+	retryDelay  time.Duration
+}
+
+type syncCursorFile struct {
+	GetUpdatesBuf string `json:"get_updates_buf"`
+}
+
+func picoclawHomeDir() string {
+	if home := os.Getenv(config.EnvHome); home != "" {
+		return home
+	}
+	userHome, _ := os.UserHomeDir()
+	return filepath.Join(userHome, ".picoclaw")
+}
+
+func buildWeixinSyncBufPath(cfg config.WeixinConfig) string {
+	key := "default"
+	token := strings.TrimSpace(cfg.Token())
+	if token != "" {
+		sum := sha256.Sum256([]byte(strings.TrimSpace(cfg.BaseURL) + "|" + token))
+		key = hex.EncodeToString(sum[:8])
+	}
+	return filepath.Join(picoclawHomeDir(), "channels", "weixin", "sync", key+".json")
+}
+
+func loadGetUpdatesBuf(path string) (string, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return "", nil
+		}
+		return "", err
+	}
+
+	var decoded syncCursorFile
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		return "", err
+	}
+
+	return decoded.GetUpdatesBuf, nil
+}
+
+func saveGetUpdatesBuf(path, cursor string) error {
+	data, err := json.Marshal(syncCursorFile{GetUpdatesBuf: cursor})
+	if err != nil {
+		return err
+	}
+	return fileutil.WriteFileAtomic(path, data, 0o600)
+}
+
+func (c *WeixinChannel) cdnBaseURL() string {
+	if base := strings.TrimSpace(c.config.CDNBaseURL); base != "" {
+		return strings.TrimRight(base, "/")
+	}
+	return weixinDefaultCDNBaseURL
+}
+
+func isSessionExpiredStatus(ret, errcode int) bool {
+	return ret == weixinSessionExpiredCode || errcode == weixinSessionExpiredCode
+}
+
+func (c *WeixinChannel) pauseSession(operation string, ret, errcode int, errmsg string) time.Duration {
+	c.pauseMu.Lock()
+	defer c.pauseMu.Unlock()
+
+	until := time.Now().Add(weixinSessionPauseDuration)
+	if until.After(c.pauseUntil) {
+		c.pauseUntil = until
+	}
+
+	remaining := time.Until(c.pauseUntil)
+	logger.ErrorCF("weixin", "Session expired; pausing Weixin channel", map[string]any{
+		"operation": operation,
+		"ret":       ret,
+		"errcode":   errcode,
+		"errmsg":    errmsg,
+		"until":     c.pauseUntil.Format(time.RFC3339),
+		"minutes":   int((remaining + time.Minute - 1) / time.Minute),
+	})
+	return remaining
+}
+
+func (c *WeixinChannel) remainingPause() time.Duration {
+	c.pauseMu.Lock()
+	defer c.pauseMu.Unlock()
+
+	if c.pauseUntil.IsZero() {
+		return 0
+	}
+	remaining := time.Until(c.pauseUntil)
+	if remaining <= 0 {
+		c.pauseUntil = time.Time{}
+		return 0
+	}
+	return remaining
+}
+
+func (c *WeixinChannel) waitWhileSessionPaused(ctx context.Context) error {
+	remaining := c.remainingPause()
+	if remaining <= 0 {
+		return nil
+	}
+
+	timer := time.NewTimer(remaining)
+	defer timer.Stop()
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}
+
+func (c *WeixinChannel) ensureSessionActive() error {
+	remaining := c.remainingPause()
+	if remaining <= 0 {
+		return nil
+	}
+	return fmt.Errorf(
+		"weixin session paused (%d min remaining): %w",
+		int((remaining+time.Minute-1)/time.Minute),
+		basechannels.ErrSendFailed,
+	)
+}
+
+func (c *WeixinChannel) getTypingTicket(ctx context.Context, userID string) (string, error) {
+	now := time.Now()
+
+	c.typingMu.Lock()
+	entry, ok := c.typingCache[userID]
+	if ok && now.Before(entry.nextFetchAt) {
+		ticket := entry.ticket
+		c.typingMu.Unlock()
+		return ticket, nil
+	}
+	cachedTicket := entry.ticket
+	retryDelay := entry.retryDelay
+	c.typingMu.Unlock()
+
+	contextToken := ""
+	if v, ok := c.contextTokens.Load(userID); ok {
+		contextToken, _ = v.(string)
+	}
+
+	resp, err := c.api.GetConfig(ctx, GetConfigReq{
+		IlinkUserID:  userID,
+		ContextToken: contextToken,
+	})
+	if err == nil && resp != nil && resp.Ret == 0 && resp.Errcode == 0 {
+		ticket := strings.TrimSpace(resp.TypingTicket)
+		c.typingMu.Lock()
+		c.typingCache[userID] = typingTicketCacheEntry{
+			ticket:      ticket,
+			nextFetchAt: now.Add(weixinConfigCacheTTL),
+			retryDelay:  weixinConfigRetryInitial,
+		}
+		c.typingMu.Unlock()
+		return ticket, nil
+	}
+
+	if resp != nil && isSessionExpiredStatus(resp.Ret, resp.Errcode) {
+		c.pauseSession("getconfig", resp.Ret, resp.Errcode, resp.Errmsg)
+	}
+
+	if retryDelay <= 0 {
+		retryDelay = weixinConfigRetryInitial
+	} else {
+		retryDelay *= 2
+		if retryDelay > weixinConfigRetryMax {
+			retryDelay = weixinConfigRetryMax
+		}
+	}
+
+	c.typingMu.Lock()
+	c.typingCache[userID] = typingTicketCacheEntry{
+		ticket:      cachedTicket,
+		nextFetchAt: now.Add(retryDelay),
+		retryDelay:  retryDelay,
+	}
+	c.typingMu.Unlock()
+
+	if err != nil {
+		return cachedTicket, err
+	}
+	if resp == nil {
+		return cachedTicket, fmt.Errorf("getconfig returned nil response")
+	}
+	return cachedTicket, fmt.Errorf(
+		"getconfig failed: ret=%d errcode=%d errmsg=%s",
+		resp.Ret,
+		resp.Errcode,
+		resp.Errmsg,
+	)
+}
diff --git a/pkg/channels/weixin/types.go b/pkg/channels/weixin/types.go
new file mode 100644
index 000000000..74c6e63c3
--- /dev/null
+++ b/pkg/channels/weixin/types.go
@@ -0,0 +1,210 @@
+package weixin
+
+// BaseInfo is attached to every outgoing CGI request
+type BaseInfo struct {
+	ChannelVersion string `json:"channel_version,omitempty"`
+}
+
+type APIStatus struct {
+	Ret     int    `json:"ret,omitempty"`
+	Errcode int    `json:"errcode,omitempty"`
+	Errmsg  string `json:"errmsg,omitempty"`
+}
+
+// UploadMediaType constants
+const (
+	UploadMediaTypeImage = 1
+	UploadMediaTypeVideo = 2
+	UploadMediaTypeFile  = 3
+	UploadMediaTypeVoice = 4
+)
+
+type GetUploadUrlReq struct {
+	Filekey         string   `json:"filekey,omitempty"`
+	MediaType       int      `json:"media_type,omitempty"`
+	ToUserID        string   `json:"to_user_id,omitempty"`
+	Rawsize         int64    `json:"rawsize,omitempty"`
+	RawfileMD5      string   `json:"rawfilemd5,omitempty"`
+	Filesize        int64    `json:"filesize,omitempty"`
+	ThumbRawsize    int64    `json:"thumb_rawsize,omitempty"`
+	ThumbRawfileMD5 string   `json:"thumb_rawfilemd5,omitempty"`
+	ThumbFilesize   int64    `json:"thumb_filesize,omitempty"`
+	NoNeedThumb     bool     `json:"no_need_thumb,omitempty"`
+	Aeskey          string   `json:"aeskey,omitempty"` // hex-encoded 16-byte AES key
+	BaseInfo        BaseInfo `json:"base_info,omitempty"`
+}
+
+type GetUploadUrlResp struct {
+	APIStatus
+	UploadParam      string `json:"upload_param,omitempty"`
+	ThumbUploadParam string `json:"thumb_upload_param,omitempty"`
+}
+
+const (
+	MessageTypeNone = 0
+	MessageTypeUser = 1
+	MessageTypeBot  = 2
+)
+
+const (
+	MessageItemTypeNone  = 0
+	MessageItemTypeText  = 1
+	MessageItemTypeImage = 2
+	MessageItemTypeVoice = 3
+	MessageItemTypeFile  = 4
+	MessageItemTypeVideo = 5
+)
+
+const (
+	MessageStateNew        = 0
+	MessageStateGenerating = 1
+	MessageStateFinish     = 2
+)
+
+type TextItem struct {
+	Text string `json:"text,omitempty"`
+}
+
+type CDNMedia struct {
+	EncryptQueryParam string `json:"encrypt_query_param,omitempty"`
+	AesKey            string `json:"aes_key,omitempty"` // base64 encoded
+	EncryptType       int    `json:"encrypt_type,omitempty"`
+}
+
+type ImageItem struct {
+	Media       *CDNMedia `json:"media,omitempty"`
+	ThumbMedia  *CDNMedia `json:"thumb_media,omitempty"`
+	Aeskey      string    `json:"aeskey,omitempty"`
+	Url         string    `json:"url,omitempty"`
+	MidSize     int64     `json:"mid_size,omitempty"`
+	ThumbSize   int64     `json:"thumb_size,omitempty"`
+	ThumbHeight int       `json:"thumb_height,omitempty"`
+	ThumbWidth  int       `json:"thumb_width,omitempty"`
+	HDSize      int64     `json:"hd_size,omitempty"`
+}
+
+type VoiceItem struct {
+	Media         *CDNMedia `json:"media,omitempty"`
+	EncodeType    int       `json:"encode_type,omitempty"`
+	BitsPerSample int       `json:"bits_per_sample,omitempty"`
+	SampleRate    int       `json:"sample_rate,omitempty"`
+	Playtime      int       `json:"playtime,omitempty"`
+	Text          string    `json:"text,omitempty"`
+}
+
+type FileItem struct {
+	Media    *CDNMedia `json:"media,omitempty"`
+	FileName string    `json:"file_name,omitempty"`
+	MD5      string    `json:"md5,omitempty"`
+	Len      string    `json:"len,omitempty"`
+}
+
+type VideoItem struct {
+	Media       *CDNMedia `json:"media,omitempty"`
+	VideoSize   int64     `json:"video_size,omitempty"`
+	PlayLength  int       `json:"play_length,omitempty"`
+	VideoMD5    string    `json:"video_md5,omitempty"`
+	ThumbMedia  *CDNMedia `json:"thumb_media,omitempty"`
+	ThumbSize   int64     `json:"thumb_size,omitempty"`
+	ThumbHeight int       `json:"thumb_height,omitempty"`
+	ThumbWidth  int       `json:"thumb_width,omitempty"`
+}
+
+type RefMessage struct {
+	MessageItem *MessageItem `json:"message_item,omitempty"`
+	Title       string       `json:"title,omitempty"`
+}
+
+type MessageItem struct {
+	Type         int         `json:"type,omitempty"`
+	CreateTimeMs int64       `json:"create_time_ms,omitempty"`
+	UpdateTimeMs int64       `json:"update_time_ms,omitempty"`
+	IsCompleted  bool        `json:"is_completed,omitempty"`
+	MsgID        string      `json:"msg_id,omitempty"`
+	RefMsg       *RefMessage `json:"ref_msg,omitempty"`
+	TextItem     *TextItem   `json:"text_item,omitempty"`
+	ImageItem    *ImageItem  `json:"image_item,omitempty"`
+	VoiceItem    *VoiceItem  `json:"voice_item,omitempty"`
+	FileItem     *FileItem   `json:"file_item,omitempty"`
+	VideoItem    *VideoItem  `json:"video_item,omitempty"`
+}
+
+type WeixinMessage struct {
+	Seq          int           `json:"seq,omitempty"`
+	MessageID    int64         `json:"message_id,omitempty"`
+	FromUserID   string        `json:"from_user_id,omitempty"`
+	ToUserID     string        `json:"to_user_id,omitempty"`
+	ClientID     string        `json:"client_id,omitempty"`
+	CreateTimeMs int64         `json:"create_time_ms,omitempty"`
+	UpdateTimeMs int64         `json:"update_time_ms,omitempty"`
+	DeleteTimeMs int64         `json:"delete_time_ms,omitempty"`
+	SessionID    string        `json:"session_id,omitempty"`
+	GroupID      string        `json:"group_id,omitempty"`
+	MessageType  int           `json:"message_type,omitempty"`
+	MessageState int           `json:"message_state,omitempty"`
+	ItemList     []MessageItem `json:"item_list,omitempty"`
+	ContextToken string        `json:"context_token,omitempty"`
+}
+
+type GetUpdatesReq struct {
+	SyncBuf       string   `json:"sync_buf,omitempty"`
+	GetUpdatesBuf string   `json:"get_updates_buf,omitempty"`
+	BaseInfo      BaseInfo `json:"base_info,omitempty"`
+}
+
+type GetUpdatesResp struct {
+	APIStatus
+	Msgs                 []WeixinMessage `json:"msgs,omitempty"`
+	SyncBuf              string          `json:"sync_buf,omitempty"`
+	GetUpdatesBuf        string          `json:"get_updates_buf,omitempty"`
+	LongpollingTimeoutMs int             `json:"longpolling_timeout_ms,omitempty"`
+}
+
+type SendMessageReq struct {
+	Msg      WeixinMessage `json:"msg,omitempty"`
+	BaseInfo BaseInfo      `json:"base_info,omitempty"`
+}
+
+type SendMessageResp struct {
+	APIStatus
+}
+
+type GetConfigReq struct {
+	IlinkUserID  string   `json:"ilink_user_id,omitempty"`
+	ContextToken string   `json:"context_token,omitempty"`
+	BaseInfo     BaseInfo `json:"base_info,omitempty"`
+}
+
+type GetConfigResp struct {
+	APIStatus
+	TypingTicket string `json:"typing_ticket,omitempty"`
+}
+
+const (
+	TypingStatusTyping = 1
+	TypingStatusCancel = 2
+)
+
+type SendTypingReq struct {
+	IlinkUserID  string   `json:"ilink_user_id,omitempty"`
+	TypingTicket string   `json:"typing_ticket,omitempty"`
+	Status       int      `json:"status,omitempty"` // 1=typing, 2=cancel
+	BaseInfo     BaseInfo `json:"base_info,omitempty"`
+}
+
+type SendTypingResp struct {
+	APIStatus
+}
+
+type QRCodeResponse struct {
+	Qrcode           string `json:"qrcode"`
+	QrcodeImgContent string `json:"qrcode_img_content"`
+}
+
+type StatusResponse struct {
+	Status      string `json:"status"` // "wait", "scaned", "confirmed", "expired"
+	BotToken    string `json:"bot_token,omitempty"`
+	IlinkBotID  string `json:"ilink_bot_id,omitempty"`
+	Baseurl     string `json:"baseurl,omitempty"`
+	IlinkUserID string `json:"ilink_user_id,omitempty"`
+}
diff --git a/pkg/channels/weixin/weixin.go b/pkg/channels/weixin/weixin.go
new file mode 100644
index 000000000..b9e821ef1
--- /dev/null
+++ b/pkg/channels/weixin/weixin.go
@@ -0,0 +1,359 @@
+package weixin
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/identity"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// WeixinChannel is the Weixin channel implementation over Tencent iLink REST API.
+type WeixinChannel struct {
+	*channels.BaseChannel
+	api    *ApiClient
+	config config.WeixinConfig
+	ctx    context.Context
+	cancel context.CancelFunc
+	bus    *bus.MessageBus
+	// contextTokens stores the last context_token per user (from_user_id → context_token).
+	// This is required by the iLink API to associate replies with the right chat session.
+	contextTokens sync.Map
+	typingMu      sync.Mutex
+	typingCache   map[string]typingTicketCacheEntry
+	pauseMu       sync.Mutex
+	pauseUntil    time.Time
+	syncBufPath   string
+}
+
+func init() {
+	channels.RegisterFactory("weixin", func(cfg *config.Config, bus *bus.MessageBus) (channels.Channel, error) {
+		return NewWeixinChannel(cfg.Channels.Weixin, bus)
+	})
+}
+
+// NewWeixinChannel creates a new WeixinChannel from config.
+func NewWeixinChannel(cfg config.WeixinConfig, messageBus *bus.MessageBus) (*WeixinChannel, error) {
+	api, err := NewApiClient(cfg.BaseURL, cfg.Token(), cfg.Proxy)
+	if err != nil {
+		return nil, fmt.Errorf("weixin: failed to create API client: %w", err)
+	}
+
+	base := channels.NewBaseChannel(
+		"weixin",
+		cfg,
+		messageBus,
+		cfg.AllowFrom,
+		channels.WithMaxMessageLength(4000),
+		channels.WithReasoningChannelID(cfg.ReasoningChannelID),
+	)
+
+	return &WeixinChannel{
+		BaseChannel: base,
+		api:         api,
+		config:      cfg,
+		bus:         messageBus,
+		typingCache: make(map[string]typingTicketCacheEntry),
+		syncBufPath: buildWeixinSyncBufPath(cfg),
+	}, nil
+}
+
+func (c *WeixinChannel) Start(ctx context.Context) error {
+	logger.InfoC("weixin", "Starting Weixin channel")
+	c.ctx, c.cancel = context.WithCancel(ctx)
+	c.SetRunning(true)
+	go c.pollLoop(c.ctx)
+	logger.InfoC("weixin", "Weixin channel started")
+	return nil
+}
+
+func (c *WeixinChannel) Stop(ctx context.Context) error {
+	logger.InfoC("weixin", "Stopping Weixin channel")
+	c.SetRunning(false)
+	if c.cancel != nil {
+		c.cancel()
+	}
+	return nil
+}
+
+// pollLoop is the long-poll receive loop. It runs until ctx is canceled.
+func (c *WeixinChannel) pollLoop(ctx context.Context) {
+	const (
+		defaultPollTimeoutMs = 35_000
+		retryDelay           = 2 * time.Second
+		backoffDelay         = 30 * time.Second
+		maxConsecutiveFails  = 3
+	)
+
+	consecutiveFails := 0
+	getUpdatesBuf, err := loadGetUpdatesBuf(c.syncBufPath)
+	if err != nil {
+		logger.WarnCF("weixin", "Failed to load persisted get_updates_buf", map[string]any{
+			"path":  c.syncBufPath,
+			"error": err.Error(),
+		})
+		getUpdatesBuf = ""
+	} else if getUpdatesBuf != "" {
+		logger.InfoCF("weixin", "Resuming persisted get_updates_buf", map[string]any{
+			"path":   c.syncBufPath,
+			"bytes":  len(getUpdatesBuf),
+			"source": "disk",
+		})
+	}
+	nextTimeoutMs := defaultPollTimeoutMs
+
+	for {
+		select {
+		case <-ctx.Done():
+			logger.InfoC("weixin", "Weixin poll loop stopped")
+			return
+		default:
+		}
+
+		if err := c.waitWhileSessionPaused(ctx); err != nil {
+			if ctx.Err() != nil {
+				return
+			}
+			continue
+		}
+
+		// Build a context with timeout slightly longer than the long-poll
+		pollCtx, pollCancel := context.WithTimeout(ctx, time.Duration(nextTimeoutMs+5000)*time.Millisecond)
+
+		resp, err := c.api.GetUpdates(pollCtx, GetUpdatesReq{
+			GetUpdatesBuf: getUpdatesBuf,
+		})
+		pollCancel()
+
+		if err != nil {
+			// Check if we're shutting down
+			if ctx.Err() != nil {
+				return
+			}
+
+			consecutiveFails++
+			logger.WarnCF("weixin", "getUpdates failed", map[string]any{
+				"error":   err.Error(),
+				"attempt": consecutiveFails,
+			})
+
+			if consecutiveFails >= maxConsecutiveFails {
+				logger.ErrorCF("weixin", "Too many consecutive failures, backing off", map[string]any{
+					"duration": backoffDelay,
+				})
+				consecutiveFails = 0
+				select {
+				case <-ctx.Done():
+					return
+				case <-time.After(backoffDelay):
+				}
+			} else {
+				select {
+				case <-ctx.Done():
+					return
+				case <-time.After(retryDelay):
+				}
+			}
+			continue
+		}
+
+		if isSessionExpiredStatus(resp.Ret, resp.Errcode) {
+			remaining := c.pauseSession("getupdates", resp.Ret, resp.Errcode, resp.Errmsg)
+			select {
+			case <-ctx.Done():
+				return
+			case <-time.After(remaining):
+			}
+			continue
+		}
+
+		if resp.Errcode != 0 || resp.Ret != 0 {
+			consecutiveFails++
+			logger.ErrorCF("weixin", "getUpdates API error", map[string]any{
+				"ret":     resp.Ret,
+				"errcode": resp.Errcode,
+				"errmsg":  resp.Errmsg,
+			})
+			select {
+			case <-ctx.Done():
+				return
+			case <-time.After(retryDelay):
+			}
+			continue
+		}
+
+		consecutiveFails = 0
+
+		// Update the long-poll timeout from server hint
+		if resp.LongpollingTimeoutMs > 0 {
+			nextTimeoutMs = resp.LongpollingTimeoutMs
+		}
+
+		// Advance cursor
+		if resp.GetUpdatesBuf != "" {
+			getUpdatesBuf = resp.GetUpdatesBuf
+			if err := saveGetUpdatesBuf(c.syncBufPath, getUpdatesBuf); err != nil {
+				logger.WarnCF("weixin", "Failed to persist get_updates_buf", map[string]any{
+					"path":  c.syncBufPath,
+					"error": err.Error(),
+				})
+			}
+		}
+
+		// Dispatch messages
+		for _, msg := range resp.Msgs {
+			c.handleInboundMessage(ctx, msg)
+		}
+	}
+}
+
+// handleInboundMessage converts a WeixinMessage to a bus.InboundMessage.
+func (c *WeixinChannel) handleInboundMessage(ctx context.Context, msg WeixinMessage) {
+	fromUserID := msg.FromUserID
+	if fromUserID == "" {
+		return
+	}
+
+	messageID := msg.ClientID
+	if messageID == "" {
+		messageID = uuid.New().String()
+	}
+
+	// Build text content from item_list
+	var parts []string
+	for _, item := range msg.ItemList {
+		switch item.Type {
+		case MessageItemTypeText:
+			if item.TextItem != nil && item.TextItem.Text != "" {
+				parts = append(parts, item.TextItem.Text)
+			}
+		case MessageItemTypeVoice:
+			if item.VoiceItem != nil && item.VoiceItem.Text != "" {
+				// Use voice → text transcription from server
+				parts = append(parts, item.VoiceItem.Text)
+			} else {
+				parts = append(parts, "[audio]")
+			}
+		case MessageItemTypeImage:
+			parts = append(parts, "[image]")
+		case MessageItemTypeFile:
+			if item.FileItem != nil && item.FileItem.FileName != "" {
+				parts = append(parts, fmt.Sprintf("[file: %s]", item.FileItem.FileName))
+			} else {
+				parts = append(parts, "[file]")
+			}
+		case MessageItemTypeVideo:
+			parts = append(parts, "[video]")
+		}
+	}
+
+	var mediaRefs []string
+	if mediaItem := selectInboundMediaItem(msg); mediaItem != nil {
+		ref, err := c.downloadMediaFromItem(ctx, fromUserID, messageID, mediaItem)
+		if err != nil {
+			logger.ErrorCF("weixin", "Failed to download inbound media", map[string]any{
+				"from_user_id": fromUserID,
+				"message_id":   messageID,
+				"type":         mediaItem.Type,
+				"error":        err.Error(),
+			})
+		} else if ref != "" {
+			mediaRefs = append(mediaRefs, ref)
+		}
+	}
+
+	content := strings.Join(parts, "\n")
+	if content == "" && len(mediaRefs) == 0 {
+		return
+	}
+
+	sender := bus.SenderInfo{
+		Platform:    "weixin",
+		PlatformID:  fromUserID,
+		CanonicalID: identity.BuildCanonicalID("weixin", fromUserID),
+		Username:    fromUserID,
+		DisplayName: fromUserID,
+	}
+
+	if !c.IsAllowedSender(sender) {
+		logger.DebugCF("weixin", "Message rejected by allowlist", map[string]any{
+			"from_user_id": fromUserID,
+		})
+		return
+	}
+
+	peer := bus.Peer{Kind: "direct", ID: fromUserID}
+
+	metadata := map[string]string{
+		"from_user_id":  fromUserID,
+		"context_token": msg.ContextToken,
+		"session_id":    msg.SessionID,
+	}
+
+	logger.DebugCF("weixin", "Received message", map[string]any{
+		"from_user_id": fromUserID,
+		"content_len":  len(content),
+		"media_count":  len(mediaRefs),
+	})
+
+	// Store context_token for outbound reply association
+	if msg.ContextToken != "" {
+		c.contextTokens.Store(fromUserID, msg.ContextToken)
+	}
+
+	c.HandleMessage(ctx, peer, messageID, fromUserID, fromUserID, content, mediaRefs, metadata, sender)
+}
+
+// Send implements channels.Channel by sending a text message to the WeChat user.
+func (c *WeixinChannel) Send(ctx context.Context, msg bus.OutboundMessage) error {
+	if !c.IsRunning() {
+		return channels.ErrNotRunning
+	}
+	if err := c.ensureSessionActive(); err != nil {
+		return err
+	}
+
+	if msg.Content == "" {
+		return nil
+	}
+
+	// We need a context_token to send a reply. It should be stored in the conversation metadata.
+	// The chat_id is the weixin user_id (from_user_id).
+	toUserID := msg.ChatID
+
+	// Retrieve context_token from our per-user map (stored on last inbound)
+	contextToken := ""
+	if ct, ok := c.contextTokens.Load(toUserID); ok {
+		contextToken, _ = ct.(string)
+	}
+
+	// If we don't have a context token for this user, we cannot send a valid reply.
+	// Treat this as a non-temporary error so the manager doesn't keep retrying.
+	if contextToken == "" {
+		logger.ErrorCF("weixin", "Missing context token, cannot send message", map[string]any{
+			"to_user_id": toUserID,
+		})
+		return fmt.Errorf("weixin send: %w: missing context token for chat %s", channels.ErrSendFailed, toUserID)
+	}
+
+	if err := c.sendTextMessage(ctx, toUserID, contextToken, msg.Content); err != nil {
+		logger.ErrorCF("weixin", "Failed to send message", map[string]any{
+			"to_user_id": toUserID,
+			"error":      err.Error(),
+		})
+		if c.remainingPause() > 0 {
+			return fmt.Errorf("weixin send: %w", channels.ErrSendFailed)
+		}
+		return fmt.Errorf("weixin send: %w", channels.ErrTemporary)
+	}
+
+	return nil
+}
diff --git a/pkg/channels/weixin/weixin_test.go b/pkg/channels/weixin/weixin_test.go
new file mode 100644
index 000000000..62984c965
--- /dev/null
+++ b/pkg/channels/weixin/weixin_test.go
@@ -0,0 +1,211 @@
+package weixin
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"errors"
+	"io"
+	"net/http"
+	"path/filepath"
+	"testing"
+	"time"
+
+	basechannels "github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}
+
+func TestParseWeixinMediaAESKey(t *testing.T) {
+	raw := []byte("1234567890abcdef")
+
+	got, err := parseWeixinMediaAESKey(base64.StdEncoding.EncodeToString(raw))
+	if err != nil {
+		t.Fatalf("parseWeixinMediaAESKey(raw) error = %v", err)
+	}
+	if !bytes.Equal(got, raw) {
+		t.Fatalf("parseWeixinMediaAESKey(raw) = %x, want %x", got, raw)
+	}
+
+	hexEncoded := base64.StdEncoding.EncodeToString([]byte("31323334353637383930616263646566"))
+	got, err = parseWeixinMediaAESKey(hexEncoded)
+	if err != nil {
+		t.Fatalf("parseWeixinMediaAESKey(hex-string) error = %v", err)
+	}
+	if !bytes.Equal(got, raw) {
+		t.Fatalf("parseWeixinMediaAESKey(hex-string) = %x, want %x", got, raw)
+	}
+}
+
+func TestDownloadAndDecryptCDNBuffer(t *testing.T) {
+	key := []byte("1234567890abcdef")
+	plaintext := []byte("hello weixin")
+	ciphertext, err := encryptAESECB(plaintext, key)
+	if err != nil {
+		t.Fatalf("encryptAESECB() error = %v", err)
+	}
+
+	ch := &WeixinChannel{
+		api: &ApiClient{
+			HttpClient: &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+				if r.URL.Path != "/download" {
+					t.Fatalf("download path = %q, want /download", r.URL.Path)
+				}
+				if r.URL.Query().Get("encrypted_query_param") != "token" {
+					t.Fatalf("encrypted_query_param = %q, want token", r.URL.Query().Get("encrypted_query_param"))
+				}
+				return &http.Response{
+					StatusCode: http.StatusOK,
+					Body:       io.NopCloser(bytes.NewReader(ciphertext)),
+					Header:     make(http.Header),
+				}, nil
+			})},
+		},
+		config: config.WeixinConfig{
+			CDNBaseURL: "https://cdn.example.com",
+		},
+		typingCache: make(map[string]typingTicketCacheEntry),
+	}
+
+	got, err := ch.downloadAndDecryptCDNBuffer(context.Background(), "token", key)
+	if err != nil {
+		t.Fatalf("downloadAndDecryptCDNBuffer() error = %v", err)
+	}
+	if !bytes.Equal(got, plaintext) {
+		t.Fatalf("downloadAndDecryptCDNBuffer() = %q, want %q", got, plaintext)
+	}
+}
+
+func TestUploadBufferToCDN(t *testing.T) {
+	key := []byte("1234567890abcdef")
+	plaintext := []byte("upload me")
+	wantCipher, err := encryptAESECB(plaintext, key)
+	if err != nil {
+		t.Fatalf("encryptAESECB() error = %v", err)
+	}
+
+	ch := &WeixinChannel{
+		api: &ApiClient{
+			HttpClient: &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+				if r.URL.Path != "/upload" {
+					t.Fatalf("upload path = %q, want /upload", r.URL.Path)
+				}
+				if got := r.URL.Query().Get("encrypted_query_param"); got != "upload-param" {
+					t.Fatalf("encrypted_query_param = %q, want upload-param", got)
+				}
+				if got := r.URL.Query().Get("filekey"); got != "file-key" {
+					t.Fatalf("filekey = %q, want file-key", got)
+				}
+				body, _ := io.ReadAll(r.Body)
+				if !bytes.Equal(body, wantCipher) {
+					t.Fatalf("upload body = %x, want %x", body, wantCipher)
+				}
+				return &http.Response{
+					StatusCode: http.StatusOK,
+					Body:       io.NopCloser(bytes.NewReader(nil)),
+					Header: http.Header{
+						"X-Encrypted-Param": []string{"download-param"},
+					},
+				}, nil
+			})},
+		},
+		config: config.WeixinConfig{
+			CDNBaseURL: "https://cdn.example.com",
+		},
+		typingCache: make(map[string]typingTicketCacheEntry),
+	}
+
+	got, err := ch.uploadBufferToCDN(context.Background(), plaintext, "upload-param", "file-key", key)
+	if err != nil {
+		t.Fatalf("uploadBufferToCDN() error = %v", err)
+	}
+	if got != "download-param" {
+		t.Fatalf("uploadBufferToCDN() = %q, want download-param", got)
+	}
+}
+
+func TestLoadSaveGetUpdatesBuf(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "sync.json")
+
+	if err := saveGetUpdatesBuf(path, "cursor-123"); err != nil {
+		t.Fatalf("saveGetUpdatesBuf() error = %v", err)
+	}
+
+	got, err := loadGetUpdatesBuf(path)
+	if err != nil {
+		t.Fatalf("loadGetUpdatesBuf() error = %v", err)
+	}
+	if got != "cursor-123" {
+		t.Fatalf("loadGetUpdatesBuf() = %q, want cursor-123", got)
+	}
+}
+
+func TestBuildWeixinSyncBufPathUsesPicoclawHome(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv(config.EnvHome, home)
+
+	wxCfg := config.WeixinConfig{
+		BaseURL: "https://ilinkai.weixin.qq.com/",
+	}
+	wxCfg.SetToken("token-123")
+	got := buildWeixinSyncBufPath(wxCfg)
+	if filepath.Dir(got) != filepath.Join(home, "channels", "weixin", "sync") {
+		t.Fatalf("sync path dir = %q", filepath.Dir(got))
+	}
+}
+
+func TestSessionPauseGuard(t *testing.T) {
+	ch := &WeixinChannel{
+		typingCache: make(map[string]typingTicketCacheEntry),
+	}
+
+	ch.pauseSession("getupdates", 0, weixinSessionExpiredCode, "expired")
+
+	if err := ch.ensureSessionActive(); !errors.Is(err, basechannels.ErrSendFailed) {
+		t.Fatalf("ensureSessionActive() error = %v, want ErrSendFailed", err)
+	}
+
+	ch.pauseMu.Lock()
+	ch.pauseUntil = time.Now().Add(-time.Second)
+	ch.pauseMu.Unlock()
+
+	if err := ch.ensureSessionActive(); err != nil {
+		t.Fatalf("ensureSessionActive() after expiry error = %v, want nil", err)
+	}
+}
+
+func TestSelectInboundMediaItemFallsBackToRefMessage(t *testing.T) {
+	msg := WeixinMessage{
+		ItemList: []MessageItem{
+			{
+				Type: MessageItemTypeText,
+				TextItem: &TextItem{
+					Text: "look",
+				},
+				RefMsg: &RefMessage{
+					MessageItem: &MessageItem{
+						Type: MessageItemTypeImage,
+						ImageItem: &ImageItem{
+							Media: &CDNMedia{
+								EncryptQueryParam: "abc",
+							},
+						},
+					},
+				},
+			},
+		},
+	}
+
+	item := selectInboundMediaItem(msg)
+	if item == nil {
+		t.Fatal("selectInboundMediaItem() = nil, want ref media item")
+	}
+	if item.Type != MessageItemTypeImage {
+		t.Fatalf("selectInboundMediaItem().Type = %d, want %d", item.Type, MessageItemTypeImage)
+	}
+}
diff --git a/pkg/channels/whatsapp/whatsapp_command_test.go b/pkg/channels/whatsapp/whatsapp_command_test.go
new file mode 100644
index 000000000..2d85d74f8
--- /dev/null
+++ b/pkg/channels/whatsapp/whatsapp_command_test.go
@@ -0,0 +1,37 @@
+package whatsapp
+
+import (
+	"context"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestHandleIncomingMessage_DoesNotConsumeGenericCommandsLocally(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	ch := &WhatsAppChannel{
+		BaseChannel: channels.NewBaseChannel("whatsapp", config.WhatsAppConfig{}, messageBus, nil),
+		ctx:         context.Background(),
+	}
+
+	ch.handleIncomingMessage(map[string]any{
+		"type":    "message",
+		"id":      "mid1",
+		"from":    "user1",
+		"chat":    "chat1",
+		"content": "/help",
+	})
+
+	inbound, ok := <-messageBus.InboundChan()
+	if !ok {
+		t.Fatal("expected inbound message to be forwarded")
+	}
+	if inbound.Channel != "whatsapp" {
+		t.Fatalf("channel=%q", inbound.Channel)
+	}
+	if inbound.Content != "/help" {
+		t.Fatalf("content=%q", inbound.Content)
+	}
+}
diff --git a/pkg/channels/whatsapp_native/whatsapp_command_test.go b/pkg/channels/whatsapp_native/whatsapp_command_test.go
new file mode 100644
index 000000000..e51bec392
--- /dev/null
+++ b/pkg/channels/whatsapp_native/whatsapp_command_test.go
@@ -0,0 +1,61 @@
+//go:build whatsapp_native
+
+package whatsapp
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"go.mau.fi/whatsmeow/proto/waE2E"
+	"go.mau.fi/whatsmeow/types"
+	"go.mau.fi/whatsmeow/types/events"
+	"google.golang.org/protobuf/proto"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestHandleIncoming_DoesNotConsumeGenericCommandsLocally(t *testing.T) {
+	messageBus := bus.NewMessageBus()
+	ch := &WhatsAppNativeChannel{
+		BaseChannel: channels.NewBaseChannel("whatsapp_native", config.WhatsAppConfig{}, messageBus, nil),
+		runCtx:      context.Background(),
+	}
+
+	evt := &events.Message{
+		Info: types.MessageInfo{
+			MessageSource: types.MessageSource{
+				Sender: types.NewJID("1001", types.DefaultUserServer),
+				Chat:   types.NewJID("1001", types.DefaultUserServer),
+			},
+			ID:       "mid1",
+			PushName: "Alice",
+		},
+		Message: &waE2E.Message{
+			Conversation: proto.String("/new"),
+		},
+	}
+
+	ch.handleIncoming(evt)
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+
+	select {
+	case <-ctx.Done():
+		t.Fatal("timeout waiting for message to be forwarded")
+		return
+	case inbound, ok := <-messageBus.InboundChan():
+		if !ok {
+			t.Fatal("expected inbound message to be forwarded")
+		}
+		if inbound.Channel != "whatsapp_native" {
+			t.Fatalf("channel=%q", inbound.Channel)
+		}
+		if inbound.Content != "/new" {
+			t.Fatalf("content=%q", inbound.Content)
+		}
+	}
+}
diff --git a/pkg/commands/builtin.go b/pkg/commands/builtin.go
new file mode 100644
index 000000000..39e76f752
--- /dev/null
+++ b/pkg/commands/builtin.go
@@ -0,0 +1,20 @@
+package commands
+
+// BuiltinDefinitions returns all built-in command definitions.
+// Each command group is defined in its own cmd_*.go file.
+// Definitions are stateless — runtime dependencies are provided
+// via the Runtime parameter passed to handlers at execution time.
+func BuiltinDefinitions() []Definition {
+	return []Definition{
+		startCommand(),
+		helpCommand(),
+		showCommand(),
+		listCommand(),
+		useCommand(),
+		switchCommand(),
+		checkCommand(),
+		clearCommand(),
+		subagentsCommand(),
+		reloadCommand(),
+	}
+}
diff --git a/pkg/commands/builtin_test.go b/pkg/commands/builtin_test.go
new file mode 100644
index 000000000..5fd8dd9bc
--- /dev/null
+++ b/pkg/commands/builtin_test.go
@@ -0,0 +1,190 @@
+package commands
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+func findDefinitionByName(t *testing.T, defs []Definition, name string) Definition {
+	t.Helper()
+	for _, def := range defs {
+		if def.Name == name {
+			return def
+		}
+	}
+	t.Fatalf("missing /%s definition", name)
+	return Definition{}
+}
+
+func TestBuiltinHelpHandler_ReturnsFormattedMessage(t *testing.T) {
+	defs := BuiltinDefinitions()
+	helpDef := findDefinitionByName(t, defs, "help")
+	if helpDef.Handler == nil {
+		t.Fatalf("/help handler should not be nil")
+	}
+
+	var reply string
+	err := helpDef.Handler(context.Background(), Request{
+		Text: "/help",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	}, nil)
+	if err != nil {
+		t.Fatalf("/help handler error: %v", err)
+	}
+	// Now uses auto-generated EffectiveUsage which includes agents
+	if !strings.Contains(reply, "/show [model|channel|agents]") {
+		t.Fatalf("/help reply missing /show usage, got %q", reply)
+	}
+	if !strings.Contains(reply, "/list [models|channels|agents|skills]") {
+		t.Fatalf("/help reply missing /list usage, got %q", reply)
+	}
+	if !strings.Contains(reply, "/use <skill> <message>") {
+		if !strings.Contains(reply, "/use <skill> [message]") {
+			t.Fatalf("/help reply missing /use usage, got %q", reply)
+		}
+	}
+}
+
+func TestBuiltinShowChannel_PreservesUserVisibleBehavior(t *testing.T) {
+	defs := BuiltinDefinitions()
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	cases := []string{"telegram", "whatsapp"}
+	for _, channel := range cases {
+		var reply string
+		res := ex.Execute(context.Background(), Request{
+			Channel: channel,
+			Text:    "/show channel",
+			Reply: func(text string) error {
+				reply = text
+				return nil
+			},
+		})
+		if res.Outcome != OutcomeHandled {
+			t.Fatalf("/show channel on %s: outcome=%v, want=%v", channel, res.Outcome, OutcomeHandled)
+		}
+		want := "Current Channel: " + channel
+		if reply != want {
+			t.Fatalf("/show channel reply=%q, want=%q", reply, want)
+		}
+	}
+}
+
+func TestBuiltinListChannels_UsesGetEnabledChannels(t *testing.T) {
+	rt := &Runtime{
+		GetEnabledChannels: func() []string {
+			return []string{"telegram", "slack"}
+		},
+	}
+	defs := BuiltinDefinitions()
+	ex := NewExecutor(NewRegistry(defs), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/list channels",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("/list channels: outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if !strings.Contains(reply, "telegram") || !strings.Contains(reply, "slack") {
+		t.Fatalf("/list channels reply=%q, want telegram and slack", reply)
+	}
+}
+
+func TestBuiltinShowAgents_RestoresOldBehavior(t *testing.T) {
+	rt := &Runtime{
+		ListAgentIDs: func() []string {
+			return []string{"default", "coder"}
+		},
+	}
+	defs := BuiltinDefinitions()
+	ex := NewExecutor(NewRegistry(defs), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/show agents",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("/show agents: outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if !strings.Contains(reply, "default") || !strings.Contains(reply, "coder") {
+		t.Fatalf("/show agents reply=%q, want agent IDs", reply)
+	}
+}
+
+func TestBuiltinListAgents_RestoresOldBehavior(t *testing.T) {
+	rt := &Runtime{
+		ListAgentIDs: func() []string {
+			return []string{"default", "coder"}
+		},
+	}
+	defs := BuiltinDefinitions()
+	ex := NewExecutor(NewRegistry(defs), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/list agents",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("/list agents: outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if !strings.Contains(reply, "default") || !strings.Contains(reply, "coder") {
+		t.Fatalf("/list agents reply=%q, want agent IDs", reply)
+	}
+}
+
+func TestBuiltinListSkills_UsesRuntimeSkillNames(t *testing.T) {
+	rt := &Runtime{
+		ListSkillNames: func() []string {
+			return []string{"shell", "git"}
+		},
+	}
+	defs := BuiltinDefinitions()
+	ex := NewExecutor(NewRegistry(defs), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/list skills",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("/list skills: outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if !strings.Contains(reply, "shell") || !strings.Contains(reply, "git") {
+		t.Fatalf("/list skills reply=%q, want installed skill names", reply)
+	}
+}
+
+func TestBuiltinUseCommand_PassthroughsToAgentLogic(t *testing.T) {
+	defs := BuiltinDefinitions()
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	res := ex.Execute(context.Background(), Request{
+		Text: "/use shell run ls",
+	})
+	if res.Outcome != OutcomePassthrough {
+		t.Fatalf("/use outcome=%v, want=%v", res.Outcome, OutcomePassthrough)
+	}
+	if res.Command != "use" {
+		t.Fatalf("/use command=%q, want=%q", res.Command, "use")
+	}
+}
diff --git a/pkg/commands/cmd_check.go b/pkg/commands/cmd_check.go
new file mode 100644
index 000000000..f0193dc4f
--- /dev/null
+++ b/pkg/commands/cmd_check.go
@@ -0,0 +1,33 @@
+package commands
+
+import (
+	"context"
+	"fmt"
+)
+
+func checkCommand() Definition {
+	return Definition{
+		Name:        "check",
+		Description: "Check channel availability",
+		SubCommands: []SubCommand{
+			{
+				Name:        "channel",
+				Description: "Check if a channel is available",
+				ArgsUsage:   "<name>",
+				Handler: func(_ context.Context, req Request, rt *Runtime) error {
+					if rt == nil || rt.SwitchChannel == nil {
+						return req.Reply(unavailableMsg)
+					}
+					value := nthToken(req.Text, 2)
+					if value == "" {
+						return req.Reply("Usage: /check channel <name>")
+					}
+					if err := rt.SwitchChannel(value); err != nil {
+						return req.Reply(err.Error())
+					}
+					return req.Reply(fmt.Sprintf("Channel '%s' is available and enabled", value))
+				},
+			},
+		},
+	}
+}
diff --git a/pkg/commands/cmd_clear.go b/pkg/commands/cmd_clear.go
new file mode 100644
index 000000000..f0951eb3b
--- /dev/null
+++ b/pkg/commands/cmd_clear.go
@@ -0,0 +1,20 @@
+package commands
+
+import "context"
+
+func clearCommand() Definition {
+	return Definition{
+		Name:        "clear",
+		Description: "Clear the chat history",
+		Usage:       "/clear",
+		Handler: func(_ context.Context, req Request, rt *Runtime) error {
+			if rt == nil || rt.ClearHistory == nil {
+				return req.Reply(unavailableMsg)
+			}
+			if err := rt.ClearHistory(); err != nil {
+				return req.Reply("Failed to clear chat history: " + err.Error())
+			}
+			return req.Reply("Chat history cleared!")
+		},
+	}
+}
diff --git a/pkg/commands/cmd_help.go b/pkg/commands/cmd_help.go
new file mode 100644
index 000000000..94f7f0101
--- /dev/null
+++ b/pkg/commands/cmd_help.go
@@ -0,0 +1,44 @@
+package commands
+
+import (
+	"context"
+	"fmt"
+	"strings"
+)
+
+func helpCommand() Definition {
+	return Definition{
+		Name:        "help",
+		Description: "Show this help message",
+		Usage:       "/help",
+		Handler: func(_ context.Context, req Request, rt *Runtime) error {
+			var defs []Definition
+			if rt != nil && rt.ListDefinitions != nil {
+				defs = rt.ListDefinitions()
+			} else {
+				defs = BuiltinDefinitions()
+			}
+			return req.Reply(formatHelpMessage(defs))
+		},
+	}
+}
+
+func formatHelpMessage(defs []Definition) string {
+	if len(defs) == 0 {
+		return "No commands available."
+	}
+
+	lines := make([]string, 0, len(defs))
+	for _, def := range defs {
+		usage := def.EffectiveUsage()
+		if usage == "" {
+			usage = "/" + def.Name
+		}
+		desc := def.Description
+		if desc == "" {
+			desc = "No description"
+		}
+		lines = append(lines, fmt.Sprintf("%s - %s", usage, desc))
+	}
+	return strings.Join(lines, "\n")
+}
diff --git a/pkg/commands/cmd_list.go b/pkg/commands/cmd_list.go
new file mode 100644
index 000000000..7186a6c25
--- /dev/null
+++ b/pkg/commands/cmd_list.go
@@ -0,0 +1,69 @@
+package commands
+
+import (
+	"context"
+	"fmt"
+	"strings"
+)
+
+func listCommand() Definition {
+	return Definition{
+		Name:        "list",
+		Description: "List available options",
+		SubCommands: []SubCommand{
+			{
+				Name:        "models",
+				Description: "Configured models",
+				Handler: func(_ context.Context, req Request, rt *Runtime) error {
+					if rt == nil || rt.GetModelInfo == nil {
+						return req.Reply(unavailableMsg)
+					}
+					name, provider := rt.GetModelInfo()
+					if provider == "" {
+						provider = "configured default"
+					}
+					return req.Reply(fmt.Sprintf(
+						"Configured Model: %s\nProvider: %s\n\nTo change models, update config.json",
+						name, provider,
+					))
+				},
+			},
+			{
+				Name:        "channels",
+				Description: "Enabled channels",
+				Handler: func(_ context.Context, req Request, rt *Runtime) error {
+					if rt == nil || rt.GetEnabledChannels == nil {
+						return req.Reply(unavailableMsg)
+					}
+					enabled := rt.GetEnabledChannels()
+					if len(enabled) == 0 {
+						return req.Reply("No channels enabled")
+					}
+					return req.Reply(fmt.Sprintf("Enabled Channels:\n- %s", strings.Join(enabled, "\n- ")))
+				},
+			},
+			{
+				Name:        "agents",
+				Description: "Registered agents",
+				Handler:     agentsHandler(),
+			},
+			{
+				Name:        "skills",
+				Description: "Installed skills",
+				Handler: func(_ context.Context, req Request, rt *Runtime) error {
+					if rt == nil || rt.ListSkillNames == nil {
+						return req.Reply(unavailableMsg)
+					}
+					names := rt.ListSkillNames()
+					if len(names) == 0 {
+						return req.Reply("No installed skills")
+					}
+					return req.Reply(fmt.Sprintf(
+						"Installed Skills:\n- %s\n\nUse /use <skill> <message> to force one for a single request, or /use <skill> to apply it to your next message.",
+						strings.Join(names, "\n- "),
+					))
+				},
+			},
+		},
+	}
+}
diff --git a/pkg/commands/cmd_reload.go b/pkg/commands/cmd_reload.go
new file mode 100644
index 000000000..07ab44016
--- /dev/null
+++ b/pkg/commands/cmd_reload.go
@@ -0,0 +1,20 @@
+package commands
+
+import "context"
+
+func reloadCommand() Definition {
+	return Definition{
+		Name:        "reload",
+		Description: "Reload the configuration file",
+		Usage:       "/reload",
+		Handler: func(_ context.Context, req Request, rt *Runtime) error {
+			if rt == nil || rt.ReloadConfig == nil {
+				return req.Reply(unavailableMsg)
+			}
+			if err := rt.ReloadConfig(); err != nil {
+				return req.Reply("Failed to reload configuration: " + err.Error())
+			}
+			return req.Reply("Config reload triggered!")
+		},
+	}
+}
diff --git a/pkg/commands/cmd_show.go b/pkg/commands/cmd_show.go
new file mode 100644
index 000000000..c655e6880
--- /dev/null
+++ b/pkg/commands/cmd_show.go
@@ -0,0 +1,38 @@
+package commands
+
+import (
+	"context"
+	"fmt"
+)
+
+func showCommand() Definition {
+	return Definition{
+		Name:        "show",
+		Description: "Show current configuration",
+		SubCommands: []SubCommand{
+			{
+				Name:        "model",
+				Description: "Current model and provider",
+				Handler: func(_ context.Context, req Request, rt *Runtime) error {
+					if rt == nil || rt.GetModelInfo == nil {
+						return req.Reply(unavailableMsg)
+					}
+					name, provider := rt.GetModelInfo()
+					return req.Reply(fmt.Sprintf("Current Model: %s (Provider: %s)", name, provider))
+				},
+			},
+			{
+				Name:        "channel",
+				Description: "Current channel",
+				Handler: func(_ context.Context, req Request, _ *Runtime) error {
+					return req.Reply(fmt.Sprintf("Current Channel: %s", req.Channel))
+				},
+			},
+			{
+				Name:        "agents",
+				Description: "Registered agents",
+				Handler:     agentsHandler(),
+			},
+		},
+	}
+}
diff --git a/pkg/commands/cmd_start.go b/pkg/commands/cmd_start.go
new file mode 100644
index 000000000..8b500aa10
--- /dev/null
+++ b/pkg/commands/cmd_start.go
@@ -0,0 +1,14 @@
+package commands
+
+import "context"
+
+func startCommand() Definition {
+	return Definition{
+		Name:        "start",
+		Description: "Start the bot",
+		Usage:       "/start",
+		Handler: func(_ context.Context, req Request, _ *Runtime) error {
+			return req.Reply("Hello! I am PicoClaw 🦞")
+		},
+	}
+}
diff --git a/pkg/commands/cmd_subagents.go b/pkg/commands/cmd_subagents.go
new file mode 100644
index 000000000..29321823c
--- /dev/null
+++ b/pkg/commands/cmd_subagents.go
@@ -0,0 +1,42 @@
+package commands
+
+import (
+	"context"
+	"fmt"
+)
+
+// TurnInfo is a mirrored struct from agent.TurnInfo to avoid circular dependencies.
+type TurnInfo struct {
+	TurnID       string
+	ParentTurnID string
+	Depth        int
+	ChildTurnIDs []string
+	IsFinished   bool
+}
+
+func subagentsCommand() Definition {
+	return Definition{
+		Name:        "subagents",
+		Description: "Show running subagents and task tree",
+		Handler: func(ctx context.Context, req Request, rt *Runtime) error {
+			getTurnFn := rt.GetActiveTurn
+			if getTurnFn == nil {
+				return req.Reply("Runtime does not support querying active turns.")
+			}
+
+			turnRaw := getTurnFn()
+			if turnRaw == nil {
+				return req.Reply("No active tasks running in this session.")
+			}
+
+			if treeStr, ok := turnRaw.(string); ok {
+				if treeStr == "" {
+					return req.Reply("No active tasks running in this session.")
+				}
+				return req.Reply(fmt.Sprintf("🤖 **Active Subagents Tree**\n```text\n%s\n```", treeStr))
+			}
+
+			return req.Reply(fmt.Sprintf("🤖 **Active Subagents List**\n```text\n%+v\n```", turnRaw))
+		},
+	}
+}
diff --git a/pkg/commands/cmd_switch.go b/pkg/commands/cmd_switch.go
new file mode 100644
index 000000000..fb8fc109e
--- /dev/null
+++ b/pkg/commands/cmd_switch.go
@@ -0,0 +1,42 @@
+package commands
+
+import (
+	"context"
+	"fmt"
+)
+
+func switchCommand() Definition {
+	return Definition{
+		Name:        "switch",
+		Description: "Switch model",
+		SubCommands: []SubCommand{
+			{
+				Name:        "model",
+				Description: "Switch to a different model",
+				ArgsUsage:   "to <name>",
+				Handler: func(_ context.Context, req Request, rt *Runtime) error {
+					if rt == nil || rt.SwitchModel == nil {
+						return req.Reply(unavailableMsg)
+					}
+					// Parse: /switch model to <value>
+					value := nthToken(req.Text, 3) // tokens: [/switch, model, to, <value>]
+					if nthToken(req.Text, 2) != "to" || value == "" {
+						return req.Reply("Usage: /switch model to <name>")
+					}
+					oldModel, err := rt.SwitchModel(value)
+					if err != nil {
+						return req.Reply(err.Error())
+					}
+					return req.Reply(fmt.Sprintf("Switched model from %s to %s", oldModel, value))
+				},
+			},
+			{
+				Name:        "channel",
+				Description: "Moved to /check channel",
+				Handler: func(_ context.Context, req Request, _ *Runtime) error {
+					return req.Reply("This command has moved. Please use: /check channel <name>")
+				},
+			},
+		},
+	}
+}
diff --git a/pkg/commands/cmd_switch_test.go b/pkg/commands/cmd_switch_test.go
new file mode 100644
index 000000000..59ed305bb
--- /dev/null
+++ b/pkg/commands/cmd_switch_test.go
@@ -0,0 +1,279 @@
+package commands
+
+import (
+	"context"
+	"fmt"
+	"testing"
+)
+
+func TestSwitchModel_Success(t *testing.T) {
+	rt := &Runtime{
+		SwitchModel: func(value string) (string, error) {
+			return "old-model", nil
+		},
+	}
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/switch model to gpt-4",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	want := "Switched model from old-model to gpt-4"
+	if reply != want {
+		t.Fatalf("reply=%q, want=%q", reply, want)
+	}
+}
+
+func TestSwitchModel_MissingToKeyword(t *testing.T) {
+	rt := &Runtime{
+		SwitchModel: func(value string) (string, error) {
+			return "old", nil
+		},
+	}
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/switch model gpt-4",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if reply != "Usage: /switch model to <name>" {
+		t.Fatalf("reply=%q, want usage message", reply)
+	}
+}
+
+func TestSwitchModel_MissingValue(t *testing.T) {
+	rt := &Runtime{
+		SwitchModel: func(value string) (string, error) {
+			return "old", nil
+		},
+	}
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/switch model to",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if reply != "Usage: /switch model to <name>" {
+		t.Fatalf("reply=%q, want usage message", reply)
+	}
+}
+
+func TestSwitchModel_Error(t *testing.T) {
+	rt := &Runtime{
+		SwitchModel: func(value string) (string, error) {
+			return "", fmt.Errorf("model not found")
+		},
+	}
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/switch model to bad-model",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if reply != "model not found" {
+		t.Fatalf("reply=%q, want error message", reply)
+	}
+}
+
+func TestSwitchModel_NilDep(t *testing.T) {
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), &Runtime{})
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/switch model to gpt-4",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if reply != "Command unavailable in current context." {
+		t.Fatalf("reply=%q, want unavailable message", reply)
+	}
+}
+
+func TestSwitchChannel_Redirect(t *testing.T) {
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), &Runtime{})
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/switch channel to telegram",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	want := "This command has moved. Please use: /check channel <name>"
+	if reply != want {
+		t.Fatalf("reply=%q, want=%q", reply, want)
+	}
+}
+
+func TestCheckChannel_Success(t *testing.T) {
+	rt := &Runtime{
+		SwitchChannel: func(value string) error {
+			return nil
+		},
+	}
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/check channel telegram",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	want := "Channel 'telegram' is available and enabled"
+	if reply != want {
+		t.Fatalf("reply=%q, want=%q", reply, want)
+	}
+}
+
+func TestCheckChannel_Error(t *testing.T) {
+	rt := &Runtime{
+		SwitchChannel: func(value string) error {
+			return fmt.Errorf("channel '%s' not found", value)
+		},
+	}
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/check channel unknown",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if reply != "channel 'unknown' not found" {
+		t.Fatalf("reply=%q, want error message", reply)
+	}
+}
+
+func TestCheckChannel_NilDep(t *testing.T) {
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), &Runtime{})
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/check channel telegram",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if reply != "Command unavailable in current context." {
+		t.Fatalf("reply=%q, want unavailable message", reply)
+	}
+}
+
+func TestCheckChannel_MissingValue(t *testing.T) {
+	rt := &Runtime{
+		SwitchChannel: func(value string) error {
+			return nil
+		},
+	}
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/check channel",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if reply != "Usage: /check channel <name>" {
+		t.Fatalf("reply=%q, want usage message", reply)
+	}
+}
+
+func TestSwitch_BangPrefix(t *testing.T) {
+	rt := &Runtime{
+		SwitchModel: func(value string) (string, error) {
+			return "old", nil
+		},
+	}
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "!switch model to gpt-4",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("! prefix: outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if reply != "Switched model from old to gpt-4" {
+		t.Fatalf("! prefix: reply=%q, want success message", reply)
+	}
+}
+
+func TestSwitch_NoSubCommand(t *testing.T) {
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), &Runtime{})
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text: "/switch",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	// Should get usage message from executor's sub-command routing
+	if reply == "" {
+		t.Fatal("expected usage reply for bare /switch")
+	}
+}
diff --git a/pkg/commands/cmd_use.go b/pkg/commands/cmd_use.go
new file mode 100644
index 000000000..4698f5f5e
--- /dev/null
+++ b/pkg/commands/cmd_use.go
@@ -0,0 +1,9 @@
+package commands
+
+func useCommand() Definition {
+	return Definition{
+		Name:        "use",
+		Description: "Force a specific installed skill for one request",
+		Usage:       "/use <skill> [message]",
+	}
+}
diff --git a/pkg/commands/definition.go b/pkg/commands/definition.go
new file mode 100644
index 000000000..7309df317
--- /dev/null
+++ b/pkg/commands/definition.go
@@ -0,0 +1,48 @@
+package commands
+
+import (
+	"fmt"
+	"strings"
+)
+
+// SubCommand defines a single sub-command within a parent command.
+type SubCommand struct {
+	Name        string
+	Description string
+	ArgsUsage   string // optional, e.g. "<session-id>"
+	Handler     Handler
+}
+
+// Definition is the single-source metadata and behavior contract for a slash command.
+//
+// Design notes (phase 1):
+//   - Every channel reads command shape from this type instead of keeping local copies.
+//   - Visibility is global: all definitions are considered available to all channels.
+//   - Platform menu registration (for example Telegram BotCommand) also derives from this
+//     same definition so UI labels and runtime behavior stay aligned.
+type Definition struct {
+	Name        string
+	Description string
+	Usage       string // for simple commands; ignored when SubCommands is set
+	Aliases     []string
+	SubCommands []SubCommand // optional; when set, Executor routes to sub-command handlers
+	Handler     Handler      // for simple commands without sub-commands
+}
+
+// EffectiveUsage returns the usage string. When SubCommands are present,
+// it is auto-generated from sub-command names so metadata and behavior
+// cannot drift.
+func (d Definition) EffectiveUsage() string {
+	if len(d.SubCommands) == 0 {
+		return d.Usage
+	}
+	names := make([]string, 0, len(d.SubCommands))
+	for _, sc := range d.SubCommands {
+		name := sc.Name
+		if sc.ArgsUsage != "" {
+			name += " " + sc.ArgsUsage
+		}
+		names = append(names, name)
+	}
+	return fmt.Sprintf("/%s [%s]", d.Name, strings.Join(names, "|"))
+}
diff --git a/pkg/commands/definition_test.go b/pkg/commands/definition_test.go
new file mode 100644
index 000000000..27ad4a0a2
--- /dev/null
+++ b/pkg/commands/definition_test.go
@@ -0,0 +1,41 @@
+package commands
+
+import (
+	"testing"
+)
+
+func TestDefinition_EffectiveUsage_NoSubCommands(t *testing.T) {
+	d := Definition{Name: "start", Usage: "/start"}
+	if got := d.EffectiveUsage(); got != "/start" {
+		t.Fatalf("EffectiveUsage()=%q, want %q", got, "/start")
+	}
+}
+
+func TestDefinition_EffectiveUsage_WithSubCommands(t *testing.T) {
+	d := Definition{
+		Name: "show",
+		SubCommands: []SubCommand{
+			{Name: "model"},
+			{Name: "channel"},
+			{Name: "agents"},
+		},
+	}
+	want := "/show [model|channel|agents]"
+	if got := d.EffectiveUsage(); got != want {
+		t.Fatalf("EffectiveUsage()=%q, want %q", got, want)
+	}
+}
+
+func TestDefinition_EffectiveUsage_WithArgsUsage(t *testing.T) {
+	d := Definition{
+		Name: "session",
+		SubCommands: []SubCommand{
+			{Name: "list"},
+			{Name: "resume", ArgsUsage: "<id>"},
+		},
+	}
+	want := "/session [list|resume <id>]"
+	if got := d.EffectiveUsage(); got != want {
+		t.Fatalf("EffectiveUsage()=%q, want %q", got, want)
+	}
+}
diff --git a/pkg/commands/executor.go b/pkg/commands/executor.go
new file mode 100644
index 000000000..78a50e6c2
--- /dev/null
+++ b/pkg/commands/executor.go
@@ -0,0 +1,89 @@
+package commands
+
+import (
+	"context"
+	"fmt"
+)
+
+type Outcome int
+
+const (
+	// OutcomePassthrough means this input should continue through normal agent flow.
+	OutcomePassthrough Outcome = iota
+	// OutcomeHandled means a command handler executed (with or without handler error).
+	OutcomeHandled
+)
+
+type ExecuteResult struct {
+	Outcome Outcome
+	Command string
+	Err     error
+}
+
+type Executor struct {
+	reg *Registry
+	rt  *Runtime
+}
+
+func NewExecutor(reg *Registry, rt *Runtime) *Executor {
+	return &Executor{reg: reg, rt: rt}
+}
+
+// Execute implements a two-state command decision:
+// 1) handled: execute command immediately;
+// 2) passthrough: not a command or intentionally deferred to agent logic.
+func (e *Executor) Execute(ctx context.Context, req Request) ExecuteResult {
+	cmdName, ok := parseCommandName(req.Text)
+	if !ok {
+		return ExecuteResult{Outcome: OutcomePassthrough}
+	}
+
+	if e == nil || e.reg == nil {
+		return ExecuteResult{Outcome: OutcomePassthrough, Command: cmdName}
+	}
+
+	def, found := e.reg.Lookup(cmdName)
+	if !found {
+		return ExecuteResult{Outcome: OutcomePassthrough, Command: cmdName}
+	}
+
+	return e.executeDefinition(ctx, req, def)
+}
+
+func (e *Executor) executeDefinition(ctx context.Context, req Request, def Definition) ExecuteResult {
+	// Ensure Reply is always non-nil so handlers don't need to check.
+	if req.Reply == nil {
+		req.Reply = func(string) error { return nil }
+	}
+
+	// Simple command — no sub-commands
+	if len(def.SubCommands) == 0 {
+		if def.Handler == nil {
+			return ExecuteResult{Outcome: OutcomePassthrough, Command: def.Name}
+		}
+		err := def.Handler(ctx, req, e.rt)
+		return ExecuteResult{Outcome: OutcomeHandled, Command: def.Name, Err: err}
+	}
+
+	// Sub-command routing
+	subName := nthToken(req.Text, 1)
+	if subName == "" {
+		err := req.Reply("Usage: " + def.EffectiveUsage())
+		return ExecuteResult{Outcome: OutcomeHandled, Command: def.Name, Err: err}
+	}
+
+	normalized := normalizeCommandName(subName)
+	for _, sc := range def.SubCommands {
+		if normalizeCommandName(sc.Name) == normalized {
+			if sc.Handler == nil {
+				return ExecuteResult{Outcome: OutcomePassthrough, Command: def.Name}
+			}
+			err := sc.Handler(ctx, req, e.rt)
+			return ExecuteResult{Outcome: OutcomeHandled, Command: def.Name, Err: err}
+		}
+	}
+
+	// Unknown sub-command
+	err := req.Reply(fmt.Sprintf("Unknown option: %s. Usage: %s", subName, def.EffectiveUsage()))
+	return ExecuteResult{Outcome: OutcomeHandled, Command: def.Name, Err: err}
+}
diff --git a/pkg/commands/executor_test.go b/pkg/commands/executor_test.go
new file mode 100644
index 000000000..09350f1b6
--- /dev/null
+++ b/pkg/commands/executor_test.go
@@ -0,0 +1,260 @@
+package commands
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestExecutor_RegisteredWithoutHandler_ReturnsPassthrough(t *testing.T) {
+	defs := []Definition{{Name: "show"}}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	res := ex.Execute(context.Background(), Request{Channel: "whatsapp", Text: "/show"})
+	if res.Outcome != OutcomePassthrough {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomePassthrough)
+	}
+}
+
+func TestExecutor_UnknownSlashCommand_ReturnsPassthrough(t *testing.T) {
+	defs := []Definition{{Name: "show"}}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	res := ex.Execute(context.Background(), Request{Channel: "telegram", Text: "/unknown"})
+	if res.Outcome != OutcomePassthrough {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomePassthrough)
+	}
+}
+
+func TestExecutor_SupportedCommandWithHandler_ReturnsHandled(t *testing.T) {
+	called := false
+	defs := []Definition{
+		{
+			Name: "help",
+			Handler: func(context.Context, Request, *Runtime) error {
+				called = true
+				return nil
+			},
+		},
+	}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	res := ex.Execute(context.Background(), Request{Channel: "telegram", Text: "/help@my_bot"})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if !called {
+		t.Fatalf("expected handler to be called")
+	}
+}
+
+func TestExecutor_AliasWithoutHandler_ReturnsPassthrough(t *testing.T) {
+	defs := []Definition{
+		{
+			Name:    "show",
+			Aliases: []string{"display"},
+		},
+	}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	res := ex.Execute(context.Background(), Request{Channel: "whatsapp", Text: "/display"})
+	if res.Outcome != OutcomePassthrough {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomePassthrough)
+	}
+	if res.Command != "show" {
+		t.Fatalf("command=%q, want=%q", res.Command, "show")
+	}
+}
+
+func TestExecutor_AliasWithHandler_ReturnsHandled(t *testing.T) {
+	called := false
+	defs := []Definition{
+		{
+			Name:    "clear",
+			Aliases: []string{"reset"},
+			Handler: func(context.Context, Request, *Runtime) error {
+				called = true
+				return nil
+			},
+		},
+	}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	res := ex.Execute(context.Background(), Request{Channel: "telegram", Text: "/reset"})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if res.Command != "clear" {
+		t.Fatalf("command=%q, want=%q", res.Command, "clear")
+	}
+	if !called {
+		t.Fatalf("expected handler to be called")
+	}
+}
+
+func TestExecutor_SupportedCommandWithNilHandler_ReturnsPassthrough(t *testing.T) {
+	defs := []Definition{
+		{Name: "placeholder"},
+	}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	res := ex.Execute(context.Background(), Request{Channel: "telegram", Text: "/placeholder list"})
+	if res.Outcome != OutcomePassthrough {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomePassthrough)
+	}
+	if res.Command != "placeholder" {
+		t.Fatalf("command=%q, want=%q", res.Command, "placeholder")
+	}
+}
+
+func TestExecutor_NilHandlerDoesNotMaskLaterHandler(t *testing.T) {
+	// With Lookup-based dispatch, the first registered definition for a name wins.
+	// A definition with nil Handler and no SubCommands returns Passthrough.
+	defs := []Definition{
+		{Name: "placeholder"},
+	}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	res := ex.Execute(context.Background(), Request{Channel: "telegram", Text: "/placeholder"})
+	if res.Outcome != OutcomePassthrough {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomePassthrough)
+	}
+	if res.Command != "placeholder" {
+		t.Fatalf("command=%q, want=%q", res.Command, "placeholder")
+	}
+}
+
+func TestExecutor_HandlerErrorIsPropagated(t *testing.T) {
+	wantErr := errors.New("handler failed")
+	defs := []Definition{
+		{
+			Name: "help",
+			Handler: func(context.Context, Request, *Runtime) error {
+				return wantErr
+			},
+		},
+	}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	res := ex.Execute(context.Background(), Request{Channel: "telegram", Text: "/help"})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if !errors.Is(res.Err, wantErr) {
+		t.Fatalf("err=%v, want=%v", res.Err, wantErr)
+	}
+}
+
+func TestExecutor_SupportsBangPrefixAndCaseInsensitiveCommand(t *testing.T) {
+	called := false
+	defs := []Definition{
+		{
+			Name: "help",
+			Handler: func(context.Context, Request, *Runtime) error {
+				called = true
+				return nil
+			},
+		},
+	}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	res := ex.Execute(context.Background(), Request{Channel: "telegram", Text: "!HELP"})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if !called {
+		t.Fatalf("expected handler to be called")
+	}
+}
+
+func TestExecutor_SubCommand_RoutesToCorrectHandler(t *testing.T) {
+	modelCalled := false
+	defs := []Definition{
+		{
+			Name: "show",
+			SubCommands: []SubCommand{
+				{Name: "model", Handler: func(_ context.Context, _ Request, _ *Runtime) error {
+					modelCalled = true
+					return nil
+				}},
+				{Name: "channel"},
+			},
+		},
+	}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	res := ex.Execute(context.Background(), Request{Text: "/show model"})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if !modelCalled {
+		t.Fatal("model sub-command handler was not called")
+	}
+}
+
+func TestExecutor_SubCommand_NoArg_RepliesUsage(t *testing.T) {
+	defs := []Definition{
+		{
+			Name: "show",
+			SubCommands: []SubCommand{
+				{Name: "model"},
+				{Name: "channel"},
+			},
+		},
+	}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text:  "/show",
+		Reply: func(text string) error { reply = text; return nil },
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if reply != "Usage: /show [model|channel]" {
+		t.Fatalf("reply=%q, want usage message", reply)
+	}
+}
+
+func TestExecutor_SubCommand_UnknownArg_RepliesError(t *testing.T) {
+	defs := []Definition{
+		{
+			Name: "show",
+			SubCommands: []SubCommand{
+				{Name: "model"},
+			},
+		},
+	}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Text:  "/show foobar",
+		Reply: func(text string) error { reply = text; return nil },
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if !strings.Contains(reply, "foobar") {
+		t.Fatalf("reply=%q, should mention unknown sub-command", reply)
+	}
+}
+
+func TestExecutor_SubCommand_NilHandler_ReturnsPassthrough(t *testing.T) {
+	defs := []Definition{
+		{
+			Name: "show",
+			SubCommands: []SubCommand{
+				{Name: "model"}, // nil Handler
+			},
+		},
+	}
+	ex := NewExecutor(NewRegistry(defs), nil)
+
+	res := ex.Execute(context.Background(), Request{Text: "/show model"})
+	if res.Outcome != OutcomePassthrough {
+		t.Fatalf("outcome=%v, want=%v", res.Outcome, OutcomePassthrough)
+	}
+}
diff --git a/pkg/commands/handler_agents.go b/pkg/commands/handler_agents.go
new file mode 100644
index 000000000..c459516eb
--- /dev/null
+++ b/pkg/commands/handler_agents.go
@@ -0,0 +1,21 @@
+package commands
+
+import (
+	"context"
+	"fmt"
+	"strings"
+)
+
+// agentsHandler returns a shared handler for both /show agents and /list agents.
+func agentsHandler() Handler {
+	return func(_ context.Context, req Request, rt *Runtime) error {
+		if rt == nil || rt.ListAgentIDs == nil {
+			return req.Reply(unavailableMsg)
+		}
+		ids := rt.ListAgentIDs()
+		if len(ids) == 0 {
+			return req.Reply("No agents registered")
+		}
+		return req.Reply(fmt.Sprintf("Registered agents: %s", strings.Join(ids, ", ")))
+	}
+}
diff --git a/pkg/commands/registry.go b/pkg/commands/registry.go
new file mode 100644
index 000000000..e17d489a6
--- /dev/null
+++ b/pkg/commands/registry.go
@@ -0,0 +1,55 @@
+package commands
+
+type Registry struct {
+	defs  []Definition
+	index map[string]int
+}
+
+// NewRegistry stores the canonical command set used by both dispatch and
+// optional platform registration adapters.
+func NewRegistry(defs []Definition) *Registry {
+	stored := make([]Definition, len(defs))
+	copy(stored, defs)
+
+	index := make(map[string]int, len(stored)*2)
+	for i, def := range stored {
+		registerCommandName(index, def.Name, i)
+		for _, alias := range def.Aliases {
+			registerCommandName(index, alias, i)
+		}
+	}
+
+	return &Registry{defs: stored, index: index}
+}
+
+// Definitions returns all registered command definitions.
+// Command availability is global and no longer channel-scoped.
+func (r *Registry) Definitions() []Definition {
+	out := make([]Definition, len(r.defs))
+	copy(out, r.defs)
+	return out
+}
+
+// Lookup returns a command definition by normalized command name or alias.
+func (r *Registry) Lookup(name string) (Definition, bool) {
+	key := normalizeCommandName(name)
+	if key == "" {
+		return Definition{}, false
+	}
+	idx, ok := r.index[key]
+	if !ok {
+		return Definition{}, false
+	}
+	return r.defs[idx], true
+}
+
+func registerCommandName(index map[string]int, name string, defIndex int) {
+	key := normalizeCommandName(name)
+	if key == "" {
+		return
+	}
+	if _, exists := index[key]; exists {
+		return
+	}
+	index[key] = defIndex
+}
diff --git a/pkg/commands/registry_test.go b/pkg/commands/registry_test.go
new file mode 100644
index 000000000..bfff76b7c
--- /dev/null
+++ b/pkg/commands/registry_test.go
@@ -0,0 +1,49 @@
+package commands
+
+import "testing"
+
+func TestRegistry_Definitions_ReturnsCopy(t *testing.T) {
+	defs := []Definition{
+		{Name: "help", Description: "Show help"},
+		{Name: "admin", Description: "Admin command"},
+	}
+	r := NewRegistry(defs)
+
+	got := r.Definitions()
+	if len(got) != 2 {
+		t.Fatalf("definitions len = %d, want 2", len(got))
+	}
+
+	got[0].Name = "mutated"
+	again := r.Definitions()
+	if again[0].Name != "help" {
+		t.Fatalf("registry should not be mutated by caller, got first name %q", again[0].Name)
+	}
+}
+
+func TestRegistry_Lookup_MatchesByLowercaseNameAndAlias(t *testing.T) {
+	r := NewRegistry([]Definition{
+		{Name: "Help", Aliases: []string{"Assist"}},
+		{Name: "List"},
+	})
+
+	def, ok := r.Lookup("help")
+	if !ok || def.Name != "Help" {
+		t.Fatalf("lookup by lowercase name failed: ok=%v def=%+v", ok, def)
+	}
+
+	def, ok = r.Lookup("HELP")
+	if !ok || def.Name != "Help" {
+		t.Fatalf("lookup by uppercase name failed: ok=%v def=%+v", ok, def)
+	}
+
+	def, ok = r.Lookup("assist")
+	if !ok || def.Name != "Help" {
+		t.Fatalf("lookup by lowercase alias failed: ok=%v def=%+v", ok, def)
+	}
+
+	def, ok = r.Lookup("ASSIST")
+	if !ok || def.Name != "Help" {
+		t.Fatalf("lookup by uppercase alias failed: ok=%v def=%+v", ok, def)
+	}
+}
diff --git a/pkg/commands/request.go b/pkg/commands/request.go
new file mode 100644
index 000000000..233b3ef9c
--- /dev/null
+++ b/pkg/commands/request.go
@@ -0,0 +1,80 @@
+package commands
+
+import (
+	"context"
+	"strings"
+)
+
+type Handler func(ctx context.Context, req Request, rt *Runtime) error
+
+type Request struct {
+	Channel  string
+	ChatID   string
+	SenderID string
+	Text     string
+	Reply    func(text string) error
+}
+
+const unavailableMsg = "Command unavailable in current context."
+
+var commandPrefixes = []string{"/", "!"}
+
+// parseCommandName accepts "/name", "!name", and Telegram's "/name@bot", then
+// normalizes to lowercase command names.
+func parseCommandName(input string) (string, bool) {
+	token := nthToken(input, 0)
+	if token == "" {
+		return "", false
+	}
+
+	name, ok := trimCommandPrefix(token)
+	if !ok {
+		return "", false
+	}
+	if i := strings.Index(name, "@"); i >= 0 {
+		name = name[:i]
+	}
+	name = normalizeCommandName(name)
+	if name == "" {
+		return "", false
+	}
+	return name, true
+}
+
+// CommandName returns the normalized command name for an input if present.
+func CommandName(input string) (string, bool) {
+	return parseCommandName(input)
+}
+
+func trimCommandPrefix(token string) (string, bool) {
+	for _, prefix := range commandPrefixes {
+		if strings.HasPrefix(token, prefix) {
+			return strings.TrimPrefix(token, prefix), true
+		}
+	}
+	return "", false
+}
+
+// HasCommandPrefix returns true if the input starts with a recognized
+// command prefix (e.g. "/" or "!").
+func HasCommandPrefix(input string) bool {
+	token := nthToken(input, 0)
+	if token == "" {
+		return false
+	}
+	_, ok := trimCommandPrefix(token)
+	return ok
+}
+
+// nthToken returns the 0-indexed token from whitespace-split input.
+func nthToken(input string, n int) string {
+	parts := strings.Fields(strings.TrimSpace(input))
+	if n >= len(parts) {
+		return ""
+	}
+	return parts[n]
+}
+
+func normalizeCommandName(name string) string {
+	return strings.ToLower(strings.TrimSpace(name))
+}
diff --git a/pkg/commands/request_test.go b/pkg/commands/request_test.go
new file mode 100644
index 000000000..4389e453b
--- /dev/null
+++ b/pkg/commands/request_test.go
@@ -0,0 +1,28 @@
+package commands
+
+import "testing"
+
+func TestHasCommandPrefix(t *testing.T) {
+	tests := []struct {
+		input string
+		want  bool
+	}{
+		{"/help", true},
+		{"!help", true},
+		{"/switch model to gpt-4", true},
+		{"!switch model to gpt-4", true},
+		{"hello", false},
+		{"", false},
+		{"   ", false},
+		{"hello /world", false},
+		{"/", true},
+		{"!", true},
+		{"  /help", true},
+	}
+	for _, tt := range tests {
+		got := HasCommandPrefix(tt.input)
+		if got != tt.want {
+			t.Errorf("HasCommandPrefix(%q) = %v, want %v", tt.input, got, tt.want)
+		}
+	}
+}
diff --git a/pkg/commands/runtime.go b/pkg/commands/runtime.go
new file mode 100644
index 000000000..5ba6a1bd2
--- /dev/null
+++ b/pkg/commands/runtime.go
@@ -0,0 +1,20 @@
+package commands
+
+import "github.com/sipeed/picoclaw/pkg/config"
+
+// Runtime provides runtime dependencies to command handlers. It is constructed
+// per-request by the agent loop so that per-request state (like session scope)
+// can coexist with long-lived callbacks (like GetModelInfo).
+type Runtime struct {
+	Config             *config.Config
+	GetModelInfo       func() (name, provider string)
+	ListAgentIDs       func() []string
+	ListDefinitions    func() []Definition
+	ListSkillNames     func() []string
+	GetEnabledChannels func() []string
+	GetActiveTurn      func() any // Returning any to avoid circular dependency with agent package
+	SwitchModel        func(value string) (oldModel string, err error)
+	SwitchChannel      func(value string) error
+	ClearHistory       func() error
+	ReloadConfig       func() error
+}
diff --git a/pkg/commands/show_list_handlers_test.go b/pkg/commands/show_list_handlers_test.go
new file mode 100644
index 000000000..28d481b67
--- /dev/null
+++ b/pkg/commands/show_list_handlers_test.go
@@ -0,0 +1,104 @@
+package commands
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+func TestShowListHandlers_ChannelPolicy(t *testing.T) {
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), nil)
+
+	var telegramReply string
+	handled := ex.Execute(context.Background(), Request{
+		Channel: "telegram",
+		Text:    "/show channel",
+		Reply: func(text string) error {
+			telegramReply = text
+			return nil
+		},
+	})
+	if handled.Outcome != OutcomeHandled {
+		t.Fatalf("telegram /show outcome=%v, want=%v", handled.Outcome, OutcomeHandled)
+	}
+	if telegramReply != "Current Channel: telegram" {
+		t.Fatalf("telegram /show reply=%q, want=%q", telegramReply, "Current Channel: telegram")
+	}
+
+	var whatsappReply string
+	handledWhatsApp := ex.Execute(context.Background(), Request{
+		Channel: "whatsapp",
+		Text:    "/show channel",
+		Reply: func(text string) error {
+			whatsappReply = text
+			return nil
+		},
+	})
+	if handledWhatsApp.Outcome != OutcomeHandled {
+		t.Fatalf("whatsapp /show outcome=%v, want=%v", handledWhatsApp.Outcome, OutcomeHandled)
+	}
+	if handledWhatsApp.Command != "show" {
+		t.Fatalf("whatsapp /show command=%q, want=%q", handledWhatsApp.Command, "show")
+	}
+	if whatsappReply != "Current Channel: whatsapp" {
+		t.Fatalf("whatsapp /show reply=%q, want=%q", whatsappReply, "Current Channel: whatsapp")
+	}
+
+	passthrough := ex.Execute(context.Background(), Request{
+		Channel: "whatsapp",
+		Text:    "/foo",
+	})
+	if passthrough.Outcome != OutcomePassthrough {
+		t.Fatalf("whatsapp /foo outcome=%v, want=%v", passthrough.Outcome, OutcomePassthrough)
+	}
+	if passthrough.Command != "foo" {
+		t.Fatalf("whatsapp /foo command=%q, want=%q", passthrough.Command, "foo")
+	}
+}
+
+func TestShowListHandlers_ListHandledOnAllChannels(t *testing.T) {
+	rt := &Runtime{
+		GetEnabledChannels: func() []string {
+			return []string{"telegram"}
+		},
+		ListSkillNames: func() []string {
+			return []string{"shell"}
+		},
+	}
+	ex := NewExecutor(NewRegistry(BuiltinDefinitions()), rt)
+
+	var reply string
+	res := ex.Execute(context.Background(), Request{
+		Channel: "whatsapp",
+		Text:    "/list channels",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("whatsapp /list outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if res.Command != "list" {
+		t.Fatalf("whatsapp /list command=%q, want=%q", res.Command, "list")
+	}
+	if !strings.Contains(reply, "telegram") {
+		t.Fatalf("whatsapp /list reply=%q, expected enabled channels content", reply)
+	}
+
+	reply = ""
+	res = ex.Execute(context.Background(), Request{
+		Channel: "whatsapp",
+		Text:    "/list skills",
+		Reply: func(text string) error {
+			reply = text
+			return nil
+		},
+	})
+	if res.Outcome != OutcomeHandled {
+		t.Fatalf("whatsapp /list skills outcome=%v, want=%v", res.Outcome, OutcomeHandled)
+	}
+	if !strings.Contains(reply, "shell") {
+		t.Fatalf("whatsapp /list skills reply=%q, expected installed skills content", reply)
+	}
+}
diff --git a/pkg/config/SECURITY_CONFIG.md b/pkg/config/SECURITY_CONFIG.md
new file mode 100644
index 000000000..4f783aaa5
--- /dev/null
+++ b/pkg/config/SECURITY_CONFIG.md
@@ -0,0 +1,545 @@
+# Security Configuration Refactoring
+
+## Overview
+
+This refactoring introduces a `.security.yml` file to store all sensitive data (API keys, tokens, secrets, passwords) separately from the main configuration. This improves security by:
+
+1. **Separation of concerns**: Configuration settings and secrets are in separate files
+2. **Easier sharing**: The main config can be shared without exposing sensitive data
+3. **Better version control**: `.security.yml` can be added to `.gitignore`
+4. **Flexible deployment**: Different environments can use different security files
+
+## File Structure
+
+```
+~/.picoclaw/
+├── config.json          # Main configuration (safe to share)
+└── .security.yml         # Security data (never share)
+```
+
+## Usage
+
+### Basic Configuration
+
+In your `config.json`, use `ref:` references to point to values in `.security.yml`:
+
+```json
+{
+  "version": 1,
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api.openai.com/v1",
+      "api_key": "ref:model_list.gpt-5.4.api_key"
+    }
+  ],
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "ref:channels.telegram.token"
+    }
+  }
+}
+```
+
+### Security Configuration
+
+In your `.security.yml`, store the actual values:
+
+```yaml
+model_list:
+  gpt-5.4:
+    api_keys:
+      - "sk-your-actual-api-key-1"
+      - "sk-your-actual-api-key-2"  # Optional: Multiple keys for failover
+  claude-sonnet-4.6:
+    api_keys:
+      - "sk-your-actual-anthropic-key"  # Single key in array format
+
+channels:
+  telegram:
+    token: "your-telegram-bot-token"
+
+web:
+  brave:
+    api_keys:
+      - "BSAyour-brave-api-key-1"
+      - "BSAyour-brave-api-key-2"  # Optional: Multiple keys for failover
+  tavily:
+    api_keys:
+      - "tvly-your-tavily-api-key"  # Single key in array format
+  glm_search:
+    api_key: "your-glm-search-api-key"  # GLMSearch uses single key format
+```
+
+## Reference Format
+
+### Model API Keys
+
+Format: `ref:model_list.<model_name>.api_key`
+
+Example: `ref:model_list.gpt-5.4.api_key`
+
+### Channel Tokens/Secrets
+
+Format: `ref:channels.<channel_name>.<field>`
+
+Examples:
+- `ref:channels.telegram.token`
+- `ref:channels.feishu.app_secret`
+- `ref:channels.feishu.encrypt_key`
+- `ref:channels.feishu.verification_token`
+- `ref:channels.discord.token`
+- `ref:channels.qq.app_secret`
+- `ref:channels.dingtalk.client_secret`
+- `ref:channels.slack.bot_token`
+- `ref:channels.slack.app_token`
+- `ref:channels.matrix.access_token`
+- `ref:channels.line.channel_secret`
+- `ref:channels.line.channel_access_token`
+- `ref:channels.onebot.access_token`
+- `ref:channels.wecom.secret`
+- `ref:channels.pico.token`
+- `ref:channels.irc.password`
+- `ref:channels.irc.nickserv_password`
+- `ref:channels.irc.sasl_password`
+
+### Web Tool API Keys
+
+Format: `ref:web.<provider>.<field>`
+
+Examples:
+- `ref:web.brave.api_key`
+- `ref:web.tavily.api_key`
+- `ref:web.perplexity.api_key`
+- `ref:web.glm_search.api_key`
+
+### Skills Registry Tokens
+
+Format: `ref:skills.<registry>.<field>`
+
+Examples:
+- `ref:skills.github.token`
+- `ref:skills.clawhub.auth_token`
+
+## Backward Compatibility
+
+The refactoring maintains full backward compatibility:
+
+1. **Direct values**: You can still use direct values in `config.json` (not recommended for production)
+2. **Mixed usage**: You can mix `ref:` references and direct values
+3. **Optional security file**: If `.security.yml` doesn't exist, all references will fail (but direct values still work)
+
+### API Key Formats in .security.yml
+
+**Models (gpt-5.4, claude-sonnet-4.6, etc.):**
+- Must use `api_keys` (array) format
+- Both single and multiple keys use array format
+
+**Web Tools (Brave, Tavily, Perplexity):**
+- Must use `api_keys` (array) format
+- Both single and multiple keys use array format
+
+**Web Tools (GLMSearch):**
+- Must use `api_key` (single string) format
+- Does NOT support array format
+
+**Channels (Telegram, Discord, etc.):**
+- Use single field names (e.g., `token`, `app_secret`)
+- Each channel uses its specific field names
+
+### Single Key (Models)
+
+Use array format with one element:
+```yaml
+model_list:
+  gpt-5.4:
+    api_keys:
+      - "sk-your-key"
+```
+
+In `config.json`:
+```json
+{
+  "api_key": "ref:model_list.gpt-5.4.api_key"
+}
+```
+
+### Single Key (GLMSearch)
+
+Use single string format:
+```yaml
+web:
+  glm_search:
+    api_key: "your-glm-key"
+```
+
+In `config.json`:
+```json
+{
+  "api_key": "ref:web.glm_search.api_key"
+}
+```
+
+## Migration Guide
+
+### Step 1: Create .security.yml
+
+Copy the example template:
+```bash
+cp security.example.yml ~/.picoclaw/.security.yml
+```
+
+### Step 2: Fill in your actual values
+
+Edit `~/.picoclaw/.security.yml` and replace placeholder values with your actual API keys and tokens.
+
+### Step 3: Update config.json
+
+Replace sensitive values in `~/.picoclaw/config.json` with `ref:` references:
+
+**Before:**
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "sk-your-actual-api-key-here"
+    }
+  ]
+}
+```
+
+**After:**
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "ref:model_list.gpt-5.4.api_key"
+    }
+  ]
+}
+```
+
+### Step 4: Verify
+
+Restart PicoClaw and verify it loads correctly:
+```bash
+picoclaw --version
+```
+
+## Security Best Practices
+
+1. **Never commit `.security.yml`** to version control
+2. **Set file permissions**: `chmod 600 ~/.picoclaw/.security.yml`
+3. **Use different keys** for different environments (dev, staging, production)
+4. **Rotate keys regularly** and update `.security.yml`
+5. **Backup securely**: Encrypt backups containing `.security.yml`
+
+## API
+
+### LoadSecurityConfig
+
+```go
+func LoadSecurityConfig(securityPath string) (*SecurityConfig, error)
+```
+
+Loads the security configuration from `.security.yml`. Returns an empty `SecurityConfig` if the file doesn't exist.
+
+### SaveSecurityConfig
+
+```go
+func SaveSecurityConfig(securityPath string, sec *SecurityConfig) error
+```
+
+Saves the security configuration to `.security.yml` with `0o600` permissions.
+
+### ResolveReference
+
+```go
+func (sec *SecurityConfig) ResolveReference(ref string) (string, error)
+```
+
+Resolves a reference string (e.g., `"ref:model_list.test.api_key"`) and returns the actual value.
+
+### SecurityPath
+
+```go
+func SecurityPath(configPath string) string
+```
+
+Returns the path to `.security.yml` relative to the config file.
+
+## Example: Complete Configuration
+
+### config.json
+```json
+{
+  "version": 1,
+  "agents": {
+    "defaults": {
+      "workspace": "~/picoclaw-workspace",
+      "model_name": "gpt-5.4"
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_base": "https://api.openai.com/v1",
+      "api_key": "ref:model_list.gpt-5.4.api_key"
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_base": "https://api.anthropic.com/v1",
+      "api_key": "ref:model_list.claude-sonnet-4.6.api_key"
+    }
+  ],
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "ref:channels.telegram.token"
+    }
+  },
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": true,
+        "api_key": "ref:web.brave.api_key"
+      }
+    }
+  }
+}
+```
+
+### .security.yml
+```yaml
+model_list:
+  gpt-5.4:
+    api_keys:
+      - "sk-proj-actual-openai-key-1"
+      - "sk-proj-actual-openai-key-2"
+  claude-sonnet-4.6:
+    api_keys:
+      - "sk-ant-actual-anthropic-key"  # Single key in array format
+
+channels:
+  telegram:
+    token: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
+
+web:
+  brave:
+    api_keys:
+      - "BSAactualbravekey-1"
+      - "BSAactualbravekey-2"
+  tavily:
+    api_keys:
+      - "tvly-your-tavily-key"  # Single key in array format
+  glm_search:
+    api_key: "your-glm-key"  # GLMSearch uses single key format
+```
+
+## Testing
+
+The refactoring includes comprehensive tests:
+
+```bash
+go test ./pkg/config -run TestSecurityConfig
+```
+
+## Troubleshooting
+
+### Error: "model security entry not found"
+
+- Ensure the model name in your reference matches exactly in `.security.yml`
+- Check that the `model_list` section exists in `.security.yml`
+- For models with indexed names (e.g., "gpt-5.4:0"), ensure the exact name is used or check the base name without index
+
+### Error: "failed to load security config"
+
+- Verify `.security.yml` exists in the same directory as `config.json`
+- Check the YAML syntax is valid (use a YAML validator)
+- Ensure file permissions allow reading
+
+### Error: "unknown reference path"
+
+- Verify the reference format is correct
+- Check the path structure matches the examples above
+- Ensure all required sections exist in `.security.yml`
+
+## Advanced Features
+
+### Multiple API Keys (Load Balancing & Failover)
+
+Both models and web tools support multiple API keys for improved reliability:
+
+**Benefits:**
+- **Load balancing**: Requests are distributed across multiple keys
+- **Failover**: Automatic switching to another key if one fails
+- **Rate limit management**: Distribute usage across multiple keys
+- **High availability**: Reduce downtime during API provider issues
+
+#### Example: Model with Multiple Keys
+
+**.security.yml:**
+```yaml
+model_list:
+  gpt-5.4:
+    api_keys:
+      - "sk-proj-key-1"
+      - "sk-proj-key-2"
+      - "sk-proj-key-3"
+```
+
+**config.json:**
+```json
+{
+  "model_list": [
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "ref:model_list.gpt-5.4.api_key"
+    }
+  ]
+}
+```
+
+#### Example: Web Tool with Multiple Keys
+
+**.security.yml:**
+```yaml
+web:
+  brave:
+    api_keys:
+      - "BSA-key-1"
+      - "BSA-key-2"
+  tavily:
+    api_keys:
+      - "tvly-your-key"  # Single key in array format
+  glm_search:
+    api_key: "your-glm-key"  # GLMSearch uses single key format
+```
+
+**config.json:**
+```json
+{
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": true,
+        "api_key": "ref:web.brave.api_key"
+      },
+      "tavily": {
+        "enabled": true,
+        "api_key": "ref:web.tavily.api_key"
+      }
+    }
+  }
+}
+```
+
+#### Supported Formats
+
+**Models - Single key:**
+```yaml
+model_list:
+  gpt-5.4:
+    api_keys:
+      - "sk-your-key"  # Array with one element
+```
+
+**Models - Multiple keys:**
+```yaml
+model_list:
+  gpt-5.4:
+    api_keys:
+      - "sk-your-key-1"
+      - "sk-your-key-2"
+      - "sk-your-key-3"
+```
+
+**Web Tools (Brave/Tavily/Perplexity) - Single key:**
+```yaml
+web:
+  brave:
+    api_keys:
+      - "BSA-your-key"  # Array with one element
+```
+
+**Web Tools (Brave/Tavily/Perplexity) - Multiple keys:**
+```yaml
+web:
+  brave:
+    api_keys:
+      - "BSA-key-1"
+      - "BSA-key-2"
+```
+
+**Web Tool (GLMSearch) - Single key only:**
+```yaml
+web:
+  glm_search:
+    api_key: "your-glm-key"  # Single string (NOT array)
+```
+
+All formats work identically in `config.json` - you always use the same reference format:
+```json
+{
+  "api_key": "ref:model_list.gpt-5.4.api_key"
+}
+```
+
+### Model Indexing for Load Balancing
+
+When you have multiple models with the same base name but different API keys, you can use indexed names:
+
+**.security.yml:**
+```yaml
+model_list:
+  gpt-5.4:
+    api_keys:
+      - "sk-proj-key-1"
+      - "sk-proj-key-2"
+```
+
+The system will automatically expand this into multiple model entries with fallback support.
+
+### Environment Variables
+
+You can override any security value using environment variables:
+
+**For models:**
+```bash
+export PICOCLAW_MODEL_LIST_GPT-5.4_API_KEY="sk-from-env"
+```
+
+**For channels:**
+```bash
+export PICOCLAW_CHANNELS_TELEGRAM_TOKEN="token-from-env"
+```
+
+**For web tools:**
+```bash
+export PICOCLAW_WEB_BRAVE_API_KEY="key-from-env"
+```
+
+Environment variables follow this pattern: `PICOCLAW_<SECTION>_<KEY1>_<KEY2>_<FIELD>` with dots replaced by underscores and converted to uppercase.
+
+### Multiple API Keys Not Working
+
+- Ensure you're using `api_keys` (plural) in `.security.yml` for models and web tools (except GLMSearch)
+- Check that the array format is correct in YAML (proper indentation)
+- Remember: Models, Brave, Tavily, Perplexity MUST use `api_keys` (array format)
+- GLMSearch MUST use `api_key` (single string format)
+- The reference in `config.json` is the same regardless of single or multiple keys
+
+### Load Balancing/Failover Issues
+
+- Verify all API keys in the `api_keys` array are valid
+- Check that all keys have the same rate limits and permissions
+- Monitor logs to see which keys are being used and failing
diff --git a/pkg/config/config.go b/pkg/config/config.go
index 9f4769de4..47bb7e8f1 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -4,11 +4,16 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
+	"path/filepath"
+	"strings"
 	"sync/atomic"
 
 	"github.com/caarlos0/env/v11"
 
+	"github.com/sipeed/picoclaw/pkg"
+	"github.com/sipeed/picoclaw/pkg/credential"
 	"github.com/sipeed/picoclaw/pkg/fileutil"
+	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
 // rrCounter is a global counter for round-robin load balancing across models.
@@ -16,6 +21,8 @@ var rrCounter atomic.Uint64
 
 // FlexibleStringSlice is a []string that also accepts JSON numbers,
 // so allow_from can contain both "123" and 123.
+// It also supports parsing comma-separated strings from environment variables,
+// including both English (,) and Chinese (，) commas.
 type FlexibleStringSlice []string
 
 func (f *FlexibleStringSlice) UnmarshalJSON(data []byte) error {
@@ -47,34 +54,133 @@ func (f *FlexibleStringSlice) UnmarshalJSON(data []byte) error {
 	return nil
 }
 
+// UnmarshalText implements encoding.TextUnmarshaler to support env variable parsing.
+// It handles comma-separated values with both English (,) and Chinese (，) commas.
+func (f *FlexibleStringSlice) UnmarshalText(text []byte) error {
+	if len(text) == 0 {
+		*f = nil
+		return nil
+	}
+
+	s := string(text)
+	// Replace Chinese comma with English comma, then split
+	s = strings.ReplaceAll(s, "，", ",")
+	parts := strings.Split(s, ",")
+
+	result := make([]string, 0, len(parts))
+	for _, part := range parts {
+		part = strings.TrimSpace(part)
+		if part != "" {
+			result = append(result, part)
+		}
+	}
+	*f = result
+	return nil
+}
+
+// CurrentVersion is the latest config schema version
+const CurrentVersion = 1
+
+// Config is the current config structure with version support
 type Config struct {
+	Version   int             `json:"version"` // Config schema version for migration
 	Agents    AgentsConfig    `json:"agents"`
 	Bindings  []AgentBinding  `json:"bindings,omitempty"`
 	Session   SessionConfig   `json:"session,omitempty"`
 	Channels  ChannelsConfig  `json:"channels"`
-	Providers ProvidersConfig `json:"providers,omitempty"`
-	ModelList []ModelConfig   `json:"model_list"` // New model-centric provider configuration
+	ModelList []*ModelConfig  `json:"model_list"` // New model-centric provider configuration
 	Gateway   GatewayConfig   `json:"gateway"`
+	Hooks     HooksConfig     `json:"hooks,omitempty"`
 	Tools     ToolsConfig     `json:"tools"`
 	Heartbeat HeartbeatConfig `json:"heartbeat"`
 	Devices   DevicesConfig   `json:"devices"`
+	Voice     VoiceConfig     `json:"voice"`
+	// BuildInfo contains build-time version information
+	BuildInfo BuildInfo `json:"build_info,omitempty"`
+
+	security *SecurityConfig
+}
+
+func (c *Config) WithSecurity(sec *SecurityConfig) *Config {
+	if sec == nil {
+		c.security = sec
+		return c
+	}
+	sec = normalizeSecurityConfig(sec)
+	err := applySecurityConfig(c, sec)
+	if err != nil {
+		return nil
+	}
+	c.security = sec
+	return c
+}
+
+// FilterSensitiveData filters sensitive values from content before sending to LLM.
+// This prevents the LLM from seeing its own credentials.
+// Uses strings.Replacer for O(n+m) performance (computed once per SecurityConfig).
+// Short content (below FilterMinLength) is returned unchanged for performance.
+func (c *Config) FilterSensitiveData(content string) string {
+	if c.security == nil || content == "" {
+		return content
+	}
+	// Check if filtering is enabled (default: true)
+	if !c.Tools.IsFilterSensitiveDataEnabled() {
+		return content
+	}
+	// Fast path: skip filtering for short content
+	if len(content) < c.Tools.GetFilterMinLength() {
+		return content
+	}
+	return c.security.SensitiveDataReplacer().Replace(content)
+}
+
+type HooksConfig struct {
+	Enabled   bool                         `json:"enabled"`
+	Defaults  HookDefaultsConfig           `json:"defaults,omitempty"`
+	Builtins  map[string]BuiltinHookConfig `json:"builtins,omitempty"`
+	Processes map[string]ProcessHookConfig `json:"processes,omitempty"`
+}
+
+type HookDefaultsConfig struct {
+	ObserverTimeoutMS    int `json:"observer_timeout_ms,omitempty"`
+	InterceptorTimeoutMS int `json:"interceptor_timeout_ms,omitempty"`
+	ApprovalTimeoutMS    int `json:"approval_timeout_ms,omitempty"`
+}
+
+type BuiltinHookConfig struct {
+	Enabled  bool            `json:"enabled"`
+	Priority int             `json:"priority,omitempty"`
+	Config   json.RawMessage `json:"config,omitempty"`
+}
+
+type ProcessHookConfig struct {
+	Enabled   bool              `json:"enabled"`
+	Priority  int               `json:"priority,omitempty"`
+	Transport string            `json:"transport,omitempty"`
+	Command   []string          `json:"command,omitempty"`
+	Dir       string            `json:"dir,omitempty"`
+	Env       map[string]string `json:"env,omitempty"`
+	Observe   []string          `json:"observe,omitempty"`
+	Intercept []string          `json:"intercept,omitempty"`
+}
+
+// BuildInfo contains build-time version information
+type BuildInfo struct {
+	Version   string `json:"version"`
+	GitCommit string `json:"git_commit"`
+	BuildTime string `json:"build_time"`
+	GoVersion string `json:"go_version"`
 }
 
 // MarshalJSON implements custom JSON marshaling for Config
 // to omit providers section when empty and session when empty
-func (c Config) MarshalJSON() ([]byte, error) {
+func (c *Config) MarshalJSON() ([]byte, error) {
 	type Alias Config
 	aux := &struct {
-		Providers *ProvidersConfig `json:"providers,omitempty"`
-		Session   *SessionConfig   `json:"session,omitempty"`
+		Session *SessionConfig `json:"session,omitempty"`
 		*Alias
 	}{
-		Alias: (*Alias)(&c),
-	}
-
-	// Only include providers if not empty
-	if !c.Providers.IsEmpty() {
-		aux.Providers = &c.Providers
+		Alias: (*Alias)(c),
 	}
 
 	// Only include session if not empty
@@ -167,44 +273,99 @@ type SessionConfig struct {
 	IdentityLinks map[string][]string `json:"identity_links,omitempty"`
 }
 
+// RoutingConfig controls the intelligent model routing feature.
+// When enabled, each incoming message is scored against structural features
+// (message length, code blocks, tool call history, conversation depth, attachments).
+// Messages scoring below Threshold are sent to LightModel; all others use the
+// agent's primary model. This reduces cost and latency for simple tasks without
+// requiring any keyword matching — all scoring is language-agnostic.
+type RoutingConfig struct {
+	Enabled    bool    `json:"enabled"`
+	LightModel string  `json:"light_model"` // model_name from model_list to use for simple tasks
+	Threshold  float64 `json:"threshold"`   // complexity score in [0,1]; score >= threshold → primary model
+}
+
+// SubTurnConfig configures the SubTurn execution system.
+type SubTurnConfig struct {
+	MaxDepth              int `json:"max_depth"               env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_MAX_DEPTH"`
+	MaxConcurrent         int `json:"max_concurrent"          env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_MAX_CONCURRENT"`
+	DefaultTimeoutMinutes int `json:"default_timeout_minutes" env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_DEFAULT_TIMEOUT_MINUTES"`
+	DefaultTokenBudget    int `json:"default_token_budget"    env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_DEFAULT_TOKEN_BUDGET"`
+	ConcurrencyTimeoutSec int `json:"concurrency_timeout_sec" env:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_CONCURRENCY_TIMEOUT_SEC"`
+}
+
+type ToolFeedbackConfig struct {
+	Enabled       bool `json:"enabled"         env:"PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_ENABLED"`
+	MaxArgsLength int  `json:"max_args_length" env:"PICOCLAW_AGENTS_DEFAULTS_TOOL_FEEDBACK_MAX_ARGS_LENGTH"`
+}
+
 type AgentDefaults struct {
-	Workspace                 string   `json:"workspace"                       env:"PICOCLAW_AGENTS_DEFAULTS_WORKSPACE"`
-	RestrictToWorkspace       bool     `json:"restrict_to_workspace"           env:"PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE"`
-	AllowReadOutsideWorkspace bool     `json:"allow_read_outside_workspace"    env:"PICOCLAW_AGENTS_DEFAULTS_ALLOW_READ_OUTSIDE_WORKSPACE"`
-	Provider                  string   `json:"provider"                        env:"PICOCLAW_AGENTS_DEFAULTS_PROVIDER"`
-	ModelName                 string   `json:"model_name,omitempty"            env:"PICOCLAW_AGENTS_DEFAULTS_MODEL_NAME"`
-	Model                     string   `json:"model"                           env:"PICOCLAW_AGENTS_DEFAULTS_MODEL"` // Deprecated: use model_name instead
-	ModelFallbacks            []string `json:"model_fallbacks,omitempty"`
-	ImageModel                string   `json:"image_model,omitempty"           env:"PICOCLAW_AGENTS_DEFAULTS_IMAGE_MODEL"`
-	ImageModelFallbacks       []string `json:"image_model_fallbacks,omitempty"`
-	MaxTokens                 int      `json:"max_tokens"                      env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOKENS"`
-	Temperature               *float64 `json:"temperature,omitempty"           env:"PICOCLAW_AGENTS_DEFAULTS_TEMPERATURE"`
-	MaxToolIterations         int      `json:"max_tool_iterations"             env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS"`
+	Workspace                 string             `json:"workspace"                       env:"PICOCLAW_AGENTS_DEFAULTS_WORKSPACE"`
+	RestrictToWorkspace       bool               `json:"restrict_to_workspace"           env:"PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE"`
+	AllowReadOutsideWorkspace bool               `json:"allow_read_outside_workspace"    env:"PICOCLAW_AGENTS_DEFAULTS_ALLOW_READ_OUTSIDE_WORKSPACE"`
+	Provider                  string             `json:"provider"                        env:"PICOCLAW_AGENTS_DEFAULTS_PROVIDER"`
+	ModelName                 string             `json:"model_name"                      env:"PICOCLAW_AGENTS_DEFAULTS_MODEL_NAME"`
+	ModelFallbacks            []string           `json:"model_fallbacks,omitempty"`
+	ImageModel                string             `json:"image_model,omitempty"           env:"PICOCLAW_AGENTS_DEFAULTS_IMAGE_MODEL"`
+	ImageModelFallbacks       []string           `json:"image_model_fallbacks,omitempty"`
+	MaxTokens                 int                `json:"max_tokens"                      env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOKENS"`
+	ContextWindow             int                `json:"context_window,omitempty"        env:"PICOCLAW_AGENTS_DEFAULTS_CONTEXT_WINDOW"`
+	Temperature               *float64           `json:"temperature,omitempty"           env:"PICOCLAW_AGENTS_DEFAULTS_TEMPERATURE"`
+	MaxToolIterations         int                `json:"max_tool_iterations"             env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS"`
+	SummarizeMessageThreshold int                `json:"summarize_message_threshold"     env:"PICOCLAW_AGENTS_DEFAULTS_SUMMARIZE_MESSAGE_THRESHOLD"`
+	SummarizeTokenPercent     int                `json:"summarize_token_percent"         env:"PICOCLAW_AGENTS_DEFAULTS_SUMMARIZE_TOKEN_PERCENT"`
+	MaxMediaSize              int                `json:"max_media_size,omitempty"        env:"PICOCLAW_AGENTS_DEFAULTS_MAX_MEDIA_SIZE"`
+	Routing                   *RoutingConfig     `json:"routing,omitempty"`
+	SteeringMode              string             `json:"steering_mode,omitempty"         env:"PICOCLAW_AGENTS_DEFAULTS_STEERING_MODE"` // "one-at-a-time" (default) or "all"
+	SubTurn                   SubTurnConfig      `json:"subturn"                                                                                     envPrefix:"PICOCLAW_AGENTS_DEFAULTS_SUBTURN_"`
+	ToolFeedback              ToolFeedbackConfig `json:"tool_feedback,omitempty"`
+}
+
+const DefaultMaxMediaSize = 20 * 1024 * 1024 // 20 MB
+
+func (d *AgentDefaults) GetMaxMediaSize() int {
+	if d.MaxMediaSize > 0 {
+		return d.MaxMediaSize
+	}
+	return DefaultMaxMediaSize
+}
+
+// GetToolFeedbackMaxArgsLength returns the max args preview length for tool feedback messages.
+func (d *AgentDefaults) GetToolFeedbackMaxArgsLength() int {
+	if d.ToolFeedback.MaxArgsLength > 0 {
+		return d.ToolFeedback.MaxArgsLength
+	}
+	return 300
+}
+
+// IsToolFeedbackEnabled returns true when tool feedback messages should be sent to the chat.
+func (d *AgentDefaults) IsToolFeedbackEnabled() bool {
+	return d.ToolFeedback.Enabled
 }
 
 // GetModelName returns the effective model name for the agent defaults.
 // It prefers the new "model_name" field but falls back to "model" for backward compatibility.
 func (d *AgentDefaults) GetModelName() string {
-	if d.ModelName != "" {
-		return d.ModelName
-	}
-	return d.Model
+	return d.ModelName
 }
 
 type ChannelsConfig struct {
-	WhatsApp WhatsAppConfig `json:"whatsapp"`
-	Telegram TelegramConfig `json:"telegram"`
-	Feishu   FeishuConfig   `json:"feishu"`
-	Discord  DiscordConfig  `json:"discord"`
-	MaixCam  MaixCamConfig  `json:"maixcam"`
-	QQ       QQConfig       `json:"qq"`
-	DingTalk DingTalkConfig `json:"dingtalk"`
-	Slack    SlackConfig    `json:"slack"`
-	LINE     LINEConfig     `json:"line"`
-	OneBot   OneBotConfig   `json:"onebot"`
-	WeCom    WeComConfig    `json:"wecom"`
-	WeComApp WeComAppConfig `json:"wecom_app"`
-	Pico     PicoConfig     `json:"pico"`
+	WhatsApp   WhatsAppConfig   `json:"whatsapp"`
+	Telegram   TelegramConfig   `json:"telegram"`
+	Feishu     FeishuConfig     `json:"feishu"`
+	Discord    DiscordConfig    `json:"discord"`
+	MaixCam    MaixCamConfig    `json:"maixcam"`
+	QQ         QQConfig         `json:"qq"`
+	DingTalk   DingTalkConfig   `json:"dingtalk"`
+	Slack      SlackConfig      `json:"slack"`
+	Matrix     MatrixConfig     `json:"matrix"`
+	LINE       LINEConfig       `json:"line"`
+	OneBot     OneBotConfig     `json:"onebot"`
+	WeCom      WeComConfig      `json:"wecom"       envPrefix:"PICOCLAW_CHANNELS_WECOM_"`
+	Weixin     WeixinConfig     `json:"weixin"`
+	Pico       PicoConfig       `json:"pico"`
+	PicoClient PicoClientConfig `json:"pico_client"`
+	IRC        IRCConfig        `json:"irc"`
 }
 
 // GroupTriggerConfig controls when the bot responds in group chats.
@@ -220,10 +381,16 @@ type TypingConfig struct {
 
 // PlaceholderConfig controls placeholder message behavior (Phase 10).
 type PlaceholderConfig struct {
-	Enabled bool   `json:"enabled,omitempty"`
+	Enabled bool   `json:"enabled"`
 	Text    string `json:"text,omitempty"`
 }
 
+type StreamingConfig struct {
+	Enabled         bool `json:"enabled,omitempty"          env:"PICOCLAW_CHANNELS_TELEGRAM_STREAMING_ENABLED"`
+	ThrottleSeconds int  `json:"throttle_seconds,omitempty" env:"PICOCLAW_CHANNELS_TELEGRAM_STREAMING_THROTTLE_SECONDS"`
+	MinGrowthChars  int  `json:"min_growth_chars,omitempty" env:"PICOCLAW_CHANNELS_TELEGRAM_STREAMING_MIN_GROWTH_CHARS"`
+}
+
 type WhatsAppConfig struct {
 	Enabled            bool                `json:"enabled"              env:"PICOCLAW_CHANNELS_WHATSAPP_ENABLED"`
 	BridgeURL          string              `json:"bridge_url"           env:"PICOCLAW_CHANNELS_WHATSAPP_BRIDGE_URL"`
@@ -234,36 +401,101 @@ type WhatsAppConfig struct {
 }
 
 type TelegramConfig struct {
-	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_TELEGRAM_ENABLED"`
-	Token              string              `json:"token"                   env:"PICOCLAW_CHANNELS_TELEGRAM_TOKEN"`
+	Enabled            bool `json:"enabled"                 env:"PICOCLAW_CHANNELS_TELEGRAM_ENABLED"`
+	token              string
+	BaseURL            string              `json:"base_url"                env:"PICOCLAW_CHANNELS_TELEGRAM_BASE_URL"`
 	Proxy              string              `json:"proxy"                   env:"PICOCLAW_CHANNELS_TELEGRAM_PROXY"`
 	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_TELEGRAM_ALLOW_FROM"`
 	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
 	Typing             TypingConfig        `json:"typing,omitempty"`
 	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
+	Streaming          StreamingConfig     `json:"streaming,omitempty"`
 	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_TELEGRAM_REASONING_CHANNEL_ID"`
+	UseMarkdownV2      bool                `json:"use_markdown_v2"         env:"PICOCLAW_CHANNELS_TELEGRAM_USE_MARKDOWN_V2"`
+	secDirty           bool
+}
+
+// Token returns the Telegram bot token
+func (c *TelegramConfig) Token() string {
+	return c.token
+}
+
+// SetToken sets the Telegram bot token
+func (c *TelegramConfig) SetToken(token string) {
+	c.token = token
+	c.secDirty = true
 }
 
 type FeishuConfig struct {
-	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_FEISHU_ENABLED"`
-	AppID              string              `json:"app_id"                  env:"PICOCLAW_CHANNELS_FEISHU_APP_ID"`
-	AppSecret          string              `json:"app_secret"              env:"PICOCLAW_CHANNELS_FEISHU_APP_SECRET"`
-	EncryptKey         string              `json:"encrypt_key"             env:"PICOCLAW_CHANNELS_FEISHU_ENCRYPT_KEY"`
-	VerificationToken  string              `json:"verification_token"      env:"PICOCLAW_CHANNELS_FEISHU_VERIFICATION_TOKEN"`
-	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_FEISHU_ALLOW_FROM"`
-	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
-	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_FEISHU_REASONING_CHANNEL_ID"`
+	Enabled             bool   `json:"enabled"                 env:"PICOCLAW_CHANNELS_FEISHU_ENABLED"`
+	AppID               string `json:"app_id"                  env:"PICOCLAW_CHANNELS_FEISHU_APP_ID"`
+	appSecret           string
+	encryptKey          string
+	verificationToken   string
+	AllowFrom           FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_FEISHU_ALLOW_FROM"`
+	GroupTrigger        GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	Placeholder         PlaceholderConfig   `json:"placeholder,omitempty"`
+	ReasoningChannelID  string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_FEISHU_REASONING_CHANNEL_ID"`
+	RandomReactionEmoji FlexibleStringSlice `json:"random_reaction_emoji"   env:"PICOCLAW_CHANNELS_FEISHU_RANDOM_REACTION_EMOJI"`
+	IsLark              bool                `json:"is_lark"                 env:"PICOCLAW_CHANNELS_FEISHU_IS_LARK"`
+	secDirty            bool
+}
+
+// AppSecret returns the Feishu app secret
+func (c *FeishuConfig) AppSecret() string {
+	return c.appSecret
+}
+
+// SetAppSecret sets the Feishu app secret
+func (c *FeishuConfig) SetAppSecret(secret string) {
+	c.appSecret = secret
+	c.secDirty = true
+}
+
+// EncryptKey returns the Feishu encrypt key
+func (c *FeishuConfig) EncryptKey() string {
+	return c.encryptKey
+}
+
+// SetEncryptKey sets the Feishu encrypt key
+func (c *FeishuConfig) SetEncryptKey(key string) {
+	c.encryptKey = key
+	c.secDirty = true
+}
+
+// VerificationToken returns the Feishu verification token
+func (c *FeishuConfig) VerificationToken() string {
+	return c.verificationToken
+}
+
+// SetVerificationToken sets the Feishu verification token
+func (c *FeishuConfig) SetVerificationToken(token string) {
+	c.verificationToken = token
+	c.secDirty = true
 }
 
 type DiscordConfig struct {
-	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_DISCORD_ENABLED"`
-	Token              string              `json:"token"                   env:"PICOCLAW_CHANNELS_DISCORD_TOKEN"`
+	Enabled            bool `json:"enabled"                 env:"PICOCLAW_CHANNELS_DISCORD_ENABLED"`
+	token              string
+	Proxy              string              `json:"proxy"                   env:"PICOCLAW_CHANNELS_DISCORD_PROXY"`
 	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_DISCORD_ALLOW_FROM"`
 	MentionOnly        bool                `json:"mention_only"            env:"PICOCLAW_CHANNELS_DISCORD_MENTION_ONLY"`
 	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
 	Typing             TypingConfig        `json:"typing,omitempty"`
 	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
 	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_DISCORD_REASONING_CHANNEL_ID"`
+	secDirty           bool
+}
+
+// Token returns the Discord bot token
+func (c *DiscordConfig) Token() string {
+	return c.token
+}
+
+// SetToken sets the Discord bot token
+func (c *DiscordConfig) SetToken(token string) {
+	c.token = token
+	c.secDirty = true
 }
 
 type MaixCamConfig struct {
@@ -275,38 +507,116 @@ type MaixCamConfig struct {
 }
 
 type QQConfig struct {
-	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_QQ_ENABLED"`
-	AppID              string              `json:"app_id"                  env:"PICOCLAW_CHANNELS_QQ_APP_ID"`
-	AppSecret          string              `json:"app_secret"              env:"PICOCLAW_CHANNELS_QQ_APP_SECRET"`
-	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_QQ_ALLOW_FROM"`
-	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
-	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_QQ_REASONING_CHANNEL_ID"`
+	Enabled              bool   `json:"enabled"                  env:"PICOCLAW_CHANNELS_QQ_ENABLED"`
+	AppID                string `json:"app_id"                   env:"PICOCLAW_CHANNELS_QQ_APP_ID"`
+	appSecret            string
+	AllowFrom            FlexibleStringSlice `json:"allow_from"               env:"PICOCLAW_CHANNELS_QQ_ALLOW_FROM"`
+	GroupTrigger         GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	MaxMessageLength     int                 `json:"max_message_length"       env:"PICOCLAW_CHANNELS_QQ_MAX_MESSAGE_LENGTH"`
+	MaxBase64FileSizeMiB int64               `json:"max_base64_file_size_mib" env:"PICOCLAW_CHANNELS_QQ_MAX_BASE64_FILE_SIZE_MIB"`
+	SendMarkdown         bool                `json:"send_markdown"            env:"PICOCLAW_CHANNELS_QQ_SEND_MARKDOWN"`
+	ReasoningChannelID   string              `json:"reasoning_channel_id"     env:"PICOCLAW_CHANNELS_QQ_REASONING_CHANNEL_ID"`
+	secDirty             bool
+}
+
+// AppSecret returns the QQ app secret
+func (c *QQConfig) AppSecret() string {
+	return c.appSecret
+}
+
+// SetAppSecret sets the QQ app secret
+func (c *QQConfig) SetAppSecret(secret string) {
+	c.appSecret = secret
+	c.secDirty = true
 }
 
 type DingTalkConfig struct {
-	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_DINGTALK_ENABLED"`
-	ClientID           string              `json:"client_id"               env:"PICOCLAW_CHANNELS_DINGTALK_CLIENT_ID"`
-	ClientSecret       string              `json:"client_secret"           env:"PICOCLAW_CHANNELS_DINGTALK_CLIENT_SECRET"`
+	Enabled            bool   `json:"enabled"                 env:"PICOCLAW_CHANNELS_DINGTALK_ENABLED"`
+	ClientID           string `json:"client_id"               env:"PICOCLAW_CHANNELS_DINGTALK_CLIENT_ID"`
+	clientSecret       string
 	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_DINGTALK_ALLOW_FROM"`
 	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
 	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_DINGTALK_REASONING_CHANNEL_ID"`
+	secDirty           bool
+}
+
+// ClientSecret returns the DingTalk client secret
+func (c *DingTalkConfig) ClientSecret() string {
+	return c.clientSecret
+}
+
+// SetClientSecret sets the DingTalk client secret
+func (c *DingTalkConfig) SetClientSecret(secret string) {
+	c.clientSecret = secret
+	c.secDirty = true
 }
 
 type SlackConfig struct {
-	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_SLACK_ENABLED"`
-	BotToken           string              `json:"bot_token"               env:"PICOCLAW_CHANNELS_SLACK_BOT_TOKEN"`
-	AppToken           string              `json:"app_token"               env:"PICOCLAW_CHANNELS_SLACK_APP_TOKEN"`
+	Enabled            bool `json:"enabled"                 env:"PICOCLAW_CHANNELS_SLACK_ENABLED"`
+	botToken           string
+	appToken           string
 	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_SLACK_ALLOW_FROM"`
 	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
 	Typing             TypingConfig        `json:"typing,omitempty"`
 	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
 	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_SLACK_REASONING_CHANNEL_ID"`
+	secDirty           bool
+}
+
+// BotToken returns the Slack bot token
+func (c *SlackConfig) BotToken() string {
+	return c.botToken
+}
+
+// SetBotToken sets the Slack bot token
+func (c *SlackConfig) SetBotToken(token string) {
+	c.botToken = token
+	c.secDirty = true
+}
+
+// AppToken returns the Slack app token
+func (c *SlackConfig) AppToken() string {
+	return c.appToken
+}
+
+// SetAppToken sets the Slack app token
+func (c *SlackConfig) SetAppToken(token string) {
+	c.appToken = token
+	c.secDirty = true
+}
+
+type MatrixConfig struct {
+	Enabled            bool   `json:"enabled"                        env:"PICOCLAW_CHANNELS_MATRIX_ENABLED"`
+	Homeserver         string `json:"homeserver"                     env:"PICOCLAW_CHANNELS_MATRIX_HOMESERVER"`
+	UserID             string `json:"user_id"                        env:"PICOCLAW_CHANNELS_MATRIX_USER_ID"`
+	accessToken        string
+	DeviceID           string              `json:"device_id,omitempty"            env:"PICOCLAW_CHANNELS_MATRIX_DEVICE_ID"`
+	JoinOnInvite       bool                `json:"join_on_invite"                 env:"PICOCLAW_CHANNELS_MATRIX_JOIN_ON_INVITE"`
+	MessageFormat      string              `json:"message_format,omitempty"       env:"PICOCLAW_CHANNELS_MATRIX_MESSAGE_FORMAT"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"                     env:"PICOCLAW_CHANNELS_MATRIX_ALLOW_FROM"`
+	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
+	ReasoningChannelID string              `json:"reasoning_channel_id"           env:"PICOCLAW_CHANNELS_MATRIX_REASONING_CHANNEL_ID"`
+	secDirty           bool
+	CryptoDatabasePath string `json:"crypto_database_path,omitempty" env:"PICOCLAW_CHANNELS_MATRIX_CRYPTO_DATABASE_PATH"`
+	CryptoPassphrase   string `json:"crypto_passphrase,omitempty"    env:"PICOCLAW_CHANNELS_MATRIX_CRYPTO_PASSPHRASE"`
+}
+
+// AccessToken returns the Matrix access token
+func (c *MatrixConfig) AccessToken() string {
+	return c.accessToken
+}
+
+// SetAccessToken sets the Matrix access token
+func (c *MatrixConfig) SetAccessToken(token string) {
+	c.accessToken = token
+	c.secDirty = true
 }
 
 type LINEConfig struct {
-	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_LINE_ENABLED"`
-	ChannelSecret      string              `json:"channel_secret"          env:"PICOCLAW_CHANNELS_LINE_CHANNEL_SECRET"`
-	ChannelAccessToken string              `json:"channel_access_token"    env:"PICOCLAW_CHANNELS_LINE_CHANNEL_ACCESS_TOKEN"`
+	Enabled            bool `json:"enabled"                 env:"PICOCLAW_CHANNELS_LINE_ENABLED"`
+	channelSecret      string
+	channelAccessToken string
 	WebhookHost        string              `json:"webhook_host"            env:"PICOCLAW_CHANNELS_LINE_WEBHOOK_HOST"`
 	WebhookPort        int                 `json:"webhook_port"            env:"PICOCLAW_CHANNELS_LINE_WEBHOOK_PORT"`
 	WebhookPath        string              `json:"webhook_path"            env:"PICOCLAW_CHANNELS_LINE_WEBHOOK_PATH"`
@@ -315,12 +625,35 @@ type LINEConfig struct {
 	Typing             TypingConfig        `json:"typing,omitempty"`
 	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
 	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_LINE_REASONING_CHANNEL_ID"`
+	secDirty           bool
+}
+
+// ChannelSecret returns the LINE channel secret
+func (c *LINEConfig) ChannelSecret() string {
+	return c.channelSecret
+}
+
+// SetChannelSecret sets the LINE channel secret
+func (c *LINEConfig) SetChannelSecret(secret string) {
+	c.channelSecret = secret
+	c.secDirty = true
+}
+
+// ChannelAccessToken returns the LINE channel access token
+func (c *LINEConfig) ChannelAccessToken() string {
+	return c.channelAccessToken
+}
+
+// SetChannelAccessToken sets the LINE channel access token
+func (c *LINEConfig) SetChannelAccessToken(token string) {
+	c.channelAccessToken = token
+	c.secDirty = true
 }
 
 type OneBotConfig struct {
-	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_ONEBOT_ENABLED"`
-	WSUrl              string              `json:"ws_url"                  env:"PICOCLAW_CHANNELS_ONEBOT_WS_URL"`
-	AccessToken        string              `json:"access_token"            env:"PICOCLAW_CHANNELS_ONEBOT_ACCESS_TOKEN"`
+	Enabled            bool   `json:"enabled"                 env:"PICOCLAW_CHANNELS_ONEBOT_ENABLED"`
+	WSUrl              string `json:"ws_url"                  env:"PICOCLAW_CHANNELS_ONEBOT_WS_URL"`
+	accessToken        string
 	ReconnectInterval  int                 `json:"reconnect_interval"      env:"PICOCLAW_CHANNELS_ONEBOT_RECONNECT_INTERVAL"`
 	GroupTriggerPrefix []string            `json:"group_trigger_prefix"    env:"PICOCLAW_CHANNELS_ONEBOT_GROUP_TRIGGER_PREFIX"`
 	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_ONEBOT_ALLOW_FROM"`
@@ -328,41 +661,71 @@ type OneBotConfig struct {
 	Typing             TypingConfig        `json:"typing,omitempty"`
 	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
 	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_ONEBOT_REASONING_CHANNEL_ID"`
+	secDirty           bool
+}
+
+// AccessToken returns the OneBot access token
+func (c *OneBotConfig) AccessToken() string {
+	return c.accessToken
+}
+
+// SetAccessToken sets the OneBot access token
+func (c *OneBotConfig) SetAccessToken(token string) {
+	c.accessToken = token
+	c.secDirty = true
+}
+
+type WeComGroupConfig struct {
+	AllowFrom FlexibleStringSlice `json:"allow_from,omitempty"`
 }
 
 type WeComConfig struct {
-	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_WECOM_ENABLED"`
-	Token              string              `json:"token"                   env:"PICOCLAW_CHANNELS_WECOM_TOKEN"`
-	EncodingAESKey     string              `json:"encoding_aes_key"        env:"PICOCLAW_CHANNELS_WECOM_ENCODING_AES_KEY"`
-	WebhookURL         string              `json:"webhook_url"             env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_URL"`
-	WebhookHost        string              `json:"webhook_host"            env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_HOST"`
-	WebhookPort        int                 `json:"webhook_port"            env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_PORT"`
-	WebhookPath        string              `json:"webhook_path"            env:"PICOCLAW_CHANNELS_WECOM_WEBHOOK_PATH"`
-	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_WECOM_ALLOW_FROM"`
-	ReplyTimeout       int                 `json:"reply_timeout"           env:"PICOCLAW_CHANNELS_WECOM_REPLY_TIMEOUT"`
-	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
-	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_WECOM_REASONING_CHANNEL_ID"`
+	Enabled             bool   `json:"enabled"                 env:"ENABLED"`
+	BotID               string `json:"bot_id"                  env:"BOT_ID"`
+	secret              string
+	WebSocketURL        string              `json:"websocket_url,omitempty" env:"WEBSOCKET_URL"`
+	SendThinkingMessage bool                `json:"send_thinking_message"   env:"SEND_THINKING_MESSAGE"`
+	AllowFrom           FlexibleStringSlice `json:"allow_from"              env:"ALLOW_FROM"`
+	ReasoningChannelID  string              `json:"reasoning_channel_id"    env:"REASONING_CHANNEL_ID"`
+	secDirty            bool
 }
 
-type WeComAppConfig struct {
-	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_WECOM_APP_ENABLED"`
-	CorpID             string              `json:"corp_id"                 env:"PICOCLAW_CHANNELS_WECOM_APP_CORP_ID"`
-	CorpSecret         string              `json:"corp_secret"             env:"PICOCLAW_CHANNELS_WECOM_APP_CORP_SECRET"`
-	AgentID            int64               `json:"agent_id"                env:"PICOCLAW_CHANNELS_WECOM_APP_AGENT_ID"`
-	Token              string              `json:"token"                   env:"PICOCLAW_CHANNELS_WECOM_APP_TOKEN"`
-	EncodingAESKey     string              `json:"encoding_aes_key"        env:"PICOCLAW_CHANNELS_WECOM_APP_ENCODING_AES_KEY"`
-	WebhookHost        string              `json:"webhook_host"            env:"PICOCLAW_CHANNELS_WECOM_APP_WEBHOOK_HOST"`
-	WebhookPort        int                 `json:"webhook_port"            env:"PICOCLAW_CHANNELS_WECOM_APP_WEBHOOK_PORT"`
-	WebhookPath        string              `json:"webhook_path"            env:"PICOCLAW_CHANNELS_WECOM_APP_WEBHOOK_PATH"`
-	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_WECOM_APP_ALLOW_FROM"`
-	ReplyTimeout       int                 `json:"reply_timeout"           env:"PICOCLAW_CHANNELS_WECOM_APP_REPLY_TIMEOUT"`
-	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
-	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_WECOM_APP_REASONING_CHANNEL_ID"`
+// Secret returns the WeCom bot secret.
+func (c *WeComConfig) Secret() string {
+	return c.secret
+}
+
+// SetSecret sets the WeCom bot secret.
+func (c *WeComConfig) SetSecret(secret string) {
+	c.secret = secret
+	c.secDirty = true
+}
+
+type WeixinConfig struct {
+	Enabled            bool `json:"enabled"              env:"PICOCLAW_CHANNELS_WEIXIN_ENABLED"`
+	token              string
+	AccountID          string              `json:"account_id,omitempty" env:"PICOCLAW_CHANNELS_WEIXIN_ACCOUNT_ID"`
+	BaseURL            string              `json:"base_url"             env:"PICOCLAW_CHANNELS_WEIXIN_BASE_URL"`
+	CDNBaseURL         string              `json:"cdn_base_url"         env:"PICOCLAW_CHANNELS_WEIXIN_CDN_BASE_URL"`
+	Proxy              string              `json:"proxy"                env:"PICOCLAW_CHANNELS_WEIXIN_PROXY"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"           env:"PICOCLAW_CHANNELS_WEIXIN_ALLOW_FROM"`
+	ReasoningChannelID string              `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WEIXIN_REASONING_CHANNEL_ID"`
+	secDirty           bool
+}
+
+func (c *WeixinConfig) Token() string {
+	return c.token
+}
+
+func (c *WeixinConfig) SetToken(token string) *WeixinConfig {
+	c.token = token
+	c.secDirty = true
+	return c
 }
 
 type PicoConfig struct {
-	Enabled         bool                `json:"enabled"                     env:"PICOCLAW_CHANNELS_PICO_ENABLED"`
-	Token           string              `json:"token"                       env:"PICOCLAW_CHANNELS_PICO_TOKEN"`
+	Enabled         bool `json:"enabled"                     env:"PICOCLAW_CHANNELS_PICO_ENABLED"`
+	token           string
 	AllowTokenQuery bool                `json:"allow_token_query,omitempty"`
 	AllowOrigins    []string            `json:"allow_origins,omitempty"`
 	PingInterval    int                 `json:"ping_interval,omitempty"`
@@ -371,6 +734,78 @@ type PicoConfig struct {
 	MaxConnections  int                 `json:"max_connections,omitempty"`
 	AllowFrom       FlexibleStringSlice `json:"allow_from"                  env:"PICOCLAW_CHANNELS_PICO_ALLOW_FROM"`
 	Placeholder     PlaceholderConfig   `json:"placeholder,omitempty"`
+	secDirty        bool
+}
+
+// Token returns the Pico channel token
+func (c *PicoConfig) Token() string {
+	return c.token
+}
+
+// SetToken sets the Pico channel token
+func (c *PicoConfig) SetToken(token string) {
+	c.token = token
+	c.secDirty = true
+}
+
+type PicoClientConfig struct {
+	Enabled      bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_PICO_CLIENT_ENABLED"`
+	URL          string              `json:"url"                     env:"PICOCLAW_CHANNELS_PICO_CLIENT_URL"`
+	Token        string              `json:"token"                   env:"PICOCLAW_CHANNELS_PICO_CLIENT_TOKEN"`
+	SessionID    string              `json:"session_id,omitempty"`
+	PingInterval int                 `json:"ping_interval,omitempty"`
+	ReadTimeout  int                 `json:"read_timeout,omitempty"`
+	AllowFrom    FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_PICO_CLIENT_ALLOW_FROM"`
+}
+
+type IRCConfig struct {
+	Enabled            bool   `json:"enabled"                 env:"PICOCLAW_CHANNELS_IRC_ENABLED"`
+	Server             string `json:"server"                  env:"PICOCLAW_CHANNELS_IRC_SERVER"`
+	TLS                bool   `json:"tls"                     env:"PICOCLAW_CHANNELS_IRC_TLS"`
+	Nick               string `json:"nick"                    env:"PICOCLAW_CHANNELS_IRC_NICK"`
+	User               string `json:"user,omitempty"          env:"PICOCLAW_CHANNELS_IRC_USER"`
+	RealName           string `json:"real_name,omitempty"     env:"PICOCLAW_CHANNELS_IRC_REAL_NAME"`
+	password           string
+	nickServPassword   string
+	SASLUser           string `json:"sasl_user"               env:"PICOCLAW_CHANNELS_IRC_SASL_USER"`
+	saslPassword       string
+	Channels           FlexibleStringSlice `json:"channels"                env:"PICOCLAW_CHANNELS_IRC_CHANNELS"`
+	RequestCaps        FlexibleStringSlice `json:"request_caps,omitempty"  env:"PICOCLAW_CHANNELS_IRC_REQUEST_CAPS"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_IRC_ALLOW_FROM"`
+	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	Typing             TypingConfig        `json:"typing,omitempty"`
+	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_IRC_REASONING_CHANNEL_ID"`
+	secDirty           bool
+}
+
+// Password returns the IRC password
+func (c *IRCConfig) Password() string {
+	return c.password
+}
+
+// NickServPassword returns the NickServ password
+func (c *IRCConfig) NickServPassword() string {
+	return c.nickServPassword
+}
+
+// SASLPassword returns the SASL password
+func (c *IRCConfig) SASLPassword() string {
+	return c.saslPassword
+}
+
+func (c *IRCConfig) SetPassword(password string) {
+	c.password = password
+	c.secDirty = true
+}
+
+func (c *IRCConfig) SetNickServPassword(password string) {
+	c.nickServPassword = password
+	c.secDirty = true
+}
+
+func (c *IRCConfig) SetSASLPassword(password string) {
+	c.saslPassword = password
+	c.secDirty = true
 }
 
 type HeartbeatConfig struct {
@@ -383,78 +818,18 @@ type DevicesConfig struct {
 	MonitorUSB bool `json:"monitor_usb" env:"PICOCLAW_DEVICES_MONITOR_USB"`
 }
 
-type ProvidersConfig struct {
-	Anthropic     ProviderConfig       `json:"anthropic"`
-	OpenAI        OpenAIProviderConfig `json:"openai"`
-	OpenRouter    ProviderConfig       `json:"openrouter"`
-	Groq          ProviderConfig       `json:"groq"`
-	Zhipu         ProviderConfig       `json:"zhipu"`
-	VLLM          ProviderConfig       `json:"vllm"`
-	Gemini        ProviderConfig       `json:"gemini"`
-	Nvidia        ProviderConfig       `json:"nvidia"`
-	Ollama        ProviderConfig       `json:"ollama"`
-	Moonshot      ProviderConfig       `json:"moonshot"`
-	ShengSuanYun  ProviderConfig       `json:"shengsuanyun"`
-	DeepSeek      ProviderConfig       `json:"deepseek"`
-	Cerebras      ProviderConfig       `json:"cerebras"`
-	VolcEngine    ProviderConfig       `json:"volcengine"`
-	GitHubCopilot ProviderConfig       `json:"github_copilot"`
-	Antigravity   ProviderConfig       `json:"antigravity"`
-	Qwen          ProviderConfig       `json:"qwen"`
-	Mistral       ProviderConfig       `json:"mistral"`
-}
-
-// IsEmpty checks if all provider configs are empty (no API keys or API bases set)
-// Note: WebSearch is an optimization option and doesn't count as "non-empty"
-func (p ProvidersConfig) IsEmpty() bool {
-	return p.Anthropic.APIKey == "" && p.Anthropic.APIBase == "" &&
-		p.OpenAI.APIKey == "" && p.OpenAI.APIBase == "" &&
-		p.OpenRouter.APIKey == "" && p.OpenRouter.APIBase == "" &&
-		p.Groq.APIKey == "" && p.Groq.APIBase == "" &&
-		p.Zhipu.APIKey == "" && p.Zhipu.APIBase == "" &&
-		p.VLLM.APIKey == "" && p.VLLM.APIBase == "" &&
-		p.Gemini.APIKey == "" && p.Gemini.APIBase == "" &&
-		p.Nvidia.APIKey == "" && p.Nvidia.APIBase == "" &&
-		p.Ollama.APIKey == "" && p.Ollama.APIBase == "" &&
-		p.Moonshot.APIKey == "" && p.Moonshot.APIBase == "" &&
-		p.ShengSuanYun.APIKey == "" && p.ShengSuanYun.APIBase == "" &&
-		p.DeepSeek.APIKey == "" && p.DeepSeek.APIBase == "" &&
-		p.Cerebras.APIKey == "" && p.Cerebras.APIBase == "" &&
-		p.VolcEngine.APIKey == "" && p.VolcEngine.APIBase == "" &&
-		p.GitHubCopilot.APIKey == "" && p.GitHubCopilot.APIBase == "" &&
-		p.Antigravity.APIKey == "" && p.Antigravity.APIBase == "" &&
-		p.Qwen.APIKey == "" && p.Qwen.APIBase == "" &&
-		p.Mistral.APIKey == "" && p.Mistral.APIBase == ""
-}
-
-// MarshalJSON implements custom JSON marshaling for ProvidersConfig
-// to omit the entire section when empty
-func (p ProvidersConfig) MarshalJSON() ([]byte, error) {
-	if p.IsEmpty() {
-		return []byte("null"), nil
-	}
-	type Alias ProvidersConfig
-	return json.Marshal((*Alias)(&p))
-}
-
-type ProviderConfig struct {
-	APIKey         string `json:"api_key"                   env:"PICOCLAW_PROVIDERS_{{.Name}}_API_KEY"`
-	APIBase        string `json:"api_base"                  env:"PICOCLAW_PROVIDERS_{{.Name}}_API_BASE"`
-	Proxy          string `json:"proxy,omitempty"           env:"PICOCLAW_PROVIDERS_{{.Name}}_PROXY"`
-	RequestTimeout int    `json:"request_timeout,omitempty" env:"PICOCLAW_PROVIDERS_{{.Name}}_REQUEST_TIMEOUT"`
-	AuthMethod     string `json:"auth_method,omitempty"     env:"PICOCLAW_PROVIDERS_{{.Name}}_AUTH_METHOD"`
-	ConnectMode    string `json:"connect_mode,omitempty"    env:"PICOCLAW_PROVIDERS_{{.Name}}_CONNECT_MODE"` // only for Github Copilot, `stdio` or `grpc`
-}
-
-type OpenAIProviderConfig struct {
-	ProviderConfig
-	WebSearch bool `json:"web_search" env:"PICOCLAW_PROVIDERS_OPENAI_WEB_SEARCH"`
+type VoiceConfig struct {
+	ModelName         string `json:"model_name,omitempty"         env:"PICOCLAW_VOICE_MODEL_NAME"`
+	EchoTranscription bool   `json:"echo_transcription"           env:"PICOCLAW_VOICE_ECHO_TRANSCRIPTION"`
+	ElevenLabsAPIKey  string `json:"elevenlabs_api_key,omitempty" env:"PICOCLAW_VOICE_ELEVENLABS_API_KEY"`
 }
 
 // ModelConfig represents a model-centric provider configuration.
 // It allows adding new providers (especially OpenAI-compatible ones) via configuration only.
 // The model field uses protocol prefix format: [protocol/]model-identifier
-// Supported protocols: openai, anthropic, antigravity, claude-cli, codex-cli, github-copilot
+// Supported protocols include openai, anthropic, antigravity, claude-cli,
+// codex-cli, github-copilot, and named OpenAI-compatible protocols such as
+// groq, deepseek, modelscope, and novita.
 // Default protocol is "openai" if no prefix is specified.
 type ModelConfig struct {
 	// Required fields
@@ -462,9 +837,9 @@ type ModelConfig struct {
 	Model     string `json:"model"`      // Protocol/model-identifier (e.g., "openai/gpt-4o", "anthropic/claude-sonnet-4.6")
 
 	// HTTP-based providers
-	APIBase string `json:"api_base,omitempty"` // API endpoint URL
-	APIKey  string `json:"api_key"`            // API authentication key
-	Proxy   string `json:"proxy,omitempty"`    // HTTP proxy URL
+	APIBase   string   `json:"api_base,omitempty"`  // API endpoint URL
+	Proxy     string   `json:"proxy,omitempty"`     // HTTP proxy URL
+	Fallbacks []string `json:"fallbacks,omitempty"` // Fallback model names for failover
 
 	// Special providers (CLI-based, OAuth, etc.)
 	AuthMethod  string `json:"auth_method,omitempty"`  // Authentication method: oauth, token
@@ -472,9 +847,33 @@ type ModelConfig struct {
 	Workspace   string `json:"workspace,omitempty"`    // Workspace path for CLI-based providers
 
 	// Optional optimizations
-	RPM            int    `json:"rpm,omitempty"`              // Requests per minute limit
-	MaxTokensField string `json:"max_tokens_field,omitempty"` // Field name for max tokens (e.g., "max_completion_tokens")
-	RequestTimeout int    `json:"request_timeout,omitempty"`
+	RPM            int            `json:"rpm,omitempty"`              // Requests per minute limit
+	MaxTokensField string         `json:"max_tokens_field,omitempty"` // Field name for max tokens (e.g., "max_completion_tokens")
+	RequestTimeout int            `json:"request_timeout,omitempty"`
+	ThinkingLevel  string         `json:"thinking_level,omitempty"` // Extended thinking: off|low|medium|high|xhigh|adaptive
+	ExtraBody      map[string]any `json:"extra_body,omitempty"`     // Additional fields to inject into request body
+
+	// from security
+	secModelName string
+	apiKeys      []string
+	secDirty     bool
+
+	// isVirtual marks this model as a virtual model generated from multi-key expansion.
+	// Virtual models should not be persisted to config files.
+	isVirtual bool
+}
+
+// APIKey returns the first API key from apiKeys
+func (c *ModelConfig) APIKey() string {
+	if len(c.apiKeys) > 0 {
+		return c.apiKeys[0]
+	}
+	return ""
+}
+
+// IsVirtual returns true if this model was generated from multi-key expansion.
+func (c *ModelConfig) IsVirtual() bool {
+	return c.isVirtual
 }
 
 // Validate checks if the ModelConfig has all required fields.
@@ -488,76 +887,284 @@ func (c *ModelConfig) Validate() error {
 	return nil
 }
 
+func (c *ModelConfig) SetAPIKey(value string) {
+	if len(c.apiKeys) > 0 {
+		c.apiKeys[0] = value
+	} else {
+		c.apiKeys = append(c.apiKeys, value)
+	}
+	c.secDirty = true
+}
+
 type GatewayConfig struct {
-	Host string `json:"host" env:"PICOCLAW_GATEWAY_HOST"`
-	Port int    `json:"port" env:"PICOCLAW_GATEWAY_PORT"`
+	Host      string `json:"host"                env:"PICOCLAW_GATEWAY_HOST"`
+	Port      int    `json:"port"                env:"PICOCLAW_GATEWAY_PORT"`
+	HotReload bool   `json:"hot_reload"          env:"PICOCLAW_GATEWAY_HOT_RELOAD"`
+	LogLevel  string `json:"log_level,omitempty" env:"PICOCLAW_LOG_LEVEL"`
+}
+
+type ToolDiscoveryConfig struct {
+	Enabled          bool `json:"enabled"            env:"PICOCLAW_TOOLS_DISCOVERY_ENABLED"`
+	TTL              int  `json:"ttl"                env:"PICOCLAW_TOOLS_DISCOVERY_TTL"`
+	MaxSearchResults int  `json:"max_search_results" env:"PICOCLAW_MAX_SEARCH_RESULTS"`
+	UseBM25          bool `json:"use_bm25"           env:"PICOCLAW_TOOLS_DISCOVERY_USE_BM25"`
+	UseRegex         bool `json:"use_regex"          env:"PICOCLAW_TOOLS_DISCOVERY_USE_REGEX"`
+}
+
+type ToolConfig struct {
+	Enabled bool `json:"enabled" env:"ENABLED"`
 }
 
 type BraveConfig struct {
-	Enabled    bool   `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_BRAVE_ENABLED"`
-	APIKey     string `json:"api_key"     env:"PICOCLAW_TOOLS_WEB_BRAVE_API_KEY"`
-	MaxResults int    `json:"max_results" env:"PICOCLAW_TOOLS_WEB_BRAVE_MAX_RESULTS"`
+	Enabled    bool `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_BRAVE_ENABLED"`
+	apiKeys    []string
+	secDirty   bool
+	MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_BRAVE_MAX_RESULTS"`
+}
+
+// APIKey returns the Brave API key
+func (c *BraveConfig) APIKey() string {
+	if len(c.apiKeys) == 0 {
+		return ""
+	}
+	return c.apiKeys[0]
+}
+
+// APIKeys returns the Brave API keys
+func (c *BraveConfig) APIKeys() []string {
+	return c.apiKeys
+}
+
+// SetAPIKey sets the Brave API key
+func (c *BraveConfig) SetAPIKey(key string) {
+	c.apiKeys = []string{key}
+	c.secDirty = true
+}
+
+// SetAPIKeys sets the Brave API keys
+func (c *BraveConfig) SetAPIKeys(keys []string) {
+	c.apiKeys = keys
+	c.secDirty = true
 }
 
 type TavilyConfig struct {
-	Enabled    bool   `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_TAVILY_ENABLED"`
-	APIKey     string `json:"api_key"     env:"PICOCLAW_TOOLS_WEB_TAVILY_API_KEY"`
+	Enabled    bool `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_TAVILY_ENABLED"`
+	apiKeys    []string
+	secDirty   bool
 	BaseURL    string `json:"base_url"    env:"PICOCLAW_TOOLS_WEB_TAVILY_BASE_URL"`
 	MaxResults int    `json:"max_results" env:"PICOCLAW_TOOLS_WEB_TAVILY_MAX_RESULTS"`
 }
 
+// APIKey returns the Tavily API key
+func (c *TavilyConfig) APIKey() string {
+	if len(c.apiKeys) == 0 {
+		return ""
+	}
+	return c.apiKeys[0]
+}
+
+// APIKeys returns the Tavily API keys
+func (c *TavilyConfig) APIKeys() []string {
+	return c.apiKeys
+}
+
+// SetAPIKey sets the Tavily API key
+func (c *TavilyConfig) SetAPIKey(key string) {
+	c.apiKeys = []string{key}
+	c.secDirty = true
+}
+
+// SetAPIKeys sets the Tavily API keys
+func (c *TavilyConfig) SetAPIKeys(keys []string) {
+	c.apiKeys = keys
+	c.secDirty = true
+}
+
 type DuckDuckGoConfig struct {
 	Enabled    bool `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_DUCKDUCKGO_ENABLED"`
 	MaxResults int  `json:"max_results" env:"PICOCLAW_TOOLS_WEB_DUCKDUCKGO_MAX_RESULTS"`
 }
 
 type PerplexityConfig struct {
-	Enabled    bool   `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_ENABLED"`
-	APIKey     string `json:"api_key"     env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_API_KEY"`
-	MaxResults int    `json:"max_results" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_MAX_RESULTS"`
+	Enabled    bool `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_ENABLED"`
+	apiKeys    []string
+	secDirty   bool
+	MaxResults int `json:"max_results" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_MAX_RESULTS"`
+}
+
+// APIKey returns the Perplexity API key
+func (c *PerplexityConfig) APIKey() string {
+	if len(c.apiKeys) == 0 {
+		return ""
+	}
+	return c.apiKeys[0]
+}
+
+// SetAPIKey sets the Perplexity API key
+func (c *PerplexityConfig) SetAPIKey(key string) {
+	c.apiKeys = []string{key}
+	c.secDirty = true
+}
+
+// APIKeys returns the Perplexity API keys
+func (c *PerplexityConfig) APIKeys() []string {
+	return c.apiKeys
+}
+
+// SetAPIKeys sets the Perplexity API keys
+func (c *PerplexityConfig) SetAPIKeys(keys []string) {
+	c.apiKeys = keys
+	c.secDirty = true
+}
+
+type SearXNGConfig struct {
+	Enabled    bool   `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_SEARXNG_ENABLED"`
+	BaseURL    string `json:"base_url"    env:"PICOCLAW_TOOLS_WEB_SEARXNG_BASE_URL"`
+	MaxResults int    `json:"max_results" env:"PICOCLAW_TOOLS_WEB_SEARXNG_MAX_RESULTS"`
+}
+
+type GLMSearchConfig struct {
+	Enabled  bool `json:"enabled"  env:"PICOCLAW_TOOLS_WEB_GLM_ENABLED"`
+	apiKey   string
+	secDirty bool
+	BaseURL  string `json:"base_url" env:"PICOCLAW_TOOLS_WEB_GLM_BASE_URL"`
+	// SearchEngine specifies the search backend: "search_std" (default),
+	// "search_pro", "search_pro_sogou", or "search_pro_quark".
+	SearchEngine string `json:"search_engine" env:"PICOCLAW_TOOLS_WEB_GLM_SEARCH_ENGINE"`
+	MaxResults   int    `json:"max_results"   env:"PICOCLAW_TOOLS_WEB_GLM_MAX_RESULTS"`
+}
+
+// APIKey returns the GLM search API key
+func (c *GLMSearchConfig) APIKey() string {
+	return c.apiKey
+}
+
+// SetAPIKey sets the GLM search API key (internal use only)
+func (c *GLMSearchConfig) SetAPIKey(key string) {
+	c.apiKey = key
+	c.secDirty = true
+}
+
+type BaiduSearchConfig struct {
+	Enabled    bool   `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_BAIDU_ENABLED"`
+	BaseURL    string `json:"base_url"    env:"PICOCLAW_TOOLS_WEB_BAIDU_BASE_URL"`
+	MaxResults int    `json:"max_results" env:"PICOCLAW_TOOLS_WEB_BAIDU_MAX_RESULTS"`
+	apiKey     string
+	secDirty   bool
+}
+
+// APIKey returns the Baidu search API key
+func (c *BaiduSearchConfig) APIKey() string {
+	return c.apiKey
+}
+
+func (c *BaiduSearchConfig) SetAPIKey(key string) {
+	c.apiKey = key
+	c.secDirty = true
 }
 
 type WebToolsConfig struct {
-	Brave      BraveConfig      `json:"brave"`
-	Tavily     TavilyConfig     `json:"tavily"`
-	DuckDuckGo DuckDuckGoConfig `json:"duckduckgo"`
-	Perplexity PerplexityConfig `json:"perplexity"`
+	ToolConfig  `                  envPrefix:"PICOCLAW_TOOLS_WEB_"`
+	Brave       BraveConfig       `                                json:"brave"`
+	Tavily      TavilyConfig      `                                json:"tavily"`
+	DuckDuckGo  DuckDuckGoConfig  `                                json:"duckduckgo"`
+	Perplexity  PerplexityConfig  `                                json:"perplexity"`
+	SearXNG     SearXNGConfig     `                                json:"searxng"`
+	GLMSearch   GLMSearchConfig   `                                json:"glm_search"`
+	BaiduSearch BaiduSearchConfig `                                json:"baidu_search"`
+	// PreferNative controls whether to use provider-native web search when
+	// the active LLM supports it (e.g. OpenAI web_search_preview). When true,
+	// the client-side web_search tool is hidden to avoid duplicate search surfaces,
+	// and the provider's built-in search is used instead. Falls back to client-side
+	// search when the provider does not support native search.
+	PreferNative bool `json:"prefer_native" env:"PICOCLAW_TOOLS_WEB_PREFER_NATIVE"`
 	// Proxy is an optional proxy URL for web tools (http/https/socks5/socks5h).
 	// For authenticated proxies, prefer HTTP_PROXY/HTTPS_PROXY env vars instead of embedding credentials in config.
-	Proxy           string `json:"proxy,omitempty"             env:"PICOCLAW_TOOLS_WEB_PROXY"`
-	FetchLimitBytes int64  `json:"fetch_limit_bytes,omitempty" env:"PICOCLAW_TOOLS_WEB_FETCH_LIMIT_BYTES"`
+	Proxy                string              `json:"proxy,omitempty"                  env:"PICOCLAW_TOOLS_WEB_PROXY"`
+	FetchLimitBytes      int64               `json:"fetch_limit_bytes,omitempty"      env:"PICOCLAW_TOOLS_WEB_FETCH_LIMIT_BYTES"`
+	Format               string              `json:"format,omitempty"                 env:"PICOCLAW_TOOLS_WEB_FORMAT"`
+	PrivateHostWhitelist FlexibleStringSlice `json:"private_host_whitelist,omitempty" env:"PICOCLAW_TOOLS_WEB_PRIVATE_HOST_WHITELIST"`
 }
 
 type CronToolsConfig struct {
-	ExecTimeoutMinutes int `json:"exec_timeout_minutes" env:"PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES"` // 0 means no timeout
+	ToolConfig         `     envPrefix:"PICOCLAW_TOOLS_CRON_"`
+	ExecTimeoutMinutes int  `                                 env:"PICOCLAW_TOOLS_CRON_EXEC_TIMEOUT_MINUTES" json:"exec_timeout_minutes"` // 0 means no timeout
+	AllowCommand       bool `                                 env:"PICOCLAW_TOOLS_CRON_ALLOW_COMMAND"        json:"allow_command"`
 }
 
 type ExecConfig struct {
-	EnableDenyPatterns  bool     `json:"enable_deny_patterns"  env:"PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS"`
-	CustomDenyPatterns  []string `json:"custom_deny_patterns"  env:"PICOCLAW_TOOLS_EXEC_CUSTOM_DENY_PATTERNS"`
-	CustomAllowPatterns []string `json:"custom_allow_patterns" env:"PICOCLAW_TOOLS_EXEC_CUSTOM_ALLOW_PATTERNS"`
+	ToolConfig          `         envPrefix:"PICOCLAW_TOOLS_EXEC_"`
+	EnableDenyPatterns  bool     `                                 env:"PICOCLAW_TOOLS_EXEC_ENABLE_DENY_PATTERNS"  json:"enable_deny_patterns"`
+	AllowRemote         bool     `                                 env:"PICOCLAW_TOOLS_EXEC_ALLOW_REMOTE"          json:"allow_remote"`
+	CustomDenyPatterns  []string `                                 env:"PICOCLAW_TOOLS_EXEC_CUSTOM_DENY_PATTERNS"  json:"custom_deny_patterns"`
+	CustomAllowPatterns []string `                                 env:"PICOCLAW_TOOLS_EXEC_CUSTOM_ALLOW_PATTERNS" json:"custom_allow_patterns"`
+	TimeoutSeconds      int      `                                 env:"PICOCLAW_TOOLS_EXEC_TIMEOUT_SECONDS"       json:"timeout_seconds"` // 0 means use default (60s)
+}
+
+type SkillsToolsConfig struct {
+	ToolConfig            `                       envPrefix:"PICOCLAW_TOOLS_SKILLS_"`
+	Registries            SkillsRegistriesConfig `                                   json:"registries"`
+	Github                SkillsGithubConfig     `                                   json:"github"`
+	MaxConcurrentSearches int                    `                                   json:"max_concurrent_searches" env:"PICOCLAW_TOOLS_SKILLS_MAX_CONCURRENT_SEARCHES"`
+	SearchCache           SearchCacheConfig      `                                   json:"search_cache"`
 }
 
 type MediaCleanupConfig struct {
-	Enabled  bool `json:"enabled"          env:"PICOCLAW_MEDIA_CLEANUP_ENABLED"`
-	MaxAge   int  `json:"max_age_minutes"  env:"PICOCLAW_MEDIA_CLEANUP_MAX_AGE"`
-	Interval int  `json:"interval_minutes" env:"PICOCLAW_MEDIA_CLEANUP_INTERVAL"`
+	ToolConfig `    envPrefix:"PICOCLAW_MEDIA_CLEANUP_"`
+	MaxAge     int `                                    env:"PICOCLAW_MEDIA_CLEANUP_MAX_AGE"  json:"max_age_minutes"`
+	Interval   int `                                    env:"PICOCLAW_MEDIA_CLEANUP_INTERVAL" json:"interval_minutes"`
+}
+
+type ReadFileToolConfig struct {
+	Enabled         bool `json:"enabled"`
+	MaxReadFileSize int  `json:"max_read_file_size"`
 }
 
 type ToolsConfig struct {
-	AllowReadPaths  []string           `json:"allow_read_paths"  env:"PICOCLAW_TOOLS_ALLOW_READ_PATHS"`
-	AllowWritePaths []string           `json:"allow_write_paths" env:"PICOCLAW_TOOLS_ALLOW_WRITE_PATHS"`
+	AllowReadPaths  []string `json:"allow_read_paths"  env:"PICOCLAW_TOOLS_ALLOW_READ_PATHS"`
+	AllowWritePaths []string `json:"allow_write_paths" env:"PICOCLAW_TOOLS_ALLOW_WRITE_PATHS"`
+	// FilterSensitiveData controls whether to filter sensitive values (API keys,
+	// tokens, secrets) from tool results before sending to the LLM.
+	// Default: true (enabled)
+	FilterSensitiveData bool `json:"filter_sensitive_data" env:"PICOCLAW_TOOLS_FILTER_SENSITIVE_DATA"`
+	// FilterMinLength is the minimum content length required for filtering.
+	// Content shorter than this will be returned unchanged for performance.
+	// Default: 8
+	FilterMinLength int                `json:"filter_min_length" env:"PICOCLAW_TOOLS_FILTER_MIN_LENGTH"`
 	Web             WebToolsConfig     `json:"web"`
 	Cron            CronToolsConfig    `json:"cron"`
 	Exec            ExecConfig         `json:"exec"`
 	Skills          SkillsToolsConfig  `json:"skills"`
 	MediaCleanup    MediaCleanupConfig `json:"media_cleanup"`
+	MCP             MCPConfig          `json:"mcp"`
+	AppendFile      ToolConfig         `json:"append_file"                                              envPrefix:"PICOCLAW_TOOLS_APPEND_FILE_"`
+	EditFile        ToolConfig         `json:"edit_file"                                                envPrefix:"PICOCLAW_TOOLS_EDIT_FILE_"`
+	FindSkills      ToolConfig         `json:"find_skills"                                              envPrefix:"PICOCLAW_TOOLS_FIND_SKILLS_"`
+	I2C             ToolConfig         `json:"i2c"                                                      envPrefix:"PICOCLAW_TOOLS_I2C_"`
+	InstallSkill    ToolConfig         `json:"install_skill"                                            envPrefix:"PICOCLAW_TOOLS_INSTALL_SKILL_"`
+	ListDir         ToolConfig         `json:"list_dir"                                                 envPrefix:"PICOCLAW_TOOLS_LIST_DIR_"`
+	Message         ToolConfig         `json:"message"                                                  envPrefix:"PICOCLAW_TOOLS_MESSAGE_"`
+	ReadFile        ReadFileToolConfig `json:"read_file"                                                envPrefix:"PICOCLAW_TOOLS_READ_FILE_"`
+	SendFile        ToolConfig         `json:"send_file"                                                envPrefix:"PICOCLAW_TOOLS_SEND_FILE_"`
+	Spawn           ToolConfig         `json:"spawn"                                                    envPrefix:"PICOCLAW_TOOLS_SPAWN_"`
+	SpawnStatus     ToolConfig         `json:"spawn_status"                                             envPrefix:"PICOCLAW_TOOLS_SPAWN_STATUS_"`
+	SPI             ToolConfig         `json:"spi"                                                      envPrefix:"PICOCLAW_TOOLS_SPI_"`
+	Subagent        ToolConfig         `json:"subagent"                                                 envPrefix:"PICOCLAW_TOOLS_SUBAGENT_"`
+	WebFetch        ToolConfig         `json:"web_fetch"                                                envPrefix:"PICOCLAW_TOOLS_WEB_FETCH_"`
+	WriteFile       ToolConfig         `json:"write_file"                                               envPrefix:"PICOCLAW_TOOLS_WRITE_FILE_"`
 }
 
-type SkillsToolsConfig struct {
-	Registries            SkillsRegistriesConfig `json:"registries"`
-	MaxConcurrentSearches int                    `json:"max_concurrent_searches" env:"PICOCLAW_SKILLS_MAX_CONCURRENT_SEARCHES"`
-	SearchCache           SearchCacheConfig      `json:"search_cache"`
+// IsFilterSensitiveDataEnabled returns true if sensitive data filtering is enabled
+func (c *ToolsConfig) IsFilterSensitiveDataEnabled() bool {
+	return c.FilterSensitiveData
+}
+
+// GetFilterMinLength returns the minimum content length for filtering (default: 8)
+func (c *ToolsConfig) GetFilterMinLength() int {
+	if c.FilterMinLength <= 0 {
+		return 8
+	}
+	return c.FilterMinLength
 }
 
 type SearchCacheConfig struct {
@@ -569,10 +1176,28 @@ type SkillsRegistriesConfig struct {
 	ClawHub ClawHubRegistryConfig `json:"clawhub"`
 }
 
+type SkillsGithubConfig struct {
+	token    string
+	secDirty bool
+	Proxy    string `json:"proxy,omitempty" env:"PICOCLAW_TOOLS_SKILLS_GITHUB_PROXY"`
+}
+
+// Token returns the GitHub token
+func (c *SkillsGithubConfig) Token() string {
+	return c.token
+}
+
+// SetToken sets the GitHub token
+func (c *SkillsGithubConfig) SetToken(token string) {
+	c.token = token
+	c.secDirty = true
+}
+
 type ClawHubRegistryConfig struct {
 	Enabled         bool   `json:"enabled"           env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_ENABLED"`
 	BaseURL         string `json:"base_url"          env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_BASE_URL"`
-	AuthToken       string `json:"auth_token"        env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_AUTH_TOKEN"`
+	authToken       string
+	secDirty        bool
 	SearchPath      string `json:"search_path"       env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_SEARCH_PATH"`
 	SkillsPath      string `json:"skills_path"       env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_SKILLS_PATH"`
 	DownloadPath    string `json:"download_path"     env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_DOWNLOAD_PATH"`
@@ -581,55 +1206,429 @@ type ClawHubRegistryConfig struct {
 	MaxResponseSize int    `json:"max_response_size" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_MAX_RESPONSE_SIZE"`
 }
 
-func LoadConfig(path string) (*Config, error) {
-	cfg := DefaultConfig()
+// AuthToken returns the ClawHub auth token
+func (c *ClawHubRegistryConfig) AuthToken() string {
+	return c.authToken
+}
 
+// SetAuthToken sets the ClawHub auth token
+func (c *ClawHubRegistryConfig) SetAuthToken(token string) {
+	c.authToken = token
+	c.secDirty = true
+}
+
+// MCPServerConfig defines configuration for a single MCP server
+type MCPServerConfig struct {
+	// Enabled indicates whether this MCP server is active
+	Enabled bool `json:"enabled"`
+	// Deferred controls whether this server's tools are registered as hidden (deferred/discovery mode).
+	// When nil, the global Discovery.Enabled setting applies.
+	// When explicitly set to true or false, it overrides the global setting for this server only.
+	Deferred *bool `json:"deferred,omitempty"`
+	// Command is the executable to run (e.g., "npx", "python", "/path/to/server")
+	Command string `json:"command"`
+	// Args are the arguments to pass to the command
+	Args []string `json:"args,omitempty"`
+	// Env are environment variables to set for the server process (stdio only)
+	Env map[string]string `json:"env,omitempty"`
+	// EnvFile is the path to a file containing environment variables (stdio only)
+	EnvFile string `json:"env_file,omitempty"`
+	// Type is "stdio", "sse", or "http" (default: stdio if command is set, sse if url is set)
+	Type string `json:"type,omitempty"`
+	// URL is used for SSE/HTTP transport
+	URL string `json:"url,omitempty"`
+	// Headers are HTTP headers to send with requests (sse/http only)
+	Headers map[string]string `json:"headers,omitempty"`
+}
+
+// MCPConfig defines configuration for all MCP servers
+type MCPConfig struct {
+	ToolConfig `                    envPrefix:"PICOCLAW_TOOLS_MCP_"`
+	Discovery  ToolDiscoveryConfig `                                json:"discovery"`
+	// Servers is a map of server name to server configuration
+	Servers map[string]MCPServerConfig `json:"servers,omitempty"`
+}
+
+func LoadConfig(path string) (*Config, error) {
+	logger.Debugf("loading config from %s", path)
 	data, err := os.ReadFile(path)
 	if err != nil {
 		if os.IsNotExist(err) {
-			return cfg, nil
+			logger.WarnF("config file not found, using default config", map[string]any{"path": path})
+			return DefaultConfig(), nil
 		}
+		logger.Errorf("failed to read config file: %v", err)
 		return nil, err
 	}
 
-	// Pre-scan the JSON to check how many model_list entries the user provided.
-	// Go's JSON decoder reuses existing slice backing-array elements rather than
-	// zero-initializing them, so fields absent from the user's JSON (e.g. api_base)
-	// would silently inherit values from the DefaultConfig template at the same
-	// index position. We only reset cfg.ModelList when the user actually provides
-	// entries; when count is 0 we keep DefaultConfig's built-in list as fallback.
-	var tmp Config
-	if err := json.Unmarshal(data, &tmp); err != nil {
-		return nil, err
+	// First, try to detect config version by reading the version field
+	var versionInfo struct {
+		Version int `json:"version"`
 	}
-	if len(tmp.ModelList) > 0 {
-		cfg.ModelList = nil
+	if e := json.Unmarshal(data, &versionInfo); e != nil {
+		return nil, fmt.Errorf("failed to detect config version: %w", e)
+	}
+	if len(data) <= 10 {
+		logger.Warn(fmt.Sprintf("content is [%s]", string(data)))
+		return DefaultConfig().WithSecurity(&SecurityConfig{}), nil
 	}
 
-	if err := json.Unmarshal(data, cfg); err != nil {
-		return nil, err
+	// Load config based on detected version
+	var cfg *Config
+	switch versionInfo.Version {
+	case 0:
+		logger.InfoF("config migrate start", map[string]any{"from": versionInfo.Version, "to": CurrentVersion})
+		// Legacy config (no version field)
+		v, e := loadConfigV0(data)
+		if e != nil {
+			return nil, e
+		}
+		cfg, e = v.Migrate()
+		if e != nil {
+			logger.ErrorF("config migrate fail", map[string]any{"from": versionInfo.Version, "to": CurrentVersion})
+			return nil, e
+		}
+		logger.InfoF("config migrate success", map[string]any{"from": versionInfo.Version, "to": CurrentVersion})
+		err = makeBackup(path)
+		if err != nil {
+			return nil, err
+		}
+		// Load existing security config and merge with migrated one to prevent data loss
+		existingSec, secErr := loadSecurityConfig(securityPath(path))
+		if secErr != nil {
+			logger.WarnF("failed to load existing security config during migration", map[string]any{"error": secErr})
+		}
+		if existingSec != nil && cfg.security != nil {
+			cfg.security = mergeSecurityConfig(existingSec, cfg.security)
+			// Re-apply the merged security config to update all channels and models
+			if err = applySecurityConfig(cfg, cfg.security); err != nil {
+				logger.WarnF("failed to re-apply merged security config during migration", map[string]any{"error": err})
+			}
+		}
+		defer func(cfg *Config) {
+			_ = SaveConfig(path, cfg)
+		}(cfg)
+	case CurrentVersion:
+		// Current version
+		cfg, err = loadConfig(data)
+		if err != nil {
+			return nil, err
+		}
+		// Load security configuration
+		securityPath := securityPath(path)
+		sec, err := loadSecurityConfig(securityPath)
+		if err != nil {
+			return nil, fmt.Errorf("failed to load security config: %w", err)
+		}
+
+		// Apply security references from .security.yml BEFORE resolveAPIKeys
+		// This resolves ref: references to actual values
+		if err := applySecurityConfig(cfg, sec); err != nil {
+			return nil, fmt.Errorf("failed to apply security config: %w", err)
+		}
+	default:
+		return nil, fmt.Errorf("unsupported config version: %d", versionInfo.Version)
+	}
+
+	if passphrase := credential.PassphraseProvider(); passphrase != "" {
+		for _, m := range cfg.ModelList {
+			for _, k := range m.apiKeys {
+				if k != "" && !strings.HasPrefix(k, "enc://") && !strings.HasPrefix(k, "file://") {
+					fmt.Fprintf(os.Stderr,
+						"picoclaw: warning: model %q has a plaintext api_key; call SaveConfig to encrypt it\n",
+						m.ModelName)
+					break // Only warn once per model
+				}
+			}
+		}
 	}
 
 	if err := env.Parse(cfg); err != nil {
 		return nil, err
 	}
 
+	if err := resolveAPIKeys(cfg.ModelList, filepath.Dir(path)); err != nil {
+		return nil, err
+	}
+
+	// Resolve security fields like authToken that may contain file:// references
+	if err := resolveSecurityFields(cfg, filepath.Dir(path)); err != nil {
+		return nil, err
+	}
+
+	// Expand multi-key configs into separate entries for key-level failover
+	cfg.ModelList = expandMultiKeyModels(cfg.ModelList)
+
 	// Migrate legacy channel config fields to new unified structures
 	cfg.migrateChannelConfigs()
 
-	// Auto-migrate: if only legacy providers config exists, convert to model_list
-	if len(cfg.ModelList) == 0 && cfg.HasProvidersConfig() {
-		cfg.ModelList = ConvertProvidersToModelList(cfg)
-	}
-
 	// Validate model_list for uniqueness and required fields
 	if err := cfg.ValidateModelList(); err != nil {
 		return nil, err
 	}
 
+	// Ensure Workspace has a default if not set
+	if cfg.Agents.Defaults.Workspace == "" {
+		homePath, _ := os.UserHomeDir()
+		if picoclawHome := os.Getenv(EnvHome); picoclawHome != "" {
+			homePath = picoclawHome
+		} else if homePath != "" {
+			homePath = filepath.Join(homePath, pkg.DefaultPicoClawHome)
+		}
+		cfg.Agents.Defaults.Workspace = filepath.Join(homePath, pkg.WorkspaceName)
+	}
+
 	return cfg, nil
 }
 
+func makeBackup(path string) error {
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		return nil
+	}
+	// Create backup of the config file before migration
+	bakPath := path + ".bak"
+	if err := fileutil.CopyFile(path, bakPath, 0o600); err != nil {
+		logger.ErrorF("failed to create config backup", map[string]any{"error": err})
+		return fmt.Errorf("failed to create config backup: %w", err)
+	}
+	return nil
+}
+
+func copyArray[T any](dst, src *[]T) {
+	*dst = make([]T, len(*src))
+	copy(*dst, *src)
+}
+
+// applySecurityConfig resolves all security references in config
+// It checks each field for "ref:" prefixed values and resolves them from .security.yml
+func applySecurityConfig(cfg *Config, sec *SecurityConfig) error {
+	if sec == nil {
+		return nil
+	}
+
+	if sec.Web != nil {
+		if sec.Web.Brave != nil && len(sec.Web.Brave.APIKeys) > 0 {
+			copyArray(&cfg.Tools.Web.Brave.apiKeys, &sec.Web.Brave.APIKeys)
+		}
+
+		if sec.Web.Tavily != nil && len(sec.Web.Tavily.APIKeys) > 0 {
+			copyArray(&cfg.Tools.Web.Tavily.apiKeys, &sec.Web.Tavily.APIKeys)
+		}
+
+		if sec.Web.Perplexity != nil && len(sec.Web.Perplexity.APIKeys) > 0 {
+			copyArray(&cfg.Tools.Web.Perplexity.apiKeys, &sec.Web.Perplexity.APIKeys)
+		}
+
+		if sec.Web.GLMSearch != nil && sec.Web.GLMSearch.APIKey != "" {
+			cfg.Tools.Web.GLMSearch.apiKey = sec.Web.GLMSearch.APIKey
+		}
+
+		if sec.Web.BaiduSearch != nil && sec.Web.BaiduSearch.APIKey != "" {
+			cfg.Tools.Web.BaiduSearch.apiKey = sec.Web.BaiduSearch.APIKey
+		}
+	}
+
+	if sec.Skills != nil {
+		if sec.Skills.Github != nil && sec.Skills.Github.Token != "" {
+			cfg.Tools.Skills.Github.token = sec.Skills.Github.Token
+		}
+
+		if sec.Skills.ClawHub != nil && sec.Skills.ClawHub.AuthToken != "" {
+			cfg.Tools.Skills.Registries.ClawHub.authToken = sec.Skills.ClawHub.AuthToken
+		}
+	}
+
+	names := toNameIndex(cfg.ModelList)
+	for i, model := range cfg.ModelList {
+		// Try exact match first (e.g., "abc:0" -> "abc:0")
+		if entry, exists := sec.ModelList[names[i]]; exists {
+			copyArray(&model.apiKeys, &entry.APIKeys)
+			model.secModelName = names[i]
+			continue
+		}
+
+		// Try match without index suffix (e.g., "abc" -> "abc")
+		// This allows .security.yml to use simpler keys like "test-model" instead of "test-model:0"
+		baseName := model.ModelName
+		if entry, exists := sec.ModelList[baseName]; exists {
+			copyArray(&model.apiKeys, &entry.APIKeys)
+			model.secModelName = baseName
+			continue
+		}
+	}
+
+	if sec.Channels != nil {
+		// Handle Telegram token
+		if sec.Channels.Telegram != nil && sec.Channels.Telegram.Token != "" {
+			cfg.Channels.Telegram.token = sec.Channels.Telegram.Token
+		}
+
+		// Handle Feishu credentials
+		if sec.Channels.Feishu != nil {
+			if sec.Channels.Feishu.AppSecret != "" {
+				cfg.Channels.Feishu.appSecret = sec.Channels.Feishu.AppSecret
+			}
+			if sec.Channels.Feishu.EncryptKey != "" {
+				cfg.Channels.Feishu.encryptKey = sec.Channels.Feishu.EncryptKey
+			}
+			if sec.Channels.Feishu.VerificationToken != "" {
+				cfg.Channels.Feishu.verificationToken = sec.Channels.Feishu.VerificationToken
+			}
+		}
+
+		// Handle Discord token
+		if sec.Channels.Discord != nil && sec.Channels.Discord.Token != "" {
+			cfg.Channels.Discord.token = sec.Channels.Discord.Token
+		}
+
+		// Handle Weixin token
+		if sec.Channels.Weixin != nil && sec.Channels.Weixin.Token != "" {
+			cfg.Channels.Weixin.token = sec.Channels.Weixin.Token
+		}
+
+		// Handle DingTalk client secret
+		if sec.Channels.DingTalk != nil && sec.Channels.DingTalk.ClientSecret != "" {
+			cfg.Channels.DingTalk.clientSecret = sec.Channels.DingTalk.ClientSecret
+		}
+
+		// Handle Slack tokens
+		if sec.Channels.Slack != nil {
+			if sec.Channels.Slack.BotToken != "" {
+				cfg.Channels.Slack.botToken = sec.Channels.Slack.BotToken
+			}
+			if sec.Channels.Slack.AppToken != "" {
+				cfg.Channels.Slack.appToken = sec.Channels.Slack.AppToken
+			}
+		}
+
+		// Handle Matrix access token
+		if sec.Channels.Matrix != nil && sec.Channels.Matrix.AccessToken != "" {
+			cfg.Channels.Matrix.accessToken = sec.Channels.Matrix.AccessToken
+		}
+
+		// Handle LINE credentials
+		if sec.Channels.LINE != nil {
+			if sec.Channels.LINE.ChannelSecret != "" {
+				cfg.Channels.LINE.channelSecret = sec.Channels.LINE.ChannelSecret
+			}
+			if sec.Channels.LINE.ChannelAccessToken != "" {
+				cfg.Channels.LINE.channelAccessToken = sec.Channels.LINE.ChannelAccessToken
+			}
+		}
+
+		// Handle OneBot access token
+		if sec.Channels.OneBot != nil && sec.Channels.OneBot.AccessToken != "" {
+			cfg.Channels.OneBot.accessToken = sec.Channels.OneBot.AccessToken
+		}
+
+		// Handle WeCom bot secret
+		if sec.Channels.WeCom != nil {
+			if sec.Channels.WeCom.Secret != "" {
+				cfg.Channels.WeCom.secret = sec.Channels.WeCom.Secret
+			}
+		}
+
+		// Handle Pico channel token
+		if sec.Channels.Pico != nil && sec.Channels.Pico.Token != "" {
+			cfg.Channels.Pico.token = sec.Channels.Pico.Token
+		}
+
+		// Handle IRC passwords
+		if sec.Channels.IRC != nil {
+			if sec.Channels.IRC.Password != "" {
+				cfg.Channels.IRC.password = sec.Channels.IRC.Password
+			}
+			if sec.Channels.IRC.NickServPassword != "" {
+				cfg.Channels.IRC.nickServPassword = sec.Channels.IRC.NickServPassword
+			}
+			if sec.Channels.IRC.SASLPassword != "" {
+				cfg.Channels.IRC.saslPassword = sec.Channels.IRC.SASLPassword
+			}
+		}
+
+		// Handle QQ app secret
+		if sec.Channels.QQ != nil && sec.Channels.QQ.AppSecret != "" {
+			cfg.Channels.QQ.appSecret = sec.Channels.QQ.AppSecret
+		}
+	}
+
+	cfg.security = sec
+
+	return nil
+}
+
+func toNameIndex(list []*ModelConfig) []string {
+	nameList := make([]string, 0, len(list))
+	countMap := make(map[string]int)
+	for _, model := range list {
+		name := model.ModelName
+		index := countMap[name]
+		nameList = append(nameList, fmt.Sprintf("%s:%d", name, index))
+		countMap[name]++
+	}
+	return nameList
+}
+
+// encryptPlaintextAPIKeys returns a copy of models with plaintext api_key values
+// encrypted. Returns (nil, nil) when nothing changed (all keys already sealed or
+// empty). Returns (nil, error) if any key fails to encrypt — callers must treat
+// this as a hard failure to prevent a mixed plaintext/ciphertext state on disk.
+// Symmetric counterpart of resolveAPIKeys: both operate purely on []ModelConfig
+// and leave JSON marshaling to the caller.
+func encryptPlaintextAPIKeys(
+	models map[string]ModelSecurityEntry,
+	passphrase string,
+) (map[string]ModelSecurityEntry, error) {
+	sealed := make(map[string]ModelSecurityEntry, len(models))
+	changed := false
+	for k, m := range models {
+		sealedEntry := ModelSecurityEntry{APIKeys: make([]string, len(m.APIKeys))}
+
+		// Encrypt each key in APIKeys
+		for i, key := range m.APIKeys {
+			if key == "" || strings.HasPrefix(key, "enc://") || strings.HasPrefix(key, "file://") {
+				sealedEntry.APIKeys[i] = key
+				continue
+			}
+			encrypted, err := credential.Encrypt(passphrase, "", key)
+			if err != nil {
+				return nil, fmt.Errorf("cannot seal api_key for model %q: %w", k, err)
+			}
+			sealedEntry.APIKeys[i] = encrypted
+			changed = true
+		}
+
+		sealed[k] = sealedEntry
+	}
+	if !changed {
+		return nil, nil
+	}
+	return sealed, nil
+}
+
+// resolveAPIKeys decrypts or dereferences each api_key in models in-place.
+// Supports plaintext (no-op), file:// (read from configDir), and enc:// (AES-GCM decrypt).
+func resolveAPIKeys(models []*ModelConfig, configDir string) error {
+	cr := credential.NewResolver(configDir)
+	for i := range models {
+		// Resolve APIKeys array
+		for j, key := range models[i].apiKeys {
+			resolved, err := cr.Resolve(key)
+			if err != nil {
+				return fmt.Errorf(
+					"model_list[%d] (%s): api_keys[%d]: %w",
+					i,
+					models[i].ModelName,
+					j,
+					err,
+				)
+			}
+			models[i].apiKeys[j] = resolved
+		}
+	}
+	return nil
+}
+
 func (c *Config) migrateChannelConfigs() {
 	// Discord: mention_only -> group_trigger.mention_only
 	if c.Channels.Discord.MentionOnly && !c.Channels.Discord.GroupTrigger.MentionOnly {
@@ -637,18 +1636,197 @@ func (c *Config) migrateChannelConfigs() {
 	}
 
 	// OneBot: group_trigger_prefix -> group_trigger.prefixes
-	if len(c.Channels.OneBot.GroupTriggerPrefix) > 0 && len(c.Channels.OneBot.GroupTrigger.Prefixes) == 0 {
+	if len(c.Channels.OneBot.GroupTriggerPrefix) > 0 &&
+		len(c.Channels.OneBot.GroupTrigger.Prefixes) == 0 {
 		c.Channels.OneBot.GroupTrigger.Prefixes = c.Channels.OneBot.GroupTriggerPrefix
 	}
 }
 
 func SaveConfig(path string, cfg *Config) error {
-	data, err := json.MarshalIndent(cfg, "", "  ")
-	if err != nil {
+	if cfg.security == nil {
+		logger.Errorf("config %#v", *cfg)
+		if len(cfg.ModelList) > 0 {
+			logger.Errorf("model[0] %#v", cfg.ModelList[0])
+		}
+		logger.ErrorC("config", "security is nil")
+		return fmt.Errorf("security is nil")
+	}
+	cfg.security = normalizeSecurityConfig(cfg.security)
+	// Ensure version is always set when saving
+	if cfg.Version == 0 {
+		cfg.Version = CurrentVersion
+	}
+	names := toNameIndex(cfg.ModelList)
+	for i, m := range cfg.ModelList {
+		if m.secDirty {
+			if m.secModelName == "" {
+				m.secModelName = names[i]
+			}
+			cfg.security.ModelList[m.secModelName] = ModelSecurityEntry{
+				APIKeys: m.apiKeys,
+			}
+			m.secDirty = false
+		}
+	}
+	if cfg.Channels.Pico.secDirty {
+		cfg.security.Channels.Pico = &PicoSecurity{
+			Token: cfg.Channels.Pico.Token(),
+		}
+		cfg.Channels.Pico.secDirty = false
+	}
+	if cfg.Channels.IRC.secDirty {
+		cfg.security.Channels.IRC = &IRCSecurity{
+			Password:         cfg.Channels.IRC.password,
+			NickServPassword: cfg.Channels.IRC.nickServPassword,
+			SASLPassword:     cfg.Channels.IRC.saslPassword,
+		}
+		cfg.Channels.IRC.secDirty = false
+	}
+	if cfg.Channels.Telegram.secDirty {
+		cfg.security.Channels.Telegram = &TelegramSecurity{
+			Token: cfg.Channels.Telegram.Token(),
+		}
+		cfg.Channels.Telegram.secDirty = false
+	}
+	if cfg.Channels.Feishu.secDirty {
+		cfg.security.Channels.Feishu = &FeishuSecurity{
+			AppSecret:         cfg.Channels.Feishu.AppSecret(),
+			EncryptKey:        cfg.Channels.Feishu.EncryptKey(),
+			VerificationToken: cfg.Channels.Feishu.VerificationToken(),
+		}
+		cfg.Channels.Feishu.secDirty = false
+	}
+	if cfg.Channels.Discord.secDirty {
+		cfg.security.Channels.Discord = &DiscordSecurity{
+			Token: cfg.Channels.Discord.Token(),
+		}
+		cfg.Channels.Discord.secDirty = false
+	}
+	if cfg.Channels.Weixin.secDirty {
+		cfg.security.Channels.Weixin = &WeixinSecurity{
+			Token: cfg.Channels.Weixin.Token(),
+		}
+		cfg.Channels.Discord.secDirty = false
+	}
+	if cfg.Channels.QQ.secDirty {
+		cfg.security.Channels.QQ = &QQSecurity{
+			AppSecret: cfg.Channels.QQ.AppSecret(),
+		}
+		cfg.Channels.QQ.secDirty = false
+	}
+	if cfg.Channels.DingTalk.secDirty {
+		cfg.security.Channels.DingTalk = &DingTalkSecurity{
+			ClientSecret: cfg.Channels.DingTalk.ClientSecret(),
+		}
+		cfg.Channels.DingTalk.secDirty = false
+	}
+	if cfg.Channels.Slack.secDirty {
+		cfg.security.Channels.Slack = &SlackSecurity{
+			BotToken: cfg.Channels.Slack.BotToken(),
+			AppToken: cfg.Channels.Slack.AppToken(),
+		}
+		cfg.Channels.Slack.secDirty = false
+	}
+	if cfg.Channels.Matrix.secDirty {
+		cfg.security.Channels.Matrix = &MatrixSecurity{
+			AccessToken: cfg.Channels.Matrix.AccessToken(),
+		}
+		cfg.Channels.Matrix.secDirty = false
+	}
+	if cfg.Channels.LINE.secDirty {
+		cfg.security.Channels.LINE = &LINESecurity{
+			ChannelSecret:      cfg.Channels.LINE.ChannelSecret(),
+			ChannelAccessToken: cfg.Channels.LINE.ChannelAccessToken(),
+		}
+		cfg.Channels.LINE.secDirty = false
+	}
+	if cfg.Channels.OneBot.secDirty {
+		cfg.security.Channels.OneBot = &OneBotSecurity{
+			AccessToken: cfg.Channels.OneBot.AccessToken(),
+		}
+		cfg.Channels.OneBot.secDirty = false
+	}
+	if cfg.Channels.WeCom.secDirty {
+		cfg.security.Channels.WeCom = &WeComSecurity{
+			Secret: cfg.Channels.WeCom.Secret(),
+		}
+		cfg.Channels.WeCom.secDirty = false
+	}
+	if cfg.Tools.Web.Brave.secDirty {
+		cfg.security.Web.Brave = &BraveSecurity{
+			APIKeys: cfg.Tools.Web.Brave.APIKeys(),
+		}
+		cfg.Tools.Web.Brave.secDirty = false
+	}
+	if cfg.Tools.Web.Tavily.secDirty {
+		cfg.security.Web.Tavily = &TavilySecurity{
+			APIKeys: cfg.Tools.Web.Tavily.APIKeys(),
+		}
+		cfg.Tools.Web.Tavily.secDirty = false
+	}
+	if cfg.Tools.Web.Perplexity.secDirty {
+		cfg.security.Web.Perplexity = &PerplexitySecurity{
+			APIKeys: cfg.Tools.Web.Perplexity.APIKeys(),
+		}
+		cfg.Tools.Web.Perplexity.secDirty = false
+	}
+	if cfg.Tools.Web.GLMSearch.secDirty {
+		cfg.security.Web.GLMSearch = &GLMSearchSecurity{
+			APIKey: cfg.Tools.Web.GLMSearch.APIKey(),
+		}
+		cfg.Tools.Web.GLMSearch.secDirty = false
+	}
+	if cfg.Tools.Web.BaiduSearch.secDirty {
+		cfg.security.Web.BaiduSearch = &BaiduSearchSecurity{
+			APIKey: cfg.Tools.Web.BaiduSearch.APIKey(),
+		}
+		cfg.Tools.Web.BaiduSearch.secDirty = false
+	}
+	if cfg.Tools.Skills.Github.secDirty {
+		cfg.security.Skills.Github = &GithubSecurity{
+			Token: cfg.Tools.Skills.Github.Token(),
+		}
+		cfg.Tools.Skills.Github.secDirty = false
+	}
+	if cfg.Tools.Skills.Registries.ClawHub.secDirty {
+		cfg.security.Skills.ClawHub = &ClawHubSecurity{
+			AuthToken: cfg.Tools.Skills.Registries.ClawHub.AuthToken(),
+		}
+		cfg.Tools.Skills.Registries.ClawHub.secDirty = false
+	}
+
+	if passphrase := credential.PassphraseProvider(); passphrase != "" {
+		sealed, err := encryptPlaintextAPIKeys(cfg.security.ModelList, passphrase)
+		if err != nil {
+			return err
+		}
+		if sealed != nil {
+			cfg.security.ModelList = sealed
+		}
+	}
+	if err := saveSecurityConfig(securityPath(path), cfg.security); err != nil {
+		logger.ErrorCF("config", "cannot save .security.yml", map[string]any{"error": err})
 		return err
 	}
 
-	// Use unified atomic write utility with explicit sync for flash storage reliability.
+	// Filter out virtual models before serializing to config file
+	nonVirtualModels := make([]*ModelConfig, 0, len(cfg.ModelList))
+	for _, m := range cfg.ModelList {
+		if !m.isVirtual {
+			nonVirtualModels = append(nonVirtualModels, m)
+		}
+	}
+	// Temporarily replace ModelList with filtered version for serialization
+	originalModelList := cfg.ModelList
+	cfg.ModelList = nonVirtualModels
+
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	// Restore original ModelList after serialization
+	cfg.ModelList = originalModelList
+	if err != nil {
+		return err
+	}
+	logger.Infof("saving config to %s", path)
 	return fileutil.WriteFileAtomic(path, data, 0o600)
 }
 
@@ -656,53 +1834,6 @@ func (c *Config) WorkspacePath() string {
 	return expandHome(c.Agents.Defaults.Workspace)
 }
 
-func (c *Config) GetAPIKey() string {
-	if c.Providers.OpenRouter.APIKey != "" {
-		return c.Providers.OpenRouter.APIKey
-	}
-	if c.Providers.Anthropic.APIKey != "" {
-		return c.Providers.Anthropic.APIKey
-	}
-	if c.Providers.OpenAI.APIKey != "" {
-		return c.Providers.OpenAI.APIKey
-	}
-	if c.Providers.Gemini.APIKey != "" {
-		return c.Providers.Gemini.APIKey
-	}
-	if c.Providers.Zhipu.APIKey != "" {
-		return c.Providers.Zhipu.APIKey
-	}
-	if c.Providers.Groq.APIKey != "" {
-		return c.Providers.Groq.APIKey
-	}
-	if c.Providers.VLLM.APIKey != "" {
-		return c.Providers.VLLM.APIKey
-	}
-	if c.Providers.ShengSuanYun.APIKey != "" {
-		return c.Providers.ShengSuanYun.APIKey
-	}
-	if c.Providers.Cerebras.APIKey != "" {
-		return c.Providers.Cerebras.APIKey
-	}
-	return ""
-}
-
-func (c *Config) GetAPIBase() string {
-	if c.Providers.OpenRouter.APIKey != "" {
-		if c.Providers.OpenRouter.APIBase != "" {
-			return c.Providers.OpenRouter.APIBase
-		}
-		return "https://openrouter.ai/api/v1"
-	}
-	if c.Providers.Zhipu.APIKey != "" {
-		return c.Providers.Zhipu.APIBase
-	}
-	if c.Providers.VLLM.APIKey != "" && c.Providers.VLLM.APIBase != "" {
-		return c.Providers.VLLM.APIBase
-	}
-	return ""
-}
-
 func expandHome(path string) string {
 	if path == "" {
 		return path
@@ -726,17 +1857,17 @@ func (c *Config) GetModelConfig(modelName string) (*ModelConfig, error) {
 		return nil, fmt.Errorf("model %q not found in model_list or providers", modelName)
 	}
 	if len(matches) == 1 {
-		return &matches[0], nil
+		return matches[0], nil
 	}
 
 	// Multiple configs - use round-robin for load balancing
-	idx := rrCounter.Add(1) % uint64(len(matches))
-	return &matches[idx], nil
+	idx := (rrCounter.Add(1) - 1) % uint64(len(matches))
+	return matches[idx], nil
 }
 
 // findMatches finds all ModelConfig entries with the given model_name.
-func (c *Config) findMatches(modelName string) []ModelConfig {
-	var matches []ModelConfig
+func (c *Config) findMatches(modelName string) []*ModelConfig {
+	var matches []*ModelConfig
 	for i := range c.ModelList {
 		if c.ModelList[i].ModelName == modelName {
 			matches = append(matches, c.ModelList[i])
@@ -745,29 +1876,6 @@ func (c *Config) findMatches(modelName string) []ModelConfig {
 	return matches
 }
 
-// HasProvidersConfig checks if any provider in the old providers config has configuration.
-func (c *Config) HasProvidersConfig() bool {
-	v := c.Providers
-	return v.Anthropic.APIKey != "" || v.Anthropic.APIBase != "" ||
-		v.OpenAI.APIKey != "" || v.OpenAI.APIBase != "" ||
-		v.OpenRouter.APIKey != "" || v.OpenRouter.APIBase != "" ||
-		v.Groq.APIKey != "" || v.Groq.APIBase != "" ||
-		v.Zhipu.APIKey != "" || v.Zhipu.APIBase != "" ||
-		v.VLLM.APIKey != "" || v.VLLM.APIBase != "" ||
-		v.Gemini.APIKey != "" || v.Gemini.APIBase != "" ||
-		v.Nvidia.APIKey != "" || v.Nvidia.APIBase != "" ||
-		v.Ollama.APIKey != "" || v.Ollama.APIBase != "" ||
-		v.Moonshot.APIKey != "" || v.Moonshot.APIBase != "" ||
-		v.ShengSuanYun.APIKey != "" || v.ShengSuanYun.APIBase != "" ||
-		v.DeepSeek.APIKey != "" || v.DeepSeek.APIBase != "" ||
-		v.Cerebras.APIKey != "" || v.Cerebras.APIBase != "" ||
-		v.VolcEngine.APIKey != "" || v.VolcEngine.APIBase != "" ||
-		v.GitHubCopilot.APIKey != "" || v.GitHubCopilot.APIBase != "" ||
-		v.Antigravity.APIKey != "" || v.Antigravity.APIBase != "" ||
-		v.Qwen.APIKey != "" || v.Qwen.APIBase != "" ||
-		v.Mistral.APIKey != "" || v.Mistral.APIBase != ""
-}
-
 // ValidateModelList validates all ModelConfig entries in the model_list.
 // It checks that each model config is valid.
 // Note: Multiple entries with the same model_name are allowed for load balancing.
@@ -779,3 +1887,240 @@ func (c *Config) ValidateModelList() error {
 	}
 	return nil
 }
+
+func (c *Config) SecurityCopyFrom(cfg *Config) {
+	c.security = cfg.security
+	if c.security != nil {
+		if err := applySecurityConfig(c, c.security); err != nil {
+			logger.Errorf("failed to apply security config in SecurityCopyFrom: %v", err)
+		}
+	}
+}
+
+// ApplySecurity re-applies the stored security config to populate private fields (tokens, API keys, etc.).
+// Call this after SecurityCopyFrom when you need private fields to be accessible for validation or use.
+func (c *Config) ApplySecurity() error {
+	return applySecurityConfig(c, c.security)
+}
+
+func MergeAPIKeys(apiKey string, apiKeys []string) []string {
+	seen := make(map[string]struct{})
+	var all []string
+
+	if k := strings.TrimSpace(apiKey); k != "" {
+		if _, exists := seen[k]; !exists {
+			seen[k] = struct{}{}
+			all = append(all, k)
+		}
+	}
+
+	for _, k := range apiKeys {
+		if trimmed := strings.TrimSpace(k); trimmed != "" {
+			if _, exists := seen[trimmed]; !exists {
+				seen[trimmed] = struct{}{}
+				all = append(all, trimmed)
+			}
+		}
+	}
+
+	return all
+}
+
+// resolveSecurityFields resolves file:// and enc:// references in security-sensitive fields
+// like authToken and token that are not part of ModelConfig's apiKeys
+func resolveSecurityFields(cfg *Config, configDir string) error {
+	cr := credential.NewResolver(configDir)
+
+	// Resolve Web tool API keys - set apiKey field to first resolved apiKeys entry
+	if len(cfg.Tools.Web.Brave.apiKeys) > 0 {
+		keys := cfg.Tools.Web.Brave.apiKeys
+		for i, key := range keys {
+			resolved, err := cr.Resolve(key)
+			if err != nil {
+				return fmt.Errorf("brave api_keys[%d]: %w", i, err)
+			}
+			keys[i] = resolved
+		}
+	}
+
+	if len(cfg.Tools.Web.Tavily.apiKeys) > 0 {
+		keys := cfg.Tools.Web.Tavily.apiKeys
+		for i, key := range keys {
+			resolved, err := cr.Resolve(key)
+			if err != nil {
+				return fmt.Errorf("tavily api_keys[%d]: %w", i, err)
+			}
+			keys[i] = resolved
+		}
+	}
+
+	if len(cfg.Tools.Web.Perplexity.apiKeys) > 0 {
+		keys := cfg.Tools.Web.Perplexity.apiKeys
+		for i, key := range keys {
+			resolved, err := cr.Resolve(key)
+			if err != nil {
+				return fmt.Errorf("perplexity api_keys[%d]: %w", i, err)
+			}
+			keys[i] = resolved
+		}
+	}
+
+	// GLMSearch has a private apiKey field
+	if cfg.Tools.Web.GLMSearch.apiKey != "" {
+		resolved, err := cr.Resolve(cfg.Tools.Web.GLMSearch.apiKey)
+		if err != nil {
+			return fmt.Errorf("glm api_key: %w", err)
+		}
+		cfg.Tools.Web.GLMSearch.apiKey = resolved
+	}
+
+	// Resolve Skills tokens
+	if cfg.Tools.Skills.Github.token != "" {
+		resolved, err := cr.Resolve(cfg.Tools.Skills.Github.token)
+		if err != nil {
+			return fmt.Errorf("github token: %w", err)
+		}
+		cfg.Tools.Skills.Github.token = resolved
+	}
+
+	if cfg.Tools.Skills.Registries.ClawHub.authToken != "" {
+		resolved, err := cr.Resolve(cfg.Tools.Skills.Registries.ClawHub.authToken)
+		if err != nil {
+			return fmt.Errorf("clawhub auth_token: %w", err)
+		}
+		cfg.Tools.Skills.Registries.ClawHub.authToken = resolved
+	}
+
+	return nil
+}
+
+// expandMultiKeyModels expands ModelConfig entries with multiple API keys into
+// separate entries for key-level failover. Each key gets its own ModelConfig entry,
+// and the original entry's fallbacks are set up to chain through the expanded entries.
+//
+// Example: {"model_name": "gpt-4", "api_keys": ["k1", "k2", "k3"]}
+// Becomes:
+//   - {"model_name": "gpt-4", "api_keys": ["k1"], "fallbacks": ["gpt-4__key_1", "gpt-4__key_2"]}
+//   - {"model_name": "gpt-4__key_1", "api_keys": {"k2"}}
+//   - {"model_name": "gpt-4__key_2", "api_keys": {"k3"}}
+func expandMultiKeyModels(models []*ModelConfig) []*ModelConfig {
+	var expanded []*ModelConfig
+
+	for _, m := range models {
+		keys := MergeAPIKeys("", m.apiKeys)
+
+		// Single key or no keys: keep as-is
+		if len(keys) <= 1 {
+			m.apiKeys = keys
+			expanded = append(expanded, m)
+			continue
+		}
+
+		// Multiple keys: expand
+		originalName := m.ModelName
+
+		// Create entries for additional keys (key_1, key_2, ...)
+		var fallbackNames []string
+		for i := 1; i < len(keys); i++ {
+			suffix := fmt.Sprintf("__key_%d", i)
+			expandedName := originalName + suffix
+
+			// Create a copy for the additional key
+			additionalEntry := &ModelConfig{
+				ModelName:      expandedName,
+				Model:          m.Model,
+				APIBase:        m.APIBase,
+				apiKeys:        []string{keys[i]},
+				Proxy:          m.Proxy,
+				AuthMethod:     m.AuthMethod,
+				ConnectMode:    m.ConnectMode,
+				Workspace:      m.Workspace,
+				RPM:            m.RPM,
+				MaxTokensField: m.MaxTokensField,
+				RequestTimeout: m.RequestTimeout,
+				ThinkingLevel:  m.ThinkingLevel,
+				ExtraBody:      m.ExtraBody,
+				isVirtual:      true,
+			}
+			expanded = append(expanded, additionalEntry)
+			fallbackNames = append(fallbackNames, expandedName)
+		}
+
+		// Create the primary entry with first key and fallbacks
+		primaryEntry := &ModelConfig{
+			ModelName:      originalName,
+			Model:          m.Model,
+			APIBase:        m.APIBase,
+			Proxy:          m.Proxy,
+			AuthMethod:     m.AuthMethod,
+			ConnectMode:    m.ConnectMode,
+			Workspace:      m.Workspace,
+			RPM:            m.RPM,
+			MaxTokensField: m.MaxTokensField,
+			RequestTimeout: m.RequestTimeout,
+			ThinkingLevel:  m.ThinkingLevel,
+			ExtraBody:      m.ExtraBody,
+			apiKeys:        []string{keys[0]},
+		}
+
+		// Prepend new fallbacks to existing ones
+		if len(fallbackNames) > 0 {
+			primaryEntry.Fallbacks = append(fallbackNames, m.Fallbacks...)
+		} else if len(m.Fallbacks) > 0 {
+			primaryEntry.Fallbacks = m.Fallbacks
+		}
+
+		expanded = append(expanded, primaryEntry)
+	}
+
+	return expanded
+}
+
+func (t *ToolsConfig) IsToolEnabled(name string) bool {
+	switch name {
+	case "web":
+		return t.Web.Enabled
+	case "cron":
+		return t.Cron.Enabled
+	case "exec":
+		return t.Exec.Enabled
+	case "skills":
+		return t.Skills.Enabled
+	case "media_cleanup":
+		return t.MediaCleanup.Enabled
+	case "append_file":
+		return t.AppendFile.Enabled
+	case "edit_file":
+		return t.EditFile.Enabled
+	case "find_skills":
+		return t.FindSkills.Enabled
+	case "i2c":
+		return t.I2C.Enabled
+	case "install_skill":
+		return t.InstallSkill.Enabled
+	case "list_dir":
+		return t.ListDir.Enabled
+	case "message":
+		return t.Message.Enabled
+	case "read_file":
+		return t.ReadFile.Enabled
+	case "spawn":
+		return t.Spawn.Enabled
+	case "spawn_status":
+		return t.SpawnStatus.Enabled
+	case "spi":
+		return t.SPI.Enabled
+	case "subagent":
+		return t.Subagent.Enabled
+	case "web_fetch":
+		return t.WebFetch.Enabled
+	case "send_file":
+		return t.SendFile.Enabled
+	case "write_file":
+		return t.WriteFile.Enabled
+	case "mcp":
+		return t.MCP.Enabled
+	default:
+		return true
+	}
+}
diff --git a/pkg/config/config_old.go b/pkg/config/config_old.go
new file mode 100644
index 000000000..44c9435d1
--- /dev/null
+++ b/pkg/config/config_old.go
@@ -0,0 +1,1034 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package config
+
+import (
+	"encoding/json"
+)
+
+type agentDefaultsV0 struct {
+	Workspace                 string         `json:"workspace"                       env:"PICOCLAW_AGENTS_DEFAULTS_WORKSPACE"`
+	RestrictToWorkspace       bool           `json:"restrict_to_workspace"           env:"PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE"`
+	AllowReadOutsideWorkspace bool           `json:"allow_read_outside_workspace"    env:"PICOCLAW_AGENTS_DEFAULTS_ALLOW_READ_OUTSIDE_WORKSPACE"`
+	Provider                  string         `json:"provider"                        env:"PICOCLAW_AGENTS_DEFAULTS_PROVIDER"`
+	ModelName                 string         `json:"model_name,omitempty"            env:"PICOCLAW_AGENTS_DEFAULTS_MODEL_NAME"`
+	Model                     string         `json:"model"                           env:"PICOCLAW_AGENTS_DEFAULTS_MODEL"` // Deprecated: use model_name instead
+	ModelFallbacks            []string       `json:"model_fallbacks,omitempty"`
+	ImageModel                string         `json:"image_model,omitempty"           env:"PICOCLAW_AGENTS_DEFAULTS_IMAGE_MODEL"`
+	ImageModelFallbacks       []string       `json:"image_model_fallbacks,omitempty"`
+	MaxTokens                 int            `json:"max_tokens"                      env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOKENS"`
+	Temperature               *float64       `json:"temperature,omitempty"           env:"PICOCLAW_AGENTS_DEFAULTS_TEMPERATURE"`
+	MaxToolIterations         int            `json:"max_tool_iterations"             env:"PICOCLAW_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS"`
+	SummarizeMessageThreshold int            `json:"summarize_message_threshold"     env:"PICOCLAW_AGENTS_DEFAULTS_SUMMARIZE_MESSAGE_THRESHOLD"`
+	SummarizeTokenPercent     int            `json:"summarize_token_percent"         env:"PICOCLAW_AGENTS_DEFAULTS_SUMMARIZE_TOKEN_PERCENT"`
+	MaxMediaSize              int            `json:"max_media_size,omitempty"        env:"PICOCLAW_AGENTS_DEFAULTS_MAX_MEDIA_SIZE"`
+	Routing                   *RoutingConfig `json:"routing,omitempty"`
+}
+
+// GetModelName returns the effective model name for the agent defaults.
+// It prefers the new "model_name" field but falls back to "model" for backward compatibility.
+func (d *agentDefaultsV0) GetModelName() string {
+	if d.ModelName != "" {
+		return d.ModelName
+	}
+	return d.Model
+}
+
+type agentsConfigV0 struct {
+	Defaults agentDefaultsV0 `json:"defaults"`
+	List     []AgentConfig   `json:"list,omitempty"`
+}
+
+// configV0 represents the config structure before versioning was introduced.
+// This struct is used for loading legacy config files (version 0).
+// It is unexported since it's only used internally for migration.
+type configV0 struct {
+	Agents    agentsConfigV0    `json:"agents"`
+	Bindings  []AgentBinding    `json:"bindings,omitempty"`
+	Session   SessionConfig     `json:"session,omitempty"`
+	Channels  channelsConfigV0  `json:"channels"`
+	Providers providersConfigV0 `json:"providers,omitempty"`
+	ModelList []modelConfigV0   `json:"model_list"`
+	Gateway   GatewayConfig     `json:"gateway"`
+	Tools     toolsConfigV0     `json:"tools"`
+	Heartbeat HeartbeatConfig   `json:"heartbeat"`
+	Devices   DevicesConfig     `json:"devices"`
+}
+
+type toolsConfigV0 struct {
+	AllowReadPaths  []string            `json:"allow_read_paths"  env:"PICOCLAW_TOOLS_ALLOW_READ_PATHS"`
+	AllowWritePaths []string            `json:"allow_write_paths" env:"PICOCLAW_TOOLS_ALLOW_WRITE_PATHS"`
+	Web             webToolsConfigV0    `json:"web"`
+	Cron            CronToolsConfig     `json:"cron"`
+	Exec            ExecConfig          `json:"exec"`
+	Skills          skillsToolsConfigV0 `json:"skills"`
+	MediaCleanup    MediaCleanupConfig  `json:"media_cleanup"`
+	MCP             MCPConfig           `json:"mcp"`
+	AppendFile      ToolConfig          `json:"append_file"                                              envPrefix:"PICOCLAW_TOOLS_APPEND_FILE_"`
+	EditFile        ToolConfig          `json:"edit_file"                                                envPrefix:"PICOCLAW_TOOLS_EDIT_FILE_"`
+	FindSkills      ToolConfig          `json:"find_skills"                                              envPrefix:"PICOCLAW_TOOLS_FIND_SKILLS_"`
+	I2C             ToolConfig          `json:"i2c"                                                      envPrefix:"PICOCLAW_TOOLS_I2C_"`
+	InstallSkill    ToolConfig          `json:"install_skill"                                            envPrefix:"PICOCLAW_TOOLS_INSTALL_SKILL_"`
+	ListDir         ToolConfig          `json:"list_dir"                                                 envPrefix:"PICOCLAW_TOOLS_LIST_DIR_"`
+	Message         ToolConfig          `json:"message"                                                  envPrefix:"PICOCLAW_TOOLS_MESSAGE_"`
+	ReadFile        ReadFileToolConfig  `json:"read_file"                                                envPrefix:"PICOCLAW_TOOLS_READ_FILE_"`
+	SendFile        ToolConfig          `json:"send_file"                                                envPrefix:"PICOCLAW_TOOLS_SEND_FILE_"`
+	Spawn           ToolConfig          `json:"spawn"                                                    envPrefix:"PICOCLAW_TOOLS_SPAWN_"`
+	SpawnStatus     ToolConfig          `json:"spawn_status"                                             envPrefix:"PICOCLAW_TOOLS_SPAWN_STATUS_"`
+	SPI             ToolConfig          `json:"spi"                                                      envPrefix:"PICOCLAW_TOOLS_SPI_"`
+	Subagent        ToolConfig          `json:"subagent"                                                 envPrefix:"PICOCLAW_TOOLS_SUBAGENT_"`
+	WebFetch        ToolConfig          `json:"web_fetch"                                                envPrefix:"PICOCLAW_TOOLS_WEB_FETCH_"`
+	WriteFile       ToolConfig          `json:"write_file"                                               envPrefix:"PICOCLAW_TOOLS_WRITE_FILE_"`
+}
+
+type channelsConfigV0 struct {
+	WhatsApp WhatsAppConfig   `json:"whatsapp"`
+	Telegram telegramConfigV0 `json:"telegram"`
+	Feishu   feishuConfigV0   `json:"feishu"`
+	Discord  discordConfigV0  `json:"discord"`
+	MaixCam  maixcamConfigV0  `json:"maixcam"`
+	Weixin   weixinConfigV0   `json:"weixin"`
+	QQ       qqConfigV0       `json:"qq"`
+	DingTalk dingtalkConfigV0 `json:"dingtalk"`
+	Slack    slackConfigV0    `json:"slack"`
+	Matrix   matrixConfigV0   `json:"matrix"`
+	LINE     lineConfigV0     `json:"line"`
+	OneBot   onebotConfigV0   `json:"onebot"`
+	WeCom    wecomConfigV0    `json:"wecom"    envPrefix:"PICOCLAW_CHANNELS_WECOM_"`
+	Pico     picoConfigV0     `json:"pico"`
+	IRC      ircConfigV0      `json:"irc"`
+}
+
+func (v *channelsConfigV0) ToChannelsConfig() (ChannelsConfig, ChannelsSecurity) {
+	telegram, telegramSecurity := v.Telegram.ToTelegramConfig()
+	feishu, feishuSecurity := v.Feishu.ToFeishuConfig()
+	discord, discordSecurity := v.Discord.ToDiscordConfig()
+	maixcam := v.MaixCam.ToMaixCamConfig()
+	qq, qqSecurity := v.QQ.ToQQConfig()
+	weixin, weixinSecurity := v.Weixin.ToWeiXinConfig()
+	dingtalk, dingtalkSecurity := v.DingTalk.ToDingTalkConfig()
+	slack, slackSecurity := v.Slack.ToSlackConfig()
+	matrix, matrixSecurity := v.Matrix.ToMatrixConfig()
+	line, lineSecurity := v.LINE.ToLINEConfig()
+	onebot, onebotSecurity := v.OneBot.ToOneBotConfig()
+	wecom, wecomSecurity := v.WeCom.ToWeComConfig()
+	pico, picoSecurity := v.Pico.ToPicoConfig()
+	irc, ircSecurity := v.IRC.ToIRCConfig()
+
+	return ChannelsConfig{
+			WhatsApp: v.WhatsApp,
+			Telegram: telegram,
+			Feishu:   feishu,
+			Discord:  discord,
+			MaixCam:  maixcam,
+			QQ:       qq,
+			Weixin:   weixin,
+			DingTalk: dingtalk,
+			Slack:    slack,
+			Matrix:   matrix,
+			LINE:     line,
+			OneBot:   onebot,
+			WeCom:    wecom,
+			Pico:     pico,
+			IRC:      irc,
+		}, ChannelsSecurity{
+			Telegram: telegramSecurity,
+			Feishu:   feishuSecurity,
+			Discord:  discordSecurity,
+			QQ:       qqSecurity,
+			Weixin:   weixinSecurity,
+			DingTalk: dingtalkSecurity,
+			Slack:    slackSecurity,
+			Matrix:   matrixSecurity,
+			LINE:     lineSecurity,
+			OneBot:   onebotSecurity,
+			WeCom:    wecomSecurity,
+			Pico:     picoSecurity,
+			IRC:      ircSecurity,
+		}
+}
+
+type qqConfigV0 struct {
+	Enabled              bool                `json:"enabled"                  env:"PICOCLAW_CHANNELS_QQ_ENABLED"`
+	AppID                string              `json:"app_id"                   env:"PICOCLAW_CHANNELS_QQ_APP_ID"`
+	AppSecret            string              `json:"app_secret"               env:"PICOCLAW_CHANNELS_QQ_APP_SECRET"`
+	AllowFrom            FlexibleStringSlice `json:"allow_from"               env:"PICOCLAW_CHANNELS_QQ_ALLOW_FROM"`
+	GroupTrigger         GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	MaxMessageLength     int                 `json:"max_message_length"       env:"PICOCLAW_CHANNELS_QQ_MAX_MESSAGE_LENGTH"`
+	MaxBase64FileSizeMiB int64               `json:"max_base64_file_size_mib" env:"PICOCLAW_CHANNELS_QQ_MAX_BASE64_FILE_SIZE_MIB"`
+	SendMarkdown         bool                `json:"send_markdown"            env:"PICOCLAW_CHANNELS_QQ_SEND_MARKDOWN"`
+	ReasoningChannelID   string              `json:"reasoning_channel_id"     env:"PICOCLAW_CHANNELS_QQ_REASONING_CHANNEL_ID"`
+}
+
+func (v *qqConfigV0) ToQQConfig() (QQConfig, *QQSecurity) {
+	var sec *QQSecurity
+	if v.AppSecret != "" {
+		sec = &QQSecurity{
+			AppSecret: v.AppSecret,
+		}
+	}
+	return QQConfig{
+		Enabled:              v.Enabled,
+		AppID:                v.AppID,
+		AllowFrom:            v.AllowFrom,
+		GroupTrigger:         v.GroupTrigger,
+		MaxMessageLength:     v.MaxMessageLength,
+		MaxBase64FileSizeMiB: v.MaxBase64FileSizeMiB,
+		SendMarkdown:         v.SendMarkdown,
+		ReasoningChannelID:   v.ReasoningChannelID,
+	}, sec
+}
+
+type telegramConfigV0 struct {
+	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_TELEGRAM_ENABLED"`
+	Token              string              `json:"token"                   env:"PICOCLAW_CHANNELS_TELEGRAM_TOKEN"`
+	BaseURL            string              `json:"base_url"                env:"PICOCLAW_CHANNELS_TELEGRAM_BASE_URL"`
+	Proxy              string              `json:"proxy"                   env:"PICOCLAW_CHANNELS_TELEGRAM_PROXY"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_TELEGRAM_ALLOW_FROM"`
+	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	Typing             TypingConfig        `json:"typing,omitempty"`
+	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
+	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_TELEGRAM_REASONING_CHANNEL_ID"`
+	UseMarkdownV2      bool                `json:"use_markdown_v2"         env:"PICOCLAW_CHANNELS_TELEGRAM_USE_MARKDOWN_V2"`
+}
+
+func (v *telegramConfigV0) ToTelegramConfig() (TelegramConfig, *TelegramSecurity) {
+	var sec *TelegramSecurity
+	if v.Token != "" {
+		sec = &TelegramSecurity{
+			Token: v.Token,
+		}
+	}
+	return TelegramConfig{
+		Enabled:            v.Enabled,
+		token:              v.Token,
+		BaseURL:            v.BaseURL,
+		Proxy:              v.Proxy,
+		AllowFrom:          v.AllowFrom,
+		GroupTrigger:       v.GroupTrigger,
+		Typing:             v.Typing,
+		Placeholder:        v.Placeholder,
+		ReasoningChannelID: v.ReasoningChannelID,
+		UseMarkdownV2:      v.UseMarkdownV2,
+	}, sec
+}
+
+type feishuConfigV0 struct {
+	Enabled             bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_FEISHU_ENABLED"`
+	AppID               string              `json:"app_id"                  env:"PICOCLAW_CHANNELS_FEISHU_APP_ID"`
+	AppSecret           string              `json:"app_secret"              env:"PICOCLAW_CHANNELS_FEISHU_APP_SECRET"`
+	EncryptKey          string              `json:"encrypt_key"             env:"PICOCLAW_CHANNELS_FEISHU_ENCRYPT_KEY"`
+	VerificationToken   string              `json:"verification_token"      env:"PICOCLAW_CHANNELS_FEISHU_VERIFICATION_TOKEN"`
+	AllowFrom           FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_FEISHU_ALLOW_FROM"`
+	GroupTrigger        GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	Placeholder         PlaceholderConfig   `json:"placeholder,omitempty"`
+	ReasoningChannelID  string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_FEISHU_REASONING_CHANNEL_ID"`
+	RandomReactionEmoji FlexibleStringSlice `json:"random_reaction_emoji"   env:"PICOCLAW_CHANNELS_FEISHU_RANDOM_REACTION_EMOJI"`
+	IsLark              bool                `json:"is_lark"                 env:"PICOCLAW_CHANNELS_FEISHU_IS_LARK"`
+}
+
+func (v *feishuConfigV0) ToFeishuConfig() (FeishuConfig, *FeishuSecurity) {
+	var sec *FeishuSecurity
+	if v.AppSecret != "" || v.EncryptKey != "" || v.VerificationToken != "" {
+		sec = &FeishuSecurity{
+			AppSecret:         v.AppSecret,
+			EncryptKey:        v.EncryptKey,
+			VerificationToken: v.VerificationToken,
+		}
+	}
+	return FeishuConfig{
+		Enabled:            v.Enabled,
+		AppID:              v.AppID,
+		appSecret:          v.AppSecret,
+		AllowFrom:          v.AllowFrom,
+		GroupTrigger:       v.GroupTrigger,
+		Placeholder:        v.Placeholder,
+		ReasoningChannelID: v.ReasoningChannelID,
+	}, sec
+}
+
+type discordConfigV0 struct {
+	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_DISCORD_ENABLED"`
+	Token              string              `json:"token"                   env:"PICOCLAW_CHANNELS_DISCORD_TOKEN"`
+	Proxy              string              `json:"proxy"                   env:"PICOCLAW_CHANNELS_DISCORD_PROXY"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_DISCORD_ALLOW_FROM"`
+	MentionOnly        bool                `json:"mention_only"            env:"PICOCLAW_CHANNELS_DISCORD_MENTION_ONLY"`
+	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	Typing             TypingConfig        `json:"typing,omitempty"`
+	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
+	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_DISCORD_REASONING_CHANNEL_ID"`
+}
+
+func (v *discordConfigV0) ToDiscordConfig() (DiscordConfig, *DiscordSecurity) {
+	var sec *DiscordSecurity
+	if v.Token != "" {
+		sec = &DiscordSecurity{
+			Token: v.Token,
+		}
+	}
+	return DiscordConfig{
+		Enabled:            v.Enabled,
+		token:              v.Token,
+		Proxy:              v.Proxy,
+		AllowFrom:          v.AllowFrom,
+		MentionOnly:        v.MentionOnly,
+		GroupTrigger:       v.GroupTrigger,
+		Typing:             v.Typing,
+		Placeholder:        v.Placeholder,
+		ReasoningChannelID: v.ReasoningChannelID,
+	}, sec
+}
+
+type maixcamConfigV0 struct {
+	Enabled            bool                `json:"enabled"              env:"PICOCLAW_CHANNELS_MAIXCAM_ENABLED"`
+	Host               string              `json:"host"                 env:"PICOCLAW_CHANNELS_MAIXCAM_HOST"`
+	Port               int                 `json:"port"                 env:"PICOCLAW_CHANNELS_MAIXCAM_PORT"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"           env:"PICOCLAW_CHANNELS_MAIXCAM_ALLOW_FROM"`
+	ReasoningChannelID string              `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_MAIXCAM_REASONING_CHANNEL_ID"`
+}
+
+func (v *maixcamConfigV0) ToMaixCamConfig() MaixCamConfig {
+	return MaixCamConfig{
+		Enabled:            v.Enabled,
+		Host:               v.Host,
+		Port:               v.Port,
+		AllowFrom:          v.AllowFrom,
+		ReasoningChannelID: v.ReasoningChannelID,
+	}
+}
+
+type dingtalkConfigV0 struct {
+	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_DINGTALK_ENABLED"`
+	ClientID           string              `json:"client_id"               env:"PICOCLAW_CHANNELS_DINGTALK_CLIENT_ID"`
+	ClientSecret       string              `json:"client_secret"           env:"PICOCLAW_CHANNELS_DINGTALK_CLIENT_SECRET"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_DINGTALK_ALLOW_FROM"`
+	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_DINGTALK_REASONING_CHANNEL_ID"`
+}
+
+func (v *dingtalkConfigV0) ToDingTalkConfig() (DingTalkConfig, *DingTalkSecurity) {
+	var sec *DingTalkSecurity
+	if v.ClientSecret != "" {
+		sec = &DingTalkSecurity{
+			ClientSecret: v.ClientSecret,
+		}
+	}
+	return DingTalkConfig{
+		Enabled:            v.Enabled,
+		ClientID:           v.ClientID,
+		clientSecret:       v.ClientSecret,
+		AllowFrom:          v.AllowFrom,
+		GroupTrigger:       v.GroupTrigger,
+		ReasoningChannelID: v.ReasoningChannelID,
+	}, sec
+}
+
+type slackConfigV0 struct {
+	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_SLACK_ENABLED"`
+	BotToken           string              `json:"bot_token"               env:"PICOCLAW_CHANNELS_SLACK_BOT_TOKEN"`
+	AppToken           string              `json:"app_token"               env:"PICOCLAW_CHANNELS_SLACK_APP_TOKEN"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_SLACK_ALLOW_FROM"`
+	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	Typing             TypingConfig        `json:"typing,omitempty"`
+	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
+	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_SLACK_REASONING_CHANNEL_ID"`
+}
+
+func (v *slackConfigV0) ToSlackConfig() (SlackConfig, *SlackSecurity) {
+	var sec *SlackSecurity
+	if v.BotToken != "" || v.AppToken != "" {
+		sec = &SlackSecurity{
+			BotToken: v.BotToken,
+			AppToken: v.AppToken,
+		}
+	}
+	return SlackConfig{
+		Enabled:            v.Enabled,
+		botToken:           v.BotToken,
+		appToken:           v.AppToken,
+		AllowFrom:          v.AllowFrom,
+		GroupTrigger:       v.GroupTrigger,
+		Typing:             v.Typing,
+		Placeholder:        v.Placeholder,
+		ReasoningChannelID: v.ReasoningChannelID,
+	}, sec
+}
+
+type matrixConfigV0 struct {
+	Enabled            bool                `json:"enabled"                  env:"PICOCLAW_CHANNELS_MATRIX_ENABLED"`
+	Homeserver         string              `json:"homeserver"               env:"PICOCLAW_CHANNELS_MATRIX_HOMESERVER"`
+	UserID             string              `json:"user_id"                  env:"PICOCLAW_CHANNELS_MATRIX_USER_ID"`
+	AccessToken        string              `json:"access_token"             env:"PICOCLAW_CHANNELS_MATRIX_ACCESS_TOKEN"`
+	DeviceID           string              `json:"device_id,omitempty"      env:"PICOCLAW_CHANNELS_MATRIX_DEVICE_ID"`
+	JoinOnInvite       bool                `json:"join_on_invite"           env:"PICOCLAW_CHANNELS_MATRIX_JOIN_ON_INVITE"`
+	MessageFormat      string              `json:"message_format,omitempty" env:"PICOCLAW_CHANNELS_MATRIX_MESSAGE_FORMAT"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"               env:"PICOCLAW_CHANNELS_MATRIX_ALLOW_FROM"`
+	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
+	ReasoningChannelID string              `json:"reasoning_channel_id"     env:"PICOCLAW_CHANNELS_MATRIX_REASONING_CHANNEL_ID"`
+}
+
+func (v *matrixConfigV0) ToMatrixConfig() (MatrixConfig, *MatrixSecurity) {
+	var sec *MatrixSecurity
+	if v.AccessToken != "" {
+		sec = &MatrixSecurity{
+			AccessToken: v.AccessToken,
+		}
+	}
+	return MatrixConfig{
+		Enabled:            v.Enabled,
+		Homeserver:         v.Homeserver,
+		UserID:             v.UserID,
+		accessToken:        v.AccessToken,
+		DeviceID:           v.DeviceID,
+		JoinOnInvite:       v.JoinOnInvite,
+		MessageFormat:      v.MessageFormat,
+		AllowFrom:          v.AllowFrom,
+		GroupTrigger:       v.GroupTrigger,
+		Placeholder:        v.Placeholder,
+		ReasoningChannelID: v.ReasoningChannelID,
+	}, sec
+}
+
+type lineConfigV0 struct {
+	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_LINE_ENABLED"`
+	ChannelSecret      string              `json:"channel_secret"          env:"PICOCLAW_CHANNELS_LINE_CHANNEL_SECRET"`
+	ChannelAccessToken string              `json:"channel_access_token"    env:"PICOCLAW_CHANNELS_LINE_CHANNEL_ACCESS_TOKEN"`
+	WebhookHost        string              `json:"webhook_host"            env:"PICOCLAW_CHANNELS_LINE_WEBHOOK_HOST"`
+	WebhookPort        int                 `json:"webhook_port"            env:"PICOCLAW_CHANNELS_LINE_WEBHOOK_PORT"`
+	WebhookPath        string              `json:"webhook_path"            env:"PICOCLAW_CHANNELS_LINE_WEBHOOK_PATH"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_LINE_ALLOW_FROM"`
+	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	Typing             TypingConfig        `json:"typing,omitempty"`
+	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
+	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_LINE_REASONING_CHANNEL_ID"`
+}
+
+func (v *lineConfigV0) ToLINEConfig() (LINEConfig, *LINESecurity) {
+	var sec *LINESecurity
+	if v.ChannelSecret != "" || v.ChannelAccessToken != "" {
+		sec = &LINESecurity{
+			ChannelSecret:      v.ChannelSecret,
+			ChannelAccessToken: v.ChannelAccessToken,
+		}
+	}
+	return LINEConfig{
+		Enabled:            v.Enabled,
+		channelSecret:      v.ChannelSecret,
+		channelAccessToken: v.ChannelAccessToken,
+		WebhookHost:        v.WebhookHost,
+		WebhookPort:        v.WebhookPort,
+		WebhookPath:        v.WebhookPath,
+		AllowFrom:          v.AllowFrom,
+		GroupTrigger:       v.GroupTrigger,
+		Typing:             v.Typing,
+		Placeholder:        v.Placeholder,
+		ReasoningChannelID: v.ReasoningChannelID,
+	}, sec
+}
+
+type onebotConfigV0 struct {
+	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_ONEBOT_ENABLED"`
+	WSUrl              string              `json:"ws_url"                  env:"PICOCLAW_CHANNELS_ONEBOT_WS_URL"`
+	AccessToken        string              `json:"access_token"            env:"PICOCLAW_CHANNELS_ONEBOT_ACCESS_TOKEN"`
+	ReconnectInterval  int                 `json:"reconnect_interval"      env:"PICOCLAW_CHANNELS_ONEBOT_RECONNECT_INTERVAL"`
+	GroupTriggerPrefix []string            `json:"group_trigger_prefix"    env:"PICOCLAW_CHANNELS_ONEBOT_GROUP_TRIGGER_PREFIX"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_ONEBOT_ALLOW_FROM"`
+	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	Typing             TypingConfig        `json:"typing,omitempty"`
+	Placeholder        PlaceholderConfig   `json:"placeholder,omitempty"`
+	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_ONEBOT_REASONING_CHANNEL_ID"`
+}
+
+func (v *onebotConfigV0) ToOneBotConfig() (OneBotConfig, *OneBotSecurity) {
+	var sec *OneBotSecurity
+	if v.AccessToken != "" {
+		sec = &OneBotSecurity{
+			AccessToken: v.AccessToken,
+		}
+	}
+	return OneBotConfig{
+		Enabled:            v.Enabled,
+		WSUrl:              v.WSUrl,
+		accessToken:        v.AccessToken,
+		ReconnectInterval:  v.ReconnectInterval,
+		GroupTriggerPrefix: v.GroupTriggerPrefix,
+		AllowFrom:          v.AllowFrom,
+		GroupTrigger:       v.GroupTrigger,
+		Typing:             v.Typing,
+		Placeholder:        v.Placeholder,
+		ReasoningChannelID: v.ReasoningChannelID,
+	}, sec
+}
+
+type wecomConfigV0 struct {
+	Enabled             bool                        `json:"enabled"                    env:"ENABLED"`
+	BotID               string                      `json:"bot_id"                     env:"BOT_ID"`
+	Secret              string                      `json:"secret"                     env:"SECRET"`
+	WebSocketURL        string                      `json:"websocket_url,omitempty"    env:"WEBSOCKET_URL"`
+	SendThinkingMessage bool                        `json:"send_thinking_message"      env:"SEND_THINKING_MESSAGE"`
+	DMPolicy            string                      `json:"dm_policy,omitempty"        env:"DM_POLICY"`
+	AllowFrom           FlexibleStringSlice         `json:"allow_from"                 env:"ALLOW_FROM"`
+	GroupPolicy         string                      `json:"group_policy,omitempty"     env:"GROUP_POLICY"`
+	GroupAllowFrom      FlexibleStringSlice         `json:"group_allow_from,omitempty" env:"GROUP_ALLOW_FROM"`
+	Groups              map[string]WeComGroupConfig `json:"groups,omitempty"`
+	ReasoningChannelID  string                      `json:"reasoning_channel_id"       env:"REASONING_CHANNEL_ID"`
+}
+
+func (v *wecomConfigV0) ToWeComConfig() (WeComConfig, *WeComSecurity) {
+	var sec *WeComSecurity
+	if v.Secret != "" {
+		sec = &WeComSecurity{Secret: v.Secret}
+	}
+	return WeComConfig{
+		Enabled:             v.Enabled,
+		BotID:               v.BotID,
+		secret:              v.Secret,
+		WebSocketURL:        v.WebSocketURL,
+		SendThinkingMessage: v.SendThinkingMessage,
+		AllowFrom:           v.AllowFrom,
+		ReasoningChannelID:  v.ReasoningChannelID,
+	}, sec
+}
+
+type weixinConfigV0 struct {
+	Enabled            bool                `json:"enabled"              env:"PICOCLAW_CHANNELS_WEIXIN_ENABLED"`
+	Token              string              `json:"token"                env:"PICOCLAW_CHANNELS_WEIXIN_TOKEN"`
+	BaseURL            string              `json:"base_url"             env:"PICOCLAW_CHANNELS_WEIXIN_BASE_URL"`
+	CDNBaseURL         string              `json:"cdn_base_url"         env:"PICOCLAW_CHANNELS_WEIXIN_CDN_BASE_URL"`
+	Proxy              string              `json:"proxy"                env:"PICOCLAW_CHANNELS_WEIXIN_PROXY"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"           env:"PICOCLAW_CHANNELS_WEIXIN_ALLOW_FROM"`
+	ReasoningChannelID string              `json:"reasoning_channel_id" env:"PICOCLAW_CHANNELS_WEIXIN_REASONING_CHANNEL_ID"`
+}
+
+func (v *weixinConfigV0) ToWeiXinConfig() (WeixinConfig, *WeixinSecurity) {
+	var sec *WeixinSecurity
+	if v.Token != "" {
+		sec = &WeixinSecurity{
+			Token: v.Token,
+		}
+	}
+	return WeixinConfig{
+		Enabled:            v.Enabled,
+		token:              v.Token,
+		BaseURL:            v.BaseURL,
+		CDNBaseURL:         v.CDNBaseURL,
+		Proxy:              v.Proxy,
+		AllowFrom:          v.AllowFrom,
+		ReasoningChannelID: v.ReasoningChannelID,
+	}, sec
+}
+
+type picoConfigV0 struct {
+	Enabled         bool                `json:"enabled"                     env:"PICOCLAW_CHANNELS_PICO_ENABLED"`
+	Token           string              `json:"token"                       env:"PICOCLAW_CHANNELS_PICO_TOKEN"`
+	AllowTokenQuery bool                `json:"allow_token_query,omitempty"`
+	AllowOrigins    []string            `json:"allow_origins,omitempty"`
+	PingInterval    int                 `json:"ping_interval,omitempty"`
+	ReadTimeout     int                 `json:"read_timeout,omitempty"`
+	WriteTimeout    int                 `json:"write_timeout,omitempty"`
+	MaxConnections  int                 `json:"max_connections,omitempty"`
+	AllowFrom       FlexibleStringSlice `json:"allow_from"                  env:"PICOCLAW_CHANNELS_PICO_ALLOW_FROM"`
+	Placeholder     PlaceholderConfig   `json:"placeholder,omitempty"`
+}
+
+func (v *picoConfigV0) ToPicoConfig() (PicoConfig, *PicoSecurity) {
+	var sec *PicoSecurity
+	if v.Token != "" {
+		sec = &PicoSecurity{
+			Token: v.Token,
+		}
+	}
+	return PicoConfig{
+		Enabled:         v.Enabled,
+		token:           v.Token,
+		AllowTokenQuery: v.AllowTokenQuery,
+		AllowOrigins:    v.AllowOrigins,
+		PingInterval:    v.PingInterval,
+		ReadTimeout:     v.ReadTimeout,
+		WriteTimeout:    v.WriteTimeout,
+		MaxConnections:  v.MaxConnections,
+		AllowFrom:       v.AllowFrom,
+		Placeholder:     v.Placeholder,
+	}, sec
+}
+
+type ircConfigV0 struct {
+	Enabled            bool                `json:"enabled"                 env:"PICOCLAW_CHANNELS_IRC_ENABLED"`
+	Server             string              `json:"server"                  env:"PICOCLAW_CHANNELS_IRC_SERVER"`
+	TLS                bool                `json:"tls"                     env:"PICOCLAW_CHANNELS_IRC_TLS"`
+	Nick               string              `json:"nick"                    env:"PICOCLAW_CHANNELS_IRC_NICK"`
+	User               string              `json:"user,omitempty"          env:"PICOCLAW_CHANNELS_IRC_USER"`
+	RealName           string              `json:"real_name,omitempty"     env:"PICOCLAW_CHANNELS_IRC_REAL_NAME"`
+	Password           string              `json:"password"                env:"PICOCLAW_CHANNELS_IRC_PASSWORD"`
+	NickServPassword   string              `json:"nickserv_password"       env:"PICOCLAW_CHANNELS_IRC_NICKSERV_PASSWORD"`
+	SASLUser           string              `json:"sasl_user"               env:"PICOCLAW_CHANNELS_IRC_SASL_USER"`
+	SASLPassword       string              `json:"sasl_password"           env:"PICOCLAW_CHANNELS_IRC_SASL_PASSWORD"`
+	Channels           FlexibleStringSlice `json:"channels"                env:"PICOCLAW_CHANNELS_IRC_CHANNELS"`
+	RequestCaps        FlexibleStringSlice `json:"request_caps,omitempty"  env:"PICOCLAW_CHANNELS_IRC_REQUEST_CAPS"`
+	AllowFrom          FlexibleStringSlice `json:"allow_from"              env:"PICOCLAW_CHANNELS_IRC_ALLOW_FROM"`
+	GroupTrigger       GroupTriggerConfig  `json:"group_trigger,omitempty"`
+	Typing             TypingConfig        `json:"typing,omitempty"`
+	ReasoningChannelID string              `json:"reasoning_channel_id"    env:"PICOCLAW_CHANNELS_IRC_REASONING_CHANNEL_ID"`
+}
+
+func (v *ircConfigV0) ToIRCConfig() (IRCConfig, *IRCSecurity) {
+	var sec *IRCSecurity
+	if v.Password != "" || v.NickServPassword != "" || v.SASLPassword != "" {
+		sec = &IRCSecurity{
+			Password:         v.Password,
+			NickServPassword: v.NickServPassword,
+			SASLPassword:     v.SASLPassword,
+		}
+	}
+	return IRCConfig{
+		Enabled:            v.Enabled,
+		Server:             v.Server,
+		TLS:                v.TLS,
+		Nick:               v.Nick,
+		User:               v.User,
+		RealName:           v.RealName,
+		password:           v.Password,
+		nickServPassword:   v.NickServPassword,
+		SASLUser:           v.SASLUser,
+		saslPassword:       v.SASLPassword,
+		Channels:           v.Channels,
+		RequestCaps:        v.RequestCaps,
+		AllowFrom:          v.AllowFrom,
+		GroupTrigger:       v.GroupTrigger,
+		Typing:             v.Typing,
+		ReasoningChannelID: v.ReasoningChannelID,
+	}, sec
+}
+
+type providersConfigV0 struct {
+	Anthropic     providerConfigV0       `json:"anthropic"`
+	OpenAI        openAIProviderConfigV0 `json:"openai"`
+	LiteLLM       providerConfigV0       `json:"litellm"`
+	OpenRouter    providerConfigV0       `json:"openrouter"`
+	Groq          providerConfigV0       `json:"groq"`
+	Zhipu         providerConfigV0       `json:"zhipu"`
+	VLLM          providerConfigV0       `json:"vllm"`
+	Gemini        providerConfigV0       `json:"gemini"`
+	Nvidia        providerConfigV0       `json:"nvidia"`
+	Ollama        providerConfigV0       `json:"ollama"`
+	Moonshot      providerConfigV0       `json:"moonshot"`
+	ShengSuanYun  providerConfigV0       `json:"shengsuanyun"`
+	DeepSeek      providerConfigV0       `json:"deepseek"`
+	Cerebras      providerConfigV0       `json:"cerebras"`
+	Vivgrid       providerConfigV0       `json:"vivgrid"`
+	VolcEngine    providerConfigV0       `json:"volcengine"`
+	GitHubCopilot providerConfigV0       `json:"github_copilot"`
+	Antigravity   providerConfigV0       `json:"antigravity"`
+	Qwen          providerConfigV0       `json:"qwen"`
+	Mistral       providerConfigV0       `json:"mistral"`
+	Avian         providerConfigV0       `json:"avian"`
+	Minimax       providerConfigV0       `json:"minimax"`
+	LongCat       providerConfigV0       `json:"longcat"`
+	ModelScope    providerConfigV0       `json:"modelscope"`
+	Novita        providerConfigV0       `json:"novita"`
+}
+
+// IsEmpty checks if all provider configs are empty (no API keys or API bases set)
+// Note: WebSearch is an optimization option and doesn't count as "non-empty"
+func (p providersConfigV0) IsEmpty() bool {
+	return p.Anthropic.APIKey == "" && p.Anthropic.APIBase == "" &&
+		p.OpenAI.APIKey == "" && p.OpenAI.APIBase == "" &&
+		p.LiteLLM.APIKey == "" && p.LiteLLM.APIBase == "" &&
+		p.OpenRouter.APIKey == "" && p.OpenRouter.APIBase == "" &&
+		p.Groq.APIKey == "" && p.Groq.APIBase == "" &&
+		p.Zhipu.APIKey == "" && p.Zhipu.APIBase == "" &&
+		p.VLLM.APIKey == "" && p.VLLM.APIBase == "" &&
+		p.Gemini.APIKey == "" && p.Gemini.APIBase == "" &&
+		p.Nvidia.APIKey == "" && p.Nvidia.APIBase == "" &&
+		p.Ollama.APIKey == "" && p.Ollama.APIBase == "" &&
+		p.Moonshot.APIKey == "" && p.Moonshot.APIBase == "" &&
+		p.ShengSuanYun.APIKey == "" && p.ShengSuanYun.APIBase == "" &&
+		p.DeepSeek.APIKey == "" && p.DeepSeek.APIBase == "" &&
+		p.Cerebras.APIKey == "" && p.Cerebras.APIBase == "" &&
+		p.Vivgrid.APIKey == "" && p.Vivgrid.APIBase == "" &&
+		p.VolcEngine.APIKey == "" && p.VolcEngine.APIBase == "" &&
+		p.GitHubCopilot.APIKey == "" && p.GitHubCopilot.APIBase == "" &&
+		p.Antigravity.APIKey == "" && p.Antigravity.APIBase == "" &&
+		p.Qwen.APIKey == "" && p.Qwen.APIBase == "" &&
+		p.Mistral.APIKey == "" && p.Mistral.APIBase == "" &&
+		p.Avian.APIKey == "" && p.Avian.APIBase == "" &&
+		p.Minimax.APIKey == "" && p.Minimax.APIBase == "" &&
+		p.LongCat.APIKey == "" && p.LongCat.APIBase == "" &&
+		p.ModelScope.APIKey == "" && p.ModelScope.APIBase == "" &&
+		p.Novita.APIKey == "" && p.Novita.APIBase == ""
+}
+
+type providerConfigV0 struct {
+	APIKey         string `json:"api_key"                   env:"PICOCLAW_PROVIDERS_{{.Name}}_API_KEY"`
+	APIBase        string `json:"api_base"                  env:"PICOCLAW_PROVIDERS_{{.Name}}_API_BASE"`
+	Proxy          string `json:"proxy,omitempty"           env:"PICOCLAW_PROVIDERS_{{.Name}}_PROXY"`
+	RequestTimeout int    `json:"request_timeout,omitempty" env:"PICOCLAW_PROVIDERS_{{.Name}}_REQUEST_TIMEOUT"`
+	AuthMethod     string `json:"auth_method,omitempty"     env:"PICOCLAW_PROVIDERS_{{.Name}}_AUTH_METHOD"`
+	ConnectMode    string `json:"connect_mode,omitempty"    env:"PICOCLAW_PROVIDERS_{{.Name}}_CONNECT_MODE"` // only for Github Copilot, `stdio` or `grpc`
+}
+
+// MarshalJSON implements custom JSON marshaling for providersConfig
+// to omit the entire section when empty
+func (p providersConfigV0) MarshalJSON() ([]byte, error) {
+	if p.IsEmpty() {
+		return []byte("null"), nil
+	}
+	type Alias providersConfigV0
+	return json.Marshal((*Alias)(&p))
+}
+
+type openAIProviderConfigV0 struct {
+	providerConfigV0
+	WebSearch bool `json:"web_search" env:"PICOCLAW_PROVIDERS_OPENAI_WEB_SEARCH"`
+}
+
+type modelConfigV0 struct {
+	// Required fields
+	ModelName string `json:"model_name"` // User-facing alias for the model
+	Model     string `json:"model"`      // Protocol/model-identifier (e.g., "openai/gpt-4o", "anthropic/claude-sonnet-4.6")
+
+	// HTTP-based providers
+	APIBase   string   `json:"api_base,omitempty"`  // API endpoint URL
+	APIKey    string   `json:"api_key"`             // API authentication key (single key)
+	APIKeys   []string `json:"api_keys,omitempty"`  // API authentication keys (multiple keys for failover)
+	Proxy     string   `json:"proxy,omitempty"`     // HTTP proxy URL
+	Fallbacks []string `json:"fallbacks,omitempty"` // Fallback model names for failover
+
+	// Special providers (CLI-based, OAuth, etc.)
+	AuthMethod  string `json:"auth_method,omitempty"`  // Authentication method: oauth, token
+	ConnectMode string `json:"connect_mode,omitempty"` // Connection mode: stdio, grpc
+	Workspace   string `json:"workspace,omitempty"`    // Workspace path for CLI-based providers
+
+	// Optional optimizations
+	RPM            int    `json:"rpm,omitempty"`              // Requests per minute limit
+	MaxTokensField string `json:"max_tokens_field,omitempty"` // Field name for max tokens (e.g., "max_completion_tokens")
+	RequestTimeout int    `json:"request_timeout,omitempty"`
+	ThinkingLevel  string `json:"thinking_level,omitempty"` // Extended thinking: off|low|medium|high|xhigh|adaptive
+}
+
+func (c *configV0) migrateChannelConfigs() {
+	// Discord: mention_only -> group_trigger.mention_only
+	if c.Channels.Discord.MentionOnly && !c.Channels.Discord.GroupTrigger.MentionOnly {
+		c.Channels.Discord.GroupTrigger.MentionOnly = true
+	}
+
+	// OneBot: group_trigger_prefix -> group_trigger.prefixes
+	if len(c.Channels.OneBot.GroupTriggerPrefix) > 0 &&
+		len(c.Channels.OneBot.GroupTrigger.Prefixes) == 0 {
+		c.Channels.OneBot.GroupTrigger.Prefixes = c.Channels.OneBot.GroupTriggerPrefix
+	}
+}
+
+func (c *configV0) Migrate() (*Config, error) {
+	// Migrate legacy channel config fields to new unified structures
+	cfg := DefaultConfig()
+
+	// Always copy user's Agents config to preserve settings like Provider, Model, MaxTokens
+	cfg.Agents.List = c.Agents.List
+	cfg.Agents.Defaults.Workspace = c.Agents.Defaults.Workspace
+	cfg.Agents.Defaults.RestrictToWorkspace = c.Agents.Defaults.RestrictToWorkspace
+	cfg.Agents.Defaults.AllowReadOutsideWorkspace = c.Agents.Defaults.AllowReadOutsideWorkspace
+	cfg.Agents.Defaults.Provider = c.Agents.Defaults.Provider
+	cfg.Agents.Defaults.ModelName = c.Agents.Defaults.GetModelName()
+	cfg.Agents.Defaults.ModelFallbacks = c.Agents.Defaults.ModelFallbacks
+	cfg.Agents.Defaults.ImageModel = c.Agents.Defaults.ImageModel
+	cfg.Agents.Defaults.ImageModelFallbacks = c.Agents.Defaults.ImageModelFallbacks
+	cfg.Agents.Defaults.MaxTokens = c.Agents.Defaults.MaxTokens
+	cfg.Agents.Defaults.Temperature = c.Agents.Defaults.Temperature
+	cfg.Agents.Defaults.MaxToolIterations = c.Agents.Defaults.MaxToolIterations
+	cfg.Agents.Defaults.SummarizeMessageThreshold = c.Agents.Defaults.SummarizeMessageThreshold
+	cfg.Agents.Defaults.SummarizeTokenPercent = c.Agents.Defaults.SummarizeTokenPercent
+	cfg.Agents.Defaults.MaxMediaSize = c.Agents.Defaults.MaxMediaSize
+	cfg.Agents.Defaults.Routing = c.Agents.Defaults.Routing
+
+	// Copy other top-level fields
+	cfg.Bindings = c.Bindings
+	cfg.Session = c.Session
+	var secChannels ChannelsSecurity
+	cfg.Channels, secChannels = c.Channels.ToChannelsConfig()
+	cfg.Gateway = c.Gateway
+	var secWeb WebToolsSecurity
+	cfg.Tools.Web, secWeb = c.Tools.Web.ToWebToolsConfig()
+	cfg.Tools.Cron = c.Tools.Cron
+	cfg.Tools.Exec = c.Tools.Exec
+	var secSkills *SkillsSecurity
+	cfg.Tools.Skills, secSkills = c.Tools.Skills.ToSkillsToolsConfig()
+	cfg.Tools.MediaCleanup = c.Tools.MediaCleanup
+	cfg.Tools.MCP = c.Tools.MCP
+	cfg.Tools.AppendFile = c.Tools.AppendFile
+	cfg.Tools.EditFile = c.Tools.EditFile
+	cfg.Tools.FindSkills = c.Tools.FindSkills
+	cfg.Tools.I2C = c.Tools.I2C
+	cfg.Tools.InstallSkill = c.Tools.InstallSkill
+	cfg.Tools.ListDir = c.Tools.ListDir
+	cfg.Tools.Message = c.Tools.Message
+	cfg.Tools.ReadFile = c.Tools.ReadFile
+	cfg.Tools.SendFile = c.Tools.SendFile
+	cfg.Tools.Spawn = c.Tools.Spawn
+	cfg.Tools.SpawnStatus = c.Tools.SpawnStatus
+	cfg.Tools.SPI = c.Tools.SPI
+	cfg.Tools.Subagent = c.Tools.Subagent
+	cfg.Tools.WebFetch = c.Tools.WebFetch
+	cfg.Tools.AllowReadPaths = c.Tools.AllowReadPaths
+	cfg.Tools.AllowWritePaths = c.Tools.AllowWritePaths
+	cfg.Heartbeat = c.Heartbeat
+	cfg.Devices = c.Devices
+
+	secModels := make(map[string]ModelSecurityEntry, 0)
+	// Only override ModelList if user provided values
+	if len(c.ModelList) > 0 {
+		// Convert []modelConfigV0 to []ModelConfig
+		cfg.ModelList = make([]*ModelConfig, len(c.ModelList))
+		for i, m := range c.ModelList {
+			// Merge APIKey and APIKeys, deduplicating
+			mergedKeys := MergeAPIKeys(m.APIKey, m.APIKeys)
+
+			cfg.ModelList[i] = &ModelConfig{
+				ModelName:      m.ModelName,
+				Model:          m.Model,
+				APIBase:        m.APIBase,
+				Proxy:          m.Proxy,
+				Fallbacks:      m.Fallbacks,
+				AuthMethod:     m.AuthMethod,
+				ConnectMode:    m.ConnectMode,
+				Workspace:      m.Workspace,
+				RPM:            m.RPM,
+				MaxTokensField: m.MaxTokensField,
+				RequestTimeout: m.RequestTimeout,
+				ThinkingLevel:  m.ThinkingLevel,
+				apiKeys:        mergedKeys,
+			}
+		}
+		names := toNameIndex(cfg.ModelList)
+		for i, m := range c.ModelList {
+			// Merge APIKey and APIKeys, deduplicating
+			mergedKeys := MergeAPIKeys(m.APIKey, m.APIKeys)
+			if len(mergedKeys) > 0 {
+				secModels[names[i]] = ModelSecurityEntry{
+					APIKeys: mergedKeys,
+				}
+			}
+		}
+	}
+
+	cfg.WithSecurity(&SecurityConfig{
+		ModelList: secModels,
+		Channels:  &secChannels,
+		Web:       &secWeb,
+		Skills:    secSkills,
+	})
+	cfg.Version = CurrentVersion
+	return cfg, nil
+}
+
+type webToolsConfigV0 struct {
+	ToolConfig           `                    envPrefix:"PICOCLAW_TOOLS_WEB_"`
+	Brave                braveConfigV0       `                                json:"brave"`
+	Tavily               tavilyConfigV0      `                                json:"tavily"`
+	DuckDuckGo           DuckDuckGoConfig    `                                json:"duckduckgo"`
+	Perplexity           perplexityConfigV0  `                                json:"perplexity"`
+	SearXNG              SearXNGConfig       `                                json:"searxng"`
+	GLMSearch            glmSearchConfigV0   `                                json:"glm_search"`
+	PreferNative         bool                `                                json:"prefer_native"                    env:"PICOCLAW_TOOLS_WEB_PREFER_NATIVE"`
+	Proxy                string              `                                json:"proxy,omitempty"                  env:"PICOCLAW_TOOLS_WEB_PROXY"`
+	FetchLimitBytes      int64               `                                json:"fetch_limit_bytes,omitempty"      env:"PICOCLAW_TOOLS_WEB_FETCH_LIMIT_BYTES"`
+	Format               string              `                                json:"format,omitempty"                 env:"PICOCLAW_TOOLS_WEB_FORMAT"`
+	PrivateHostWhitelist FlexibleStringSlice `                                json:"private_host_whitelist,omitempty" env:"PICOCLAW_TOOLS_WEB_PRIVATE_HOST_WHITELIST"`
+}
+
+type braveConfigV0 struct {
+	Enabled    bool     `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_BRAVE_ENABLED"`
+	APIKey     string   `json:"api_key"     env:"PICOCLAW_TOOLS_WEB_BRAVE_API_KEY"`
+	APIKeys    []string `json:"api_keys"    env:"PICOCLAW_TOOLS_WEB_BRAVE_API_KEYS"`
+	MaxResults int      `json:"max_results" env:"PICOCLAW_TOOLS_WEB_BRAVE_MAX_RESULTS"`
+}
+
+func (v *braveConfigV0) ToBraveConfig() (BraveConfig, *BraveSecurity) {
+	var sec *BraveSecurity
+	if k := MergeAPIKeys(v.APIKey, v.APIKeys); len(k) > 0 {
+		sec = &BraveSecurity{
+			APIKeys: MergeAPIKeys(v.APIKey, v.APIKeys),
+		}
+	}
+	return BraveConfig{
+		Enabled:    v.Enabled,
+		MaxResults: v.MaxResults,
+	}, sec
+}
+
+type tavilyConfigV0 struct {
+	Enabled    bool     `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_TAVILY_ENABLED"`
+	APIKey     string   `json:"api_key"     env:"PICOCLAW_TOOLS_WEB_TAVILY_API_KEY"`
+	APIKeys    []string `json:"api_keys"    env:"PICOCLAW_TOOLS_WEB_TAVILY_API_KEYS"`
+	BaseURL    string   `json:"base_url"    env:"PICOCLAW_TOOLS_WEB_TAVILY_BASE_URL"`
+	MaxResults int      `json:"max_results" env:"PICOCLAW_TOOLS_WEB_TAVILY_MAX_RESULTS"`
+}
+
+func (v *tavilyConfigV0) ToTavilyConfig() (TavilyConfig, *TavilySecurity) {
+	var sec *TavilySecurity
+	if k := MergeAPIKeys(v.APIKey, v.APIKeys); len(k) > 0 {
+		sec = &TavilySecurity{
+			APIKeys: k,
+		}
+	}
+	return TavilyConfig{
+		Enabled:    v.Enabled,
+		BaseURL:    v.BaseURL,
+		MaxResults: v.MaxResults,
+	}, sec
+}
+
+type perplexityConfigV0 struct {
+	Enabled    bool     `json:"enabled"     env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_ENABLED"`
+	APIKey     string   `json:"api_key"     env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_API_KEY"`
+	APIKeys    []string `json:"api_keys"    env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_API_KEYS"`
+	MaxResults int      `json:"max_results" env:"PICOCLAW_TOOLS_WEB_PERPLEXITY_MAX_RESULTS"`
+}
+
+func (v *perplexityConfigV0) ToPerplexityConfig() (PerplexityConfig, *PerplexitySecurity) {
+	var sec *PerplexitySecurity
+	if k := MergeAPIKeys(v.APIKey, v.APIKeys); len(k) > 0 {
+		sec = &PerplexitySecurity{
+			APIKeys: k,
+		}
+	}
+	return PerplexityConfig{
+		Enabled:    v.Enabled,
+		MaxResults: v.MaxResults,
+	}, sec
+}
+
+type glmSearchConfigV0 struct {
+	Enabled      bool   `json:"enabled"       env:"PICOCLAW_TOOLS_WEB_GLM_ENABLED"`
+	APIKey       string `json:"api_key"       env:"PICOCLAW_TOOLS_WEB_GLM_API_KEY"`
+	BaseURL      string `json:"base_url"      env:"PICOCLAW_TOOLS_WEB_GLM_BASE_URL"`
+	SearchEngine string `json:"search_engine" env:"PICOCLAW_TOOLS_WEB_GLM_SEARCH_ENGINE"`
+}
+
+func (v *glmSearchConfigV0) ToGLMSearchConfig() (GLMSearchConfig, *GLMSearchSecurity) {
+	var sec *GLMSearchSecurity
+	if v.APIKey != "" {
+		sec = &GLMSearchSecurity{
+			APIKey: v.APIKey,
+		}
+	}
+	return GLMSearchConfig{
+		Enabled:      v.Enabled,
+		apiKey:       v.APIKey,
+		BaseURL:      v.BaseURL,
+		SearchEngine: v.SearchEngine,
+	}, sec
+}
+
+func (v *webToolsConfigV0) ToWebToolsConfig() (WebToolsConfig, WebToolsSecurity) {
+	brave, braveSecurity := v.Brave.ToBraveConfig()
+	tavily, tavilySecurity := v.Tavily.ToTavilyConfig()
+	perplexity, perplexitySecurity := v.Perplexity.ToPerplexityConfig()
+	glmSearch, glmSearchSecurity := v.GLMSearch.ToGLMSearchConfig()
+
+	return WebToolsConfig{
+			ToolConfig:           v.ToolConfig,
+			Brave:                brave,
+			Tavily:               tavily,
+			DuckDuckGo:           v.DuckDuckGo,
+			Perplexity:           perplexity,
+			SearXNG:              v.SearXNG,
+			GLMSearch:            glmSearch,
+			PreferNative:         v.PreferNative,
+			Proxy:                v.Proxy,
+			FetchLimitBytes:      v.FetchLimitBytes,
+			Format:               v.Format,
+			PrivateHostWhitelist: v.PrivateHostWhitelist,
+		}, WebToolsSecurity{
+			Brave:      braveSecurity,
+			Tavily:     tavilySecurity,
+			Perplexity: perplexitySecurity,
+			GLMSearch:  glmSearchSecurity,
+		}
+}
+
+type skillsToolsConfigV0 struct {
+	ToolConfig            `                         envPrefix:"PICOCLAW_TOOLS_SKILLS_"`
+	Registries            skillsRegistriesConfigV0 `                                   json:"registries"`
+	Github                skillsGithubConfigV0     `                                   json:"github"`
+	MaxConcurrentSearches int                      `                                   json:"max_concurrent_searches" env:"PICOCLAW_TOOLS_SKILLS_MAX_CONCURRENT_SEARCHES"`
+	SearchCache           SearchCacheConfig        `                                   json:"search_cache"`
+}
+
+type skillsRegistriesConfigV0 struct {
+	ClawHub clawHubRegistryConfigV0 `json:"clawhub"`
+}
+
+type clawHubRegistryConfigV0 struct {
+	Enabled    bool   `json:"enabled"     env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_ENABLED"`
+	BaseURL    string `json:"base_url"    env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_BASE_URL"`
+	AuthToken  string `json:"auth_token"  env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_AUTH_TOKEN"`
+	SearchPath string `json:"search_path" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_SEARCH_PATH"`
+	SkillsPath string `json:"skills_path" env:"PICOCLAW_SKILLS_REGISTRIES_CLAWHUB_SKILLS_PATH"`
+}
+
+func (v *clawHubRegistryConfigV0) ToClawHubRegistryConfig() (ClawHubRegistryConfig, *ClawHubSecurity) {
+	var sec *ClawHubSecurity
+	if v.AuthToken != "" {
+		sec = &ClawHubSecurity{
+			AuthToken: v.AuthToken,
+		}
+	}
+	return ClawHubRegistryConfig{
+		Enabled:    v.Enabled,
+		BaseURL:    v.BaseURL,
+		authToken:  v.AuthToken,
+		SearchPath: v.SearchPath,
+		SkillsPath: v.SkillsPath,
+	}, sec
+}
+
+type skillsGithubConfigV0 struct {
+	Token string `json:"token"           env:"PICOCLAW_TOOLS_SKILLS_GITHUB_TOKEN"`
+	Proxy string `json:"proxy,omitempty" env:"PICOCLAW_TOOLS_SKILLS_GITHUB_PROXY"`
+}
+
+func (v *skillsGithubConfigV0) ToSkillsGithubConfig() (SkillsGithubConfig, *GithubSecurity) {
+	var sec *GithubSecurity
+	if v.Token != "" {
+		sec = &GithubSecurity{
+			Token: v.Token,
+		}
+	}
+	return SkillsGithubConfig{
+		token: v.Token,
+		Proxy: v.Proxy,
+	}, sec
+}
+
+func (v *skillsRegistriesConfigV0) ToSkillsRegistriesConfig() (SkillsRegistriesConfig, *ClawHubSecurity) {
+	clawHub, clawHubSecurity := v.ClawHub.ToClawHubRegistryConfig()
+
+	return SkillsRegistriesConfig{
+		ClawHub: clawHub,
+	}, clawHubSecurity
+}
+
+func (v *skillsToolsConfigV0) ToSkillsToolsConfig() (SkillsToolsConfig, *SkillsSecurity) {
+	registries, registriesSecurity := v.Registries.ToSkillsRegistriesConfig()
+	github, githubSecurity := v.Github.ToSkillsGithubConfig()
+
+	var sec *SkillsSecurity
+	if githubSecurity != nil || registriesSecurity != nil {
+		sec = &SkillsSecurity{
+			Github:  githubSecurity,
+			ClawHub: registriesSecurity,
+		}
+	}
+	return SkillsToolsConfig{
+		ToolConfig:            v.ToolConfig,
+		Registries:            registries,
+		Github:                github,
+		MaxConcurrentSearches: v.MaxConcurrentSearches,
+		SearchCache:           v.SearchCache,
+	}, sec
+}
diff --git a/pkg/config/config_test.go b/pkg/config/config_test.go
index 6af7c209e..bedd46f6e 100644
--- a/pkg/config/config_test.go
+++ b/pkg/config/config_test.go
@@ -7,8 +7,25 @@ import (
 	"runtime"
 	"strings"
 	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"gopkg.in/yaml.v3"
+
+	"github.com/sipeed/picoclaw/pkg/credential"
 )
 
+// mustSetupSSHKey generates a temporary Ed25519 SSH key in t.TempDir() and sets
+// PICOCLAW_SSH_KEY_PATH to its path for the duration of the test. This is required
+// whenever a test exercises encryption/decryption via credential.Encrypt or SaveConfig.
+func mustSetupSSHKey(t *testing.T) {
+	t.Helper()
+	keyPath := filepath.Join(t.TempDir(), "picoclaw_ed25519.key")
+	if err := credential.GenerateSSHKey(keyPath); err != nil {
+		t.Fatalf("mustSetupSSHKey: %v", err)
+	}
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", keyPath)
+}
+
 func TestAgentModelConfig_UnmarshalString(t *testing.T) {
 	var m AgentModelConfig
 	if err := json.Unmarshal([]byte(`"gpt-4"`), &m); err != nil {
@@ -63,6 +80,23 @@ func TestAgentModelConfig_MarshalObject(t *testing.T) {
 	}
 }
 
+func TestProvidersConfig_IsEmpty(t *testing.T) {
+	var empty providersConfigV0
+	t.Logf("empty: %+v", empty)
+	if !empty.IsEmpty() {
+		t.Fatal("empty providersConfig should report empty")
+	}
+
+	novita := providersConfigV0{
+		Novita: providerConfigV0{
+			APIKey: "test-key",
+		},
+	}
+	if novita.IsEmpty() {
+		t.Fatal("providersConfig with novita settings should not report empty")
+	}
+}
+
 func TestAgentConfig_FullParse(t *testing.T) {
 	jsonData := `{
 		"agents": {
@@ -207,15 +241,6 @@ func TestDefaultConfig_WorkspacePath(t *testing.T) {
 	}
 }
 
-// TestDefaultConfig_Model verifies model is set
-func TestDefaultConfig_Model(t *testing.T) {
-	cfg := DefaultConfig()
-
-	if cfg.Agents.Defaults.Model != "" {
-		t.Error("Model should be empty")
-	}
-}
-
 // TestDefaultConfig_MaxTokens verifies max tokens has default value
 func TestDefaultConfig_MaxTokens(t *testing.T) {
 	cfg := DefaultConfig()
@@ -253,20 +278,8 @@ func TestDefaultConfig_Gateway(t *testing.T) {
 	if cfg.Gateway.Port == 0 {
 		t.Error("Gateway port should have default value")
 	}
-}
-
-// TestDefaultConfig_Providers verifies provider structure
-func TestDefaultConfig_Providers(t *testing.T) {
-	cfg := DefaultConfig()
-
-	if cfg.Providers.Anthropic.APIKey != "" {
-		t.Error("Anthropic API key should be empty by default")
-	}
-	if cfg.Providers.OpenAI.APIKey != "" {
-		t.Error("OpenAI API key should be empty by default")
-	}
-	if cfg.Providers.OpenRouter.APIKey != "" {
-		t.Error("OpenRouter API key should be empty by default")
+	if cfg.Gateway.HotReload {
+		t.Error("Gateway hot reload should be disabled by default")
 	}
 }
 
@@ -283,6 +296,9 @@ func TestDefaultConfig_Channels(t *testing.T) {
 	if cfg.Channels.Slack.Enabled {
 		t.Error("Slack should be disabled by default")
 	}
+	if cfg.Channels.Matrix.Enabled {
+		t.Error("Matrix should be disabled by default")
+	}
 }
 
 // TestDefaultConfig_WebTools verifies web tools config
@@ -293,7 +309,7 @@ func TestDefaultConfig_WebTools(t *testing.T) {
 	if cfg.Tools.Web.Brave.MaxResults != 5 {
 		t.Error("Expected Brave MaxResults 5, got ", cfg.Tools.Web.Brave.MaxResults)
 	}
-	if cfg.Tools.Web.Brave.APIKey != "" {
+	if len(cfg.Tools.Web.Brave.APIKeys()) != 0 {
 		t.Error("Brave API key should be empty by default")
 	}
 	if cfg.Tools.Web.DuckDuckGo.MaxResults != 5 {
@@ -339,8 +355,98 @@ func TestSaveConfig_IncludesEmptyLegacyModelField(t *testing.T) {
 		t.Fatalf("ReadFile failed: %v", err)
 	}
 
-	if !strings.Contains(string(data), `"model": ""`) {
-		t.Fatalf("saved config should include empty legacy model field, got: %s", string(data))
+	if !strings.Contains(string(data), `"model_name": ""`) {
+		t.Fatalf("saved config should include empty legacy model_name field, got: %s", string(data))
+	}
+}
+
+func TestSaveConfig_PreservesDisabledTelegramPlaceholder(t *testing.T) {
+	tmpDir := t.TempDir()
+	path := filepath.Join(tmpDir, "config.json")
+
+	cfg := DefaultConfig()
+	cfg.Channels.Telegram.Placeholder.Enabled = false
+
+	if err := SaveConfig(path, cfg); err != nil {
+		t.Fatalf("SaveConfig failed: %v", err)
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile failed: %v", err)
+	}
+	if !strings.Contains(string(data), `"placeholder": {`) {
+		t.Fatalf("saved config should include telegram placeholder config, got: %s", string(data))
+	}
+	if !strings.Contains(string(data), `"enabled": false`) {
+		t.Fatalf("saved config should persist placeholder.enabled=false, got: %s", string(data))
+	}
+
+	loaded, err := LoadConfig(path)
+	if err != nil {
+		t.Fatalf("LoadConfig failed: %v", err)
+	}
+	if loaded.Channels.Telegram.Placeholder.Enabled {
+		t.Fatal("telegram placeholder should remain disabled after SaveConfig/LoadConfig round-trip")
+	}
+}
+
+// TestSaveConfig_FiltersVirtualModels verifies that SaveConfig does not write
+// virtual models (generated by expandMultiKeyModels) to the config file.
+func TestSaveConfig_FiltersVirtualModels(t *testing.T) {
+	tmpDir := t.TempDir()
+	path := filepath.Join(tmpDir, "config.json")
+
+	cfg := DefaultConfig()
+
+	// Manually add a virtual model to ModelList (simulating what expandMultiKeyModels does)
+	primaryModel := &ModelConfig{
+		ModelName: "gpt-4",
+		Model:     "openai/gpt-4o",
+		apiKeys:   []string{"key1"},
+	}
+	virtualModel := &ModelConfig{
+		ModelName: "gpt-4__key_1",
+		Model:     "openai/gpt-4o",
+		apiKeys:   []string{"key2"},
+		isVirtual: true,
+	}
+	cfg.ModelList = []*ModelConfig{primaryModel, virtualModel}
+
+	// SaveConfig should filter out virtual models
+	if err := SaveConfig(path, cfg); err != nil {
+		t.Fatalf("SaveConfig failed: %v", err)
+	}
+
+	// Reload and verify
+	reloaded, err := LoadConfig(path)
+	if err != nil {
+		t.Fatalf("LoadConfig failed: %v", err)
+	}
+
+	// Should only have the primary model, not the virtual one
+	if len(reloaded.ModelList) != 1 {
+		t.Fatalf("expected 1 model after reload, got %d", len(reloaded.ModelList))
+	}
+
+	if reloaded.ModelList[0].ModelName != "gpt-4" {
+		t.Errorf("expected model_name 'gpt-4', got %q", reloaded.ModelList[0].ModelName)
+	}
+
+	// Verify virtual model was not persisted
+	for _, m := range reloaded.ModelList {
+		if m.ModelName == "gpt-4__key_1" {
+			t.Errorf("virtual model gpt-4__key_1 should not have been saved")
+		}
+	}
+
+	// Verify the saved file does not contain the virtual model name
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("ReadFile failed: %v", err)
+	}
+	if strings.Contains(string(data), "gpt-4__key_1") {
+		t.Errorf("saved config should not contain virtual model name 'gpt-4__key_1'")
 	}
 }
 
@@ -351,9 +457,6 @@ func TestConfig_Complete(t *testing.T) {
 	if cfg.Agents.Defaults.Workspace == "" {
 		t.Error("Workspace should not be empty")
 	}
-	if cfg.Agents.Defaults.Model != "" {
-		t.Error("Model should be empty")
-	}
 	if cfg.Agents.Defaults.Temperature != nil {
 		t.Error("Temperature should be nil when not provided")
 	}
@@ -372,19 +475,22 @@ func TestConfig_Complete(t *testing.T) {
 	if !cfg.Heartbeat.Enabled {
 		t.Error("Heartbeat should be enabled by default")
 	}
+	if !cfg.Tools.Exec.AllowRemote {
+		t.Error("Exec.AllowRemote should be true by default")
+	}
 }
 
-func TestDefaultConfig_OpenAIWebSearchEnabled(t *testing.T) {
+func TestDefaultConfig_WebPreferNativeEnabled(t *testing.T) {
 	cfg := DefaultConfig()
-	if !cfg.Providers.OpenAI.WebSearch {
-		t.Fatal("DefaultConfig().Providers.OpenAI.WebSearch should be true")
+	if !cfg.Tools.Web.PreferNative {
+		t.Fatal("DefaultConfig().Tools.Web.PreferNative should be true")
 	}
 }
 
-func TestLoadConfig_OpenAIWebSearchDefaultsTrueWhenUnset(t *testing.T) {
+func TestLoadConfig_WebPreferNativeDefaultsTrueWhenUnset(t *testing.T) {
 	dir := t.TempDir()
 	configPath := filepath.Join(dir, "config.json")
-	if err := os.WriteFile(configPath, []byte(`{"providers":{"openai":{"api_base":""}}}`), 0o600); err != nil {
+	if err := os.WriteFile(configPath, []byte(`{"version":1,"tools":{"web":{"enabled":true}}}`), 0o600); err != nil {
 		t.Fatalf("WriteFile() error: %v", err)
 	}
 
@@ -392,15 +498,15 @@ func TestLoadConfig_OpenAIWebSearchDefaultsTrueWhenUnset(t *testing.T) {
 	if err != nil {
 		t.Fatalf("LoadConfig() error: %v", err)
 	}
-	if !cfg.Providers.OpenAI.WebSearch {
-		t.Fatal("OpenAI codex web search should remain true when unset in config file")
+	if !cfg.Tools.Web.PreferNative {
+		t.Fatal("PreferNative should remain true when unset in config file")
 	}
 }
 
-func TestLoadConfig_OpenAIWebSearchCanBeDisabled(t *testing.T) {
+func TestLoadConfig_WebPreferNativeCanBeDisabled(t *testing.T) {
 	dir := t.TempDir()
 	configPath := filepath.Join(dir, "config.json")
-	if err := os.WriteFile(configPath, []byte(`{"providers":{"openai":{"web_search":false}}}`), 0o600); err != nil {
+	if err := os.WriteFile(configPath, []byte(`{"tools":{"web":{"prefer_native":false}}}`), 0o600); err != nil {
 		t.Fatalf("WriteFile() error: %v", err)
 	}
 
@@ -408,8 +514,116 @@ func TestLoadConfig_OpenAIWebSearchCanBeDisabled(t *testing.T) {
 	if err != nil {
 		t.Fatalf("LoadConfig() error: %v", err)
 	}
-	if cfg.Providers.OpenAI.WebSearch {
-		t.Fatal("OpenAI codex web search should be false when disabled in config file")
+	if cfg.Tools.Web.PreferNative {
+		t.Fatal("PreferNative should be false when disabled in config file")
+	}
+}
+
+func TestDefaultConfig_ExecAllowRemoteEnabled(t *testing.T) {
+	cfg := DefaultConfig()
+	if !cfg.Tools.Exec.AllowRemote {
+		t.Fatal("DefaultConfig().Tools.Exec.AllowRemote should be true")
+	}
+}
+
+func TestDefaultConfig_FilterSensitiveDataEnabled(t *testing.T) {
+	cfg := DefaultConfig()
+	if !cfg.Tools.FilterSensitiveData {
+		t.Fatal("DefaultConfig().Tools.FilterSensitiveData should be true")
+	}
+}
+
+func TestDefaultConfig_FilterMinLength(t *testing.T) {
+	cfg := DefaultConfig()
+	if cfg.Tools.FilterMinLength != 8 {
+		t.Fatalf("DefaultConfig().Tools.FilterMinLength = %d, want 8", cfg.Tools.FilterMinLength)
+	}
+}
+
+func TestToolsConfig_GetFilterMinLength(t *testing.T) {
+	tests := []struct {
+		name     string
+		minLen   int
+		expected int
+	}{
+		{"zero returns default", 0, 8},
+		{"negative returns default", -1, 8},
+		{"positive returns value", 16, 16},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := &ToolsConfig{FilterMinLength: tt.minLen}
+			if got := cfg.GetFilterMinLength(); got != tt.expected {
+				t.Errorf("GetFilterMinLength() = %v, want %v", got, tt.expected)
+			}
+		})
+	}
+}
+
+func TestDefaultConfig_CronAllowCommandEnabled(t *testing.T) {
+	cfg := DefaultConfig()
+	if !cfg.Tools.Cron.AllowCommand {
+		t.Fatal("DefaultConfig().Tools.Cron.AllowCommand should be true")
+	}
+}
+
+func TestDefaultConfig_HooksDefaults(t *testing.T) {
+	cfg := DefaultConfig()
+	if !cfg.Hooks.Enabled {
+		t.Fatal("DefaultConfig().Hooks.Enabled should be true")
+	}
+	if cfg.Hooks.Defaults.ObserverTimeoutMS != 500 {
+		t.Fatalf("ObserverTimeoutMS = %d, want 500", cfg.Hooks.Defaults.ObserverTimeoutMS)
+	}
+	if cfg.Hooks.Defaults.InterceptorTimeoutMS != 5000 {
+		t.Fatalf("InterceptorTimeoutMS = %d, want 5000", cfg.Hooks.Defaults.InterceptorTimeoutMS)
+	}
+	if cfg.Hooks.Defaults.ApprovalTimeoutMS != 60000 {
+		t.Fatalf("ApprovalTimeoutMS = %d, want 60000", cfg.Hooks.Defaults.ApprovalTimeoutMS)
+	}
+}
+
+func TestDefaultConfig_LogLevel(t *testing.T) {
+	cfg := DefaultConfig()
+	if cfg.Gateway.LogLevel != "fatal" {
+		t.Errorf("LogLevel = %q, want \"fatal\"", cfg.Gateway.LogLevel)
+	}
+}
+
+func TestLoadConfig_ExecAllowRemoteDefaultsTrueWhenUnset(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "config.json")
+	if err := os.WriteFile(configPath, []byte(`{"version":1,"tools":{"exec":{"enable_deny_patterns":true}}}`),
+		0o600); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	cfg, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error: %v", err)
+	}
+	if !cfg.Tools.Exec.AllowRemote {
+		t.Fatal("tools.exec.allow_remote should remain true when unset in config file")
+	}
+}
+
+func TestLoadConfig_CronAllowCommandDefaultsTrueWhenUnset(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "config.json")
+	if err := os.WriteFile(
+		configPath,
+		[]byte(`{"version":1,"tools":{"cron":{"exec_timeout_minutes":5}}}`),
+		0o600,
+	); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	cfg, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error: %v", err)
+	}
+	if !cfg.Tools.Cron.AllowCommand {
+		t.Fatal("tools.cron.allow_command should remain true when unset in config file")
 	}
 }
 
@@ -418,7 +632,7 @@ func TestLoadConfig_WebToolsProxy(t *testing.T) {
 	configPath := filepath.Join(tmpDir, "config.json")
 	configJSON := `{
   "agents": {"defaults":{"workspace":"./workspace","model":"gpt4","max_tokens":8192,"max_tool_iterations":20}},
-  "model_list": [{"model_name":"gpt4","model":"openai/gpt-5.2","api_key":"x"}],
+  "model_list": [{"model_name":"gpt4","model":"openai/gpt-5.4","api_key":"x"}],
   "tools": {"web":{"proxy":"http://127.0.0.1:7890"}}
 }`
 	if err := os.WriteFile(configPath, []byte(configJSON), 0o600); err != nil {
@@ -434,7 +648,102 @@ func TestLoadConfig_WebToolsProxy(t *testing.T) {
 	}
 }
 
+func TestLoadConfig_HooksProcessConfig(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+	configJSON := `{
+  "version": 1,
+  "hooks": {
+    "processes": {
+      "review-gate": {
+        "enabled": true,
+        "transport": "stdio",
+        "command": ["uvx", "picoclaw-hook-reviewer"],
+        "dir": "/tmp/hooks",
+        "env": {
+          "HOOK_MODE": "rewrite"
+        },
+        "observe": ["turn_start", "turn_end"],
+        "intercept": ["before_tool", "approve_tool"]
+      }
+    },
+    "builtins": {
+      "audit": {
+        "enabled": true,
+        "priority": 5,
+        "config": {
+          "label": "audit"
+        }
+      }
+    }
+  }
+}`
+	if err := os.WriteFile(configPath, []byte(configJSON), 0o600); err != nil {
+		t.Fatalf("os.WriteFile() error: %v", err)
+	}
+
+	cfg, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error: %v", err)
+	}
+
+	processCfg, ok := cfg.Hooks.Processes["review-gate"]
+	if !ok {
+		t.Fatal("expected review-gate process hook")
+	}
+	if !processCfg.Enabled {
+		t.Fatal("expected review-gate process hook to be enabled")
+	}
+	if processCfg.Transport != "stdio" {
+		t.Fatalf("Transport = %q, want stdio", processCfg.Transport)
+	}
+	if len(processCfg.Command) != 2 || processCfg.Command[0] != "uvx" {
+		t.Fatalf("Command = %v", processCfg.Command)
+	}
+	if processCfg.Dir != "/tmp/hooks" {
+		t.Fatalf("Dir = %q, want /tmp/hooks", processCfg.Dir)
+	}
+	if processCfg.Env["HOOK_MODE"] != "rewrite" {
+		t.Fatalf("HOOK_MODE = %q, want rewrite", processCfg.Env["HOOK_MODE"])
+	}
+	if len(processCfg.Observe) != 2 || processCfg.Observe[1] != "turn_end" {
+		t.Fatalf("Observe = %v", processCfg.Observe)
+	}
+	if len(processCfg.Intercept) != 2 || processCfg.Intercept[1] != "approve_tool" {
+		t.Fatalf("Intercept = %v", processCfg.Intercept)
+	}
+
+	builtinCfg, ok := cfg.Hooks.Builtins["audit"]
+	if !ok {
+		t.Fatal("expected audit builtin hook")
+	}
+	if !builtinCfg.Enabled {
+		t.Fatal("expected audit builtin hook to be enabled")
+	}
+	if builtinCfg.Priority != 5 {
+		t.Fatalf("Priority = %d, want 5", builtinCfg.Priority)
+	}
+	if !strings.Contains(string(builtinCfg.Config), `"audit"`) {
+		t.Fatalf("Config = %s", string(builtinCfg.Config))
+	}
+	if cfg.Hooks.Defaults.ApprovalTimeoutMS != 60000 {
+		t.Fatalf("ApprovalTimeoutMS = %d, want 60000", cfg.Hooks.Defaults.ApprovalTimeoutMS)
+	}
+}
+
 // TestDefaultConfig_DMScope verifies the default dm_scope value
+// TestDefaultConfig_SummarizationThresholds verifies summarization defaults
+func TestDefaultConfig_SummarizationThresholds(t *testing.T) {
+	cfg := DefaultConfig()
+
+	if cfg.Agents.Defaults.SummarizeMessageThreshold != 20 {
+		t.Errorf("SummarizeMessageThreshold = %d, want 20", cfg.Agents.Defaults.SummarizeMessageThreshold)
+	}
+	if cfg.Agents.Defaults.SummarizeTokenPercent != 75 {
+		t.Errorf("SummarizeTokenPercent = %d, want 75", cfg.Agents.Defaults.SummarizeTokenPercent)
+	}
+}
+
 func TestDefaultConfig_DMScope(t *testing.T) {
 	cfg := DefaultConfig()
 
@@ -444,13 +753,19 @@ func TestDefaultConfig_DMScope(t *testing.T) {
 }
 
 func TestDefaultConfig_WorkspacePath_Default(t *testing.T) {
-	// Unset to ensure we test the default
 	t.Setenv("PICOCLAW_HOME", "")
-	// Set a known home for consistent test results
-	t.Setenv("HOME", "/tmp/home")
+
+	var fakeHome string
+	if runtime.GOOS == "windows" {
+		fakeHome = `C:\tmp\home`
+		t.Setenv("USERPROFILE", fakeHome)
+	} else {
+		fakeHome = "/tmp/home"
+		t.Setenv("HOME", fakeHome)
+	}
 
 	cfg := DefaultConfig()
-	want := filepath.Join("/tmp/home", ".picoclaw", "workspace")
+	want := filepath.Join(fakeHome, ".picoclaw", "workspace")
 
 	if cfg.Agents.Defaults.Workspace != want {
 		t.Errorf("Default workspace path = %q, want %q", cfg.Agents.Defaults.Workspace, want)
@@ -461,9 +776,782 @@ func TestDefaultConfig_WorkspacePath_WithPicoclawHome(t *testing.T) {
 	t.Setenv("PICOCLAW_HOME", "/custom/picoclaw/home")
 
 	cfg := DefaultConfig()
-	want := "/custom/picoclaw/home/workspace"
+	want := filepath.Join("/custom/picoclaw/home", "workspace")
 
 	if cfg.Agents.Defaults.Workspace != want {
 		t.Errorf("Workspace path with PICOCLAW_HOME = %q, want %q", cfg.Agents.Defaults.Workspace, want)
 	}
 }
+
+// TestFlexibleStringSlice_UnmarshalText tests UnmarshalText with various comma separators
+func TestFlexibleStringSlice_UnmarshalText(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    string
+		expected []string
+	}{
+		{
+			name:     "English commas only",
+			input:    "123,456,789",
+			expected: []string{"123", "456", "789"},
+		},
+		{
+			name:     "Chinese commas only",
+			input:    "123，456，789",
+			expected: []string{"123", "456", "789"},
+		},
+		{
+			name:     "Mixed English and Chinese commas",
+			input:    "123,456，789",
+			expected: []string{"123", "456", "789"},
+		},
+		{
+			name:     "Single value",
+			input:    "123",
+			expected: []string{"123"},
+		},
+		{
+			name:     "Values with whitespace",
+			input:    " 123 , 456 , 789 ",
+			expected: []string{"123", "456", "789"},
+		},
+		{
+			name:     "Empty string",
+			input:    "",
+			expected: nil,
+		},
+		{
+			name:     "Only commas - English",
+			input:    ",,",
+			expected: []string{},
+		},
+		{
+			name:     "Only commas - Chinese",
+			input:    "，，",
+			expected: []string{},
+		},
+		{
+			name:     "Mixed commas with empty parts",
+			input:    "123,,456，，789",
+			expected: []string{"123", "456", "789"},
+		},
+		{
+			name:     "Complex mixed values",
+			input:    "user1@example.com，user2@test.com, admin@domain.org",
+			expected: []string{"user1@example.com", "user2@test.com", "admin@domain.org"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var f FlexibleStringSlice
+			err := f.UnmarshalText([]byte(tt.input))
+			if err != nil {
+				t.Fatalf("UnmarshalText(%q) error = %v", tt.input, err)
+			}
+
+			if tt.expected == nil {
+				if f != nil {
+					t.Errorf("UnmarshalText(%q) = %v, want nil", tt.input, f)
+				}
+				return
+			}
+
+			if len(f) != len(tt.expected) {
+				t.Errorf("UnmarshalText(%q) length = %d, want %d", tt.input, len(f), len(tt.expected))
+				return
+			}
+
+			for i, v := range tt.expected {
+				if f[i] != v {
+					t.Errorf("UnmarshalText(%q)[%d] = %q, want %q", tt.input, i, f[i], v)
+				}
+			}
+		})
+	}
+}
+
+// TestFlexibleStringSlice_UnmarshalText_EmptySliceConsistency tests nil vs empty slice behavior
+func TestFlexibleStringSlice_UnmarshalText_EmptySliceConsistency(t *testing.T) {
+	t.Run("Empty string returns nil", func(t *testing.T) {
+		var f FlexibleStringSlice
+		err := f.UnmarshalText([]byte(""))
+		if err != nil {
+			t.Fatalf("UnmarshalText error = %v", err)
+		}
+		if f != nil {
+			t.Errorf("Empty string should return nil, got %v", f)
+		}
+	})
+
+	t.Run("Commas only returns empty slice", func(t *testing.T) {
+		var f FlexibleStringSlice
+		err := f.UnmarshalText([]byte(",,,"))
+		if err != nil {
+			t.Fatalf("UnmarshalText error = %v", err)
+		}
+		if f == nil {
+			t.Error("Commas only should return empty slice, not nil")
+		}
+		if len(f) != 0 {
+			t.Errorf("Expected empty slice, got %v", f)
+		}
+	})
+}
+
+// TestLoadConfig_WarnsForPlaintextAPIKey verifies that LoadConfig resolves a plaintext
+// api_key into memory but does NOT rewrite the config file. File writes are the sole
+// responsibility of SaveConfig.
+func TestLoadConfig_WarnsForPlaintextAPIKey(t *testing.T) {
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+	const original = `{"version":1,"model_list":[{"model_name":"test","model":"openai/gpt-4","api_key":"sk-plaintext"}]}`
+	if err := os.WriteFile(cfgPath, []byte(original), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	secPath := filepath.Join(dir, SecurityConfigFile)
+	const securityConfig = `
+model_list:
+  test:0:
+    api_keys:
+      - "sk-plaintext"
+`
+	if err := os.WriteFile(secPath, []byte(securityConfig), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	if err := os.WriteFile(cfgPath, []byte(original), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "test-passphrase")
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", "")
+
+	cfg, err := LoadConfig(cfgPath)
+	if err != nil {
+		t.Fatalf("LoadConfig: %v", err)
+	}
+	// In-memory value must be the resolved plaintext.
+	if cfg.ModelList[0].APIKey() != "sk-plaintext" {
+		t.Errorf("in-memory api_key = %q, want %q", cfg.ModelList[0].APIKey(), "sk-plaintext")
+	}
+	// The file on disk must remain unchanged — no need upgrade version
+	raw, _ := os.ReadFile(cfgPath)
+	if string(raw) != original {
+		t.Errorf("LoadConfig must not modify the config file; got:\n%s", string(raw))
+	}
+}
+
+// TestSaveConfig_EncryptsPlaintextAPIKey verifies that SaveConfig writes enc:// ciphertext
+// to disk and that a subsequent LoadConfig decrypts it back to the original plaintext.
+func TestSaveConfig_EncryptsPlaintextAPIKey(t *testing.T) {
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "test-passphrase")
+	mustSetupSSHKey(t)
+
+	cfg := DefaultConfig()
+	cfg.ModelList = []*ModelConfig{
+		{ModelName: "test", Model: "openai/gpt-4", apiKeys: []string{"sk-plaintext"}},
+	}
+	cfg.security = &SecurityConfig{
+		ModelList: map[string]ModelSecurityEntry{"test:0": {APIKeys: []string{"sk-plaintext"}}},
+	}
+	if err := SaveConfig(cfgPath, cfg); err != nil {
+		t.Fatalf("SaveConfig: %v", err)
+	}
+
+	// Disk must contain enc://, not the raw key.
+	secPath := filepath.Join(dir, SecurityConfigFile)
+	raw, _ := os.ReadFile(secPath)
+	if !strings.Contains(string(raw), "enc://") {
+		t.Errorf("saved file should contain enc://, got:\n%s", string(raw))
+	}
+	if strings.Contains(string(raw), "sk-plaintext") {
+		t.Errorf("saved file must not contain the plaintext key")
+	}
+
+	// A fresh load must decrypt back to the original plaintext.
+	cfg2, err := LoadConfig(cfgPath)
+	if err != nil {
+		t.Fatalf("LoadConfig after SaveConfig: %v", err)
+	}
+	if cfg2.ModelList[0].APIKey() != "sk-plaintext" {
+		t.Errorf("loaded api_key = %q, want %q", cfg2.ModelList[0].APIKey(), "sk-plaintext")
+	}
+}
+
+// TestLoadConfig_NoSealWithoutPassphrase verifies that api_key values are left
+// unchanged when PICOCLAW_KEY_PASSPHRASE is not set.
+func TestLoadConfig_NoSealWithoutPassphrase(t *testing.T) {
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+	data := `{"model_list":[{"model_name":"test","model":"openai/gpt-4","api_key":"sk-plaintext"}]}`
+	if err := os.WriteFile(cfgPath, []byte(data), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "")
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", "")
+
+	if _, err := LoadConfig(cfgPath); err != nil {
+		t.Fatalf("LoadConfig: %v", err)
+	}
+
+	raw, _ := os.ReadFile(cfgPath)
+	if strings.Contains(string(raw), "enc://") {
+		t.Error("config file must not be modified when no passphrase is set")
+	}
+}
+
+// TestLoadConfig_FileRefNotSealed verifies that file:// api_key references are not
+// converted to enc:// values (they are resolved at runtime by the Resolver).
+func TestLoadConfig_FileRefNotSealed(t *testing.T) {
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+	keyFile := filepath.Join(dir, "openai.key")
+	if err := os.WriteFile(keyFile, []byte("sk-from-file"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	data := `{"version":1,"model_list":[{"model_name":"test","model":"openai/gpt-4"}]}`
+	if err := os.WriteFile(cfgPath, []byte(data), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	secPath := filepath.Join(dir, SecurityConfigFile)
+	if err := saveSecurityConfig(
+		secPath,
+		&SecurityConfig{ModelList: map[string]ModelSecurityEntry{"test:0": {APIKeys: []string{"file://openai.key"}}}},
+	); err != nil {
+		t.Fatalf("saveSecurityConfig: %v", err)
+	}
+
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "test-passphrase")
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", "")
+
+	if _, err := LoadConfig(cfgPath); err != nil {
+		t.Fatalf("LoadConfig: %v", err)
+	}
+
+	raw, _ := os.ReadFile(secPath)
+	if !strings.Contains(string(raw), "file://openai.key") {
+		t.Error("file:// reference should be preserved unchanged in the config file")
+	}
+	if strings.Contains(string(raw), "enc://") {
+		t.Error("file:// reference must not be converted to enc://")
+	}
+}
+
+// TestSaveConfig_MixedKeys verifies that SaveConfig encrypts only plaintext api_keys
+// and leaves already-encrypted (enc://) and file:// entries unchanged.
+func TestSaveConfig_MixedKeys(t *testing.T) {
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "test-passphrase")
+	mustSetupSSHKey(t)
+
+	// Pre-encrypt one key so we have a genuine enc:// value to put in the config.
+	if err := SaveConfig(cfgPath, &Config{
+		ModelList: []*ModelConfig{
+			{ModelName: "pre", Model: "openai/gpt-4"},
+		},
+		security: &SecurityConfig{
+			ModelList: map[string]ModelSecurityEntry{
+				"pre:0": {APIKeys: []string{"sk-already-plain"}},
+			},
+		},
+	}); err != nil {
+		t.Fatalf("setup SaveConfig: %v", err)
+	}
+	raw, _ := os.ReadFile(filepath.Join(dir, SecurityConfigFile))
+	// Extract the enc:// value from the saved file.
+	var tmp struct {
+		ModelList map[string]struct {
+			APIKeys []string `yaml:"api_keys"`
+		} `yaml:"model_list"`
+	}
+	if err := yaml.Unmarshal(raw, &tmp); err != nil || len(tmp.ModelList) == 0 {
+		t.Fatalf("setup: could not parse saved config: %v", err)
+	}
+	alreadyEncrypted := tmp.ModelList["pre:0"].APIKeys[0]
+	if !strings.HasPrefix(alreadyEncrypted, "enc://") {
+		t.Fatalf("setup: expected enc:// key, got %q", alreadyEncrypted)
+	}
+
+	// Build a config with three models:
+	//   1. plaintext   → must be encrypted by SaveConfig
+	//   2. enc://      → must be left unchanged (already encrypted)
+	//   3. file://     → must be left unchanged (file reference)
+	keyFile := filepath.Join(dir, "api.key")
+	if err := os.WriteFile(keyFile, []byte("sk-from-file"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	cfg := &Config{
+		ModelList: []*ModelConfig{
+			{ModelName: "plain", Model: "openai/gpt-4", apiKeys: []string{"sk-new-plaintext"}},
+			{ModelName: "enc", Model: "openai/gpt-4", apiKeys: []string{alreadyEncrypted}},
+			{ModelName: "file", Model: "openai/gpt-4", apiKeys: []string{"file://api.key"}},
+		},
+		security: &SecurityConfig{
+			ModelList: map[string]ModelSecurityEntry{
+				"plain:0": {APIKeys: []string{"sk-new-plaintext"}},
+				"enc:0":   {APIKeys: []string{alreadyEncrypted}},
+				"file:0":  {APIKeys: []string{"file://api.key"}},
+			},
+		},
+	}
+	if err := SaveConfig(cfgPath, cfg); err != nil {
+		t.Fatalf("SaveConfig: %v", err)
+	}
+
+	raw, _ = os.ReadFile(filepath.Join(dir, SecurityConfigFile))
+	s := string(raw)
+
+	t.Logf("saved file:\n%s", s)
+
+	// 1. Plaintext must be encrypted.
+	if strings.Contains(s, "sk-new-plaintext") {
+		t.Error("plaintext key must not appear in saved file")
+	}
+	// 2. The pre-existing enc:// value must still be present (byte-for-byte unchanged).
+	if !strings.Contains(s, alreadyEncrypted) {
+		t.Error("pre-existing enc:// entry must be preserved unchanged")
+	}
+	// 3. file:// must be preserved.
+	if !strings.Contains(s, "file://api.key") {
+		t.Error("file:// reference must be preserved unchanged")
+	}
+
+	// Now load and verify all three decrypt/resolve correctly.
+	cfg2, err := LoadConfig(cfgPath)
+	if err != nil {
+		t.Fatalf("LoadConfig after SaveConfig: %v", err)
+	}
+	byName := make(map[string]string)
+	for _, m := range cfg2.ModelList {
+		byName[m.ModelName] = m.APIKey()
+	}
+	if byName["plain"] != "sk-new-plaintext" {
+		t.Errorf("plain model api_key = %q, want %q", byName["plain"], "sk-new-plaintext")
+	}
+	if byName["enc"] != "sk-already-plain" {
+		t.Errorf("enc model api_key = %q, want %q", byName["enc"], "sk-already-plain")
+	}
+	if byName["file"] != "sk-from-file" {
+		t.Errorf("file model api_key = %q, want %q", byName["file"], "sk-from-file")
+	}
+}
+
+// TestLoadConfig_MixedKeys_NoPassphrase verifies that when PICOCLAW_KEY_PASSPHRASE
+// is not set, enc:// entries cause LoadConfig to return an error, while plaintext
+// and file:// entries in the same config are not affected.
+func TestLoadConfig_MixedKeys_NoPassphrase(t *testing.T) {
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+
+	// First encrypt a key so we have a real enc:// value.
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "test-passphrase")
+	mustSetupSSHKey(t)
+	if err := SaveConfig(cfgPath, &Config{
+		ModelList: []*ModelConfig{
+			{ModelName: "m", Model: "openai/gpt-4", apiKeys: []string{"sk-secret"}},
+		},
+		security: &SecurityConfig{
+			ModelList: map[string]ModelSecurityEntry{
+				"m:0": {APIKeys: []string{"sk-secret"}},
+			},
+		},
+	}); err != nil {
+		t.Fatalf("setup SaveConfig: %v", err)
+	}
+	raw, err := LoadConfig(cfgPath)
+	assert.NoError(t, err)
+	encValue := raw.security.ModelList["m:0"].APIKeys[0]
+	assert.NotEmpty(t, encValue)
+	assert.Equal(t, "enc://", encValue[:6])
+
+	// Write a mixed config: enc:// + plaintext + file://
+	keyFile := filepath.Join(dir, "api.key")
+	if err = os.WriteFile(keyFile, []byte("sk-from-file"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	mixed, _ := json.Marshal(map[string]any{
+		"model_list": []map[string]any{
+			{"model_name": "enc", "model": "openai/gpt-4", "api_key": encValue},
+			{"model_name": "plain", "model": "openai/gpt-4", "api_key": "sk-plain"},
+			{"model_name": "file", "model": "openai/gpt-4", "api_key": "file://api.key"},
+		},
+	})
+	if err = os.WriteFile(cfgPath, mixed, 0o600); err != nil {
+		t.Fatalf("setup write: %v", err)
+	}
+	secs, _ := yaml.Marshal(map[string]any{
+		"model_list": map[string]map[string]any{
+			"enc:0":   {"api_keys": []string{encValue}},
+			"plain:0": {"api_keys": []string{"sk-plain"}},
+			"file:0":  {"api_keys": []string{"file://api.key"}},
+		},
+	})
+	if err = os.WriteFile(filepath.Join(dir, SecurityConfigFile), secs, 0o600); err != nil {
+		t.Fatalf("security write: %v", err)
+	}
+
+	// Now clear the passphrase — LoadConfig must fail because enc:// cannot be decrypted.
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "")
+
+	_, err = LoadConfig(cfgPath)
+	if err == nil {
+		t.Fatal("LoadConfig should fail when enc:// key is present and no passphrase is set")
+	}
+	if !strings.Contains(err.Error(), "passphrase required") {
+		t.Errorf("error should mention passphrase required, got: %v", err)
+	}
+}
+
+// TestSaveConfig_UsesPassphraseProvider verifies that SaveConfig encrypts plaintext
+// api_keys using credential.PassphraseProvider() rather than os.Getenv directly.
+// This matters for the launcher, which clears the environment variable and redirects
+// PassphraseProvider to an in-memory SecureStore.
+func TestSaveConfig_UsesPassphraseProvider(t *testing.T) {
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+
+	// Ensure the env var is empty — passphrase must come from PassphraseProvider only.
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "")
+	mustSetupSSHKey(t)
+
+	// Replace PassphraseProvider with an in-memory function (simulating SecureStore).
+	const testPassphrase = "provider-passphrase"
+	orig := credential.PassphraseProvider
+	credential.PassphraseProvider = func() string { return testPassphrase }
+	t.Cleanup(func() { credential.PassphraseProvider = orig })
+
+	cfg := DefaultConfig()
+	cfg.ModelList = []*ModelConfig{
+		{ModelName: "test", Model: "openai/gpt-4"},
+	}
+	cfg.security.ModelList["test:0"] = ModelSecurityEntry{APIKeys: []string{"sk-plaintext"}}
+	if err := SaveConfig(cfgPath, cfg); err != nil {
+		t.Fatalf("SaveConfig: %v", err)
+	}
+
+	raw, _ := os.ReadFile(filepath.Join(dir, SecurityConfigFile))
+	if !strings.Contains(string(raw), "enc://") {
+		t.Errorf("SaveConfig should have encrypted plaintext key via PassphraseProvider; got:\n%s", raw)
+	}
+}
+
+// TestLoadConfig_UsesPassphraseProvider verifies that LoadConfig decrypts enc:// keys
+// using credential.PassphraseProvider() rather than os.Getenv directly.
+func TestLoadConfig_UsesPassphraseProvider(t *testing.T) {
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+
+	// Ensure the env var is empty throughout.
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "")
+	mustSetupSSHKey(t)
+
+	const testPassphrase = "provider-passphrase"
+	const plainKey = "sk-secret"
+
+	// First, encrypt the key using the same passphrase.
+	encrypted, err := credential.Encrypt(testPassphrase, "", plainKey)
+	if err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	raw, _ := json.Marshal(map[string]any{
+		"model_list": []map[string]any{
+			{"model_name": "test", "model": "openai/gpt-4", "api_key": encrypted},
+		},
+	})
+	if err = os.WriteFile(cfgPath, raw, 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	// Redirect PassphraseProvider — env var is empty, so without this the load would fail.
+	orig := credential.PassphraseProvider
+	credential.PassphraseProvider = func() string { return testPassphrase }
+	t.Cleanup(func() { credential.PassphraseProvider = orig })
+
+	cfg, err := LoadConfig(cfgPath)
+	if err != nil {
+		t.Fatalf("LoadConfig: %v", err)
+	}
+	if cfg.ModelList[0].APIKey() != plainKey {
+		t.Errorf("api_key = %q, want %q", cfg.ModelList[0].APIKey(), plainKey)
+	}
+}
+
+func TestConfigParsesLogLevel(t *testing.T) {
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+	data := `{"version":1,"gateway":{"log_level":"debug"}}`
+	if err := os.WriteFile(cfgPath, []byte(data), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	cfg, err := LoadConfig(cfgPath)
+	if err != nil {
+		t.Fatalf("LoadConfig: %v", err)
+	}
+	if cfg.Gateway.LogLevel != "debug" {
+		t.Errorf("LogLevel = %q, want \"debug\"", cfg.Gateway.LogLevel)
+	}
+}
+
+func TestConfigLogLevelEmpty(t *testing.T) {
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+	data := `{"version":1}`
+	if err := os.WriteFile(cfgPath, []byte(data), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	cfg, err := LoadConfig(cfgPath)
+	if err != nil {
+		t.Fatalf("LoadConfig: %v", err)
+	}
+	// When config omits log_level, the DefaultConfig value ("fatal") is preserved.
+	if cfg.Gateway.LogLevel != "fatal" {
+		t.Errorf("LogLevel = %q, want \"fatal\"", cfg.Gateway.LogLevel)
+	}
+}
+
+func TestModelConfig_ExtraBodyRoundTrip(t *testing.T) {
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+
+	cfg := &Config{
+		ModelList: []*ModelConfig{
+			{
+				ModelName: "test-model",
+				Model:     "openai/test",
+				apiKeys:   []string{"sk-test"},
+				ExtraBody: map[string]any{"custom_field": "value", "num_field": 42},
+			},
+		},
+		security: &SecurityConfig{
+			ModelList: map[string]ModelSecurityEntry{"test-model:0": {APIKeys: []string{"sk-test"}}},
+		},
+	}
+
+	if err := SaveConfig(cfgPath, cfg); err != nil {
+		t.Fatalf("SaveConfig error: %v", err)
+	}
+
+	loaded, err := LoadConfig(cfgPath)
+	if err != nil {
+		t.Fatalf("LoadConfig error: %v", err)
+	}
+
+	if loaded.ModelList[0].ExtraBody == nil {
+		t.Fatal("ExtraBody should not be nil after round-trip")
+	}
+	if got := loaded.ModelList[0].ExtraBody["custom_field"]; got != "value" {
+		t.Errorf("ExtraBody[custom_field] = %v, want value", got)
+	}
+	if got := loaded.ModelList[0].ExtraBody["num_field"]; got != float64(42) {
+		t.Errorf("ExtraBody[num_field] = %v, want 42", got)
+	}
+}
+
+func TestDefaultConfig_MinimaxExtraBody(t *testing.T) {
+	cfg := DefaultConfig()
+
+	var minimaxCfg *ModelConfig
+	for i := range cfg.ModelList {
+		if cfg.ModelList[i].Model == "minimax/MiniMax-M2.5" {
+			minimaxCfg = cfg.ModelList[i]
+			break
+		}
+	}
+	if minimaxCfg == nil {
+		t.Fatal("Minimax model not found in ModelList")
+	}
+	if minimaxCfg.ExtraBody == nil {
+		t.Fatal("Minimax ExtraBody should not be nil")
+	}
+	if got, ok := minimaxCfg.ExtraBody["reasoning_split"]; !ok || got != true {
+		t.Fatalf("Minimax ExtraBody[reasoning_split] = %v, want true", got)
+	}
+}
+
+func TestFilterSensitiveData(t *testing.T) {
+	// Test with nil security config
+	cfg := &Config{}
+	if got := cfg.FilterSensitiveData("hello sk-key123 world"); got != "hello sk-key123 world" {
+		t.Errorf("nil security: got %q, want original", got)
+	}
+
+	// Test with empty content
+	cfg.security = &SecurityConfig{}
+	if got := cfg.FilterSensitiveData(""); got != "" {
+		t.Errorf("empty content: got %q, want empty", got)
+	}
+
+	// Test short content (less than FilterMinLength=8, should skip filtering)
+	cfg.security.ModelList = map[string]ModelSecurityEntry{
+		"test": {APIKeys: []string{"sk-long-key-12345"}},
+	}
+	cfg.Tools.FilterSensitiveData = true
+	cfg.Tools.FilterMinLength = 8
+
+	// Debug: check if sensitive values are collected
+	values := cfg.security.collectSensitiveValues()
+	t.Logf("collected %d sensitive values: %v", len(values), values)
+
+	if got := cfg.FilterSensitiveData("sk-key"); got != "sk-key" {
+		t.Errorf("short content should not be filtered: got %q", got)
+	}
+
+	// Test filtering works
+	content := "Your API key is sk-long-key-12345 and token abc123"
+	// abc123 is not in sensitive values, only sk-long-key-12345 should be filtered
+	expected := "Your API key is [FILTERED] and token abc123"
+	if got := cfg.FilterSensitiveData(content); got != expected {
+		t.Errorf("filtering failed: got %q, want %q", got, expected)
+	}
+
+	// Test disabled filtering
+	cfg.Tools.FilterSensitiveData = false
+	if got := cfg.FilterSensitiveData(content); got != content {
+		t.Errorf("disabled filtering: got %q, want original %q", got, content)
+	}
+}
+
+func TestFilterSensitiveData_MultipleKeys(t *testing.T) {
+	cfg := &Config{
+		Tools: ToolsConfig{
+			FilterSensitiveData: true,
+			FilterMinLength:     8,
+		},
+	}
+	cfg.security = &SecurityConfig{
+		ModelList: map[string]ModelSecurityEntry{
+			"model1": {APIKeys: []string{"key-one", "key-two"}},
+			"model2": {APIKeys: []string{"key-three"}},
+		},
+	}
+
+	content := "key-one and key-two and key-three should be filtered"
+	expected := "[FILTERED] and [FILTERED] and [FILTERED] should be filtered"
+	if got := cfg.FilterSensitiveData(content); got != expected {
+		t.Errorf("multiple keys: got %q, want %q", got, expected)
+	}
+}
+
+func TestFilterSensitiveData_AllTokenTypes(t *testing.T) {
+	cfg := &Config{
+		Tools: ToolsConfig{
+			FilterSensitiveData: true,
+			FilterMinLength:     8,
+		},
+	}
+	cfg.security = &SecurityConfig{
+		// Model API keys
+		ModelList: map[string]ModelSecurityEntry{
+			"test-model": {APIKeys: []string{"sk-model-key-12345"}},
+		},
+		// Channel tokens
+		Channels: &ChannelsSecurity{
+			Telegram: &TelegramSecurity{Token: "telegram-bot-token-abcdef"},
+			Discord:  &DiscordSecurity{Token: "discord-bot-token-xyz789"},
+			Slack:    &SlackSecurity{BotToken: "xoxb-slack-bot-token", AppToken: "xapp-slack-app-token"},
+			Matrix:   &MatrixSecurity{AccessToken: "matrix-access-token-abc"},
+			Feishu:   &FeishuSecurity{AppSecret: "feishu-app-secret-123", EncryptKey: "feishu-encrypt-key"},
+			DingTalk: &DingTalkSecurity{ClientSecret: "dingtalk-client-secret"},
+			OneBot:   &OneBotSecurity{AccessToken: "onebot-access-token"},
+			WeCom:    &WeComSecurity{Secret: "wecom-secret"},
+			Pico:     &PicoSecurity{Token: "pico-token-abc123"},
+			IRC: &IRCSecurity{
+				Password:         "irc-password",
+				NickServPassword: "nickserv-pass",
+				SASLPassword:     "sasl-pass",
+			},
+		},
+		// Web tool API keys
+		Web: &WebToolsSecurity{
+			Brave:       &BraveSecurity{APIKeys: []string{"brave-api-key"}},
+			Tavily:      &TavilySecurity{APIKeys: []string{"tavily-api-key"}},
+			Perplexity:  &PerplexitySecurity{APIKeys: []string{"perplexity-api-key"}},
+			GLMSearch:   &GLMSearchSecurity{APIKey: "glm-search-key"},
+			BaiduSearch: &BaiduSearchSecurity{APIKey: "baidu-search-key"},
+		},
+		// Skills tokens
+		Skills: &SkillsSecurity{
+			Github:  &GithubSecurity{Token: "github-token-xyz"},
+			ClawHub: &ClawHubSecurity{AuthToken: "clawhub-auth-token"},
+		},
+	}
+
+	tests := []struct {
+		name    string
+		content string
+		want    string
+	}{
+		{
+			name:    "model_api_key",
+			content: "Using model with key sk-model-key-12345",
+			want:    "Using model with key [FILTERED]",
+		},
+		{
+			name:    "telegram_token",
+			content: "Telegram token: telegram-bot-token-abcdef",
+			want:    "Telegram token: [FILTERED]",
+		},
+		{
+			name:    "discord_token",
+			content: "Discord token: discord-bot-token-xyz789",
+			want:    "Discord token: [FILTERED]",
+		},
+		{
+			name:    "slack_tokens",
+			content: "Slack bot: xoxb-slack-bot-token, app: xapp-slack-app-token",
+			want:    "Slack bot: [FILTERED], app: [FILTERED]",
+		},
+		{
+			name:    "matrix_token",
+			content: "Matrix access token: matrix-access-token-abc",
+			want:    "Matrix access token: [FILTERED]",
+		},
+		{
+			name:    "brave_api_key",
+			content: "Brave key: brave-api-key",
+			want:    "Brave key: [FILTERED]",
+		},
+		{
+			name:    "tavily_api_key",
+			content: "Tavily key: tavily-api-key",
+			want:    "Tavily key: [FILTERED]",
+		},
+		{
+			name:    "github_token",
+			content: "GitHub token: github-token-xyz",
+			want:    "GitHub token: [FILTERED]",
+		},
+		{
+			name:    "irc_passwords",
+			content: "IRC password: irc-password, nickserv: nickserv-pass",
+			want:    "IRC password: [FILTERED], nickserv: [FILTERED]",
+		},
+		{
+			name:    "mixed_content",
+			content: "Model key sk-model-key-12345 and Telegram token telegram-bot-token-abcdef",
+			want:    "Model key [FILTERED] and Telegram token [FILTERED]",
+		},
+		{
+			name:    "short_key_not_filtered",
+			content: "Key abc not filtered because length < 8",
+			want:    "Key abc not filtered because length < 8",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := cfg.FilterSensitiveData(tt.content); got != tt.want {
+				t.Errorf("got %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
diff --git a/pkg/config/defaults.go b/pkg/config/defaults.go
index 44f4de7e9..ba1a5a0cf 100644
--- a/pkg/config/defaults.go
+++ b/pkg/config/defaults.go
@@ -8,6 +8,8 @@ package config
 import (
 	"os"
 	"path/filepath"
+
+	"github.com/sipeed/picoclaw/pkg"
 )
 
 // DefaultConfig returns the default configuration for PicoClaw.
@@ -15,24 +17,31 @@ func DefaultConfig() *Config {
 	// Determine the base path for the workspace.
 	// Priority: $PICOCLAW_HOME > ~/.picoclaw
 	var homePath string
-	if picoclawHome := os.Getenv("PICOCLAW_HOME"); picoclawHome != "" {
+	if picoclawHome := os.Getenv(EnvHome); picoclawHome != "" {
 		homePath = picoclawHome
 	} else {
 		userHome, _ := os.UserHomeDir()
-		homePath = filepath.Join(userHome, ".picoclaw")
+		homePath = filepath.Join(userHome, pkg.DefaultPicoClawHome)
 	}
-	workspacePath := filepath.Join(homePath, "workspace")
+	workspacePath := filepath.Join(homePath, pkg.WorkspaceName)
 
 	return &Config{
+		Version: CurrentVersion,
 		Agents: AgentsConfig{
 			Defaults: AgentDefaults{
-				Workspace:           workspacePath,
-				RestrictToWorkspace: true,
-				Provider:            "",
-				Model:               "",
-				MaxTokens:           32768,
-				Temperature:         nil, // nil means use provider default
-				MaxToolIterations:   50,
+				Workspace:                 workspacePath,
+				RestrictToWorkspace:       true,
+				Provider:                  "",
+				MaxTokens:                 32768,
+				Temperature:               nil, // nil means use provider default
+				MaxToolIterations:         50,
+				SummarizeMessageThreshold: 20,
+				SummarizeTokenPercent:     75,
+				SteeringMode:              "one-at-a-time",
+				ToolFeedback: ToolFeedbackConfig{
+					Enabled:       true,
+					MaxArgsLength: 300,
+				},
 			},
 		},
 		Bindings: []AgentBinding{},
@@ -49,25 +58,22 @@ func DefaultConfig() *Config {
 			},
 			Telegram: TelegramConfig{
 				Enabled:   false,
-				Token:     "",
 				AllowFrom: FlexibleStringSlice{},
 				Typing:    TypingConfig{Enabled: true},
 				Placeholder: PlaceholderConfig{
 					Enabled: true,
 					Text:    "Thinking... 💭",
 				},
+				Streaming:     StreamingConfig{Enabled: true, ThrottleSeconds: 3, MinGrowthChars: 200},
+				UseMarkdownV2: false,
 			},
 			Feishu: FeishuConfig{
-				Enabled:           false,
-				AppID:             "",
-				AppSecret:         "",
-				EncryptKey:        "",
-				VerificationToken: "",
-				AllowFrom:         FlexibleStringSlice{},
+				Enabled:   false,
+				AppID:     "",
+				AllowFrom: FlexibleStringSlice{},
 			},
 			Discord: DiscordConfig{
 				Enabled:     false,
-				Token:       "",
 				AllowFrom:   FlexibleStringSlice{},
 				MentionOnly: false,
 			},
@@ -78,68 +84,68 @@ func DefaultConfig() *Config {
 				AllowFrom: FlexibleStringSlice{},
 			},
 			QQ: QQConfig{
-				Enabled:   false,
-				AppID:     "",
-				AppSecret: "",
-				AllowFrom: FlexibleStringSlice{},
+				Enabled:              false,
+				AppID:                "",
+				AllowFrom:            FlexibleStringSlice{},
+				MaxMessageLength:     2000,
+				MaxBase64FileSizeMiB: 0,
 			},
 			DingTalk: DingTalkConfig{
-				Enabled:      false,
-				ClientID:     "",
-				ClientSecret: "",
-				AllowFrom:    FlexibleStringSlice{},
+				Enabled:   false,
+				ClientID:  "",
+				AllowFrom: FlexibleStringSlice{},
 			},
 			Slack: SlackConfig{
 				Enabled:   false,
-				BotToken:  "",
-				AppToken:  "",
 				AllowFrom: FlexibleStringSlice{},
 			},
+			Matrix: MatrixConfig{
+				Enabled:      false,
+				Homeserver:   "https://matrix.org",
+				UserID:       "",
+				DeviceID:     "",
+				JoinOnInvite: true,
+				AllowFrom:    FlexibleStringSlice{},
+				GroupTrigger: GroupTriggerConfig{
+					MentionOnly: true,
+				},
+				Placeholder: PlaceholderConfig{
+					Enabled: true,
+					Text:    "Thinking... 💭",
+				},
+				CryptoDatabasePath: "",
+				CryptoPassphrase:   "",
+			},
 			LINE: LINEConfig{
-				Enabled:            false,
-				ChannelSecret:      "",
-				ChannelAccessToken: "",
-				WebhookHost:        "0.0.0.0",
-				WebhookPort:        18791,
-				WebhookPath:        "/webhook/line",
-				AllowFrom:          FlexibleStringSlice{},
-				GroupTrigger:       GroupTriggerConfig{MentionOnly: true},
+				Enabled:      false,
+				WebhookHost:  "0.0.0.0",
+				WebhookPort:  18791,
+				WebhookPath:  "/webhook/line",
+				AllowFrom:    FlexibleStringSlice{},
+				GroupTrigger: GroupTriggerConfig{MentionOnly: true},
 			},
 			OneBot: OneBotConfig{
-				Enabled:            false,
-				WSUrl:              "ws://127.0.0.1:3001",
-				AccessToken:        "",
-				ReconnectInterval:  5,
-				GroupTriggerPrefix: []string{},
-				AllowFrom:          FlexibleStringSlice{},
+				Enabled:           false,
+				WSUrl:             "ws://127.0.0.1:3001",
+				ReconnectInterval: 5,
+				AllowFrom:         FlexibleStringSlice{},
 			},
 			WeCom: WeComConfig{
-				Enabled:        false,
-				Token:          "",
-				EncodingAESKey: "",
-				WebhookURL:     "",
-				WebhookHost:    "0.0.0.0",
-				WebhookPort:    18793,
-				WebhookPath:    "/webhook/wecom",
-				AllowFrom:      FlexibleStringSlice{},
-				ReplyTimeout:   5,
+				Enabled:             false,
+				BotID:               "",
+				WebSocketURL:        "wss://openws.work.weixin.qq.com",
+				SendThinkingMessage: true,
+				AllowFrom:           FlexibleStringSlice{},
 			},
-			WeComApp: WeComAppConfig{
-				Enabled:        false,
-				CorpID:         "",
-				CorpSecret:     "",
-				AgentID:        0,
-				Token:          "",
-				EncodingAESKey: "",
-				WebhookHost:    "0.0.0.0",
-				WebhookPort:    18792,
-				WebhookPath:    "/webhook/wecom-app",
-				AllowFrom:      FlexibleStringSlice{},
-				ReplyTimeout:   5,
+			Weixin: WeixinConfig{
+				Enabled:    false,
+				BaseURL:    "https://ilinkai.weixin.qq.com/",
+				CDNBaseURL: "https://novac2c.cdn.weixin.qq.com/c2c",
+				AllowFrom:  FlexibleStringSlice{},
+				Proxy:      "",
 			},
 			Pico: PicoConfig{
 				Enabled:        false,
-				Token:          "",
 				PingInterval:   30,
 				ReadTimeout:    60,
 				WriteTimeout:   10,
@@ -147,10 +153,15 @@ func DefaultConfig() *Config {
 				AllowFrom:      FlexibleStringSlice{},
 			},
 		},
-		Providers: ProvidersConfig{
-			OpenAI: OpenAIProviderConfig{WebSearch: true},
+		Hooks: HooksConfig{
+			Enabled: true,
+			Defaults: HookDefaultsConfig{
+				ObserverTimeoutMS:    500,
+				InterceptorTimeoutMS: 5000,
+				ApprovalTimeoutMS:    60000,
+			},
 		},
-		ModelList: []ModelConfig{
+		ModelList: []*ModelConfig{
 			// ============================================
 			// Add your API key to the model you want to use
 			// ============================================
@@ -160,15 +171,13 @@ func DefaultConfig() *Config {
 				ModelName: "glm-4.7",
 				Model:     "zhipu/glm-4.7",
 				APIBase:   "https://open.bigmodel.cn/api/paas/v4",
-				APIKey:    "",
 			},
 
 			// OpenAI - https://platform.openai.com/api-keys
 			{
-				ModelName: "gpt-5.2",
-				Model:     "openai/gpt-5.2",
+				ModelName: "gpt-5.4",
+				Model:     "openai/gpt-5.4",
 				APIBase:   "https://api.openai.com/v1",
-				APIKey:    "",
 			},
 
 			// Anthropic Claude - https://console.anthropic.com/settings/keys
@@ -176,7 +185,6 @@ func DefaultConfig() *Config {
 				ModelName: "claude-sonnet-4.6",
 				Model:     "anthropic/claude-sonnet-4.6",
 				APIBase:   "https://api.anthropic.com/v1",
-				APIKey:    "",
 			},
 
 			// DeepSeek - https://platform.deepseek.com/
@@ -184,7 +192,6 @@ func DefaultConfig() *Config {
 				ModelName: "deepseek-chat",
 				Model:     "deepseek/deepseek-chat",
 				APIBase:   "https://api.deepseek.com/v1",
-				APIKey:    "",
 			},
 
 			// Google Gemini - https://ai.google.dev/
@@ -192,7 +199,6 @@ func DefaultConfig() *Config {
 				ModelName: "gemini-2.0-flash",
 				Model:     "gemini/gemini-2.0-flash-exp",
 				APIBase:   "https://generativelanguage.googleapis.com/v1beta",
-				APIKey:    "",
 			},
 
 			// Qwen (通义千问) - https://dashscope.console.aliyun.com/apiKey
@@ -200,7 +206,6 @@ func DefaultConfig() *Config {
 				ModelName: "qwen-plus",
 				Model:     "qwen/qwen-plus",
 				APIBase:   "https://dashscope.aliyuncs.com/compatible-mode/v1",
-				APIKey:    "",
 			},
 
 			// Moonshot (月之暗面) - https://platform.moonshot.cn/console/api-keys
@@ -208,7 +213,6 @@ func DefaultConfig() *Config {
 				ModelName: "moonshot-v1-8k",
 				Model:     "moonshot/moonshot-v1-8k",
 				APIBase:   "https://api.moonshot.cn/v1",
-				APIKey:    "",
 			},
 
 			// Groq - https://console.groq.com/keys
@@ -216,7 +220,6 @@ func DefaultConfig() *Config {
 				ModelName: "llama-3.3-70b",
 				Model:     "groq/llama-3.3-70b-versatile",
 				APIBase:   "https://api.groq.com/openai/v1",
-				APIKey:    "",
 			},
 
 			// OpenRouter (100+ models) - https://openrouter.ai/keys
@@ -224,13 +227,11 @@ func DefaultConfig() *Config {
 				ModelName: "openrouter-auto",
 				Model:     "openrouter/auto",
 				APIBase:   "https://openrouter.ai/api/v1",
-				APIKey:    "",
 			},
 			{
-				ModelName: "openrouter-gpt-5.2",
-				Model:     "openrouter/openai/gpt-5.2",
+				ModelName: "openrouter-gpt-5.4",
+				Model:     "openrouter/openai/gpt-5.4",
 				APIBase:   "https://openrouter.ai/api/v1",
-				APIKey:    "",
 			},
 
 			// NVIDIA - https://build.nvidia.com/
@@ -238,7 +239,6 @@ func DefaultConfig() *Config {
 				ModelName: "nemotron-4-340b",
 				Model:     "nvidia/nemotron-4-340b-instruct",
 				APIBase:   "https://integrate.api.nvidia.com/v1",
-				APIKey:    "",
 			},
 
 			// Cerebras - https://inference.cerebras.ai/
@@ -246,15 +246,25 @@ func DefaultConfig() *Config {
 				ModelName: "cerebras-llama-3.3-70b",
 				Model:     "cerebras/llama-3.3-70b",
 				APIBase:   "https://api.cerebras.ai/v1",
-				APIKey:    "",
+			},
+
+			// Vivgrid - https://vivgrid.com
+			{
+				ModelName: "vivgrid-auto",
+				Model:     "vivgrid/auto",
+				APIBase:   "https://api.vivgrid.com/v1",
 			},
 
 			// Volcengine (火山引擎) - https://console.volcengine.com/ark
+			{
+				ModelName: "ark-code-latest",
+				Model:     "volcengine/ark-code-latest",
+				APIBase:   "https://ark.cn-beijing.volces.com/api/v3",
+			},
 			{
 				ModelName: "doubao-pro",
 				Model:     "volcengine/doubao-pro-32k",
 				APIBase:   "https://ark.cn-beijing.volces.com/api/v3",
-				APIKey:    "",
 			},
 
 			// ShengsuanYun (神算云)
@@ -262,7 +272,6 @@ func DefaultConfig() *Config {
 				ModelName: "deepseek-v3",
 				Model:     "shengsuanyun/deepseek-v3",
 				APIBase:   "https://api.shengsuanyun.com/v1",
-				APIKey:    "",
 			},
 
 			// Antigravity (Google Cloud Code Assist) - OAuth only
@@ -274,8 +283,8 @@ func DefaultConfig() *Config {
 
 			// GitHub Copilot - https://github.com/settings/tokens
 			{
-				ModelName:  "copilot-gpt-5.2",
-				Model:      "github-copilot/gpt-5.2",
+				ModelName:  "copilot-gpt-5.4",
+				Model:      "github-copilot/gpt-5.4",
 				APIBase:    "http://localhost:4321",
 				AuthMethod: "oauth",
 			},
@@ -285,7 +294,6 @@ func DefaultConfig() *Config {
 				ModelName: "llama3",
 				Model:     "ollama/llama3",
 				APIBase:   "http://localhost:11434/v1",
-				APIKey:    "ollama",
 			},
 
 			// Mistral AI - https://console.mistral.ai/api-keys
@@ -293,7 +301,40 @@ func DefaultConfig() *Config {
 				ModelName: "mistral-small",
 				Model:     "mistral/mistral-small-latest",
 				APIBase:   "https://api.mistral.ai/v1",
-				APIKey:    "",
+			},
+
+			// Avian - https://avian.io
+			{
+				ModelName: "deepseek-v3.2",
+				Model:     "avian/deepseek/deepseek-v3.2",
+				APIBase:   "https://api.avian.io/v1",
+			},
+			{
+				ModelName: "kimi-k2.5",
+				Model:     "avian/moonshotai/kimi-k2.5",
+				APIBase:   "https://api.avian.io/v1",
+			},
+
+			// Minimax - https://api.minimaxi.com/
+			{
+				ModelName: "MiniMax-M2.5",
+				Model:     "minimax/MiniMax-M2.5",
+				APIBase:   "https://api.minimaxi.com/v1",
+				ExtraBody: map[string]any{"reasoning_split": true},
+			},
+
+			// LongCat - https://longcat.chat/platform
+			{
+				ModelName: "LongCat-Flash-Thinking",
+				Model:     "longcat/LongCat-Flash-Thinking",
+				APIBase:   "https://api.longcat.chat/openai",
+			},
+
+			// ModelScope (魔搭社区) - https://modelscope.cn/my/tokens
+			{
+				ModelName: "modelscope-qwen",
+				Model:     "modelscope/Qwen/Qwen3-235B-A22B-Instruct-2507",
+				APIBase:   "https://api-inference.modelscope.cn/v1",
 			},
 
 			// VLLM (local) - http://localhost:8000
@@ -301,25 +342,46 @@ func DefaultConfig() *Config {
 				ModelName: "local-model",
 				Model:     "vllm/custom-model",
 				APIBase:   "http://localhost:8000/v1",
-				APIKey:    "",
+			},
+
+			// Azure OpenAI - https://portal.azure.com
+			// model_name is a user-friendly alias; the model field's path after "azure/" is your deployment name
+			{
+				ModelName: "azure-gpt5",
+				Model:     "azure/my-gpt5-deployment",
+				APIBase:   "https://your-resource.openai.azure.com",
 			},
 		},
 		Gateway: GatewayConfig{
-			Host: "127.0.0.1",
-			Port: 18790,
+			Host:      "127.0.0.1",
+			Port:      18790,
+			HotReload: false,
+			LogLevel:  "fatal",
 		},
 		Tools: ToolsConfig{
+			FilterSensitiveData: true,
+			FilterMinLength:     8,
 			MediaCleanup: MediaCleanupConfig{
-				Enabled:  true,
+				ToolConfig: ToolConfig{
+					Enabled: true,
+				},
 				MaxAge:   30,
 				Interval: 5,
 			},
 			Web: WebToolsConfig{
+				ToolConfig: ToolConfig{
+					Enabled: true,
+				},
+				PreferNative:    true,
 				Proxy:           "",
 				FetchLimitBytes: 10 * 1024 * 1024, // 10MB by default
+				Format:          "plaintext",
 				Brave: BraveConfig{
 					Enabled:    false,
-					APIKey:     "",
+					MaxResults: 5,
+				},
+				Tavily: TavilyConfig{
+					Enabled:    false,
 					MaxResults: 5,
 				},
 				DuckDuckGo: DuckDuckGoConfig{
@@ -328,17 +390,44 @@ func DefaultConfig() *Config {
 				},
 				Perplexity: PerplexityConfig{
 					Enabled:    false,
-					APIKey:     "",
 					MaxResults: 5,
 				},
+				SearXNG: SearXNGConfig{
+					Enabled:    false,
+					BaseURL:    "",
+					MaxResults: 5,
+				},
+				GLMSearch: GLMSearchConfig{
+					Enabled:      false,
+					BaseURL:      "https://open.bigmodel.cn/api/paas/v4/web_search",
+					SearchEngine: "search_std",
+					MaxResults:   5,
+				},
+				BaiduSearch: BaiduSearchConfig{
+					Enabled:    false,
+					BaseURL:    "https://qianfan.baidubce.com/v2/ai_search/web_search",
+					MaxResults: 10,
+				},
 			},
 			Cron: CronToolsConfig{
+				ToolConfig: ToolConfig{
+					Enabled: true,
+				},
 				ExecTimeoutMinutes: 5,
+				AllowCommand:       true,
 			},
 			Exec: ExecConfig{
+				ToolConfig: ToolConfig{
+					Enabled: true,
+				},
 				EnableDenyPatterns: true,
+				AllowRemote:        true,
+				TimeoutSeconds:     60,
 			},
 			Skills: SkillsToolsConfig{
+				ToolConfig: ToolConfig{
+					Enabled: true,
+				},
 				Registries: SkillsRegistriesConfig{
 					ClawHub: ClawHubRegistryConfig{
 						Enabled: true,
@@ -351,6 +440,65 @@ func DefaultConfig() *Config {
 					TTLSeconds: 300,
 				},
 			},
+			SendFile: ToolConfig{
+				Enabled: true,
+			},
+			MCP: MCPConfig{
+				ToolConfig: ToolConfig{
+					Enabled: false,
+				},
+				Discovery: ToolDiscoveryConfig{
+					Enabled:          false,
+					TTL:              5,
+					MaxSearchResults: 5,
+					UseBM25:          true,
+					UseRegex:         false,
+				},
+				Servers: map[string]MCPServerConfig{},
+			},
+			AppendFile: ToolConfig{
+				Enabled: true,
+			},
+			EditFile: ToolConfig{
+				Enabled: true,
+			},
+			FindSkills: ToolConfig{
+				Enabled: true,
+			},
+			I2C: ToolConfig{
+				Enabled: false, // Hardware tool - Linux only
+			},
+			InstallSkill: ToolConfig{
+				Enabled: true,
+			},
+			ListDir: ToolConfig{
+				Enabled: true,
+			},
+			Message: ToolConfig{
+				Enabled: true,
+			},
+			ReadFile: ReadFileToolConfig{
+				Enabled:         true,
+				MaxReadFileSize: 64 * 1024, // 64KB
+			},
+			Spawn: ToolConfig{
+				Enabled: true,
+			},
+			SpawnStatus: ToolConfig{
+				Enabled: false,
+			},
+			SPI: ToolConfig{
+				Enabled: false, // Hardware tool - Linux only
+			},
+			Subagent: ToolConfig{
+				Enabled: true,
+			},
+			WebFetch: ToolConfig{
+				Enabled: true,
+			},
+			WriteFile: ToolConfig{
+				Enabled: true,
+			},
 		},
 		Heartbeat: HeartbeatConfig{
 			Enabled:  true,
@@ -360,5 +508,21 @@ func DefaultConfig() *Config {
 			Enabled:    false,
 			MonitorUSB: true,
 		},
+		Voice: VoiceConfig{
+			ModelName:         "",
+			EchoTranscription: false,
+		},
+		BuildInfo: BuildInfo{
+			Version:   Version,
+			GitCommit: GitCommit,
+			BuildTime: BuildTime,
+			GoVersion: GoVersion,
+		},
+		security: &SecurityConfig{
+			ModelList: map[string]ModelSecurityEntry{},
+			Channels:  &ChannelsSecurity{},
+			Web:       &WebToolsSecurity{},
+			Skills:    &SkillsSecurity{},
+		},
 	}
 }
diff --git a/pkg/config/envkeys.go b/pkg/config/envkeys.go
new file mode 100644
index 000000000..b04ff19f5
--- /dev/null
+++ b/pkg/config/envkeys.go
@@ -0,0 +1,37 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package config
+
+// Runtime environment variable keys for the picoclaw process.
+// These control the location of files and binaries at runtime and are read
+// directly via os.Getenv / os.LookupEnv. All picoclaw-specific keys use the
+// PICOCLAW_ prefix. Reference these constants instead of inline string
+// literals to keep all supported knobs visible in one place and to prevent
+// typos.
+const (
+	// EnvHome overrides the base directory for all picoclaw data
+	// (config, workspace, skills, auth store, …).
+	// Default: ~/.picoclaw
+	EnvHome = "PICOCLAW_HOME"
+
+	// EnvConfig overrides the full path to the JSON config file.
+	// Default: $PICOCLAW_HOME/config.json
+	EnvConfig = "PICOCLAW_CONFIG"
+
+	// EnvBuiltinSkills overrides the directory from which built-in
+	// skills are loaded.
+	// Default: <cwd>/skills
+	EnvBuiltinSkills = "PICOCLAW_BUILTIN_SKILLS"
+
+	// EnvBinary overrides the path to the picoclaw executable.
+	// Used by the web launcher when spawning the gateway subprocess.
+	// Default: resolved from the same directory as the current executable.
+	EnvBinary = "PICOCLAW_BINARY"
+
+	// EnvGatewayHost overrides the host address for the gateway server.
+	// Default: "127.0.0.1"
+	EnvGatewayHost = "PICOCLAW_GATEWAY_HOST"
+)
diff --git a/pkg/config/example_security_usage.go b/pkg/config/example_security_usage.go
new file mode 100644
index 000000000..09aee9aa3
--- /dev/null
+++ b/pkg/config/example_security_usage.go
@@ -0,0 +1,417 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+// This file demonstrates how to use the security configuration feature
+// It's not meant to be compiled, just for documentation purposes
+
+/*
+Package config
+
+# Example: Using Security Configuration
+
+## 1. Create security.yml
+
+File: ~/.picoclaw/security.yml
+
+```yaml
+# Model API Keys
+# Note: Use 'api_keys' array for multiple keys (load balancing/failover)
+# Single key should be provided as an array with one element
+model_list:
+
+	gpt-5.4:
+	  api_keys:
+	    - "sk-proj-your-actual-openai-key-1"
+	    - "sk-proj-your-actual-openai-key-2"  # Failover key
+	claude-sonnet-4.6:
+	  api_keys:
+	    - "sk-ant-your-actual-anthropic-key"  # Single key in array format
+
+# Channel Tokens
+channels:
+
+	telegram:
+	  token: "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"
+	discord:
+	  token: "your-discord-bot-token"
+
+# Web Tool Keys
+# Note: Use 'api_keys' array for multiple keys (load balancing/failover)
+# For GLMSearch, use 'api_key' (single string)
+web:
+
+	brave:
+	  api_keys:
+	    - "BSAyour-brave-api-key-1"
+	    - "BSAyour-brave-api-key-2"  # Failover key
+	tavily:
+	  api_keys:
+	    - "tvly-your-tavily-api-key"  # Single key in array format
+	glm_search:
+	  api_key: "your-glm-search-api-key"  # Single key (not array)
+
+```
+
+## 2. Update config.json to use references
+
+File: ~/.picoclaw/config.json
+
+```json
+
+		{
+		  "version": 1,
+		  "agents": {
+		    "defaults": {
+		      "workspace": "~/picoclaw-workspace",
+		      "model_name": "gpt-5.4"
+		    }
+		  },
+		  "model_list": [
+		    {
+		      "model_name": "gpt-5.4",
+		      "model": "openai/gpt-5.4",
+		      "api_base": "https://api.openai.com/v1",
+		      "api_key": "ref:model_list.gpt-5.4.api_key"
+		    },
+		    {
+		      "model_name": "claude-sonnet-4.6",
+		      "model": "anthropic/claude-sonnet-4.6",
+		      "api_base": "https://api.anthropic.com/v1",
+		      "api_key": "ref:model_list.claude-sonnet-4.6.api_key"
+		    }
+		  ],
+		  "channels": {
+		    "telegram": {
+		      "enabled": true,
+		      "token": "ref:channels.telegram.token"
+		    },
+		    "discord": {
+		      "enabled": true,
+		      "token": "ref:channels.discord.token"
+		    }
+		  },
+	  "tools": {
+	    "web": {
+	      "brave": {
+	        "enabled": true,
+	        "api_key": "ref:web.brave.api_key"
+	      },
+	      "tavily": {
+	        "enabled": true,
+	        "api_key": "ref:web.tavily.api_key"
+	      }
+	    }
+	  }
+		}
+
+```
+
+## 3. Set proper permissions
+
+```bash
+chmod 600 ~/.picoclaw/security.yml
+```
+
+## 4. Add to .gitignore
+
+```gitignore
+# Security configuration
+.security.yml
+```
+
+## 5. Verify it works
+
+```bash
+picoclaw --version
+```
+
+# Available Reference Paths
+
+## Model API Keys
+- ref:model_list.<model_name>.api_key
+
+Examples:
+- ref:model_list.gpt-5.4.api_key
+- ref:model_list.claude-sonnet-4.6.api_key
+
+**Note:** In .security.yml, use `api_keys` (array) format for models.
+Both single and multiple keys should use the array format.
+
+## Channel Tokens/Secrets
+- ref:channels.telegram.token
+- ref:channels.feishu.app_secret
+- ref:channels.feishu.encrypt_key
+- ref:channels.feishu.verification_token
+- ref:channels.discord.token
+- ref:channels.qq.app_secret
+- ref:channels.dingtalk.client_secret
+- ref:channels.slack.bot_token
+- ref:channels.slack.app_token
+- ref:channels.matrix.access_token
+- ref:channels.line.channel_secret
+- ref:channels.line.channel_access_token
+- ref:channels.onebot.access_token
+- ref:channels.wecom.secret
+- ref:channels.pico.token
+- ref:channels.irc.password
+- ref:channels.irc.nickserv_password
+- ref:channels.irc.sasl_password
+
+## Web Tool API Keys
+- ref:web.brave.api_key
+- ref:web.tavily.api_key
+- ref:web.perplexity.api_key
+- ref:web.glm_search.api_key
+
+**Note:**
+- Brave, Tavily, Perplexity: Use `api_keys` (array) format in .security.yml
+- GLMSearch: Use `api_key` (single string) format in .security.yml
+
+## Skills Registry Tokens
+- ref:skills.github.token
+- ref:skills.clawhub.auth_token
+
+# Backward Compatibility
+
+You can still use direct values in config.json if needed:
+
+```json
+
+	{
+	  "model_list": [
+	    {
+	      "model_name": "local-model",
+	      "model": "ollama/llama3",
+	      "api_base": "http://localhost:11434/v1",
+	      "api_key": "ollama"  // Direct value (no reference)
+	    }
+	  ]
+	}
+
+```
+
+You can also mix references and direct values:
+
+```json
+
+	{
+	  "model_list": [
+	    {
+	      "model_name": "cloud-model",
+	      "api_key": "ref:model_list.cloud-model.api_key"  // From .security.yml
+	    },
+	    {
+	      "model_name": "local-model",
+	      "api_key": "ollama"  // Direct value
+	    }
+	  ]
+	}
+
+```
+
+# Migration from Old Config
+
+## Step 1: Backup your config
+```bash
+cp ~/.picoclaw/config.json ~/.picoclaw/config.json.backup
+```
+
+## Step 2: Copy the example security file
+```bash
+cp security.example.yml ~/.picoclaw/.security.yml
+```
+
+## Step 3: Fill in your API keys
+Edit ~/.picoclaw/.security.yml and replace placeholders with your actual keys.
+
+## Step 4: Update config.json references
+Replace sensitive values in ~/.picoclaw/config.json with ref: references.
+
+## Step 5: Test
+```bash
+picoclaw --version
+```
+
+If everything works, you can delete the backup:
+```bash
+rm ~/.picoclaw/config.json.backup
+```
+
+# Advanced Features
+
+## Multiple API Keys (Load Balancing & Failover)
+
+You can configure multiple API keys for both models and web tools to enable:
+- **Load balancing**: Requests are distributed across multiple keys
+- **Failover**: If a key fails, the system automatically switches to another key
+
+### Example: Model with Multiple Keys
+
+**.security.yml:**
+```yaml
+model_list:
+
+	gpt-5.4:
+	  api_keys:
+	    - "sk-proj-key-1"
+	    - "sk-proj-key-2"
+	    - "sk-proj-key-3"
+
+```
+
+**config.json:**
+```json
+
+	{
+	  "model_list": [
+	    {
+	      "model_name": "gpt-5.4",
+	      "model": "openai/gpt-5.4",
+	      "api_key": "ref:model_list.gpt-5.4.api_key"
+	    }
+	  ]
+	}
+
+```
+
+### Example: Web Tool with Multiple Keys
+
+**.security.yml:**
+```yaml
+web:
+
+	brave:
+	  api_keys:
+	    - "BSA-key-1"
+	    - "BSA-key-2"
+	tavily:
+	  api_keys:
+	    - "tvly-your-key"  # Single key in array format
+	glm_search:
+	  api_key: "your-glm-key"  # GLMSearch uses single key format
+
+```
+
+**config.json:**
+```json
+
+	{
+	  "tools": {
+	    "web": {
+	      "brave": {
+	        "enabled": true,
+	        "api_key": "ref:web.brave.api_key"
+	      }
+	    }
+	  }
+	}
+
+```
+
+### Single Key
+
+Use array format with one element:
+```yaml
+model_list:
+
+	gpt-5.4:
+	  api_keys:
+	    - "sk-proj-your-key"  # Single key in array format
+
+```
+
+### Multiple Keys (Load Balancing & Failover)
+
+Use array format with multiple elements:
+```yaml
+model_list:
+
+	gpt-5.4:
+	  api_keys:
+	    - "sk-proj-key-1"
+	    - "sk-proj-key-2"
+	    - "sk-proj-key-3"
+
+```
+
+**Important:** All model keys in .security.yml must use the `api_keys` (plural) array format.
+The single `api_key` (singular) format is NOT supported for models.
+
+### Model Index Matching
+
+The system supports intelligent model name matching in .security.yml:
+
+**Example 1: Exact Match**
+```yaml
+# config.json
+
+	{
+	  "model_name": "gpt-5.4:0"
+	}
+
+# .security.yml (exact match with index)
+model_list:
+
+	gpt-5.4:0:
+	  api_keys: ["key-1"]
+
+```
+
+**Example 2: Base Name Match**
+```yaml
+# config.json
+
+	{
+	  "model_name": "gpt-5.4:0"
+	}
+
+# .security.yml (base name without index)
+model_list:
+
+	gpt-5.4:
+	  api_keys: ["key-1"]
+
+```
+
+Both methods work. The base name match allows you to use simpler keys in .security.yml
+even when your config uses indexed model names for load balancing.
+
+### Security File Permissions
+
+The security file should have restricted permissions:
+
+```bash
+chmod 600 ~/.picoclaw/.security.yml
+```
+
+This ensures only the owner can read and write the file.
+
+# Security Best Practices
+
+1. Never commit .security.yml to version control
+2. Set file permissions: chmod 600 ~/.picoclaw/.security.yml
+3. Use different keys for different environments
+4. Rotate keys regularly and update .security.yml
+5. Encrypt backups containing .security.yml
+
+# Troubleshooting
+
+## Error: "model security entry not found"
+- Check that the model name in config.json matches exactly in .security.yml
+- Verify the model_list section exists in .security.yml
+
+## Error: "failed to load security config"
+- Ensure .security.yml exists in the same directory as config.json
+- Check YAML syntax is valid
+- Verify file permissions allow reading
+
+## Error: "unknown reference path"
+- Verify the reference format is correct
+- Check the path structure matches the examples above
+- Ensure all required sections exist in .security.yml
+*/
+package config
+
+// This file is documentation only
diff --git a/pkg/config/migration.go b/pkg/config/migration.go
index 5deb09270..fee800a76 100644
--- a/pkg/config/migration.go
+++ b/pkg/config/migration.go
@@ -6,10 +6,15 @@
 package config
 
 import (
+	"encoding/json"
 	"slices"
 	"strings"
 )
 
+type migratable interface {
+	Migrate() (*Config, error)
+}
+
 // buildModelWithProtocol constructs a model string with protocol prefix.
 // If the model already contains a "/" (indicating it has a protocol prefix), it is returned as-is.
 // Otherwise, the protocol prefix is added.
@@ -21,31 +26,31 @@ func buildModelWithProtocol(protocol, model string) string {
 	return protocol + "/" + model
 }
 
-// providerMigrationConfig defines how to migrate a provider from old config to new format.
-type providerMigrationConfig struct {
-	// providerNames are the possible names used in agents.defaults.provider
-	providerNames []string
-	// protocol is the protocol prefix for the model field
-	protocol string
-	// buildConfig creates the ModelConfig from ProviderConfig
-	buildConfig func(p ProvidersConfig) (ModelConfig, bool)
-}
-
-// ConvertProvidersToModelList converts the old ProvidersConfig to a slice of ModelConfig.
+// v0ConvertProvidersToModelList converts the old providersConfigV0 to a slice of ModelConfig.
 // This enables backward compatibility with existing configurations.
 // It preserves the user's configured model from agents.defaults.model when possible.
-func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
+func v0ConvertProvidersToModelList(cfg *configV0) []modelConfigV0 {
 	if cfg == nil {
 		return nil
 	}
 
+	// providerMigrationConfig defines how to migrate a provider from old config to new format.
+	type providerMigrationConfig struct {
+		// providerNames are the possible names used in agents.defaults.provider
+		providerNames []string
+		// protocol is the protocol prefix for the model field
+		protocol string
+		// buildConfig creates the ModelConfig from ProviderConfig
+		buildConfig func(p providersConfigV0) (modelConfigV0, bool)
+	}
+
 	// Get user's configured provider and model
 	userProvider := strings.ToLower(cfg.Agents.Defaults.Provider)
 	userModel := cfg.Agents.Defaults.GetModelName()
 
 	p := cfg.Providers
 
-	var result []ModelConfig
+	var result []modelConfigV0
 
 	// Track if we've applied the legacy model name fix (only for first provider)
 	legacyModelNameApplied := false
@@ -55,13 +60,13 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"openai", "gpt"},
 			protocol:      "openai",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.OpenAI.APIKey == "" && p.OpenAI.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "openai",
-					Model:          "openai/gpt-5.2",
+					Model:          "openai/gpt-5.4",
 					APIKey:         p.OpenAI.APIKey,
 					APIBase:        p.OpenAI.APIBase,
 					Proxy:          p.OpenAI.Proxy,
@@ -73,11 +78,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"anthropic", "claude"},
 			protocol:      "anthropic",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.Anthropic.APIKey == "" && p.Anthropic.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "anthropic",
 					Model:          "anthropic/claude-sonnet-4.6",
 					APIKey:         p.Anthropic.APIKey,
@@ -88,14 +93,31 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 				}, true
 			},
 		},
+		{
+			providerNames: []string{"litellm"},
+			protocol:      "litellm",
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
+				if p.LiteLLM.APIKey == "" && p.LiteLLM.APIBase == "" {
+					return modelConfigV0{}, false
+				}
+				return modelConfigV0{
+					ModelName:      "litellm",
+					Model:          "litellm/auto",
+					APIKey:         p.LiteLLM.APIKey,
+					APIBase:        p.LiteLLM.APIBase,
+					Proxy:          p.LiteLLM.Proxy,
+					RequestTimeout: p.LiteLLM.RequestTimeout,
+				}, true
+			},
+		},
 		{
 			providerNames: []string{"openrouter"},
 			protocol:      "openrouter",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.OpenRouter.APIKey == "" && p.OpenRouter.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "openrouter",
 					Model:          "openrouter/auto",
 					APIKey:         p.OpenRouter.APIKey,
@@ -108,11 +130,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"groq"},
 			protocol:      "groq",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.Groq.APIKey == "" && p.Groq.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "groq",
 					Model:          "groq/llama-3.1-70b-versatile",
 					APIKey:         p.Groq.APIKey,
@@ -125,11 +147,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"zhipu", "glm"},
 			protocol:      "zhipu",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.Zhipu.APIKey == "" && p.Zhipu.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "zhipu",
 					Model:          "zhipu/glm-4",
 					APIKey:         p.Zhipu.APIKey,
@@ -142,11 +164,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"vllm"},
 			protocol:      "vllm",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.VLLM.APIKey == "" && p.VLLM.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "vllm",
 					Model:          "vllm/auto",
 					APIKey:         p.VLLM.APIKey,
@@ -159,11 +181,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"gemini", "google"},
 			protocol:      "gemini",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.Gemini.APIKey == "" && p.Gemini.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "gemini",
 					Model:          "gemini/gemini-pro",
 					APIKey:         p.Gemini.APIKey,
@@ -176,11 +198,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"nvidia"},
 			protocol:      "nvidia",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.Nvidia.APIKey == "" && p.Nvidia.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "nvidia",
 					Model:          "nvidia/meta/llama-3.1-8b-instruct",
 					APIKey:         p.Nvidia.APIKey,
@@ -193,11 +215,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"ollama"},
 			protocol:      "ollama",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.Ollama.APIKey == "" && p.Ollama.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "ollama",
 					Model:          "ollama/llama3",
 					APIKey:         p.Ollama.APIKey,
@@ -210,11 +232,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"moonshot", "kimi"},
 			protocol:      "moonshot",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.Moonshot.APIKey == "" && p.Moonshot.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "moonshot",
 					Model:          "moonshot/kimi",
 					APIKey:         p.Moonshot.APIKey,
@@ -227,11 +249,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"shengsuanyun"},
 			protocol:      "shengsuanyun",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.ShengSuanYun.APIKey == "" && p.ShengSuanYun.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "shengsuanyun",
 					Model:          "shengsuanyun/auto",
 					APIKey:         p.ShengSuanYun.APIKey,
@@ -244,11 +266,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"deepseek"},
 			protocol:      "deepseek",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.DeepSeek.APIKey == "" && p.DeepSeek.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "deepseek",
 					Model:          "deepseek/deepseek-chat",
 					APIKey:         p.DeepSeek.APIKey,
@@ -261,11 +283,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"cerebras"},
 			protocol:      "cerebras",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.Cerebras.APIKey == "" && p.Cerebras.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "cerebras",
 					Model:          "cerebras/llama-3.3-70b",
 					APIKey:         p.Cerebras.APIKey,
@@ -275,14 +297,31 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 				}, true
 			},
 		},
+		{
+			providerNames: []string{"vivgrid"},
+			protocol:      "vivgrid",
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
+				if p.Vivgrid.APIKey == "" && p.Vivgrid.APIBase == "" {
+					return modelConfigV0{}, false
+				}
+				return modelConfigV0{
+					ModelName:      "vivgrid",
+					Model:          "vivgrid/auto",
+					APIKey:         p.Vivgrid.APIKey,
+					APIBase:        p.Vivgrid.APIBase,
+					Proxy:          p.Vivgrid.Proxy,
+					RequestTimeout: p.Vivgrid.RequestTimeout,
+				}, true
+			},
+		},
 		{
 			providerNames: []string{"volcengine", "doubao"},
 			protocol:      "volcengine",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.VolcEngine.APIKey == "" && p.VolcEngine.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "volcengine",
 					Model:          "volcengine/doubao-pro",
 					APIKey:         p.VolcEngine.APIKey,
@@ -295,13 +334,13 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"github_copilot", "copilot"},
 			protocol:      "github-copilot",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.GitHubCopilot.APIKey == "" && p.GitHubCopilot.APIBase == "" && p.GitHubCopilot.ConnectMode == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:   "github-copilot",
-					Model:       "github-copilot/gpt-5.2",
+					Model:       "github-copilot/gpt-5.4",
 					APIBase:     p.GitHubCopilot.APIBase,
 					ConnectMode: p.GitHubCopilot.ConnectMode,
 				}, true
@@ -310,11 +349,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"antigravity"},
 			protocol:      "antigravity",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.Antigravity.APIKey == "" && p.Antigravity.AuthMethod == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:  "antigravity",
 					Model:      "antigravity/gemini-2.0-flash",
 					APIKey:     p.Antigravity.APIKey,
@@ -325,11 +364,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"qwen", "tongyi"},
 			protocol:      "qwen",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.Qwen.APIKey == "" && p.Qwen.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "qwen",
 					Model:          "qwen/qwen-max",
 					APIKey:         p.Qwen.APIKey,
@@ -342,11 +381,11 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 		{
 			providerNames: []string{"mistral"},
 			protocol:      "mistral",
-			buildConfig: func(p ProvidersConfig) (ModelConfig, bool) {
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
 				if p.Mistral.APIKey == "" && p.Mistral.APIBase == "" {
-					return ModelConfig{}, false
+					return modelConfigV0{}, false
 				}
-				return ModelConfig{
+				return modelConfigV0{
 					ModelName:      "mistral",
 					Model:          "mistral/mistral-small-latest",
 					APIKey:         p.Mistral.APIKey,
@@ -356,6 +395,57 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 				}, true
 			},
 		},
+		{
+			providerNames: []string{"avian"},
+			protocol:      "avian",
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
+				if p.Avian.APIKey == "" && p.Avian.APIBase == "" {
+					return modelConfigV0{}, false
+				}
+				return modelConfigV0{
+					ModelName:      "avian",
+					Model:          "avian/deepseek/deepseek-v3.2",
+					APIKey:         p.Avian.APIKey,
+					APIBase:        p.Avian.APIBase,
+					Proxy:          p.Avian.Proxy,
+					RequestTimeout: p.Avian.RequestTimeout,
+				}, true
+			},
+		},
+		{
+			providerNames: []string{"longcat"},
+			protocol:      "longcat",
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
+				if p.LongCat.APIKey == "" && p.LongCat.APIBase == "" {
+					return modelConfigV0{}, false
+				}
+				return modelConfigV0{
+					ModelName:      "longcat",
+					Model:          "longcat/LongCat-Flash-Thinking",
+					APIKey:         p.LongCat.APIKey,
+					APIBase:        p.LongCat.APIBase,
+					Proxy:          p.LongCat.Proxy,
+					RequestTimeout: p.LongCat.RequestTimeout,
+				}, true
+			},
+		},
+		{
+			providerNames: []string{"modelscope"},
+			protocol:      "modelscope",
+			buildConfig: func(p providersConfigV0) (modelConfigV0, bool) {
+				if p.ModelScope.APIKey == "" && p.ModelScope.APIBase == "" {
+					return modelConfigV0{}, false
+				}
+				return modelConfigV0{
+					ModelName:      "modelscope",
+					Model:          "modelscope/Qwen/Qwen3-235B-A22B-Instruct-2507",
+					APIKey:         p.ModelScope.APIKey,
+					APIBase:        p.ModelScope.APIBase,
+					Proxy:          p.ModelScope.Proxy,
+					RequestTimeout: p.ModelScope.RequestTimeout,
+				}, true
+			},
+		},
 	}
 
 	// Process each provider migration
@@ -383,3 +473,64 @@ func ConvertProvidersToModelList(cfg *Config) []ModelConfig {
 
 	return result
 }
+
+// loadConfigV0 loads a legacy config (no version field)
+func loadConfigV0(data []byte) (migratable, error) {
+	var v0 configV0
+	if err := json.Unmarshal(data, &v0); err != nil {
+		return nil, err
+	}
+
+	v0.migrateChannelConfigs()
+
+	// Auto-migrate: if only legacy providers config exists, convert to model_list
+	if len(v0.ModelList) == 0 && !v0.Providers.IsEmpty() {
+		newModelList := v0ConvertProvidersToModelList(&v0)
+		// Convert []ModelConfig to []modelConfigV0
+		v0.ModelList = make([]modelConfigV0, len(newModelList))
+		for i, m := range newModelList {
+			v0.ModelList[i] = modelConfigV0{
+				ModelName:      m.ModelName,
+				Model:          m.Model,
+				APIBase:        m.APIBase,
+				Proxy:          m.Proxy,
+				Fallbacks:      m.Fallbacks,
+				AuthMethod:     m.AuthMethod,
+				ConnectMode:    m.ConnectMode,
+				Workspace:      m.Workspace,
+				RPM:            m.RPM,
+				MaxTokensField: m.MaxTokensField,
+				RequestTimeout: m.RequestTimeout,
+				ThinkingLevel:  m.ThinkingLevel,
+				APIKey:         m.APIKey,
+				APIKeys:        m.APIKeys,
+			}
+		}
+	}
+
+	return &v0, nil
+}
+
+// loadConfigV1 loads a version 1 config (current schema)
+func loadConfig(data []byte) (*Config, error) {
+	cfg := DefaultConfig()
+
+	// Pre-scan the JSON to check how many model_list entries the user provided.
+	// Go's JSON decoder reuses existing slice backing-array elements rather than
+	// zero-initializing them, so fields absent from the user's JSON (e.g. api_base)
+	// would silently inherit values from the DefaultConfig template at the same
+	// index position. We only reset cfg.ModelList when the user actually provides
+	// entries; when count is 0 we keep DefaultConfig's built-in list as fallback.
+	var tmp Config
+	if err := json.Unmarshal(data, &tmp); err != nil {
+		return nil, err
+	}
+	if len(tmp.ModelList) > 0 {
+		cfg.ModelList = nil
+	}
+
+	if err := json.Unmarshal(data, cfg); err != nil {
+		return nil, err
+	}
+	return cfg, nil
+}
diff --git a/pkg/config/migration_integration_test.go b/pkg/config/migration_integration_test.go
new file mode 100644
index 000000000..49d2a5831
--- /dev/null
+++ b/pkg/config/migration_integration_test.go
@@ -0,0 +1,683 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package config
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// TestMigration_Integration_LegacyConfigWithoutWorkspace tests the issue reported:
+// User configured Model and Provider but no Workspace - settings should not be lost
+func TestMigration_Integration_LegacyConfigWithoutWorkspace(t *testing.T) {
+	// Create a temporary directory for test config files
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+
+	// Create a legacy config (version 0) with Model and Provider but NO Workspace
+	// This simulates the real-world scenario where user settings would be lost
+	legacyConfig := `{
+		"agents": {
+			"defaults": {
+				"provider": "openai",
+				"model": "gpt-4o",
+				"max_tokens": 8192,
+				"temperature": 0.7
+			}
+		},
+		"channels": {
+			"telegram": {
+				"enabled": true,
+				"token": "test-token"
+			}
+		},
+		"gateway": {
+			"host": "127.0.0.1",
+			"port": 18790
+		},
+		"tools": {
+			"web": {
+				"enabled": true
+			}
+		},
+		"heartbeat": {
+			"enabled": true,
+			"interval": 30
+		},
+		"devices": {
+			"enabled": false
+		}
+	}`
+
+	if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+		t.Fatalf("Failed to write legacy config: %v", err)
+	}
+
+	// Load the config - this should trigger migration
+	cfg, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig failed: %v", err)
+	}
+
+	// Verify version is updated
+	if cfg.Version != CurrentVersion {
+		t.Errorf("Version = %d, want %d", cfg.Version, CurrentVersion)
+	}
+
+	// CRITICAL: Verify that user's settings are preserved
+	// This was the bug - these settings were lost when Workspace was empty
+	if cfg.Agents.Defaults.Provider != "openai" {
+		t.Errorf("Provider = %q, want %q (user's setting should be preserved)", cfg.Agents.Defaults.Provider, "openai")
+	}
+	// Old "model" field is migrated to "model_name" field
+	if cfg.Agents.Defaults.ModelName != "gpt-4o" {
+		t.Errorf(
+			"ModelName = %q, want %q (user's setting should be preserved)",
+			cfg.Agents.Defaults.ModelName, "gpt-4o",
+		)
+	}
+	// GetModelName() should also return the migrated value
+	if cfg.Agents.Defaults.GetModelName() != "gpt-4o" {
+		t.Errorf("GetModelName() = %q, want %q", cfg.Agents.Defaults.GetModelName(), "gpt-4o")
+	}
+	if cfg.Agents.Defaults.MaxTokens != 8192 {
+		t.Errorf("MaxTokens = %d, want %d", cfg.Agents.Defaults.MaxTokens, 8192)
+	}
+	if cfg.Agents.Defaults.Temperature == nil {
+		t.Error("Temperature should not be nil")
+	} else if *cfg.Agents.Defaults.Temperature != 0.7 {
+		t.Errorf("Temperature = %v, want %v", *cfg.Agents.Defaults.Temperature, 0.7)
+	}
+
+	// Verify Workspace has a default value (should not be empty)
+	if cfg.Agents.Defaults.Workspace == "" {
+		t.Error("Workspace should have a default value, not be empty")
+	}
+
+	// Verify other config sections are preserved
+	if !cfg.Channels.Telegram.Enabled {
+		t.Error("Telegram.Enabled should be true")
+	}
+	if cfg.Channels.Telegram.Token() != "test-token" {
+		t.Errorf("Telegram.Token = %q, want %q", cfg.Channels.Telegram.Token(), "test-token")
+	}
+	if cfg.Gateway.Port != 18790 {
+		t.Errorf("Gateway.Port = %d, want %d", cfg.Gateway.Port, 18790)
+	}
+}
+
+// TestMigration_Integration_LegacyConfigWithWorkspace tests migration with Workspace set
+func TestMigration_Integration_LegacyConfigWithWorkspace(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+
+	legacyConfig := `{
+		"agents": {
+			"defaults": {
+				"workspace": "/custom/workspace",
+				"provider": "deepseek",
+				"model": "deepseek-chat",
+				"max_tokens": 16384
+			}
+		},
+		"channels": {
+			"telegram": {
+				"enabled": false
+			}
+		},
+		"gateway": {
+			"host": "0.0.0.0",
+			"port": 8080
+		},
+		"tools": {
+			"web": {
+				"enabled": false
+			}
+		},
+		"heartbeat": {
+			"enabled": false
+		},
+		"devices": {
+			"enabled": true
+		}
+	}`
+
+	if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+		t.Fatalf("Failed to write legacy config: %v", err)
+	}
+
+	cfg, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig failed: %v", err)
+	}
+
+	// All user settings should be preserved
+	if cfg.Agents.Defaults.Workspace != "/custom/workspace" {
+		t.Errorf("Workspace = %q, want %q", cfg.Agents.Defaults.Workspace, "/custom/workspace")
+	}
+	if cfg.Agents.Defaults.Provider != "deepseek" {
+		t.Errorf("Provider = %q, want %q", cfg.Agents.Defaults.Provider, "deepseek")
+	}
+	if cfg.Agents.Defaults.ModelName != "deepseek-chat" {
+		t.Errorf("ModelName = %q, want %q", cfg.Agents.Defaults.ModelName, "deepseek-chat")
+	}
+	if cfg.Agents.Defaults.MaxTokens != 16384 {
+		t.Errorf("MaxTokens = %d, want %d", cfg.Agents.Defaults.MaxTokens, 16384)
+	}
+
+	// Verify other settings
+	if cfg.Gateway.Port != 8080 {
+		t.Errorf("Gateway.Port = %d, want %d", cfg.Gateway.Port, 8080)
+	}
+	if !cfg.Devices.Enabled {
+		t.Error("Devices.Enabled should be true")
+	}
+}
+
+// TestMigration_Integration_PreservesAllAgentsFields tests that ALL Agents fields are preserved
+func TestMigration_Integration_PreservesAllAgentsFields(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+
+	legacyConfig := `{
+		"agents": {
+			"defaults": {
+				"workspace": "",
+				"restrict_to_workspace": false,
+				"allow_read_outside_workspace": true,
+				"provider": "anthropic",
+				"model": "claude-opus-4",
+				"model_fallbacks": ["claude-sonnet-4", "claude-haiku-4"],
+				"image_model": "claude-opus-4-vision",
+				"image_model_fallbacks": ["claude-sonnet-4-vision"],
+				"max_tokens": 4096,
+				"temperature": 0.5,
+				"max_tool_iterations": 100,
+				"summarize_message_threshold": 30,
+				"summarize_token_percent": 80,
+				"max_media_size": 10485760
+			},
+			"list": [
+				{
+					"id": "special-agent",
+					"default": false,
+					"name": "Special Agent",
+					"workspace": "/special/workspace"
+				}
+			]
+		},
+		"channels": {
+			"telegram": {"enabled": false}
+		},
+		"gateway": {
+			"host": "127.0.0.1",
+			"port": 18790
+		},
+		"tools": {
+			"web": {"enabled": true}
+		},
+		"heartbeat": {
+			"enabled": true,
+			"interval": 30
+		},
+		"devices": {
+			"enabled": false
+		}
+	}`
+
+	if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+		t.Fatalf("Failed to write legacy config: %v", err)
+	}
+
+	cfg, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig failed: %v", err)
+	}
+
+	// Verify ALL defaults fields are preserved
+	d := cfg.Agents.Defaults
+
+	if d.RestrictToWorkspace != false {
+		t.Errorf("RestrictToWorkspace = %v, want false", d.RestrictToWorkspace)
+	}
+	if d.AllowReadOutsideWorkspace != true {
+		t.Errorf("AllowReadOutsideWorkspace = %v, want true", d.AllowReadOutsideWorkspace)
+	}
+	if d.Provider != "anthropic" {
+		t.Errorf("Provider = %q, want %q", d.Provider, "anthropic")
+	}
+	if d.ModelName != "claude-opus-4" {
+		t.Errorf("ModelName = %q, want %q", d.ModelName, "claude-opus-4")
+	}
+	if len(d.ModelFallbacks) != 2 {
+		t.Errorf("len(ModelFallbacks) = %d, want 2", len(d.ModelFallbacks))
+	} else {
+		if d.ModelFallbacks[0] != "claude-sonnet-4" {
+			t.Errorf("ModelFallbacks[0] = %q, want %q", d.ModelFallbacks[0], "claude-sonnet-4")
+		}
+		if d.ModelFallbacks[1] != "claude-haiku-4" {
+			t.Errorf("ModelFallbacks[1] = %q, want %q", d.ModelFallbacks[1], "claude-haiku-4")
+		}
+	}
+	if d.ImageModel != "claude-opus-4-vision" {
+		t.Errorf("ImageModel = %q, want %q", d.ImageModel, "claude-opus-4-vision")
+	}
+	if len(d.ImageModelFallbacks) != 1 {
+		t.Errorf("len(ImageModelFallbacks) = %d, want 1", len(d.ImageModelFallbacks))
+	} else if d.ImageModelFallbacks[0] != "claude-sonnet-4-vision" {
+		t.Errorf("ImageModelFallbacks[0] = %q, want %q", d.ImageModelFallbacks[0], "claude-sonnet-4-vision")
+	}
+	if d.MaxTokens != 4096 {
+		t.Errorf("MaxTokens = %d, want %d", d.MaxTokens, 4096)
+	}
+	if d.Temperature == nil || *d.Temperature != 0.5 {
+		t.Errorf("Temperature = %v, want 0.5", d.Temperature)
+	}
+	if d.MaxToolIterations != 100 {
+		t.Errorf("MaxToolIterations = %d, want %d", d.MaxToolIterations, 100)
+	}
+	if d.SummarizeMessageThreshold != 30 {
+		t.Errorf("SummarizeMessageThreshold = %d, want %d", d.SummarizeMessageThreshold, 30)
+	}
+	if d.SummarizeTokenPercent != 80 {
+		t.Errorf("SummarizeTokenPercent = %d, want %d", d.SummarizeTokenPercent, 80)
+	}
+	if d.MaxMediaSize != 10485760 {
+		t.Errorf("MaxMediaSize = %d, want %d", d.MaxMediaSize, 10485760)
+	}
+
+	// Verify agent list is preserved
+	if len(cfg.Agents.List) != 1 {
+		t.Fatalf("len(Agents.List) = %d, want 1", len(cfg.Agents.List))
+	}
+	if cfg.Agents.List[0].ID != "special-agent" {
+		t.Errorf("Agent.ID = %q, want %q", cfg.Agents.List[0].ID, "special-agent")
+	}
+	if cfg.Agents.List[0].Workspace != "/special/workspace" {
+		t.Errorf("Agent.Workspace = %q, want %q", cfg.Agents.List[0].Workspace, "/special/workspace")
+	}
+
+	// Workspace should have default since it was empty in legacy config
+	if d.Workspace == "" {
+		t.Error("Workspace should have a default value, not be empty")
+	}
+}
+
+// TestMigration_Integration_ChannelsConfigMigrated tests channel config migration
+func TestMigration_Integration_ChannelsConfigMigrated(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+
+	// Legacy config with old channel field formats
+	legacyConfig := `{
+		"agents": {
+			"defaults": {}
+		},
+		"channels": {
+			"discord": {
+				"enabled": true,
+				"token": "discord-token",
+				"mention_only": true
+			},
+			"onebot": {
+				"enabled": true,
+				"ws_url": "ws://127.0.0.1:3001",
+				"group_trigger_prefix": ["/", "!"]
+			}
+		},
+		"gateway": {
+			"host": "127.0.0.1",
+			"port": 18790
+		},
+		"tools": {
+			"web": {"enabled": true}
+		},
+		"heartbeat": {
+			"enabled": true,
+			"interval": 30
+		},
+		"devices": {
+			"enabled": false
+		}
+	}`
+
+	if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+		t.Fatalf("Failed to write legacy config: %v", err)
+	}
+
+	cfg, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig failed: %v", err)
+	}
+
+	// Discord: mention_only should be migrated to group_trigger.mention_only
+	if cfg.Channels.Discord.GroupTrigger.MentionOnly != true {
+		t.Error("Discord.GroupTrigger.MentionOnly should be true after migration")
+	}
+
+	// OneBot: group_trigger_prefix should be migrated to group_trigger.prefixes
+	if len(cfg.Channels.OneBot.GroupTrigger.Prefixes) != 2 {
+		t.Errorf("len(OneBot.GroupTrigger.Prefixes) = %d, want 2", len(cfg.Channels.OneBot.GroupTrigger.Prefixes))
+	} else {
+		if cfg.Channels.OneBot.GroupTrigger.Prefixes[0] != "/" {
+			t.Errorf("Prefixes[0] = %q, want %q", cfg.Channels.OneBot.GroupTrigger.Prefixes[0], "/")
+		}
+		if cfg.Channels.OneBot.GroupTrigger.Prefixes[1] != "!" {
+			t.Errorf("Prefixes[1] = %q, want %q", cfg.Channels.OneBot.GroupTrigger.Prefixes[1], "!")
+		}
+	}
+}
+
+// TestMigration_Integration_RoundTrip_SerializeAndLoad tests that migrated config can be saved and reloaded
+func TestMigration_Integration_RoundTrip_SerializeAndLoad(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+
+	legacyConfig := `{
+		"agents": {
+			"defaults": {
+				"provider": "openai",
+				"model": "gpt-4o",
+				"max_tokens": 8192
+			}
+		},
+		"channels": {
+			"telegram": {
+				"enabled": true,
+				"token": "test-token"
+			}
+		},
+		"gateway": {
+			"host": "127.0.0.1",
+			"port": 18790
+		},
+		"tools": {
+			"web": {"enabled": true}
+		},
+		"heartbeat": {
+			"enabled": true,
+			"interval": 30
+		},
+		"devices": {
+			"enabled": false
+		}
+	}`
+
+	if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+		t.Fatalf("Failed to write legacy config: %v", err)
+	}
+
+	// First load - triggers migration and saves
+	cfg1, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("First LoadConfig failed: %v", err)
+	}
+
+	// Read the migrated config from disk
+	migratedData, err := os.ReadFile(configPath)
+	if err != nil {
+		t.Fatalf("Failed to read migrated config: %v", err)
+	}
+
+	// Verify it has the current version
+	var versionCheck struct {
+		Version int `json:"version"`
+	}
+	if err = json.Unmarshal(migratedData, &versionCheck); err != nil {
+		t.Fatalf("Failed to parse migrated config version: %v", err)
+	}
+	if versionCheck.Version != CurrentVersion {
+		t.Errorf("Migrated config version = %d, want %d", versionCheck.Version, CurrentVersion)
+	}
+
+	// Second load - should load the migrated config without changes
+	cfg2, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("Second LoadConfig failed: %v", err)
+	}
+
+	// Verify configs are identical
+	if cfg2.Agents.Defaults.Provider != cfg1.Agents.Defaults.Provider {
+		t.Errorf("Provider changed from %q to %q", cfg1.Agents.Defaults.Provider, cfg2.Agents.Defaults.Provider)
+	}
+	if cfg2.Agents.Defaults.ModelName != cfg1.Agents.Defaults.ModelName {
+		t.Errorf("ModelName changed from %q to %q", cfg1.Agents.Defaults.ModelName, cfg2.Agents.Defaults.ModelName)
+	}
+	if cfg2.Agents.Defaults.MaxTokens != cfg1.Agents.Defaults.MaxTokens {
+		t.Errorf("MaxTokens changed from %d to %d", cfg1.Agents.Defaults.MaxTokens, cfg2.Agents.Defaults.MaxTokens)
+	}
+}
+
+// TestMigration_Integration_EmptyAgentsDefaults tests migration with completely empty agents config
+func TestMigration_Integration_EmptyAgentsDefaults(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+
+	// Legacy config with empty agents defaults
+	legacyConfig := `{
+		"agents": {
+			"defaults": {}
+		},
+		"channels": {
+			"telegram": {"enabled": false}
+		},
+		"gateway": {
+			"host": "127.0.0.1",
+			"port": 18790
+		},
+		"tools": {
+			"web": {"enabled": true}
+		},
+		"heartbeat": {
+			"enabled": true,
+			"interval": 30
+		},
+		"devices": {
+			"enabled": false
+		}
+	}`
+
+	if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+		t.Fatalf("Failed to write legacy config: %v", err)
+	}
+
+	cfg, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig failed: %v", err)
+	}
+
+	// Workspace should have default value
+	if cfg.Agents.Defaults.Workspace == "" {
+		t.Error("Workspace should have a default value")
+	}
+
+	// Note: When fields are explicitly set in config (even to zero values),
+	// they override defaults. This is correct JSON unmarshaling behavior.
+	// Users should set values they want; defaults are for unspecified fields.
+	if cfg.Agents.Defaults.MaxTokens == 0 {
+		// This is expected when users don't set max_tokens in their config
+		// The zero value (0) from the legacy config is preserved
+	}
+	if cfg.Agents.Defaults.MaxToolIterations == 0 {
+		// Same as above - zero value is preserved if it was in the config
+	}
+}
+
+// TestMigration_Integration_ModelNameField tests migration using new model_name field
+func TestMigration_Integration_ModelNameField(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+
+	// Legacy config using the new model_name field
+	legacyConfig := `{
+		"agents": {
+			"defaults": {
+				"provider": "deepseek",
+				"model_name": "deepseek-reasoner",
+				"model_fallbacks": ["deepseek-chat"]
+			}
+		},
+		"channels": {
+			"telegram": {"enabled": false}
+		},
+		"gateway": {
+			"host": "127.0.0.1",
+			"port": 18790
+		},
+		"tools": {
+			"web": {"enabled": true}
+		},
+		"heartbeat": {
+			"enabled": true,
+			"interval": 30
+		},
+		"devices": {
+			"enabled": false
+		}
+	}`
+
+	if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+		t.Fatalf("Failed to write legacy config: %v", err)
+	}
+
+	cfg, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig failed: %v", err)
+	}
+
+	// model_name field should be preserved
+	if cfg.Agents.Defaults.ModelName != "deepseek-reasoner" {
+		t.Errorf("ModelName = %q, want %q", cfg.Agents.Defaults.ModelName, "deepseek-reasoner")
+	}
+
+	// GetModelName() should return model_name, not model (deprecated)
+	if cfg.Agents.Defaults.GetModelName() != "deepseek-reasoner" {
+		t.Errorf("GetModelName() = %q, want %q", cfg.Agents.Defaults.GetModelName(), "deepseek-reasoner")
+	}
+
+	if len(cfg.Agents.Defaults.ModelFallbacks) != 1 {
+		t.Errorf("len(ModelFallbacks) = %d, want 1", len(cfg.Agents.Defaults.ModelFallbacks))
+	} else if cfg.Agents.Defaults.ModelFallbacks[0] != "deepseek-chat" {
+		t.Errorf("ModelFallbacks[0] = %q, want %q", cfg.Agents.Defaults.ModelFallbacks[0], "deepseek-chat")
+	}
+}
+
+// TestMigration_PreservesExistingSecurityConfig tests that when migrating from v0 to v1,
+// existing .security.yml values (e.g., loaded from environment variables) are preserved
+// and not overwritten by empty values from the legacy config.
+func TestMigration_PreservesExistingSecurityConfig(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "config.json")
+	securityPath := filepath.Join(tmpDir, ".security.yml")
+
+	// Create a legacy config (version 0) with model_list and channel config
+	// The model_list doesn't have api_keys, they should come from existing .security.yml
+	legacyConfig := `{
+		"agents": {
+			"defaults": {
+				"provider": "openai",
+				"model": "gpt-4"
+			}
+		},
+		"model_list": [
+			{
+				"model_name": "openai",
+				"model": "openai/gpt-4"
+			}
+		],
+		"channels": {
+			"telegram": {
+				"enabled": true
+			}
+		},
+		"gateway": {
+			"host": "127.0.0.1",
+			"port": 18790
+		},
+		"tools": {
+			"web": {"enabled": true}
+		},
+		"heartbeat": {
+			"enabled": true,
+			"interval": 30
+		},
+		"devices": {
+			"enabled": false
+		}
+	}`
+
+	// Create an existing .security.yml with values that might come from env vars
+	existingSecurity := `model_list:
+  openai:0:
+    api_keys:
+      - sk-existing-key-from-env
+channels:
+  telegram:
+    token: existing-telegram-token-from-env
+  discord:
+    token: existing-discord-token-from-env
+web:
+  brave:
+    api_keys:
+      - existing-brave-key
+`
+
+	if err := os.WriteFile(configPath, []byte(legacyConfig), 0o600); err != nil {
+		t.Fatalf("Failed to write legacy config: %v", err)
+	}
+
+	if err := os.WriteFile(securityPath, []byte(existingSecurity), 0o600); err != nil {
+		t.Fatalf("Failed to write existing security config: %v", err)
+	}
+
+	// Load the config - this should trigger migration
+	cfg, err := LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig failed: %v", err)
+	}
+
+	// Verify that the migrated config has the existing security values
+	// Telegram token should be preserved
+	if cfg.Channels.Telegram.Token() != "existing-telegram-token-from-env" {
+		t.Errorf("Telegram token was overwritten: got %q, want %q",
+			cfg.Channels.Telegram.Token(), "existing-telegram-token-from-env")
+	}
+
+	// Discord token should be preserved (even though legacy config didn't have it)
+	if cfg.Channels.Discord.Token() != "existing-discord-token-from-env" {
+		t.Errorf("Discord token was overwritten: got %q, want %q",
+			cfg.Channels.Discord.Token(), "existing-discord-token-from-env")
+	}
+
+	// Model API key should be preserved
+	if cfg.ModelList[0].APIKey() != "sk-existing-key-from-env" {
+		t.Errorf("Model API key was overwritten: got %q, want %q",
+			cfg.ModelList[0].APIKey(), "sk-existing-key-from-env")
+	}
+
+	// Brave API key should be preserved
+	if cfg.Tools.Web.Brave.APIKey() != "existing-brave-key" {
+		t.Errorf("Brave API key was overwritten: got %q, want %q",
+			cfg.Tools.Web.Brave.APIKey(), "existing-brave-key")
+	}
+
+	// Reload the security config from disk to verify it wasn't corrupted
+	reloadedSec, err := loadSecurityConfig(securityPath)
+	if err != nil {
+		t.Fatalf("Failed to reload security config: %v", err)
+	}
+
+	if reloadedSec.Channels.Telegram == nil ||
+		reloadedSec.Channels.Telegram.Token != "existing-telegram-token-from-env" {
+		t.Error("Telegram token not preserved in .security.yml file")
+	}
+
+	if reloadedSec.Channels.Discord == nil || reloadedSec.Channels.Discord.Token != "existing-discord-token-from-env" {
+		t.Error("Discord token not preserved in .security.yml file")
+	}
+}
diff --git a/pkg/config/migration_test.go b/pkg/config/migration_test.go
index db8f4657d..aeabe9730 100644
--- a/pkg/config/migration_test.go
+++ b/pkg/config/migration_test.go
@@ -11,10 +11,10 @@ import (
 )
 
 func TestConvertProvidersToModelList_OpenAI(t *testing.T) {
-	cfg := &Config{
-		Providers: ProvidersConfig{
-			OpenAI: OpenAIProviderConfig{
-				ProviderConfig: ProviderConfig{
+	cfg := &configV0{
+		Providers: providersConfigV0{
+			OpenAI: openAIProviderConfigV0{
+				providerConfigV0: providerConfigV0{
 					APIKey:  "sk-test-key",
 					APIBase: "https://custom.api.com/v1",
 				},
@@ -22,7 +22,7 @@ func TestConvertProvidersToModelList_OpenAI(t *testing.T) {
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 1 {
 		t.Fatalf("len(result) = %d, want 1", len(result))
@@ -31,8 +31,8 @@ func TestConvertProvidersToModelList_OpenAI(t *testing.T) {
 	if result[0].ModelName != "openai" {
 		t.Errorf("ModelName = %q, want %q", result[0].ModelName, "openai")
 	}
-	if result[0].Model != "openai/gpt-5.2" {
-		t.Errorf("Model = %q, want %q", result[0].Model, "openai/gpt-5.2")
+	if result[0].Model != "openai/gpt-5.4" {
+		t.Errorf("Model = %q, want %q", result[0].Model, "openai/gpt-5.4")
 	}
 	if result[0].APIKey != "sk-test-key" {
 		t.Errorf("APIKey = %q, want %q", result[0].APIKey, "sk-test-key")
@@ -40,16 +40,15 @@ func TestConvertProvidersToModelList_OpenAI(t *testing.T) {
 }
 
 func TestConvertProvidersToModelList_Anthropic(t *testing.T) {
-	cfg := &Config{
-		Providers: ProvidersConfig{
-			Anthropic: ProviderConfig{
-				APIKey:  "ant-key",
+	cfg := &configV0{
+		Providers: providersConfigV0{
+			Anthropic: providerConfigV0{
 				APIBase: "https://custom.anthropic.com",
 			},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 1 {
 		t.Fatalf("len(result) = %d, want 1", len(result))
@@ -63,16 +62,42 @@ func TestConvertProvidersToModelList_Anthropic(t *testing.T) {
 	}
 }
 
-func TestConvertProvidersToModelList_Multiple(t *testing.T) {
-	cfg := &Config{
-		Providers: ProvidersConfig{
-			OpenAI: OpenAIProviderConfig{ProviderConfig: ProviderConfig{APIKey: "openai-key"}},
-			Groq:   ProviderConfig{APIKey: "groq-key"},
-			Zhipu:  ProviderConfig{APIKey: "zhipu-key"},
+func TestConvertProvidersToModelList_LiteLLM(t *testing.T) {
+	cfg := &configV0{
+		Providers: providersConfigV0{
+			LiteLLM: providerConfigV0{
+				APIBase: "http://localhost:4000/v1",
+			},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
+
+	if len(result) != 1 {
+		t.Fatalf("len(result) = %d, want 1", len(result))
+	}
+
+	if result[0].ModelName != "litellm" {
+		t.Errorf("ModelName = %q, want %q", result[0].ModelName, "litellm")
+	}
+	if result[0].Model != "litellm/auto" {
+		t.Errorf("Model = %q, want %q", result[0].Model, "litellm/auto")
+	}
+	if result[0].APIBase != "http://localhost:4000/v1" {
+		t.Errorf("APIBase = %q, want %q", result[0].APIBase, "http://localhost:4000/v1")
+	}
+}
+
+func TestConvertProvidersToModelList_Multiple(t *testing.T) {
+	cfg := &configV0{
+		Providers: providersConfigV0{
+			OpenAI: openAIProviderConfigV0{providerConfigV0: providerConfigV0{APIKey: "openai-key"}},
+			Groq:   providerConfigV0{APIKey: "groq-key"},
+			Zhipu:  providerConfigV0{APIKey: "zhipu-key"},
+		},
+	}
+
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 3 {
 		t.Fatalf("len(result) = %d, want 3", len(result))
@@ -92,11 +117,11 @@ func TestConvertProvidersToModelList_Multiple(t *testing.T) {
 }
 
 func TestConvertProvidersToModelList_Empty(t *testing.T) {
-	cfg := &Config{
-		Providers: ProvidersConfig{},
+	cfg := &configV0{
+		Providers: providersConfigV0{},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 0 {
 		t.Errorf("len(result) = %d, want 0", len(result))
@@ -104,7 +129,7 @@ func TestConvertProvidersToModelList_Empty(t *testing.T) {
 }
 
 func TestConvertProvidersToModelList_Nil(t *testing.T) {
-	result := ConvertProvidersToModelList(nil)
+	result := v0ConvertProvidersToModelList(nil)
 
 	if result != nil {
 		t.Errorf("result = %v, want nil", result)
@@ -112,42 +137,50 @@ func TestConvertProvidersToModelList_Nil(t *testing.T) {
 }
 
 func TestConvertProvidersToModelList_AllProviders(t *testing.T) {
-	cfg := &Config{
-		Providers: ProvidersConfig{
-			OpenAI:        OpenAIProviderConfig{ProviderConfig: ProviderConfig{APIKey: "key1"}},
-			Anthropic:     ProviderConfig{APIKey: "key2"},
-			OpenRouter:    ProviderConfig{APIKey: "key3"},
-			Groq:          ProviderConfig{APIKey: "key4"},
-			Zhipu:         ProviderConfig{APIKey: "key5"},
-			VLLM:          ProviderConfig{APIKey: "key6"},
-			Gemini:        ProviderConfig{APIKey: "key7"},
-			Nvidia:        ProviderConfig{APIKey: "key8"},
-			Ollama:        ProviderConfig{APIKey: "key9"},
-			Moonshot:      ProviderConfig{APIKey: "key10"},
-			ShengSuanYun:  ProviderConfig{APIKey: "key11"},
-			DeepSeek:      ProviderConfig{APIKey: "key12"},
-			Cerebras:      ProviderConfig{APIKey: "key13"},
-			VolcEngine:    ProviderConfig{APIKey: "key14"},
-			GitHubCopilot: ProviderConfig{ConnectMode: "grpc"},
-			Antigravity:   ProviderConfig{AuthMethod: "oauth"},
-			Qwen:          ProviderConfig{APIKey: "key17"},
-			Mistral:       ProviderConfig{APIKey: "key18"},
+	// This test verifies that when providers have at least one configured field,
+	// they are converted. GitHubCopilot has ConnectMode set, Antigravity has AuthMethod.
+	// Other providers have no configuration, so they won't be converted.
+	cfg := &configV0{
+		Providers: providersConfigV0{
+			OpenAI:        openAIProviderConfigV0{providerConfigV0: providerConfigV0{APIKey: "key1"}},
+			LiteLLM:       providerConfigV0{APIKey: "key-litellm", APIBase: "http://localhost:4000/v1"},
+			Anthropic:     providerConfigV0{APIKey: "key2"},
+			OpenRouter:    providerConfigV0{APIKey: "key3"},
+			Groq:          providerConfigV0{APIKey: "key4"},
+			Zhipu:         providerConfigV0{APIKey: "key5"},
+			VLLM:          providerConfigV0{APIKey: "key6"},
+			Gemini:        providerConfigV0{APIKey: "key7"},
+			Nvidia:        providerConfigV0{APIKey: "key8"},
+			Ollama:        providerConfigV0{APIKey: "key9"},
+			Moonshot:      providerConfigV0{APIKey: "key10"},
+			ShengSuanYun:  providerConfigV0{APIKey: "key11"},
+			DeepSeek:      providerConfigV0{APIKey: "key12"},
+			Cerebras:      providerConfigV0{APIKey: "key13"},
+			Vivgrid:       providerConfigV0{APIKey: "key14"},
+			VolcEngine:    providerConfigV0{APIKey: "key15"},
+			GitHubCopilot: providerConfigV0{ConnectMode: "grpc"},
+			Antigravity:   providerConfigV0{AuthMethod: "oauth"},
+			Qwen:          providerConfigV0{APIKey: "key17"},
+			Mistral:       providerConfigV0{APIKey: "key18"},
+			Avian:         providerConfigV0{APIKey: "key19"},
+			LongCat:       providerConfigV0{APIKey: "key-longcat"},
+			ModelScope:    providerConfigV0{APIKey: "key-modelscope"},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
-	// All 18 providers should be converted
-	if len(result) != 18 {
-		t.Errorf("len(result) = %d, want 18", len(result))
+	// All 23 providers should be converted
+	if len(result) != 23 {
+		t.Errorf("len(result) = %d, want 23", len(result))
 	}
 }
 
 func TestConvertProvidersToModelList_Proxy(t *testing.T) {
-	cfg := &Config{
-		Providers: ProvidersConfig{
-			OpenAI: OpenAIProviderConfig{
-				ProviderConfig: ProviderConfig{
+	cfg := &configV0{
+		Providers: providersConfigV0{
+			OpenAI: openAIProviderConfigV0{
+				providerConfigV0: providerConfigV0{
 					APIKey: "key",
 					Proxy:  "http://proxy:8080",
 				},
@@ -155,7 +188,7 @@ func TestConvertProvidersToModelList_Proxy(t *testing.T) {
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 1 {
 		t.Fatalf("len(result) = %d, want 1", len(result))
@@ -167,16 +200,16 @@ func TestConvertProvidersToModelList_Proxy(t *testing.T) {
 }
 
 func TestConvertProvidersToModelList_RequestTimeout(t *testing.T) {
-	cfg := &Config{
-		Providers: ProvidersConfig{
-			Ollama: ProviderConfig{
-				APIKey:         "ollama-key",
+	cfg := &configV0{
+		Providers: providersConfigV0{
+			Ollama: providerConfigV0{
+				APIBase:        "http://localhost:11434",
 				RequestTimeout: 300,
 			},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 1 {
 		t.Fatalf("len(result) = %d, want 1", len(result))
@@ -188,17 +221,17 @@ func TestConvertProvidersToModelList_RequestTimeout(t *testing.T) {
 }
 
 func TestConvertProvidersToModelList_AuthMethod(t *testing.T) {
-	cfg := &Config{
-		Providers: ProvidersConfig{
-			OpenAI: OpenAIProviderConfig{
-				ProviderConfig: ProviderConfig{
+	cfg := &configV0{
+		Providers: providersConfigV0{
+			OpenAI: openAIProviderConfigV0{
+				providerConfigV0: providerConfigV0{
 					AuthMethod: "oauth",
 				},
 			},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 0 {
 		t.Errorf("len(result) = %d, want 0 (AuthMethod alone should not create entry)", len(result))
@@ -208,19 +241,19 @@ func TestConvertProvidersToModelList_AuthMethod(t *testing.T) {
 // Tests for preserving user's configured model during migration
 
 func TestConvertProvidersToModelList_PreservesUserModel_DeepSeek(t *testing.T) {
-	cfg := &Config{
-		Agents: AgentsConfig{
-			Defaults: AgentDefaults{
+	cfg := &configV0{
+		Agents: agentsConfigV0{
+			Defaults: agentDefaultsV0{
 				Provider: "deepseek",
 				Model:    "deepseek-reasoner",
 			},
 		},
-		Providers: ProvidersConfig{
-			DeepSeek: ProviderConfig{APIKey: "sk-deepseek"},
+		Providers: providersConfigV0{
+			DeepSeek: providerConfigV0{APIKey: "sk-deepseek"},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 1 {
 		t.Fatalf("len(result) = %d, want 1", len(result))
@@ -233,19 +266,19 @@ func TestConvertProvidersToModelList_PreservesUserModel_DeepSeek(t *testing.T) {
 }
 
 func TestConvertProvidersToModelList_PreservesUserModel_OpenAI(t *testing.T) {
-	cfg := &Config{
-		Agents: AgentsConfig{
-			Defaults: AgentDefaults{
+	cfg := &configV0{
+		Agents: agentsConfigV0{
+			Defaults: agentDefaultsV0{
 				Provider: "openai",
 				Model:    "gpt-4-turbo",
 			},
 		},
-		Providers: ProvidersConfig{
-			OpenAI: OpenAIProviderConfig{ProviderConfig: ProviderConfig{APIKey: "sk-openai"}},
+		Providers: providersConfigV0{
+			OpenAI: openAIProviderConfigV0{providerConfigV0: providerConfigV0{APIKey: "sk-openai"}},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 1 {
 		t.Fatalf("len(result) = %d, want 1", len(result))
@@ -257,19 +290,19 @@ func TestConvertProvidersToModelList_PreservesUserModel_OpenAI(t *testing.T) {
 }
 
 func TestConvertProvidersToModelList_PreservesUserModel_Anthropic(t *testing.T) {
-	cfg := &Config{
-		Agents: AgentsConfig{
-			Defaults: AgentDefaults{
+	cfg := &configV0{
+		Agents: agentsConfigV0{
+			Defaults: agentDefaultsV0{
 				Provider: "claude", // alternative name
 				Model:    "claude-opus-4-20250514",
 			},
 		},
-		Providers: ProvidersConfig{
-			Anthropic: ProviderConfig{APIKey: "sk-ant"},
+		Providers: providersConfigV0{
+			Anthropic: providerConfigV0{APIKey: "sk-ant"},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 1 {
 		t.Fatalf("len(result) = %d, want 1", len(result))
@@ -281,19 +314,19 @@ func TestConvertProvidersToModelList_PreservesUserModel_Anthropic(t *testing.T)
 }
 
 func TestConvertProvidersToModelList_PreservesUserModel_Qwen(t *testing.T) {
-	cfg := &Config{
-		Agents: AgentsConfig{
-			Defaults: AgentDefaults{
+	cfg := &configV0{
+		Agents: agentsConfigV0{
+			Defaults: agentDefaultsV0{
 				Provider: "qwen",
 				Model:    "qwen-plus",
 			},
 		},
-		Providers: ProvidersConfig{
-			Qwen: ProviderConfig{APIKey: "sk-qwen"},
+		Providers: providersConfigV0{
+			Qwen: providerConfigV0{APIKey: "sk-qwen"},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 1 {
 		t.Fatalf("len(result) = %d, want 1", len(result))
@@ -305,19 +338,19 @@ func TestConvertProvidersToModelList_PreservesUserModel_Qwen(t *testing.T) {
 }
 
 func TestConvertProvidersToModelList_UsesDefaultWhenNoUserModel(t *testing.T) {
-	cfg := &Config{
-		Agents: AgentsConfig{
-			Defaults: AgentDefaults{
+	cfg := &configV0{
+		Agents: agentsConfigV0{
+			Defaults: agentDefaultsV0{
 				Provider: "deepseek",
 				Model:    "", // no model specified
 			},
 		},
-		Providers: ProvidersConfig{
-			DeepSeek: ProviderConfig{APIKey: "sk-deepseek"},
+		Providers: providersConfigV0{
+			DeepSeek: providerConfigV0{APIKey: "sk-deepseek"},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 1 {
 		t.Fatalf("len(result) = %d, want 1", len(result))
@@ -330,20 +363,20 @@ func TestConvertProvidersToModelList_UsesDefaultWhenNoUserModel(t *testing.T) {
 }
 
 func TestConvertProvidersToModelList_MultipleProviders_PreservesUserModel(t *testing.T) {
-	cfg := &Config{
-		Agents: AgentsConfig{
-			Defaults: AgentDefaults{
+	cfg := &configV0{
+		Agents: agentsConfigV0{
+			Defaults: agentDefaultsV0{
 				Provider: "deepseek",
 				Model:    "deepseek-reasoner",
 			},
 		},
-		Providers: ProvidersConfig{
-			OpenAI:   OpenAIProviderConfig{ProviderConfig: ProviderConfig{APIKey: "sk-openai"}},
-			DeepSeek: ProviderConfig{APIKey: "sk-deepseek"},
+		Providers: providersConfigV0{
+			OpenAI:   openAIProviderConfigV0{providerConfigV0: providerConfigV0{APIKey: "sk-openai"}},
+			DeepSeek: providerConfigV0{APIKey: "sk-deepseek"},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 2 {
 		t.Fatalf("len(result) = %d, want 2", len(result))
@@ -353,8 +386,8 @@ func TestConvertProvidersToModelList_MultipleProviders_PreservesUserModel(t *tes
 	for _, mc := range result {
 		switch mc.ModelName {
 		case "openai":
-			if mc.Model != "openai/gpt-5.2" {
-				t.Errorf("OpenAI Model = %q, want %q (default)", mc.Model, "openai/gpt-5.2")
+			if mc.Model != "openai/gpt-5.4" {
+				t.Errorf("OpenAI Model = %q, want %q (default)", mc.Model, "openai/gpt-5.4")
 			}
 		case "deepseek":
 			if mc.Model != "deepseek/deepseek-reasoner" {
@@ -368,20 +401,20 @@ func TestConvertProvidersToModelList_ProviderNameAliases(t *testing.T) {
 	tests := []struct {
 		providerAlias string
 		expectedModel string
-		provider      ProviderConfig
+		provider      providerConfigV0
 	}{
-		{"gpt", "openai/gpt-4-custom", ProviderConfig{APIKey: "key"}},
-		{"claude", "anthropic/claude-custom", ProviderConfig{APIKey: "key"}},
-		{"doubao", "volcengine/doubao-custom", ProviderConfig{APIKey: "key"}},
-		{"tongyi", "qwen/qwen-custom", ProviderConfig{APIKey: "key"}},
-		{"kimi", "moonshot/kimi-custom", ProviderConfig{APIKey: "key"}},
+		{"gpt", "openai/gpt-4-custom", providerConfigV0{APIKey: "key"}},
+		{"claude", "anthropic/claude-custom", providerConfigV0{APIKey: "key"}},
+		{"doubao", "volcengine/doubao-custom", providerConfigV0{APIKey: "key"}},
+		{"tongyi", "qwen/qwen-custom", providerConfigV0{APIKey: "key"}},
+		{"kimi", "moonshot/kimi-custom", providerConfigV0{APIKey: "key"}},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.providerAlias, func(t *testing.T) {
-			cfg := &Config{
-				Agents: AgentsConfig{
-					Defaults: AgentDefaults{
+			cfg := &configV0{
+				Agents: agentsConfigV0{
+					Defaults: agentDefaultsV0{
 						Provider: tt.providerAlias,
 						Model: strings.TrimPrefix(
 							tt.expectedModel,
@@ -389,13 +422,13 @@ func TestConvertProvidersToModelList_ProviderNameAliases(t *testing.T) {
 						),
 					},
 				},
-				Providers: ProvidersConfig{},
+				Providers: providersConfigV0{},
 			}
 
 			// Set the appropriate provider config
 			switch tt.providerAlias {
 			case "gpt":
-				cfg.Providers.OpenAI = OpenAIProviderConfig{ProviderConfig: tt.provider}
+				cfg.Providers.OpenAI = openAIProviderConfigV0{providerConfigV0: tt.provider}
 			case "claude":
 				cfg.Providers.Anthropic = tt.provider
 			case "doubao":
@@ -412,7 +445,7 @@ func TestConvertProvidersToModelList_ProviderNameAliases(t *testing.T) {
 				tt.expectedModel[:strings.Index(tt.expectedModel, "/")+1],
 			)
 
-			result := ConvertProvidersToModelList(cfg)
+			result := v0ConvertProvidersToModelList(cfg)
 			if len(result) != 1 {
 				t.Fatalf("len(result) = %d, want 1", len(result))
 			}
@@ -434,19 +467,21 @@ func TestConvertProvidersToModelList_NoProviderField_SingleProvider(t *testing.T
 	// - No provider field set
 	// - model = "glm-4.7"
 	// - Only zhipu has API key configured
-	cfg := &Config{
-		Agents: AgentsConfig{
-			Defaults: AgentDefaults{
+	cfg := &configV0{
+		Agents: agentsConfigV0{
+			Defaults: agentDefaultsV0{
 				Provider: "", // Not set
 				Model:    "glm-4.7",
 			},
 		},
-		Providers: ProvidersConfig{
-			Zhipu: ProviderConfig{APIKey: "test-zhipu-key"},
+		Providers: providersConfigV0{
+			Zhipu: providerConfigV0{
+				APIKey: "test-zhipu-key",
+			},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 1 {
 		t.Fatalf("len(result) = %d, want 1", len(result))
@@ -467,20 +502,20 @@ func TestConvertProvidersToModelList_NoProviderField_MultipleProviders(t *testin
 	// When multiple providers are configured but no provider field is set,
 	// the FIRST provider (in migration order) will use userModel as ModelName
 	// for backward compatibility with legacy implicit provider selection
-	cfg := &Config{
-		Agents: AgentsConfig{
-			Defaults: AgentDefaults{
+	cfg := &configV0{
+		Agents: agentsConfigV0{
+			Defaults: agentDefaultsV0{
 				Provider: "", // Not set
 				Model:    "some-model",
 			},
 		},
-		Providers: ProvidersConfig{
-			OpenAI: OpenAIProviderConfig{ProviderConfig: ProviderConfig{APIKey: "openai-key"}},
-			Zhipu:  ProviderConfig{APIKey: "zhipu-key"},
+		Providers: providersConfigV0{
+			OpenAI: openAIProviderConfigV0{providerConfigV0: providerConfigV0{APIKey: "openai-key"}},
+			Zhipu:  providerConfigV0{APIKey: "zhipu-key"},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 2 {
 		t.Fatalf("len(result) = %d, want 2", len(result))
@@ -500,19 +535,19 @@ func TestConvertProvidersToModelList_NoProviderField_MultipleProviders(t *testin
 
 func TestConvertProvidersToModelList_NoProviderField_NoModel(t *testing.T) {
 	// Edge case: no provider, no model
-	cfg := &Config{
-		Agents: AgentsConfig{
-			Defaults: AgentDefaults{
+	cfg := &configV0{
+		Agents: agentsConfigV0{
+			Defaults: agentDefaultsV0{
 				Provider: "",
 				Model:    "",
 			},
 		},
-		Providers: ProvidersConfig{
-			Zhipu: ProviderConfig{APIKey: "zhipu-key"},
+		Providers: providersConfigV0{
+			Zhipu: providerConfigV0{APIKey: "zhipu-key"},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) != 1 {
 		t.Fatalf("len(result) = %d, want 1", len(result))
@@ -527,9 +562,9 @@ func TestConvertProvidersToModelList_NoProviderField_NoModel(t *testing.T) {
 // Tests for buildModelWithProtocol helper function
 
 func TestBuildModelWithProtocol_NoPrefix(t *testing.T) {
-	result := buildModelWithProtocol("openai", "gpt-5.2")
-	if result != "openai/gpt-5.2" {
-		t.Errorf("buildModelWithProtocol(openai, gpt-5.2) = %q, want %q", result, "openai/gpt-5.2")
+	result := buildModelWithProtocol("openai", "gpt-5.4")
+	if result != "openai/gpt-5.4" {
+		t.Errorf("buildModelWithProtocol(openai, gpt-5.4) = %q, want %q", result, "openai/gpt-5.4")
 	}
 }
 
@@ -553,19 +588,19 @@ func TestBuildModelWithProtocol_DifferentPrefix(t *testing.T) {
 
 // Test for legacy config with protocol prefix in model name
 func TestConvertProvidersToModelList_LegacyModelWithProtocolPrefix(t *testing.T) {
-	cfg := &Config{
-		Agents: AgentsConfig{
-			Defaults: AgentDefaults{
+	cfg := &configV0{
+		Agents: agentsConfigV0{
+			Defaults: agentDefaultsV0{
 				Provider: "",                // No explicit provider
 				Model:    "openrouter/auto", // Model already has protocol prefix
 			},
 		},
-		Providers: ProvidersConfig{
-			OpenRouter: ProviderConfig{APIKey: "sk-or-test"},
+		Providers: providersConfigV0{
+			OpenRouter: providerConfigV0{APIKey: "sk-or-test"},
 		},
 	}
 
-	result := ConvertProvidersToModelList(cfg)
+	result := v0ConvertProvidersToModelList(cfg)
 
 	if len(result) < 1 {
 		t.Fatalf("len(result) = %d, want at least 1", len(result))
diff --git a/pkg/config/model_config_test.go b/pkg/config/model_config_test.go
index da6e506f8..3252d2f26 100644
--- a/pkg/config/model_config_test.go
+++ b/pkg/config/model_config_test.go
@@ -13,12 +13,20 @@ import (
 )
 
 func TestGetModelConfig_Found(t *testing.T) {
-	cfg := &Config{
-		ModelList: []ModelConfig{
-			{ModelName: "test-model", Model: "openai/gpt-4o", APIKey: "key1"},
-			{ModelName: "other-model", Model: "anthropic/claude", APIKey: "key2"},
+	cfg := (&Config{
+		Version: CurrentVersion,
+		ModelList: []*ModelConfig{
+			{ModelName: "test-model", Model: "openai/gpt-4o"},
+			{ModelName: "other-model", Model: "anthropic/claude"},
 		},
-	}
+	}).WithSecurity(&SecurityConfig{ModelList: map[string]ModelSecurityEntry{
+		"test-model:0": {
+			APIKeys: []string{"key1"},
+		},
+		"other-model:0": {
+			APIKeys: []string{"key2"},
+		},
+	}})
 
 	result, err := cfg.GetModelConfig("test-model")
 	if err != nil {
@@ -30,11 +38,17 @@ func TestGetModelConfig_Found(t *testing.T) {
 }
 
 func TestGetModelConfig_NotFound(t *testing.T) {
-	cfg := &Config{
-		ModelList: []ModelConfig{
-			{ModelName: "test-model", Model: "openai/gpt-4o", APIKey: "key1"},
+	cfg := (&Config{
+		ModelList: []*ModelConfig{
+			{ModelName: "test-model", Model: "openai/gpt-4o"},
 		},
-	}
+	}).WithSecurity(&SecurityConfig{
+		ModelList: map[string]ModelSecurityEntry{
+			"test-model:0": {
+				APIKeys: []string{"key1"},
+			},
+		},
+	})
 
 	_, err := cfg.GetModelConfig("nonexistent")
 	if err == nil {
@@ -44,7 +58,7 @@ func TestGetModelConfig_NotFound(t *testing.T) {
 
 func TestGetModelConfig_EmptyList(t *testing.T) {
 	cfg := &Config{
-		ModelList: []ModelConfig{},
+		ModelList: []*ModelConfig{},
 	}
 
 	_, err := cfg.GetModelConfig("any-model")
@@ -54,13 +68,25 @@ func TestGetModelConfig_EmptyList(t *testing.T) {
 }
 
 func TestGetModelConfig_RoundRobin(t *testing.T) {
-	cfg := &Config{
-		ModelList: []ModelConfig{
-			{ModelName: "lb-model", Model: "openai/gpt-4o-1", APIKey: "key1"},
-			{ModelName: "lb-model", Model: "openai/gpt-4o-2", APIKey: "key2"},
-			{ModelName: "lb-model", Model: "openai/gpt-4o-3", APIKey: "key3"},
+	cfg := (&Config{
+		ModelList: []*ModelConfig{
+			{ModelName: "lb-model", Model: "openai/gpt-4o-1"},
+			{ModelName: "lb-model", Model: "openai/gpt-4o-2"},
+			{ModelName: "lb-model", Model: "openai/gpt-4o-3"},
 		},
-	}
+	}).WithSecurity(&SecurityConfig{
+		ModelList: map[string]ModelSecurityEntry{
+			"lb-model:0": {
+				APIKeys: []string{"key1"},
+			},
+			"lb-model:1": {
+				APIKeys: []string{"key2"},
+			},
+			"lb-model:2": {
+				APIKeys: []string{"key3"},
+			},
+		},
+	})
 
 	// Test round-robin distribution
 	results := make(map[string]int)
@@ -80,11 +106,41 @@ func TestGetModelConfig_RoundRobin(t *testing.T) {
 	}
 }
 
+func TestGetModelConfig_RoundRobinStartsFromFirstMatch(t *testing.T) {
+	rrCounter.Store(0)
+
+	cfg := &Config{
+		ModelList: []*ModelConfig{
+			{ModelName: "lb-model", Model: "openai/gpt-4o-1", apiKeys: []string{"key1"}},
+			{ModelName: "lb-model", Model: "openai/gpt-4o-2", apiKeys: []string{"key2"}},
+			{ModelName: "lb-model", Model: "openai/gpt-4o-3", apiKeys: []string{"key3"}},
+		},
+	}
+
+	wantOrder := []string{
+		"openai/gpt-4o-1",
+		"openai/gpt-4o-2",
+		"openai/gpt-4o-3",
+		"openai/gpt-4o-1",
+		"openai/gpt-4o-2",
+	}
+
+	for i, want := range wantOrder {
+		result, err := cfg.GetModelConfig("lb-model")
+		if err != nil {
+			t.Fatalf("GetModelConfig() call %d error = %v", i, err)
+		}
+		if result.Model != want {
+			t.Fatalf("GetModelConfig() call %d model = %q, want %q", i, result.Model, want)
+		}
+	}
+}
+
 func TestGetModelConfig_Concurrent(t *testing.T) {
 	cfg := &Config{
-		ModelList: []ModelConfig{
-			{ModelName: "concurrent-model", Model: "openai/gpt-4o-1", APIKey: "key1"},
-			{ModelName: "concurrent-model", Model: "openai/gpt-4o-2", APIKey: "key2"},
+		ModelList: []*ModelConfig{
+			{ModelName: "concurrent-model", Model: "openai/gpt-4o-1", apiKeys: []string{"key1"}},
+			{ModelName: "concurrent-model", Model: "openai/gpt-4o-2", apiKeys: []string{"key2"}},
 		},
 	}
 
@@ -113,39 +169,7 @@ func TestGetModelConfig_Concurrent(t *testing.T) {
 	}
 }
 
-func TestAgentDefaults_GetModelName_BackwardCompat(t *testing.T) {
-	tests := []struct {
-		name     string
-		defaults AgentDefaults
-		wantName string
-	}{
-		{
-			name:     "new model_name field only",
-			defaults: AgentDefaults{ModelName: "new-model"},
-			wantName: "new-model",
-		},
-		{
-			name:     "old model field only",
-			defaults: AgentDefaults{Model: "legacy-model"},
-			wantName: "legacy-model",
-		},
-		{
-			name:     "both fields - model_name takes precedence",
-			defaults: AgentDefaults{ModelName: "new-model", Model: "old-model"},
-			wantName: "new-model",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			if got := tt.defaults.GetModelName(); got != tt.wantName {
-				t.Errorf("GetModelName() = %q, want %q", got, tt.wantName)
-			}
-		})
-	}
-}
-
-func TestAgentDefaults_JSON_BackwardCompat(t *testing.T) {
+func TestAgentDefaultsV0_JSON_BackwardCompat(t *testing.T) {
 	tests := []struct {
 		name     string
 		json     string
@@ -170,7 +194,7 @@ func TestAgentDefaults_JSON_BackwardCompat(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			var defaults AgentDefaults
+			var defaults agentDefaultsV0
 			if err := json.Unmarshal([]byte(tt.json), &defaults); err != nil {
 				t.Fatalf("Unmarshal error: %v", err)
 			}
@@ -181,69 +205,6 @@ func TestAgentDefaults_JSON_BackwardCompat(t *testing.T) {
 	}
 }
 
-func TestFullConfig_JSON_BackwardCompat(t *testing.T) {
-	// Test complete config with both old and new formats
-	oldFormat := `{
-		"agents": {
-			"defaults": {
-				"workspace": "~/.picoclaw/workspace",
-				"model": "gpt4",
-				"max_tokens": 4096
-			}
-		},
-		"model_list": [
-			{
-				"model_name": "gpt4",
-				"model": "openai/gpt-4o",
-				"api_key": "test-key"
-			}
-		]
-	}`
-
-	newFormat := `{
-		"agents": {
-			"defaults": {
-				"workspace": "~/.picoclaw/workspace",
-				"model_name": "gpt4",
-				"max_tokens": 4096
-			}
-		},
-		"model_list": [
-			{
-				"model_name": "gpt4",
-				"model": "openai/gpt-4o",
-				"api_key": "test-key"
-			}
-		]
-	}`
-
-	for name, jsonStr := range map[string]string{
-		"old format (model)":      oldFormat,
-		"new format (model_name)": newFormat,
-	} {
-		t.Run(name, func(t *testing.T) {
-			cfg := &Config{}
-			if err := json.Unmarshal([]byte(jsonStr), cfg); err != nil {
-				t.Fatalf("Unmarshal error: %v", err)
-			}
-
-			// Check that GetModelName returns correct value
-			if got := cfg.Agents.Defaults.GetModelName(); got != "gpt4" {
-				t.Errorf("GetModelName() = %q, want %q", got, "gpt4")
-			}
-
-			// Check that GetModelConfig works
-			modelCfg, err := cfg.GetModelConfig("gpt4")
-			if err != nil {
-				t.Fatalf("GetModelConfig error: %v", err)
-			}
-			if modelCfg.Model != "openai/gpt-4o" {
-				t.Errorf("Model = %q, want %q", modelCfg.Model, "openai/gpt-4o")
-			}
-		})
-	}
-}
-
 func TestModelConfig_Validate(t *testing.T) {
 	tests := []struct {
 		name    string
@@ -299,7 +260,7 @@ func TestConfig_ValidateModelList(t *testing.T) {
 		{
 			name: "valid list",
 			config: &Config{
-				ModelList: []ModelConfig{
+				ModelList: []*ModelConfig{
 					{ModelName: "test1", Model: "openai/gpt-4o"},
 					{ModelName: "test2", Model: "anthropic/claude"},
 				},
@@ -309,7 +270,7 @@ func TestConfig_ValidateModelList(t *testing.T) {
 		{
 			name: "invalid entry",
 			config: &Config{
-				ModelList: []ModelConfig{
+				ModelList: []*ModelConfig{
 					{ModelName: "test1", Model: "openai/gpt-4o"},
 					{ModelName: "", Model: "anthropic/claude"}, // missing model_name
 				},
@@ -320,7 +281,7 @@ func TestConfig_ValidateModelList(t *testing.T) {
 		{
 			name: "empty list",
 			config: &Config{
-				ModelList: []ModelConfig{},
+				ModelList: []*ModelConfig{},
 			},
 			wantErr: false,
 		},
@@ -328,10 +289,7 @@ func TestConfig_ValidateModelList(t *testing.T) {
 			// Load balancing: multiple entries with same model_name are allowed
 			name: "duplicate model_name for load balancing",
 			config: &Config{
-				ModelList: []ModelConfig{
-					{ModelName: "gpt-4", Model: "openai/gpt-4o", APIKey: "key1"},
-					{ModelName: "gpt-4", Model: "openai/gpt-4-turbo", APIKey: "key2"},
-				},
+				ModelList: []*ModelConfig{},
 			},
 			wantErr: false, // Changed: duplicates are allowed for load balancing
 		},
@@ -339,7 +297,7 @@ func TestConfig_ValidateModelList(t *testing.T) {
 			// Load balancing: non-adjacent entries with same model_name are also allowed
 			name: "duplicate model_name non-adjacent for load balancing",
 			config: &Config{
-				ModelList: []ModelConfig{
+				ModelList: []*ModelConfig{
 					{ModelName: "model-a", Model: "openai/gpt-4o"},
 					{ModelName: "model-b", Model: "anthropic/claude"},
 					{ModelName: "model-a", Model: "openai/gpt-4-turbo"},
diff --git a/pkg/config/multikey_test.go b/pkg/config/multikey_test.go
new file mode 100644
index 000000000..c17fcc53b
--- /dev/null
+++ b/pkg/config/multikey_test.go
@@ -0,0 +1,359 @@
+package config
+
+import (
+	"testing"
+)
+
+func TestExpandMultiKeyModels_SingleKey(t *testing.T) {
+	models := []*ModelConfig{
+		{
+			ModelName: "gpt-4",
+			Model:     "openai/gpt-4o",
+			apiKeys:   []string{"single-key"},
+		},
+	}
+
+	result := expandMultiKeyModels(models)
+
+	if len(result) != 1 {
+		t.Fatalf("expected 1 model, got %d", len(result))
+	}
+
+	if result[0].ModelName != "gpt-4" {
+		t.Errorf("expected model_name 'gpt-4', got %q", result[0].ModelName)
+	}
+
+	if result[0].APIKey() != "single-key" {
+		t.Errorf("expected api_key 'single-key', got %q", result[0].APIKey())
+	}
+
+	if len(result[0].Fallbacks) != 0 {
+		t.Errorf("expected no fallbacks, got %v", result[0].Fallbacks)
+	}
+}
+
+func TestExpandMultiKeyModels_APIKeysOnly(t *testing.T) {
+	models := []*ModelConfig{
+		{
+			ModelName: "glm-4.7",
+			Model:     "zhipu/glm-4.7",
+			APIBase:   "https://api.example.com",
+			apiKeys:   []string{"key1", "key2", "key3"},
+		},
+	}
+
+	result := expandMultiKeyModels(models)
+
+	// Should expand to 3 models
+	if len(result) != 3 {
+		t.Fatalf("expected 3 models, got %d", len(result))
+	}
+
+	// First entry should be the primary with key1 and fallbacks
+	primary := result[2] // Primary is added last
+	if primary.ModelName != "glm-4.7" {
+		t.Errorf("expected primary model_name 'glm-4.7', got %q", primary.ModelName)
+	}
+	if primary.APIKey() != "key1" {
+		t.Errorf("expected primary api_key 'key1', got %q", primary.APIKey())
+	}
+	if len(primary.Fallbacks) != 2 {
+		t.Errorf("expected 2 fallbacks, got %d", len(primary.Fallbacks))
+	}
+	if primary.Fallbacks[0] != "glm-4.7__key_1" {
+		t.Errorf("expected first fallback 'glm-4.7__key_1', got %q", primary.Fallbacks[0])
+	}
+	if primary.Fallbacks[1] != "glm-4.7__key_2" {
+		t.Errorf("expected second fallback 'glm-4.7__key_2', got %q", primary.Fallbacks[1])
+	}
+
+	// Second entry should be key2
+	second := result[0]
+	if second.ModelName != "glm-4.7__key_1" {
+		t.Errorf("expected second model_name 'glm-4.7__key_1', got %q", second.ModelName)
+	}
+	if second.APIKey() != "key2" {
+		t.Errorf("expected second api_key 'key2', got %q", second.APIKey())
+	}
+
+	// Third entry should be key3
+	third := result[1]
+	if third.ModelName != "glm-4.7__key_2" {
+		t.Errorf("expected third model_name 'glm-4.7__key_2', got %q", third.ModelName)
+	}
+	if third.APIKey() != "key3" {
+		t.Errorf("expected third api_key 'key3', got %q", third.APIKey())
+	}
+}
+
+func TestExpandMultiKeyModels_APIKeyAndAPIKeys(t *testing.T) {
+	models := []*ModelConfig{
+		{
+			ModelName: "gpt-4",
+			Model:     "openai/gpt-4o",
+			apiKeys:   []string{"key0", "key1", "key2"},
+		},
+	}
+
+	result := expandMultiKeyModels(models)
+
+	// Should expand to 3 models (key0 from APIKey + key1, key2 from APIKeys)
+	if len(result) != 3 {
+		t.Fatalf("expected 3 models, got %d", len(result))
+	}
+
+	// Primary should use key0
+	primary := result[2]
+	if primary.APIKey() != "key0" {
+		t.Errorf("expected primary api_key 'key0', got %q", primary.APIKey())
+	}
+	if len(primary.Fallbacks) != 2 {
+		t.Errorf("expected 2 fallbacks, got %d", len(primary.Fallbacks))
+	}
+}
+
+func TestExpandMultiKeyModels_WithExistingFallbacks(t *testing.T) {
+	modelCfg := &ModelConfig{
+		ModelName: "gpt-4",
+		Model:     "openai/gpt-4o",
+	}
+	modelCfg.apiKeys = []string{"key0", "key1"} // Use internal field for multi-key testing
+	modelCfg.Fallbacks = []string{"claude-3"}
+	models := []*ModelConfig{modelCfg}
+
+	result := expandMultiKeyModels(models)
+
+	primary := result[1]
+	// With 2 keys, we get 1 key fallback + 1 existing fallback = 2 total
+	if len(primary.Fallbacks) != 2 {
+		t.Fatalf("expected 2 fallbacks, got %d: %v", len(primary.Fallbacks), primary.Fallbacks)
+	}
+
+	// Key fallbacks should come first, then existing fallbacks
+	if primary.Fallbacks[0] != "gpt-4__key_1" {
+		t.Errorf("expected first fallback 'gpt-4__key_1', got %q", primary.Fallbacks[0])
+	}
+	if primary.Fallbacks[1] != "claude-3" {
+		t.Errorf("expected second fallback 'claude-3', got %q", primary.Fallbacks[1])
+	}
+}
+
+func TestExpandMultiKeyModels_EmptyAPIKeys(t *testing.T) {
+	models := []*ModelConfig{
+		{
+			ModelName: "gpt-4",
+			Model:     "openai/gpt-4o",
+			apiKeys:   []string{},
+		},
+	}
+
+	result := expandMultiKeyModels(models)
+
+	// Should keep as-is with no changes
+	if len(result) != 1 {
+		t.Fatalf("expected 1 model, got %d", len(result))
+	}
+
+	if result[0].ModelName != "gpt-4" {
+		t.Errorf("expected model_name 'gpt-4', got %q", result[0].ModelName)
+	}
+}
+
+func TestExpandMultiKeyModels_Deduplication(t *testing.T) {
+	models := []*ModelConfig{
+		{
+			ModelName: "gpt-4",
+			Model:     "openai/gpt-4o",
+			apiKeys:   []string{"key1", "key2", "key1"}, // Duplicate key1
+		},
+	}
+
+	result := expandMultiKeyModels(models)
+
+	t.Logf("result: %#v", result)
+	// Should only create 2 models (deduplicated keys)
+	if len(result) != 2 {
+		t.Fatalf("expected 2 models (deduplicated), got %d", len(result))
+	}
+
+	primary := result[1]
+	if primary.APIKey() != "key1" {
+		t.Errorf("expected primary api_key 'key1', got %q", primary.APIKey())
+	}
+	if len(primary.Fallbacks) != 1 {
+		t.Errorf("expected 1 fallback, got %d", len(primary.Fallbacks))
+	}
+}
+
+func TestExpandMultiKeyModels_PreservesOtherFields(t *testing.T) {
+	modelCfg := &ModelConfig{
+		ModelName:      "gpt-4",
+		Model:          "openai/gpt-4o",
+		APIBase:        "https://api.example.com",
+		Proxy:          "http://proxy:8080",
+		RPM:            60,
+		MaxTokensField: "max_completion_tokens",
+		RequestTimeout: 30,
+		ThinkingLevel:  "high",
+	}
+	modelCfg.apiKeys = []string{"key0", "key1"} // Use internal field for multi-key testing
+	models := []*ModelConfig{modelCfg}
+
+	result := expandMultiKeyModels(models)
+
+	// Check primary entry preserves all fields
+	primary := result[1]
+	if primary.APIBase != "https://api.example.com" {
+		t.Errorf("expected api_base preserved, got %q", primary.APIBase)
+	}
+	if primary.Proxy != "http://proxy:8080" {
+		t.Errorf("expected proxy preserved, got %q", primary.Proxy)
+	}
+	if primary.RPM != 60 {
+		t.Errorf("expected rpm preserved, got %d", primary.RPM)
+	}
+	if primary.MaxTokensField != "max_completion_tokens" {
+		t.Errorf("expected max_tokens_field preserved, got %q", primary.MaxTokensField)
+	}
+	if primary.RequestTimeout != 30 {
+		t.Errorf("expected request_timeout preserved, got %d", primary.RequestTimeout)
+	}
+	if primary.ThinkingLevel != "high" {
+		t.Errorf("expected thinking_level preserved, got %q", primary.ThinkingLevel)
+	}
+
+	// Check additional entry also preserves fields
+	additional := result[0]
+	if additional.APIBase != "https://api.example.com" {
+		t.Errorf("expected additional api_base preserved, got %q", additional.APIBase)
+	}
+	if additional.RPM != 60 {
+		t.Errorf("expected additional rpm preserved, got %d", additional.RPM)
+	}
+}
+
+func TestExpandMultiKeyModels_IsVirtualFlag(t *testing.T) {
+	models := []*ModelConfig{
+		{
+			ModelName: "gpt-4",
+			Model:     "openai/gpt-4o",
+			apiKeys:   []string{"key1", "key2", "key3"},
+		},
+	}
+
+	result := expandMultiKeyModels(models)
+
+	// Should expand to 3 models
+	if len(result) != 3 {
+		t.Fatalf("expected 3 models, got %d", len(result))
+	}
+
+	// Primary model should NOT be virtual
+	primary := result[2]
+	if primary.isVirtual {
+		t.Errorf("primary model should not be virtual")
+	}
+	if primary.ModelName != "gpt-4" {
+		t.Errorf("expected primary model_name 'gpt-4', got %q", primary.ModelName)
+	}
+
+	// Virtual models should have isVirtual = true
+	virtual1 := result[0]
+	if !virtual1.isVirtual {
+		t.Errorf("gpt-4__key_1 should be virtual")
+	}
+	if virtual1.ModelName != "gpt-4__key_1" {
+		t.Errorf("expected virtual model_name 'gpt-4__key_1', got %q", virtual1.ModelName)
+	}
+
+	virtual2 := result[1]
+	if !virtual2.isVirtual {
+		t.Errorf("gpt-4__key_2 should be virtual")
+	}
+	if virtual2.ModelName != "gpt-4__key_2" {
+		t.Errorf("expected virtual model_name 'gpt-4__key_2', got %q", virtual2.ModelName)
+	}
+
+	// IsVirtual() method should work
+	if !virtual1.IsVirtual() {
+		t.Errorf("IsVirtual() should return true for virtual model")
+	}
+	if primary.IsVirtual() {
+		t.Errorf("IsVirtual() should return false for primary model")
+	}
+}
+
+func TestExpandMultiKeyModels_SingleKey_NotVirtual(t *testing.T) {
+	models := []*ModelConfig{
+		{
+			ModelName: "gpt-4",
+			Model:     "openai/gpt-4o",
+			apiKeys:   []string{"single-key"},
+		},
+	}
+
+	result := expandMultiKeyModels(models)
+
+	if len(result) != 1 {
+		t.Fatalf("expected 1 model, got %d", len(result))
+	}
+
+	// Single key model should NOT be virtual
+	if result[0].isVirtual {
+		t.Errorf("single key model should not be virtual")
+	}
+}
+
+func TestMergeAPIKeys(t *testing.T) {
+	tests := []struct {
+		name     string
+		apiKey   string
+		apiKeys  []string
+		expected []string
+	}{
+		{
+			name:     "both empty",
+			apiKey:   "",
+			apiKeys:  nil,
+			expected: nil,
+		},
+		{
+			name:     "only ApiKey",
+			apiKey:   "key1",
+			apiKeys:  nil,
+			expected: []string{"key1"},
+		},
+		{
+			name:     "only ApiKeys",
+			apiKey:   "",
+			apiKeys:  []string{"key1", "key2"},
+			expected: []string{"key1", "key2"},
+		},
+		{
+			name:     "both with overlap",
+			apiKey:   "key1",
+			apiKeys:  []string{"key1", "key2", "key3"},
+			expected: []string{"key1", "key2", "key3"},
+		},
+		{
+			name:     "with whitespace",
+			apiKey:   "  key1  ",
+			apiKeys:  []string{"  key2  ", "  key1  "},
+			expected: []string{"key1", "key2"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := MergeAPIKeys(tt.apiKey, tt.apiKeys)
+			if len(result) != len(tt.expected) {
+				t.Fatalf("expected %d keys, got %d", len(tt.expected), len(result))
+			}
+			for i, k := range result {
+				if k != tt.expected[i] {
+					t.Errorf("expected key[%d] = %q, got %q", i, tt.expected[i], k)
+				}
+			}
+		})
+	}
+}
diff --git a/pkg/config/security.go b/pkg/config/security.go
new file mode 100644
index 000000000..47ad1a5b0
--- /dev/null
+++ b/pkg/config/security.go
@@ -0,0 +1,446 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package config
+
+import (
+	"bytes"
+	"fmt"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"sync"
+
+	"github.com/caarlos0/env/v11"
+	"github.com/tencent-connect/botgo/log"
+	"gopkg.in/yaml.v3"
+
+	"github.com/sipeed/picoclaw/pkg/fileutil"
+)
+
+const (
+	SecurityConfigFile = ".security.yml"
+)
+
+func normalizeSecurityConfig(sec *SecurityConfig) *SecurityConfig {
+	if sec == nil {
+		sec = &SecurityConfig{}
+	}
+	if sec.ModelList == nil {
+		sec.ModelList = map[string]ModelSecurityEntry{}
+	}
+	if sec.Channels == nil {
+		sec.Channels = &ChannelsSecurity{}
+	}
+	if sec.Web == nil {
+		sec.Web = &WebToolsSecurity{}
+	}
+	if sec.Skills == nil {
+		sec.Skills = &SkillsSecurity{}
+	}
+	return sec
+}
+
+// SecurityConfig stores all sensitive data (API keys, tokens, secrets, passwords)
+// This data is loaded from security.yml and kept separate from the main config
+type SecurityConfig struct {
+	// Model API keys. Map key is model_name, can include suffix like "abc:0", "abc:1"
+	// for load balancing with same model_name. The suffix ":N" is used to distinguish
+	// multiple configs that share the same base model_name.
+	ModelList map[string]ModelSecurityEntry `yaml:"model_list"`
+
+	// Channel tokens/secrets
+	Channels *ChannelsSecurity `yaml:"channels,omitempty"`
+
+	Web    *WebToolsSecurity `yaml:"web,omitempty"`
+	Skills *SkillsSecurity   `yaml:"skills,omitempty"`
+
+	// cache for sensitive values and compiled regex (computed once)
+	sensitiveCache *SensitiveDataCache
+}
+
+// ModelSecurityEntry stores security data for a model
+type ModelSecurityEntry struct {
+	APIKeys []string `yaml:"api_keys,omitempty"` // API authentication keys (multiple keys for failover)
+}
+
+// ChannelsSecurity stores channel-related security data
+type ChannelsSecurity struct {
+	Telegram *TelegramSecurity `yaml:"telegram,omitempty"`
+	Feishu   *FeishuSecurity   `yaml:"feishu,omitempty"`
+	Discord  *DiscordSecurity  `yaml:"discord,omitempty"`
+	Weixin   *WeixinSecurity   `yaml:"weixin,omitempty"`
+	QQ       *QQSecurity       `yaml:"qq,omitempty"`
+	DingTalk *DingTalkSecurity `yaml:"dingtalk,omitempty"`
+	Slack    *SlackSecurity    `yaml:"slack,omitempty"`
+	Matrix   *MatrixSecurity   `yaml:"matrix,omitempty"`
+	LINE     *LINESecurity     `yaml:"line,omitempty"`
+	OneBot   *OneBotSecurity   `yaml:"onebot,omitempty"`
+	WeCom    *WeComSecurity    `yaml:"wecom,omitempty"`
+	Pico     *PicoSecurity     `yaml:"pico,omitempty"`
+	IRC      *IRCSecurity      `yaml:"irc,omitempty"`
+}
+
+type TelegramSecurity struct {
+	Token string `yaml:"token,omitempty" env:"PICOCLAW_CHANNELS_TELEGRAM_TOKEN"`
+}
+
+type FeishuSecurity struct {
+	AppSecret         string `yaml:"app_secret,omitempty"         env:"PICOCLAW_CHANNELS_FEISHU_APP_SECRET"`
+	EncryptKey        string `yaml:"encrypt_key,omitempty"        env:"PICOCLAW_CHANNELS_FEISHU_ENCRYPT_KEY"`
+	VerificationToken string `yaml:"verification_token,omitempty" env:"PICOCLAW_CHANNELS_FEISHU_VERIFICATION_TOKEN"`
+}
+
+type DiscordSecurity struct {
+	Token string `yaml:"token,omitempty" env:"PICOCLAW_CHANNELS_DISCORD_TOKEN"`
+}
+
+type WeixinSecurity struct {
+	Token string `yaml:"token,omitempty" env:"PICOCLAW_CHANNELS_WEIXIN_TOKEN"`
+}
+
+type QQSecurity struct {
+	AppSecret string `yaml:"app_secret,omitempty" env:"PICOCLAW_CHANNELS_QQ_APP_SECRET"`
+}
+
+type DingTalkSecurity struct {
+	ClientSecret string `yaml:"client_secret,omitempty" env:"PICOCLAW_CHANNELS_DINGTALK_CLIENT_SECRET"`
+}
+
+type SlackSecurity struct {
+	BotToken string `yaml:"bot_token,omitempty" env:"PICOCLAW_CHANNELS_SLACK_BOT_TOKEN"`
+	AppToken string `yaml:"app_token,omitempty" env:"PICOCLAW_CHANNELS_SLACK_APP_TOKEN"`
+}
+
+type MatrixSecurity struct {
+	AccessToken string `yaml:"access_token,omitempty" env:"PICOCLAW_CHANNELS_MATRIX_ACCESS_TOKEN"`
+}
+
+type LINESecurity struct {
+	ChannelSecret      string `yaml:"channel_secret,omitempty"       env:"PICOCLAW_CHANNELS_LINE_CHANNEL_SECRET"`
+	ChannelAccessToken string `yaml:"channel_access_token,omitempty" env:"PICOCLAW_CHANNELS_LINE_CHANNEL_ACCESS_TOKEN"`
+}
+
+type OneBotSecurity struct {
+	AccessToken string `yaml:"access_token,omitempty" env:"PICOCLAW_CHANNELS_ONEBOT_ACCESS_TOKEN"`
+}
+
+type WeComSecurity struct {
+	Secret string `yaml:"secret,omitempty" env:"PICOCLAW_CHANNELS_WECOM_SECRET"`
+}
+
+type PicoSecurity struct {
+	Token string `yaml:"token,omitempty" env:"PICOCLAW_CHANNELS_PICO_TOKEN"`
+}
+
+type IRCSecurity struct {
+	Password         string `yaml:"password,omitempty"          env:"PICOCLAW_CHANNELS_IRC_PASSWORD"`
+	NickServPassword string `yaml:"nickserv_password,omitempty" env:"PICOCLAW_CHANNELS_IRC_NICKSERV_PASSWORD"`
+	SASLPassword     string `yaml:"sasl_password,omitempty"     env:"PICOCLAW_CHANNELS_IRC_SASL_PASSWORD"`
+}
+
+type WebToolsSecurity struct {
+	Brave       *BraveSecurity       `yaml:"brave,omitempty"`
+	Tavily      *TavilySecurity      `yaml:"tavily,omitempty"`
+	Perplexity  *PerplexitySecurity  `yaml:"perplexity,omitempty"`
+	GLMSearch   *GLMSearchSecurity   `yaml:"glm_search,omitempty"`
+	BaiduSearch *BaiduSearchSecurity `yaml:"baidu_search,omitempty"`
+}
+
+type BraveSecurity struct {
+	APIKeys []string `yaml:"api_keys,omitempty"`
+}
+
+type TavilySecurity struct {
+	APIKeys []string `yaml:"api_keys,omitempty"`
+}
+
+type PerplexitySecurity struct {
+	APIKeys []string `yaml:"api_keys,omitempty"`
+}
+
+type GLMSearchSecurity struct {
+	APIKey string `yaml:"api_key,omitempty"`
+}
+
+type BaiduSearchSecurity struct {
+	APIKey string `yaml:"api_key,omitempty" env:"PICOCLAW_TOOLS_WEB_BAIDU_API_KEY"`
+}
+
+type SkillsSecurity struct {
+	Github  *GithubSecurity  `yaml:"github,omitempty"`
+	ClawHub *ClawHubSecurity `yaml:"clawhub,omitempty"`
+}
+
+type GithubSecurity struct {
+	Token string `yaml:"token,omitempty"`
+}
+
+type ClawHubSecurity struct {
+	AuthToken string `yaml:"auth_token,omitempty"`
+}
+
+// securityPath returns the path to security.yml relative to the config file
+func securityPath(configPath string) string {
+	configDir := filepath.Dir(configPath)
+	return filepath.Join(configDir, SecurityConfigFile)
+}
+
+// loadSecurityConfig loads the security configuration from security.yml
+// Returns an empty SecurityConfig if the file doesn't exist
+func loadSecurityConfig(securityPath string) (*SecurityConfig, error) {
+	data, err := os.ReadFile(securityPath)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return normalizeSecurityConfig(nil), nil
+		}
+		return nil, fmt.Errorf("failed to read security config: %w", err)
+	}
+
+	var sec SecurityConfig
+	if err := yaml.Unmarshal(data, &sec); err != nil {
+		return nil, fmt.Errorf("failed to parse security config: %w", err)
+	}
+
+	// No need to validate model_name format here - both formats are supported:
+	// - "model-name:0" (with index for multiple entries)
+	// - "model-name" (without index for single entry or default to index 0)
+
+	if err := env.Parse(&sec); err != nil {
+		log.Errorf("failed to parse environment variables: %v", err)
+		return nil, err
+	}
+
+	return normalizeSecurityConfig(&sec), nil
+}
+
+// saveSecurityConfig saves the security configuration to security.yml
+func saveSecurityConfig(securityPath string, sec *SecurityConfig) error {
+	var buf bytes.Buffer
+	enc := yaml.NewEncoder(&buf)
+	enc.SetIndent(2)
+	err := enc.Encode(sec)
+	if err != nil {
+		return fmt.Errorf("failed to marshal security config: %w", err)
+	}
+	return fileutil.WriteFileAtomic(securityPath, buf.Bytes(), 0o600)
+}
+
+// mergeSecurityConfig merges two SecurityConfig instances, preferring non-empty values from 'newer'.
+// This is used during config migration to preserve existing security data while adding new entries.
+func mergeSecurityConfig(existing, newer *SecurityConfig) *SecurityConfig {
+	if existing == nil {
+		return normalizeSecurityConfig(newer)
+	}
+	if newer == nil {
+		return normalizeSecurityConfig(existing)
+	}
+
+	result := normalizeSecurityConfig(nil)
+
+	// Merge ModelList: prefer newer if it has keys, otherwise use existing
+	for k, v := range existing.ModelList {
+		result.ModelList[k] = v
+	}
+	for k, v := range newer.ModelList {
+		if len(v.APIKeys) > 0 {
+			result.ModelList[k] = v
+		}
+	}
+
+	// Merge Channels
+	if existing.Channels != nil {
+		result.Channels = existing.Channels
+	}
+	if newer.Channels != nil {
+		if result.Channels == nil {
+			result.Channels = &ChannelsSecurity{}
+		}
+		mergeChannelsSecurity(result.Channels, newer.Channels)
+	}
+
+	// Merge Web
+	if existing.Web != nil {
+		result.Web = existing.Web
+	}
+	if newer.Web != nil {
+		if result.Web == nil {
+			result.Web = &WebToolsSecurity{}
+		}
+		mergeWebToolsSecurity(result.Web, newer.Web)
+	}
+
+	// Merge Skills
+	if existing.Skills != nil {
+		result.Skills = existing.Skills
+	}
+	if newer.Skills != nil {
+		if result.Skills == nil {
+			result.Skills = &SkillsSecurity{}
+		}
+		mergeSkillsSecurity(result.Skills, newer.Skills)
+	}
+
+	return result
+}
+
+func mergeChannelsSecurity(dst, src *ChannelsSecurity) {
+	if src.Telegram != nil && src.Telegram.Token != "" {
+		dst.Telegram = src.Telegram
+	}
+	if src.Feishu != nil &&
+		(src.Feishu.AppSecret != "" || src.Feishu.EncryptKey != "" || src.Feishu.VerificationToken != "") {
+		dst.Feishu = src.Feishu
+	}
+	if src.Discord != nil && src.Discord.Token != "" {
+		dst.Discord = src.Discord
+	}
+	if src.Weixin != nil && src.Weixin.Token != "" {
+		dst.Weixin = src.Weixin
+	}
+	if src.QQ != nil && src.QQ.AppSecret != "" {
+		dst.QQ = src.QQ
+	}
+	if src.DingTalk != nil && src.DingTalk.ClientSecret != "" {
+		dst.DingTalk = src.DingTalk
+	}
+	if src.Slack != nil && (src.Slack.BotToken != "" || src.Slack.AppToken != "") {
+		dst.Slack = src.Slack
+	}
+	if src.Matrix != nil && src.Matrix.AccessToken != "" {
+		dst.Matrix = src.Matrix
+	}
+	if src.LINE != nil && (src.LINE.ChannelSecret != "" || src.LINE.ChannelAccessToken != "") {
+		dst.LINE = src.LINE
+	}
+	if src.OneBot != nil && src.OneBot.AccessToken != "" {
+		dst.OneBot = src.OneBot
+	}
+	if src.WeCom != nil && src.WeCom.Secret != "" {
+		dst.WeCom = src.WeCom
+	}
+	if src.Pico != nil && src.Pico.Token != "" {
+		dst.Pico = src.Pico
+	}
+	if src.IRC != nil && (src.IRC.Password != "" || src.IRC.NickServPassword != "" || src.IRC.SASLPassword != "") {
+		dst.IRC = src.IRC
+	}
+}
+
+func mergeWebToolsSecurity(dst, src *WebToolsSecurity) {
+	if src.Brave != nil && len(src.Brave.APIKeys) > 0 {
+		dst.Brave = src.Brave
+	}
+	if src.Tavily != nil && len(src.Tavily.APIKeys) > 0 {
+		dst.Tavily = src.Tavily
+	}
+	if src.Perplexity != nil && len(src.Perplexity.APIKeys) > 0 {
+		dst.Perplexity = src.Perplexity
+	}
+	if src.GLMSearch != nil && src.GLMSearch.APIKey != "" {
+		dst.GLMSearch = src.GLMSearch
+	}
+	if src.BaiduSearch != nil && src.BaiduSearch.APIKey != "" {
+		dst.BaiduSearch = src.BaiduSearch
+	}
+}
+
+func mergeSkillsSecurity(dst, src *SkillsSecurity) {
+	if src.Github != nil && src.Github.Token != "" {
+		dst.Github = src.Github
+	}
+	if src.ClawHub != nil && src.ClawHub.AuthToken != "" {
+		dst.ClawHub = src.ClawHub
+	}
+}
+
+// SensitiveDataCache caches the compiled regex for filtering sensitive data.
+// SensitiveDataCache caches the strings.Replacer for filtering sensitive data.
+// Computed once on first access via sync.Once.
+type SensitiveDataCache struct {
+	replacer *strings.Replacer
+	once     sync.Once
+}
+
+// SensitiveDataReplacer returns the strings.Replacer for filtering sensitive data.
+// It is computed once on first access via sync.Once.
+func (sec *SecurityConfig) SensitiveDataReplacer() *strings.Replacer {
+	sec.initSensitiveCache()
+	return sec.sensitiveCache.replacer
+}
+
+// initSensitiveCache initializes the sensitive data cache if not already done.
+func (sec *SecurityConfig) initSensitiveCache() {
+	if sec.sensitiveCache == nil {
+		sec.sensitiveCache = &SensitiveDataCache{}
+	}
+	sec.sensitiveCache.once.Do(func() {
+		values := sec.collectSensitiveValues()
+		if len(values) == 0 {
+			sec.sensitiveCache.replacer = strings.NewReplacer()
+			return
+		}
+
+		// Build old/new pairs for strings.Replacer
+		var pairs []string
+		for _, v := range values {
+			if len(v) > 3 {
+				pairs = append(pairs, v, "[FILTERED]")
+			}
+		}
+		if len(pairs) == 0 {
+			sec.sensitiveCache.replacer = strings.NewReplacer()
+			return
+		}
+		sec.sensitiveCache.replacer = strings.NewReplacer(pairs...)
+	})
+}
+
+// collectSensitiveValues collects all sensitive strings from SecurityConfig using reflection.
+func (sec *SecurityConfig) collectSensitiveValues() []string {
+	var values []string
+	collectSensitive(reflect.ValueOf(sec), &values)
+	return values
+}
+
+// collectSensitive recursively traverses the value and collects all non-empty string fields.
+func collectSensitive(v reflect.Value, values *[]string) {
+	// Dereference pointers/interfaces to get the underlying value
+	for v.Kind() == reflect.Ptr || v.Kind() == reflect.Interface {
+		if v.IsNil() {
+			return
+		}
+		v = v.Elem()
+	}
+
+	switch v.Kind() {
+	case reflect.Struct:
+		for i := 0; i < v.NumField(); i++ {
+			field := v.Field(i)
+			fieldType := v.Type().Field(i)
+			if !fieldType.IsExported() {
+				continue
+			}
+			collectSensitive(field, values)
+		}
+	case reflect.String:
+		if v.String() != "" {
+			*values = append(*values, v.String())
+		}
+	case reflect.Slice:
+		if v.Type().Elem().Kind() == reflect.String {
+			for i := 0; i < v.Len(); i++ {
+				if s := v.Index(i).String(); s != "" {
+					*values = append(*values, s)
+				}
+			}
+		}
+	case reflect.Map:
+		for _, key := range v.MapKeys() {
+			collectSensitive(v.MapIndex(key), values)
+		}
+	}
+}
diff --git a/pkg/config/security_integration_test.go b/pkg/config/security_integration_test.go
new file mode 100644
index 000000000..03990ce5b
--- /dev/null
+++ b/pkg/config/security_integration_test.go
@@ -0,0 +1,440 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package config
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Test JSON unmarshal of private fields
+func TestJSONUnmarshalPrivateFields(t *testing.T) {
+	type testStruct struct {
+		PublicField  string `json:"public"`
+		privateField string
+	}
+
+	data := `{"public": "pub", "privateField": "priv"}`
+	var s testStruct
+	if err := json.Unmarshal([]byte(data), &s); err != nil {
+		t.Fatalf("JSON unmarshal failed: %v", err)
+	}
+
+	t.Logf("PublicField: %s", s.PublicField)
+	t.Logf("privateField: %s", s.privateField)
+
+	if s.PublicField != "pub" {
+		t.Errorf("PublicField = %q, want 'pub'", s.PublicField)
+	}
+	if s.privateField != "" {
+		t.Errorf("privateField = %q, want empty because unexported fields are ignored", s.privateField)
+	}
+}
+
+func TestSecurityConfigIntegration(t *testing.T) {
+	t.Run("Full workflow with security references", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create config.json with references
+		configPath := filepath.Join(tmpDir, "config.json")
+		configContent := `{
+  "version": 1,
+  "model_list": [
+    {
+      "model_name": "test-model",
+      "model": "openai/test-model",
+      "api_base": "https://api.openai.com/v1",
+      "api_key": "ref:model_list.test-model.api_key"
+    }
+  ],
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "ref:channels.telegram.token"
+    }
+  },
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": true,
+        "api_key": "ref:web.brave.api_key"
+      }
+    },
+    "skills": {
+      "github": {
+        "token": "ref:skills.github.token"
+      }
+    }
+  }
+}`
+		err := os.WriteFile(configPath, []byte(configContent), 0o644)
+		require.NoError(t, err)
+
+		// Create .security.yml with actual values
+		securityPath := filepath.Join(tmpDir, SecurityConfigFile)
+		securityContent := `model_list:
+  test-model:
+    api_keys:
+      - "sk-test-api-key-12345"
+
+channels:
+  telegram:
+    token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
+
+web:
+  brave:
+    api_keys:
+      - "BSAbrave-api-key-67890"
+
+skills:
+  github:
+    token: "ghp_github-token-abc123"`
+		err = os.WriteFile(securityPath, []byte(securityContent), 0o600)
+		require.NoError(t, err)
+
+		// Load config and verify references are resolved
+		cfg, err := LoadConfig(configPath)
+		require.NoError(t, err)
+		require.NotNil(t, cfg)
+
+		// Verify model API key is resolved
+		assert.Equal(t, 1, len(cfg.ModelList))
+		assert.Equal(t, "test-model", cfg.ModelList[0].ModelName)
+		assert.Equal(t, "sk-test-api-key-12345", cfg.ModelList[0].apiKeys[0])
+
+		// Verify channel token is resolved
+		assert.Equal(t, "123456789:ABCdefGHIjklMNOpqrsTUVwxyz", cfg.Channels.Telegram.token)
+
+		// Verify web tool API key is resolved
+		assert.Equal(t, "BSAbrave-api-key-67890", cfg.Tools.Web.Brave.APIKey())
+
+		// Verify skills token is resolved
+		assert.Equal(t, "ghp_github-token-abc123", cfg.Tools.Skills.Github.token)
+	})
+}
+
+func TestSecurityConfigWithAPIKeysArray(t *testing.T) {
+	t.Run("Multiple API keys via security", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create config with APIKeys array
+		configPath := filepath.Join(tmpDir, "config.json")
+		configContent := `{
+  "version": 1,
+  "model_list": [
+    {
+      "model_name": "multi-key-model",
+      "model": "openai/multi-key-model"
+    }
+  ]
+}`
+		err := os.WriteFile(configPath, []byte(configContent), 0o644)
+		require.NoError(t, err)
+
+		// Create .security.yml
+		securityPath := filepath.Join(tmpDir, SecurityConfigFile)
+		securityContent := `model_list:
+  multi-key-model:0:
+    api_key: "sk-key-1"
+    api_keys:
+      - "sk-key-1"
+      - "sk-key-2"
+      - "sk-key-3"
+`
+		err = os.WriteFile(securityPath, []byte(securityContent), 0o600)
+		require.NoError(t, err)
+
+		// Load config
+		cfg, err := LoadConfig(configPath)
+		require.NoError(t, err)
+
+		t.Logf("Config: %+v", cfg.ModelList)
+		for _, m := range cfg.ModelList {
+			t.Logf("Model: %+v", m)
+		}
+		// Verify multi-key expansion works
+		assert.Equal(t, 3, len(cfg.ModelList))
+		assert.Equal(t, "multi-key-model", cfg.ModelList[2].ModelName)
+	})
+}
+
+func TestAllSecurityKeysAccessible(t *testing.T) {
+	t.Run("All security keys accessible via Key() methods including file://", func(t *testing.T) {
+		tmpDir := t.TempDir()
+
+		// Create test files for file:// references
+		modelAPIKeyFile := filepath.Join(tmpDir, "model_api_key.txt")
+		err := os.WriteFile(modelAPIKeyFile, []byte("sk-model-from-file-12345"), 0o600)
+		require.NoError(t, err)
+
+		braveAPIKeyFile := filepath.Join(tmpDir, "brave_api_key.txt")
+		err = os.WriteFile(braveAPIKeyFile, []byte("BSA-brave-from-file-67890"), 0o600)
+		require.NoError(t, err)
+
+		tavilyAPIKeyFile := filepath.Join(tmpDir, "tavily_api_key.txt")
+		err = os.WriteFile(tavilyAPIKeyFile, []byte("tvly-tavily-from-file-11111"), 0o600)
+		require.NoError(t, err)
+
+		perplexityAPIKeyFile := filepath.Join(tmpDir, "perplexity_api_key.txt")
+		err = os.WriteFile(perplexityAPIKeyFile, []byte("pplx-perplexity-from-file-22222"), 0o600)
+		require.NoError(t, err)
+
+		githubTokenFile := filepath.Join(tmpDir, "github_token.txt")
+		err = os.WriteFile(githubTokenFile, []byte("ghp-github-from-file-abc123"), 0o600)
+		require.NoError(t, err)
+
+		clawhubAuthTokenFile := filepath.Join(tmpDir, "clawhub_auth_token.txt")
+		err = os.WriteFile(clawhubAuthTokenFile, []byte("clawhub-auth-token-from-file"), 0o600)
+		require.NoError(t, err)
+
+		// Create config.json without sensitive values (they'll be in .security.yml)
+		configPath := filepath.Join(tmpDir, "config.json")
+		configContent := `{
+  "version": 1,
+  "model_list": [
+    {
+      "model_name": "test-model-1",
+      "model": "openai/test-model-1"
+    }
+  ],
+  "channels": {
+    "telegram": {
+      "enabled": true
+    },
+    "feishu": {
+      "enabled": true,
+      "app_id": "test_app_id"
+    },
+    "discord": {
+      "enabled": true
+    },
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "test_client_id"
+    },
+    "slack": {
+      "enabled": true
+    },
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@test:matrix.org"
+    },
+    "line": {
+      "enabled": true,
+      "webhook_host": "localhost",
+      "webhook_port": 8080,
+      "webhook_path": "/webhook"
+    },
+    "onebot": {
+      "enabled": true,
+      "ws_url": "ws://localhost:8080"
+    },
+    "wecom": {
+      "enabled": true,
+      "bot_id": "test_wecom_bot_id"
+    },
+    "pico": {
+      "enabled": true
+    },
+    "irc": {
+      "enabled": true,
+      "server": "irc.example.com",
+      "nick": "testbot"
+    },
+    "qq": {
+      "enabled": true,
+      "app_id": "test_qq_app_id"
+    }
+  },
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": true
+      },
+      "tavily": {
+        "enabled": true
+      },
+      "perplexity": {
+        "enabled": true
+      },
+      "glm_search": {
+        "enabled": true
+      }
+    },
+    "skills": {
+      "github": {}
+    }
+  }
+}`
+		err = os.WriteFile(configPath, []byte(configContent), 0o644)
+		require.NoError(t, err)
+
+		// Create .security.yml with file:// references and plaintext values
+		securityPath := filepath.Join(tmpDir, SecurityConfigFile)
+		securityContent := `model_list:
+  test-model-1:
+    api_keys:
+      - "file://model_api_key.txt"
+
+channels:
+  telegram:
+    token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
+  feishu:
+    app_secret: "feishu_test_app_secret"
+    encrypt_key: "feishu_test_encrypt_key"
+    verification_token: "feishu_test_verification_token"
+  discord:
+    token: "discord_test_bot_token_xyz"
+  dingtalk:
+    client_secret: "dingtalk_test_client_secret"
+  slack:
+    bot_token: "xoxb-slack-bot-token-123"
+    app_token: "xapp-slack-app-token-456"
+  matrix:
+    access_token: "matrix_test_access_token"
+  line:
+    channel_secret: "line_test_channel_secret"
+    channel_access_token: "line_test_channel_access_token"
+  onebot:
+    access_token: "onebot_test_access_token"
+  wecom:
+    secret: "wecom_test_secret"
+  pico:
+    token: "pico_test_token"
+  irc:
+    password: "irc_test_password"
+    nickserv_password: "irc_test_nickserv_password"
+    sasl_password: "irc_test_sasl_password"
+  qq:
+    app_secret: "qq_test_app_secret"
+
+web:
+  brave:
+    api_keys:
+      - "file://brave_api_key.txt"
+  tavily:
+    api_keys:
+      - "file://tavily_api_key.txt"
+  perplexity:
+    api_keys:
+      - "file://perplexity_api_key.txt"
+  glm_search:
+    api_key: "glm-test-glm-search-key"
+
+skills:
+  github:
+    token: "file://github_token.txt"
+  clawhub:
+    auth_token: "file://clawhub_auth_token.txt"
+`
+		err = os.WriteFile(securityPath, []byte(securityContent), 0o600)
+		require.NoError(t, err)
+
+		// Load config and verify all security keys are accessible
+		cfg, err := LoadConfig(configPath)
+		require.NoError(t, err)
+		require.NotNil(t, cfg)
+
+		// Verify Model API keys
+		assert.Equal(t, 1, len(cfg.ModelList))
+		assert.Equal(t, "test-model-1", cfg.ModelList[0].ModelName)
+		// file:// reference should be resolved
+		assert.Equal(t, "sk-model-from-file-12345", cfg.ModelList[0].APIKey())
+		t.Logf("Model APIKey(): %s", cfg.ModelList[0].APIKey())
+
+		// Verify Channel tokens via Key() methods
+		// Telegram
+		assert.Equal(t, "123456789:ABCdefGHIjklMNOpqrsTUVwxyz", cfg.Channels.Telegram.Token())
+		t.Logf("Telegram Token(): %s", cfg.Channels.Telegram.Token())
+
+		// Feishu
+		assert.Equal(t, "feishu_test_app_secret", cfg.Channels.Feishu.AppSecret())
+		assert.Equal(t, "feishu_test_encrypt_key", cfg.Channels.Feishu.EncryptKey())
+		assert.Equal(t, "feishu_test_verification_token", cfg.Channels.Feishu.VerificationToken())
+		t.Logf("Feishu AppSecret(): %s", cfg.Channels.Feishu.AppSecret())
+		t.Logf("Feishu EncryptKey(): %s", cfg.Channels.Feishu.EncryptKey())
+		t.Logf("Feishu VerificationToken(): %s", cfg.Channels.Feishu.VerificationToken())
+
+		// Discord
+		assert.Equal(t, "discord_test_bot_token_xyz", cfg.Channels.Discord.Token())
+		t.Logf("Discord Token(): %s", cfg.Channels.Discord.Token())
+
+		// DingTalk
+		assert.Equal(t, "dingtalk_test_client_secret", cfg.Channels.DingTalk.ClientSecret())
+		t.Logf("DingTalk ClientSecret(): %s", cfg.Channels.DingTalk.ClientSecret())
+
+		// Slack
+		assert.Equal(t, "xoxb-slack-bot-token-123", cfg.Channels.Slack.BotToken())
+		assert.Equal(t, "xapp-slack-app-token-456", cfg.Channels.Slack.AppToken())
+		t.Logf("Slack BotToken(): %s", cfg.Channels.Slack.BotToken())
+		t.Logf("Slack AppToken(): %s", cfg.Channels.Slack.AppToken())
+
+		// Matrix
+		assert.Equal(t, "matrix_test_access_token", cfg.Channels.Matrix.AccessToken())
+		t.Logf("Matrix AccessToken(): %s", cfg.Channels.Matrix.AccessToken())
+
+		// LINE
+		assert.Equal(t, "line_test_channel_secret", cfg.Channels.LINE.ChannelSecret())
+		assert.Equal(t, "line_test_channel_access_token", cfg.Channels.LINE.ChannelAccessToken())
+		t.Logf("LINE ChannelSecret(): %s", cfg.Channels.LINE.ChannelSecret())
+		t.Logf("LINE ChannelAccessToken(): %s", cfg.Channels.LINE.ChannelAccessToken())
+
+		// OneBot
+		assert.Equal(t, "onebot_test_access_token", cfg.Channels.OneBot.AccessToken())
+		t.Logf("OneBot AccessToken(): %s", cfg.Channels.OneBot.AccessToken())
+
+		// WeCom
+		assert.Equal(t, "test_wecom_bot_id", cfg.Channels.WeCom.BotID)
+		assert.Equal(t, "wecom_test_secret", cfg.Channels.WeCom.Secret())
+		t.Logf("WeCom BotID: %s", cfg.Channels.WeCom.BotID)
+		t.Logf("WeCom Secret(): %s", cfg.Channels.WeCom.Secret())
+
+		// Pico
+		assert.Equal(t, "pico_test_token", cfg.Channels.Pico.Token())
+		t.Logf("Pico Token(): %s", cfg.Channels.Pico.Token())
+
+		// IRC
+		assert.Equal(t, "irc_test_password", cfg.Channels.IRC.Password())
+		assert.Equal(t, "irc_test_nickserv_password", cfg.Channels.IRC.NickServPassword())
+		assert.Equal(t, "irc_test_sasl_password", cfg.Channels.IRC.SASLPassword())
+		t.Logf("IRC Password(): %s", cfg.Channels.IRC.Password())
+		t.Logf("IRC NickServPassword(): %s", cfg.Channels.IRC.NickServPassword())
+		t.Logf("IRC SASLPassword(): %s", cfg.Channels.IRC.SASLPassword())
+
+		// QQ
+		assert.Equal(t, "qq_test_app_secret", cfg.Channels.QQ.AppSecret())
+		t.Logf("QQ AppSecret(): %s", cfg.Channels.QQ.AppSecret())
+
+		// Verify Web tool API keys
+		assert.Equal(t, "BSA-brave-from-file-67890", cfg.Tools.Web.Brave.APIKey())
+		t.Logf("Brave APIKey(): %s", cfg.Tools.Web.Brave.APIKey())
+
+		assert.Equal(t, "tvly-tavily-from-file-11111", cfg.Tools.Web.Tavily.APIKey())
+		t.Logf("Tavily APIKey(): %s", cfg.Tools.Web.Tavily.APIKey())
+
+		assert.Equal(t, "pplx-perplexity-from-file-22222", cfg.Tools.Web.Perplexity.APIKey())
+		t.Logf("Perplexity APIKey(): %s", cfg.Tools.Web.Perplexity.APIKey())
+
+		// GLM Search - Note: GLM uses SetAPIKey (lowercase) internally
+		t.Logf("GLMSearch APIKey(): %s", cfg.Tools.Web.GLMSearch.APIKey())
+		assert.Equal(t, "glm-test-glm-search-key", cfg.Tools.Web.GLMSearch.APIKey())
+
+		// Verify Skills tokens
+		assert.Equal(t, "ghp-github-from-file-abc123", cfg.Tools.Skills.Github.Token())
+		t.Logf("Github Token(): %s", cfg.Tools.Skills.Github.Token())
+
+		assert.Equal(t, "clawhub-auth-token-from-file", cfg.Tools.Skills.Registries.ClawHub.AuthToken())
+		t.Logf("ClawHub AuthToken(): %s", cfg.Tools.Skills.Registries.ClawHub.AuthToken())
+
+		t.Log("All security keys are successfully accessible via their respective Key() methods")
+	})
+}
diff --git a/pkg/config/security_test.go b/pkg/config/security_test.go
new file mode 100644
index 000000000..0f260ed59
--- /dev/null
+++ b/pkg/config/security_test.go
@@ -0,0 +1,93 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package config
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestSecurityConfig(t *testing.T) {
+	t.Run("LoadNonExistent", func(t *testing.T) {
+		sec, err := loadSecurityConfig("/nonexistent/.security.yml")
+		require.NoError(t, err)
+		assert.NotNil(t, sec)
+		assert.Empty(t, sec.ModelList)
+		assert.NotNil(t, sec.Channels)
+		assert.NotNil(t, sec.Web)
+		assert.NotNil(t, sec.Skills)
+	})
+}
+
+func TestSecurityPath(t *testing.T) {
+	tests := []struct {
+		name      string
+		configDir string
+		want      string
+	}{
+		{
+			name:      "standard path",
+			configDir: "/home/user/.picoclaw/config.json",
+			want:      "/home/user/.picoclaw/.security.yml",
+		},
+		{
+			name:      "nested path",
+			configDir: "/path/to/config/myconfig.json",
+			want:      "/path/to/config/.security.yml",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := securityPath(tt.configDir)
+			assert.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestSaveAndLoadSecurityConfig(t *testing.T) {
+	tmpDir := t.TempDir()
+	secPath := filepath.Join(tmpDir, SecurityConfigFile)
+
+	original := &SecurityConfig{
+		ModelList: map[string]ModelSecurityEntry{
+			"model1:0": {
+				APIKeys: []string{"key1", "key2"},
+			},
+		},
+		Channels: &ChannelsSecurity{
+			Telegram: &TelegramSecurity{
+				Token: "telegram-token",
+			},
+		},
+		Web: &WebToolsSecurity{
+			Brave: &BraveSecurity{
+				APIKeys: []string{"brave-api-key"},
+			},
+		},
+	}
+
+	// Save
+	err := saveSecurityConfig(secPath, original)
+	require.NoError(t, err)
+
+	// Verify file was created with correct permissions
+	info, err := os.Stat(secPath)
+	require.NoError(t, err)
+	assert.Equal(t, os.FileMode(0o600), info.Mode())
+
+	// Load
+	loaded, err := loadSecurityConfig(secPath)
+	require.NoError(t, err)
+
+	assert.Equal(t, original.ModelList, loaded.ModelList)
+	assert.Equal(t, original.Channels.Telegram.Token, loaded.Channels.Telegram.Token)
+	assert.EqualValues(t, original.Web.Brave.APIKeys, loaded.Web.Brave.APIKeys)
+}
diff --git a/pkg/config/version.go b/pkg/config/version.go
new file mode 100644
index 000000000..b65d3cf33
--- /dev/null
+++ b/pkg/config/version.go
@@ -0,0 +1,44 @@
+package config
+
+import (
+	"fmt"
+	"runtime"
+)
+
+// Build-time variables injected via ldflags during build process.
+// These are set by the Makefile or .goreleaser.yaml using the -X flag:
+//
+//	-X github.com/sipeed/picoclaw/pkg/config.Version=<version>
+//	-X github.com/sipeed/picoclaw/pkg/config.GitCommit=<commit>
+//	-X github.com/sipeed/picoclaw/pkg/config.BuildTime=<timestamp>
+//	-X github.com/sipeed/picoclaw/pkg/config.GoVersion=<go-version>
+var (
+	Version   = "dev" // Default value when not built with ldflags
+	GitCommit string  // Git commit SHA (short)
+	BuildTime string  // Build timestamp in RFC3339 format
+	GoVersion string  // Go version used for building
+)
+
+// FormatVersion returns the version string with optional git commit
+func FormatVersion() string {
+	v := Version
+	if GitCommit != "" {
+		v += fmt.Sprintf(" (git: %s)", GitCommit)
+	}
+	return v
+}
+
+// FormatBuildInfo returns build time and go version info
+func FormatBuildInfo() (string, string) {
+	build := BuildTime
+	goVer := GoVersion
+	if goVer == "" {
+		goVer = runtime.Version()
+	}
+	return build, goVer
+}
+
+// GetVersion returns the version string
+func GetVersion() string {
+	return Version
+}
diff --git a/pkg/config/version_test.go b/pkg/config/version_test.go
new file mode 100644
index 000000000..34bc906ce
--- /dev/null
+++ b/pkg/config/version_test.go
@@ -0,0 +1,92 @@
+package config
+
+import (
+	"runtime"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestFormatVersion_NoGitCommit(t *testing.T) {
+	oldVersion, oldGit := Version, GitCommit
+	t.Cleanup(func() { Version, GitCommit = oldVersion, oldGit })
+
+	Version = "1.2.3"
+	GitCommit = ""
+
+	assert.Equal(t, "1.2.3", FormatVersion())
+}
+
+func TestFormatVersion_WithGitCommit(t *testing.T) {
+	oldVersion, oldGit := Version, GitCommit
+	t.Cleanup(func() { Version, GitCommit = oldVersion, oldGit })
+
+	Version = "1.2.3"
+	GitCommit = "abc123"
+
+	assert.Equal(t, "1.2.3 (git: abc123)", FormatVersion())
+}
+
+func TestFormatBuildInfo_UsesBuildTimeAndGoVersion_WhenSet(t *testing.T) {
+	oldBuildTime, oldGoVersion := BuildTime, GoVersion
+	t.Cleanup(func() { BuildTime, GoVersion = oldBuildTime, oldGoVersion })
+
+	BuildTime = "2026-02-20T00:00:00Z"
+	GoVersion = "go1.23.0"
+
+	build, goVer := FormatBuildInfo()
+
+	assert.Equal(t, BuildTime, build)
+	assert.Equal(t, GoVersion, goVer)
+}
+
+func TestFormatBuildInfo_EmptyBuildTime_ReturnsEmptyBuild(t *testing.T) {
+	oldBuildTime, oldGoVersion := BuildTime, GoVersion
+	t.Cleanup(func() { BuildTime, GoVersion = oldBuildTime, oldGoVersion })
+
+	BuildTime = ""
+	GoVersion = "go1.23.0"
+
+	build, goVer := FormatBuildInfo()
+
+	assert.Empty(t, build)
+	assert.Equal(t, GoVersion, goVer)
+}
+
+func TestFormatBuildInfo_EmptyGoVersion_FallsBackToRuntimeVersion(t *testing.T) {
+	oldBuildTime, oldGoVersion := BuildTime, GoVersion
+	t.Cleanup(func() { BuildTime, GoVersion = oldBuildTime, oldGoVersion })
+
+	BuildTime = "x"
+	GoVersion = ""
+
+	build, goVer := FormatBuildInfo()
+
+	assert.Equal(t, "x", build)
+	assert.Equal(t, runtime.Version(), goVer)
+}
+
+func TestGetVersion(t *testing.T) {
+	oldVersion := Version
+	t.Cleanup(func() { Version = oldVersion })
+
+	Version = "dev"
+	assert.Equal(t, "dev", GetVersion())
+}
+
+func TestGetVersion_Custom(t *testing.T) {
+	oldVersion := Version
+	t.Cleanup(func() { Version = oldVersion })
+
+	Version = "v1.0.0"
+	assert.Equal(t, "v1.0.0", GetVersion())
+}
+
+func TestVersion_DefaultIsDev(t *testing.T) {
+	// Reset to default values
+	oldVersion := Version
+	Version = "dev"
+	t.Cleanup(func() { Version = oldVersion })
+
+	assert.Equal(t, "dev", Version)
+}
diff --git a/pkg/credential/credential.go b/pkg/credential/credential.go
new file mode 100644
index 000000000..b65c19446
--- /dev/null
+++ b/pkg/credential/credential.go
@@ -0,0 +1,342 @@
+// Package credential resolves API credential values for model_list entries.
+//
+// An API key is a form of authorization credential. This package centralizes
+// how raw credential strings—plaintext or file references—are resolved into
+// their actual values, keeping that logic out of the config loader.
+//
+// Supported formats for the api_key field:
+//
+//   - Plaintext:   "sk-abc123"          → returned as-is
+//   - File ref:    "file://filename.key" → content read from configDir/filename.key
+//   - Encrypted:   "enc://<base64>"     → AES-256-GCM decrypt via PICOCLAW_KEY_PASSPHRASE
+//   - Empty:       ""                   → returned as-is (auth_method=oauth etc.)
+//
+// Encryption uses AES-256-GCM with HKDF-SHA256 key derivation (< 1ms, safe for embedded Linux).
+// An SSH private key is required for both encryption and decryption.
+// Key derivation:
+//
+//	HKDF-SHA256(ikm=HMAC-SHA256(SHA256(sshKeyBytes), passphrase), salt, info)
+//
+// SSH key path resolution priority:
+//
+//  1. sshKeyPath argument to Encrypt (explicit)
+//  2. PICOCLAW_SSH_KEY_PATH env var
+//  3. ~/.ssh/picoclaw_ed25519.key (os.UserHomeDir is cross-platform)
+package credential
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/hkdf"
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+// PassphraseEnvVar is the environment variable that holds the encryption passphrase.
+// Other packages (e.g. config) reference this constant to avoid duplicating the string.
+const PassphraseEnvVar = "PICOCLAW_KEY_PASSPHRASE"
+
+// PassphraseProvider is the function used to retrieve the passphrase for enc://
+// credential decryption. It defaults to reading PICOCLAW_KEY_PASSPHRASE from the
+// process environment. Replace it at startup to use a different source, such as
+// an in-memory SecureStore, so that all LoadConfig() calls everywhere share the
+// same passphrase source without needing os.Environ.
+//
+// Example (launcher main.go):
+//
+//	credential.PassphraseProvider = apiHandler.passphraseStore.Get
+var PassphraseProvider func() string = func() string {
+	return os.Getenv(PassphraseEnvVar)
+}
+
+// ErrPassphraseRequired is returned when an enc:// credential is encountered but
+// no passphrase is available from PassphraseProvider. Callers can detect this
+// with errors.Is to distinguish a missing-passphrase condition from other errors.
+var ErrPassphraseRequired = errors.New("credential: enc:// passphrase required")
+
+// ErrDecryptionFailed is returned when an enc:// credential cannot be decrypted,
+// indicating a wrong passphrase or SSH key. Callers can detect this with errors.Is.
+var ErrDecryptionFailed = errors.New("credential: enc:// decryption failed (wrong passphrase or SSH key?)")
+
+// SSHKeyPathEnvVar is the environment variable that specifies the path to the
+// SSH private key used for enc:// credential encryption and decryption.
+const SSHKeyPathEnvVar = "PICOCLAW_SSH_KEY_PATH"
+
+// picoclawHome is a package-local copy of config.EnvHome. It is kept here to
+// avoid a circular import between pkg/credential and pkg/config.
+const picoclawHome = "PICOCLAW_HOME"
+
+const (
+	fileScheme = "file://"
+	encScheme  = "enc://"
+	hkdfInfo   = "picoclaw-credential-v1"
+	saltLen    = 16
+	nonceLen   = 12
+	keyLen     = 32
+)
+
+// Resolver resolves raw credential strings for model_list api_key fields.
+// File references are resolved relative to the directory of the config file.
+type Resolver struct {
+	configDir         string
+	resolvedConfigDir string // symlink-resolved form of configDir
+}
+
+// NewResolver returns a Resolver that resolves file:// references relative to
+// configDir (typically filepath.Dir of the config file path).
+func NewResolver(configDir string) *Resolver {
+	resolved := configDir
+	if configDir != "" {
+		if linkedPath, err := filepath.EvalSymlinks(configDir); err == nil {
+			resolved = linkedPath
+		}
+	}
+	return &Resolver{configDir: configDir, resolvedConfigDir: resolved}
+}
+
+// Resolve returns the actual credential value for raw:
+//
+//   - ""                → "" (no error; auth_method=oauth needs no key)
+//   - "file://name.key" → trimmed content of configDir/name.key
+//   - anything else     → raw unchanged (plaintext credential)
+func (r *Resolver) Resolve(raw string) (string, error) {
+	if raw == "" {
+		return "", nil
+	}
+
+	if strings.HasPrefix(raw, fileScheme) {
+		fileName := strings.TrimSpace(strings.TrimPrefix(raw, fileScheme))
+		if fileName == "" {
+			return "", fmt.Errorf("credential: file:// reference has no filename")
+		}
+
+		baseDir := r.resolvedConfigDir
+		if baseDir == "" {
+			baseDir = r.configDir
+		}
+		keyPath := filepath.Join(baseDir, fileName)
+		// Resolve symlinks before enforcing containment to prevent escaping via symlinks.
+		realKeyPath, err := filepath.EvalSymlinks(keyPath)
+		if err != nil {
+			return "", fmt.Errorf("credential: failed to resolve credential file path %q: %w", keyPath, err)
+		}
+		if !isWithinDir(realKeyPath, baseDir) {
+			return "", fmt.Errorf("credential: file:// path escapes config directory")
+		}
+		data, err := os.ReadFile(realKeyPath)
+		if err != nil {
+			return "", fmt.Errorf("credential: failed to read credential file %q: %w", realKeyPath, err)
+		}
+
+		value := strings.TrimSpace(string(data))
+		if value == "" {
+			return "", fmt.Errorf("credential: credential file %q is empty", realKeyPath)
+		}
+
+		return value, nil
+	}
+
+	if strings.HasPrefix(raw, encScheme) {
+		return resolveEncrypted(raw)
+	}
+
+	// Plaintext credential — return unchanged.
+	return raw, nil
+}
+
+// resolveEncrypted decrypts an enc:// credential using PassphraseProvider.
+func resolveEncrypted(raw string) (string, error) {
+	passphrase := PassphraseProvider()
+	if passphrase == "" {
+		return "", ErrPassphraseRequired
+	}
+
+	sshKeyPath := pickSSHKeyPath("") // override="": consult env then auto-detect
+
+	b64 := strings.TrimPrefix(raw, encScheme)
+	blob, err := base64.StdEncoding.DecodeString(b64)
+	if err != nil {
+		return "", fmt.Errorf("credential: enc:// invalid base64: %w", err)
+	}
+	if len(blob) < saltLen+nonceLen+1 {
+		return "", fmt.Errorf("credential: enc:// payload too short")
+	}
+
+	salt := blob[:saltLen]
+	nonce := blob[saltLen : saltLen+nonceLen]
+	ciphertext := blob[saltLen+nonceLen:]
+
+	key, err := deriveKey(passphrase, sshKeyPath, salt)
+	if err != nil {
+		return "", err
+	}
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return "", fmt.Errorf("credential: enc:// cipher init: %w", err)
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", fmt.Errorf("credential: enc:// gcm init: %w", err)
+	}
+
+	plaintext, err := gcm.Open(nil, nonce, ciphertext, nil)
+	if err != nil {
+		return "", fmt.Errorf("%w: %w", ErrDecryptionFailed, err)
+	}
+	return string(plaintext), nil
+}
+
+// Encrypt encrypts plaintext and returns an enc:// credential string.
+//
+// passphrase is required (PICOCLAW_KEY_PASSPHRASE value).
+// sshKeyPath is the SSH private key file to use; pass "" to auto-detect via
+// PICOCLAW_SSH_KEY_PATH env var or ~/.ssh/picoclaw_ed25519.key.
+// An SSH private key must be resolvable or Encrypt returns an error.
+func Encrypt(passphrase, sshKeyPath, plaintext string) (string, error) {
+	if passphrase == "" {
+		return "", fmt.Errorf("credential: passphrase must not be empty")
+	}
+	sshKeyPath = pickSSHKeyPath(sshKeyPath)
+
+	salt := make([]byte, saltLen)
+	if _, err := io.ReadFull(rand.Reader, salt); err != nil {
+		return "", fmt.Errorf("credential: failed to generate salt: %w", err)
+	}
+
+	key, err := deriveKey(passphrase, sshKeyPath, salt)
+	if err != nil {
+		return "", err
+	}
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return "", fmt.Errorf("credential: cipher init: %w", err)
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", fmt.Errorf("credential: gcm init: %w", err)
+	}
+
+	nonce := make([]byte, nonceLen)
+	if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
+		return "", fmt.Errorf("credential: failed to generate nonce: %w", err)
+	}
+
+	ciphertext := gcm.Seal(nil, nonce, []byte(plaintext), nil)
+	blob := make([]byte, 0, saltLen+nonceLen+len(ciphertext))
+	blob = append(blob, salt...)
+	blob = append(blob, nonce...)
+	blob = append(blob, ciphertext...)
+	return encScheme + base64.StdEncoding.EncodeToString(blob), nil
+}
+
+// isWithinDir reports whether path is contained within (or equal to) dir.
+// Uses filepath.IsLocal on the relative path for robust cross-platform traversal detection.
+func isWithinDir(path, dir string) bool {
+	rel, err := filepath.Rel(filepath.Clean(dir), filepath.Clean(path))
+	return err == nil && filepath.IsLocal(rel)
+}
+
+// allowedSSHKeyPath reports whether path is in a permitted location for SSH key files:
+//   - exact match with PICOCLAW_SSH_KEY_PATH env var
+//   - within the PICOCLAW_HOME env var directory
+//   - within ~/.ssh/
+func allowedSSHKeyPath(path string) bool {
+	if path == "" {
+		return true // passphrase-only mode; no file will be read
+	}
+	clean := filepath.Clean(path)
+
+	// Exact match with PICOCLAW_SSH_KEY_PATH.
+	if envPath, ok := os.LookupEnv(SSHKeyPathEnvVar); ok && envPath != "" {
+		if clean == filepath.Clean(envPath) {
+			return true
+		}
+	}
+
+	// Within PICOCLAW_HOME.
+	if picoHome := os.Getenv(picoclawHome); picoHome != "" {
+		if isWithinDir(clean, picoHome) {
+			return true
+		}
+	}
+
+	// Within ~/.ssh/.
+	if userHome, err := os.UserHomeDir(); err == nil {
+		if isWithinDir(clean, filepath.Join(userHome, ".ssh")) {
+			return true
+		}
+	}
+
+	return false
+}
+
+// deriveKey derives a 32-byte AES-256 key from passphrase and SSH private key.
+//
+// ikm = HMAC-SHA256(key=SHA256(sshKeyBytes), msg=passphrase)
+// Final key: HKDF-SHA256(ikm, salt, info="picoclaw-credential-v1", 32 bytes)
+// sshKeyPath must be non-empty; returns an error otherwise.
+func deriveKey(passphrase, sshKeyPath string, salt []byte) ([]byte, error) {
+	if sshKeyPath == "" {
+		return nil, fmt.Errorf(
+			"credential: SSH private key is required but not found" +
+				" (set PICOCLAW_SSH_KEY_PATH or place key at ~/.ssh/picoclaw_ed25519.key)")
+	}
+	if !allowedSSHKeyPath(sshKeyPath) {
+		return nil, fmt.Errorf(
+			"credential: SSH key path %q is not in an allowed location (PICOCLAW_SSH_KEY_PATH, PICOCLAW_HOME, or ~/.ssh/)",
+			sshKeyPath,
+		)
+	}
+	sshBytes, err := os.ReadFile(sshKeyPath)
+	if err != nil {
+		return nil, fmt.Errorf("credential: cannot read SSH key %q: %w", sshKeyPath, err)
+	}
+	sshHash := sha256.Sum256(sshBytes)
+	mac := hmac.New(sha256.New, sshHash[:])
+	mac.Write([]byte(passphrase))
+	ikm := mac.Sum(nil)
+
+	key, err := hkdf.Key(sha256.New, ikm, salt, hkdfInfo, keyLen)
+	if err != nil {
+		return nil, fmt.Errorf("credential: HKDF expand failed: %w", err)
+	}
+	return key, nil
+}
+
+// pickSSHKeyPath returns the SSH private key path to use for encryption/decryption.
+//
+// Priority:
+//  1. override (non-empty explicit argument)
+//  2. PICOCLAW_SSH_KEY_PATH env var
+//  3. ~/.ssh/picoclaw_ed25519.key (auto-detection)
+//
+// Returns "" when no key is found; deriveKey will return an error in that case.
+func pickSSHKeyPath(override string) string {
+	if override != "" {
+		return override
+	}
+	if p, ok := os.LookupEnv(SSHKeyPathEnvVar); ok {
+		return p // respect explicit setting, even if ""
+	}
+	return findDefaultSSHKey()
+}
+
+// findDefaultSSHKey returns the picoclaw-specific SSH key path if it exists.
+func findDefaultSSHKey() string {
+	p, err := DefaultSSHKeyPath()
+	if err != nil {
+		return ""
+	}
+	if _, err := os.Stat(p); err == nil {
+		return p
+	}
+	return ""
+}
diff --git a/pkg/credential/credential_test.go b/pkg/credential/credential_test.go
new file mode 100644
index 000000000..138af3134
--- /dev/null
+++ b/pkg/credential/credential_test.go
@@ -0,0 +1,283 @@
+package credential_test
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/credential"
+)
+
+func TestResolve_PlainKey(t *testing.T) {
+	r := credential.NewResolver(t.TempDir())
+	got, err := r.Resolve("sk-plaintext-key")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "sk-plaintext-key" {
+		t.Fatalf("got %q, want %q", got, "sk-plaintext-key")
+	}
+}
+
+func TestResolve_FileKey_Success(t *testing.T) {
+	dir := t.TempDir()
+	keyFile := "openai_plain.key"
+	if err := os.WriteFile(filepath.Join(dir, keyFile), []byte("sk-from-file\n"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	r := credential.NewResolver(dir)
+	got, err := r.Resolve("file://" + keyFile)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "sk-from-file" {
+		t.Fatalf("got %q, want %q", got, "sk-from-file")
+	}
+}
+
+func TestResolve_FileKey_NotFound(t *testing.T) {
+	r := credential.NewResolver(t.TempDir())
+	_, err := r.Resolve("file://missing.key")
+	if err == nil {
+		t.Fatal("expected error for missing file, got nil")
+	}
+}
+
+func TestResolve_FileKey_Empty(t *testing.T) {
+	dir := t.TempDir()
+	keyFile := "empty.key"
+	if err := os.WriteFile(filepath.Join(dir, keyFile), []byte("   \n"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	r := credential.NewResolver(dir)
+	_, err := r.Resolve("file://" + keyFile)
+	if err == nil {
+		t.Fatal("expected error for empty credential file, got nil")
+	}
+}
+
+// TestResolve_EncKey_RoundTrip tests basic encryption/decryption round-trip with an SSH key.
+func TestResolve_EncKey_RoundTrip(t *testing.T) {
+	dir := t.TempDir()
+	sshKeyPath := filepath.Join(dir, "picoclaw_ed25519.key")
+	if err := os.WriteFile(sshKeyPath, []byte("fake-ssh-key-material\n"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	const passphrase = "test-passphrase-32bytes-long-ok!"
+	const plaintext = "sk-encrypted-secret"
+
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", sshKeyPath)
+
+	enc, err := credential.Encrypt(passphrase, "", plaintext)
+	if err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", passphrase)
+
+	r := credential.NewResolver(t.TempDir())
+	got, err := r.Resolve(enc)
+	if err != nil {
+		t.Fatalf("Resolve: %v", err)
+	}
+	if got != plaintext {
+		t.Fatalf("got %q, want %q", got, plaintext)
+	}
+}
+
+// TestResolve_EncKey_WithSSHKey tests that the SSH key file is incorporated into key derivation.
+func TestResolve_EncKey_WithSSHKey(t *testing.T) {
+	dir := t.TempDir()
+	sshKeyPath := filepath.Join(dir, "picoclaw_ed25519.key")
+	if err := os.WriteFile(sshKeyPath, []byte("fake-ssh-private-key-material\n"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	const passphrase = "test-passphrase"
+	const plaintext = "sk-ssh-protected-secret"
+
+	// Set PICOCLAW_SSH_KEY_PATH before Encrypt so the path passes allowedSSHKeyPath validation.
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", passphrase)
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", sshKeyPath)
+
+	enc, err := credential.Encrypt(passphrase, sshKeyPath, plaintext)
+	if err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	r := credential.NewResolver(t.TempDir())
+	got, err := r.Resolve(enc)
+	if err != nil {
+		t.Fatalf("Resolve: %v", err)
+	}
+	if got != plaintext {
+		t.Fatalf("got %q, want %q", got, plaintext)
+	}
+}
+
+func TestResolve_EncKey_NoPassphrase(t *testing.T) {
+	dir := t.TempDir()
+	sshKeyPath := filepath.Join(dir, "picoclaw_ed25519.key")
+	if err := os.WriteFile(sshKeyPath, []byte("fake-ssh-key\n"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", sshKeyPath)
+
+	enc, err := credential.Encrypt("some-passphrase", "", "sk-secret")
+	if err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "")
+
+	r := credential.NewResolver(t.TempDir())
+	_, err = r.Resolve(enc)
+	if err == nil {
+		t.Fatal("expected error when PICOCLAW_KEY_PASSPHRASE is unset, got nil")
+	}
+}
+
+func TestResolve_EncKey_BadCiphertext(t *testing.T) {
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "some-passphrase")
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", "")
+
+	r := credential.NewResolver(t.TempDir())
+	_, err := r.Resolve("enc://!!not-valid-base64!!")
+	if err == nil {
+		t.Fatal("expected error for invalid enc:// payload, got nil")
+	}
+}
+
+func TestResolve_EncKey_PayloadTooShort(t *testing.T) {
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "some-passphrase")
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", "")
+
+	// Valid base64 but fewer bytes than salt(16)+nonce(12)+1 minimum.
+	import64 := "dG9vc2hvcnQ=" // "tooshort" = 8 bytes
+	r := credential.NewResolver(t.TempDir())
+	_, err := r.Resolve("enc://" + import64)
+	if err == nil {
+		t.Fatal("expected error for too-short enc:// payload, got nil")
+	}
+}
+
+func TestResolve_EncKey_WrongPassphrase(t *testing.T) {
+	dir := t.TempDir()
+	sshKeyPath := filepath.Join(dir, "picoclaw_ed25519.key")
+	if err := os.WriteFile(sshKeyPath, []byte("fake-ssh-key\n"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", sshKeyPath)
+
+	enc, err := credential.Encrypt("correct-passphrase", "", "sk-secret")
+	if err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "wrong-passphrase")
+
+	r := credential.NewResolver(t.TempDir())
+	_, err = r.Resolve(enc)
+	if err == nil {
+		t.Fatal("expected decryption error for wrong passphrase, got nil")
+	}
+}
+
+func TestEncrypt_EmptyPassphrase(t *testing.T) {
+	_, err := credential.Encrypt("", "", "sk-secret")
+	if err == nil {
+		t.Fatal("expected error for empty passphrase, got nil")
+	}
+}
+
+func TestDeriveKey_SSHKeyNotFound(t *testing.T) {
+	// Encrypt with a real SSH key path, then try to decrypt with a missing path.
+	dir := t.TempDir()
+	sshKeyPath := filepath.Join(dir, "picoclaw_ed25519.key")
+	if err := os.WriteFile(sshKeyPath, []byte("fake-key\n"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	// Register the real key path so allowedSSHKeyPath validation passes for Encrypt.
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", sshKeyPath)
+
+	enc, err := credential.Encrypt("passphrase", sshKeyPath, "sk-secret")
+	if err != nil {
+		t.Fatalf("Encrypt: %v", err)
+	}
+
+	// Point to a non-existent SSH key so deriveKey's ReadFile fails.
+	// The path is still under the same dir, so allowedSSHKeyPath passes (exact env match).
+	t.Setenv("PICOCLAW_KEY_PASSPHRASE", "passphrase")
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", filepath.Join(dir, "nonexistent_key"))
+
+	r := credential.NewResolver(t.TempDir())
+	_, err = r.Resolve(enc)
+	if err == nil {
+		t.Fatal("expected error when SSH key file is missing, got nil")
+	}
+}
+
+// TestResolve_FileRef_PathTraversal verifies that file:// references cannot escape configDir
+// via relative traversal ("../../etc/passwd") or absolute paths ("/abs/path").
+func TestResolve_FileRef_PathTraversal(t *testing.T) {
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.json")
+	// Create a file outside configDir that the traversal would point to.
+	outsideFile := filepath.Join(t.TempDir(), "secret.key")
+	if err := os.WriteFile(outsideFile, []byte("stolen"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	r := credential.NewResolver(filepath.Dir(cfgPath))
+
+	cases := []string{
+		"file://../../secret.key",
+		"file://../secret.key",
+		"file://" + outsideFile, // absolute path
+	}
+	for _, raw := range cases {
+		_, err := r.Resolve(raw)
+		if err == nil {
+			t.Errorf("Resolve(%q): expected path traversal error, got nil", raw)
+		}
+	}
+}
+
+// TestResolve_FileRef_withinConfigDir verifies that a legitimate relative file:// ref works.
+func TestResolve_FileRef_withinConfigDir(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "my.key"), []byte("sk-valid\n"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+	r := credential.NewResolver(dir)
+	got, err := r.Resolve("file://my.key")
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if got != "sk-valid" {
+		t.Fatalf("got %q, want %q", got, "sk-valid")
+	}
+}
+
+// TestEncrypt_SSHKeyOutsideAllowedDirs verifies that Encrypt rejects SSH key paths
+// that are not under PICOCLAW_SSH_KEY_PATH, PICOCLAW_HOME, or ~/.ssh/.
+func TestEncrypt_SSHKeyOutsideAllowedDirs(t *testing.T) {
+	dir := t.TempDir()
+	sshKeyPath := filepath.Join(dir, "picoclaw_ed25519.key")
+	if err := os.WriteFile(sshKeyPath, []byte("fake-key\n"), 0o600); err != nil {
+		t.Fatalf("setup: %v", err)
+	}
+
+	// Make sure none of the allowed env vars point here.
+	t.Setenv("PICOCLAW_SSH_KEY_PATH", "")
+	t.Setenv("PICOCLAW_HOME", "")
+
+	_, err := credential.Encrypt("passphrase", sshKeyPath, "sk-secret")
+	if err == nil {
+		t.Fatal("expected error for SSH key outside allowed directories, got nil")
+	}
+}
diff --git a/pkg/credential/keygen.go b/pkg/credential/keygen.go
new file mode 100644
index 000000000..c57564a76
--- /dev/null
+++ b/pkg/credential/keygen.go
@@ -0,0 +1,62 @@
+package credential
+
+import (
+	"crypto/ed25519"
+	"crypto/rand"
+	"encoding/pem"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"golang.org/x/crypto/ssh"
+)
+
+// DefaultSSHKeyPath returns the canonical path for the picoclaw-specific SSH key.
+// The path is always ~/.ssh/picoclaw_ed25519.key (os.UserHomeDir is cross-platform).
+func DefaultSSHKeyPath() (string, error) {
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("credential: cannot determine home directory: %w", err)
+	}
+	return filepath.Join(home, ".ssh", "picoclaw_ed25519.key"), nil
+}
+
+// GenerateSSHKey generates an Ed25519 SSH key pair and writes the private key
+// to path (permissions 0600) and the public key to path+".pub" (permissions 0644).
+// The ~/.ssh/ directory is created with 0700 if it does not exist.
+// If the files already exist they are overwritten.
+func GenerateSSHKey(path string) error {
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return fmt.Errorf("credential: keygen: cannot create directory %q: %w", filepath.Dir(path), err)
+	}
+
+	pubRaw, privRaw, err := ed25519.GenerateKey(rand.Reader)
+	if err != nil {
+		return fmt.Errorf("credential: keygen: ed25519 key generation failed: %w", err)
+	}
+
+	// Marshal private key as OpenSSH PEM.
+	block, err := ssh.MarshalPrivateKey(privRaw, "")
+	if err != nil {
+		return fmt.Errorf("credential: keygen: marshal private key: %w", err)
+	}
+	privPEM := pem.EncodeToMemory(block)
+
+	if err = os.WriteFile(path, privPEM, 0o600); err != nil {
+		return fmt.Errorf("credential: keygen: write private key %q: %w", path, err)
+	}
+
+	// Marshal public key as authorized_keys line.
+	sshPub, err := ssh.NewPublicKey(pubRaw)
+	if err != nil {
+		return fmt.Errorf("credential: keygen: marshal public key: %w", err)
+	}
+	pubLine := ssh.MarshalAuthorizedKey(sshPub)
+
+	pubPath := path + ".pub"
+	if err := os.WriteFile(pubPath, pubLine, 0o644); err != nil {
+		return fmt.Errorf("credential: keygen: write public key %q: %w", pubPath, err)
+	}
+
+	return nil
+}
diff --git a/pkg/credential/keygen_test.go b/pkg/credential/keygen_test.go
new file mode 100644
index 000000000..1e21ea0b9
--- /dev/null
+++ b/pkg/credential/keygen_test.go
@@ -0,0 +1,115 @@
+package credential
+
+import (
+	"crypto/ed25519"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"golang.org/x/crypto/ssh"
+)
+
+func TestGenerateSSHKey_CreatesFiles(t *testing.T) {
+	dir := t.TempDir()
+	keyPath := filepath.Join(dir, "test_ed25519.key")
+
+	if err := GenerateSSHKey(keyPath); err != nil {
+		t.Fatalf("GenerateSSHKey() error = %v", err)
+	}
+
+	// Private key must exist.
+	privInfo, err := os.Stat(keyPath)
+	if err != nil {
+		t.Fatalf("private key file missing: %v", err)
+	}
+
+	// Check permissions on non-Windows (Windows does not support Unix permission bits).
+	if runtime.GOOS != "windows" {
+		if got := privInfo.Mode().Perm(); got != 0o600 {
+			t.Errorf("private key permissions = %04o, want 0600", got)
+		}
+	}
+
+	// Public key must exist.
+	pubPath := keyPath + ".pub"
+	pubInfo, err := os.Stat(pubPath)
+	if err != nil {
+		t.Fatalf("public key file missing: %v", err)
+	}
+	if runtime.GOOS != "windows" {
+		if got := pubInfo.Mode().Perm(); got != 0o644 {
+			t.Errorf("public key permissions = %04o, want 0644", got)
+		}
+	}
+
+	// Private key must be parseable as an OpenSSH ed25519 key.
+	privPEM, err := os.ReadFile(keyPath)
+	if err != nil {
+		t.Fatalf("read private key: %v", err)
+	}
+	privKey, err := ssh.ParseRawPrivateKey(privPEM)
+	if err != nil {
+		t.Fatalf("parse private key: %v", err)
+	}
+	if _, ok := privKey.(*ed25519.PrivateKey); !ok {
+		t.Errorf("private key type = %T, want *ed25519.PrivateKey", privKey)
+	}
+
+	// Public key must be parseable as authorized_keys line.
+	pubBytes, err := os.ReadFile(pubPath)
+	if err != nil {
+		t.Fatalf("read public key: %v", err)
+	}
+	pubKey, _, _, rest, err := ssh.ParseAuthorizedKey(pubBytes)
+	if err != nil {
+		t.Fatalf("parse public key: %v", err)
+	}
+	if pubKey == nil {
+		t.Fatal("expected non-nil public key")
+	}
+	if len(rest) > 0 {
+		t.Errorf("unexpected trailing bytes after public key: %d bytes", len(rest))
+	}
+}
+
+func TestGenerateSSHKey_OverwritesExisting(t *testing.T) {
+	dir := t.TempDir()
+	keyPath := filepath.Join(dir, "test_ed25519.key")
+
+	// Generate twice; second call must not error and must produce a different key.
+	if err := GenerateSSHKey(keyPath); err != nil {
+		t.Fatalf("first GenerateSSHKey() error = %v", err)
+	}
+	first, err := os.ReadFile(keyPath)
+	if err != nil {
+		t.Fatalf("read first key: %v", err)
+	}
+
+	if err = GenerateSSHKey(keyPath); err != nil {
+		t.Fatalf("second GenerateSSHKey() error = %v", err)
+	}
+	second, err := os.ReadFile(keyPath)
+	if err != nil {
+		t.Fatalf("read second key: %v", err)
+	}
+
+	// Two independently generated Ed25519 keys must differ.
+	if string(first) == string(second) {
+		t.Error("expected overwritten key to differ from original")
+	}
+}
+
+func TestGenerateSSHKey_CreatesDirectory(t *testing.T) {
+	dir := t.TempDir()
+	// Nested directory that does not yet exist.
+	keyPath := filepath.Join(dir, "subdir", ".ssh", "picoclaw_ed25519.key")
+
+	if err := GenerateSSHKey(keyPath); err != nil {
+		t.Fatalf("GenerateSSHKey() error = %v", err)
+	}
+
+	if _, err := os.Stat(keyPath); err != nil {
+		t.Fatalf("private key not created: %v", err)
+	}
+}
diff --git a/pkg/credential/store.go b/pkg/credential/store.go
new file mode 100644
index 000000000..9c72974b0
--- /dev/null
+++ b/pkg/credential/store.go
@@ -0,0 +1,44 @@
+package credential
+
+import "sync/atomic"
+
+// SecureStore holds a passphrase in memory.
+//
+// Uses atomic.Pointer so reads and writes are lock-free.
+// The passphrase is never written to disk; callers decide how to
+// transport it outside this store (e.g., via cmd.Env or os.Environ).
+type SecureStore struct {
+	val atomic.Pointer[string]
+}
+
+// NewSecureStore creates an empty SecureStore.
+func NewSecureStore() *SecureStore {
+	return &SecureStore{}
+}
+
+// SetString stores the passphrase. An empty string clears the store.
+func (s *SecureStore) SetString(passphrase string) {
+	if passphrase == "" {
+		s.val.Store(nil)
+		return
+	}
+	s.val.Store(&passphrase)
+}
+
+// Get returns the stored passphrase, or "" if not set.
+func (s *SecureStore) Get() string {
+	if p := s.val.Load(); p != nil {
+		return *p
+	}
+	return ""
+}
+
+// IsSet reports whether a passphrase is currently stored.
+func (s *SecureStore) IsSet() bool {
+	return s.val.Load() != nil
+}
+
+// Clear removes the stored passphrase.
+func (s *SecureStore) Clear() {
+	s.val.Store(nil)
+}
diff --git a/pkg/credential/store_test.go b/pkg/credential/store_test.go
new file mode 100644
index 000000000..63299743a
--- /dev/null
+++ b/pkg/credential/store_test.go
@@ -0,0 +1,81 @@
+package credential
+
+import (
+	"sync"
+	"testing"
+)
+
+func TestSecureStore_SetGet(t *testing.T) {
+	s := NewSecureStore()
+	if s.IsSet() {
+		t.Error("expected empty store")
+	}
+
+	s.SetString("hunter2")
+	if !s.IsSet() {
+		t.Error("expected store to be set")
+	}
+	if got := s.Get(); got != "hunter2" {
+		t.Errorf("Get() = %q, want %q", got, "hunter2")
+	}
+}
+
+func TestSecureStore_Clear(t *testing.T) {
+	s := NewSecureStore()
+	s.SetString("secret")
+	s.Clear()
+
+	if s.IsSet() {
+		t.Error("expected store to be empty after Clear()")
+	}
+	if got := s.Get(); got != "" {
+		t.Errorf("Get() after Clear() = %q, want empty", got)
+	}
+}
+
+func TestSecureStore_SetOverwrites(t *testing.T) {
+	s := NewSecureStore()
+	s.SetString("first")
+	s.SetString("second")
+
+	if got := s.Get(); got != "second" {
+		t.Errorf("Get() = %q, want %q", got, "second")
+	}
+}
+
+func TestSecureStore_EmptyPassphrase(t *testing.T) {
+	s := NewSecureStore()
+	s.SetString("") // empty → should not mark as set
+
+	if s.IsSet() {
+		t.Error("empty passphrase should not mark store as set")
+	}
+}
+
+func TestSecureStore_ConcurrentSetGet(t *testing.T) {
+	s := NewSecureStore()
+	const goroutines = 10
+	const iterations = 1000
+
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+	for i := 0; i < goroutines; i++ {
+		go func(id int) {
+			defer wg.Done()
+			for j := 0; j < iterations; j++ {
+				if id%2 == 0 {
+					s.SetString("even")
+				} else {
+					s.SetString("odd")
+				}
+				_ = s.Get()
+			}
+		}(i)
+	}
+	wg.Wait()
+
+	final := s.Get()
+	if final != "" && final != "even" && final != "odd" {
+		t.Errorf("Get() returned unexpected value %q after concurrent Set/Get", final)
+	}
+}
diff --git a/pkg/cron/service.go b/pkg/cron/service.go
index 6962041c1..77a413133 100644
--- a/pkg/cron/service.go
+++ b/pkg/cron/service.go
@@ -65,6 +65,7 @@ type CronService struct {
 	mu        sync.RWMutex
 	running   bool
 	stopChan  chan struct{}
+	wakeChan  chan struct{}
 	gronx     *gronx.Gronx
 }
 
@@ -73,6 +74,7 @@ func NewCronService(storePath string, onJob JobHandler) *CronService {
 		storePath: storePath,
 		onJob:     onJob,
 		gronx:     gronx.New(),
+		wakeChan:  make(chan struct{}),
 	}
 	// Initialize and load store on creation
 	cs.loadStore()
@@ -97,6 +99,9 @@ func (cs *CronService) Start() error {
 	}
 
 	cs.stopChan = make(chan struct{})
+	if cs.wakeChan == nil {
+		cs.wakeChan = make(chan struct{})
+	}
 	cs.running = true
 	go cs.runLoop(cs.stopChan)
 
@@ -119,14 +124,47 @@ func (cs *CronService) Stop() {
 }
 
 func (cs *CronService) runLoop(stopChan chan struct{}) {
-	ticker := time.NewTicker(1 * time.Second)
-	defer ticker.Stop()
+	timer := time.NewTimer(time.Hour)
+	if !timer.Stop() {
+		<-timer.C
+	}
+	defer timer.Stop()
 
 	for {
+		// every loop, recalculate the next wake time
+		cs.mu.RLock()
+		nextWake := cs.getNextWakeMS()
+		cs.mu.RUnlock()
+
+		var delay time.Duration
+		now := time.Now().UnixMilli()
+
+		if nextWake == nil {
+			// no jobs, sleep for a long time (or until a new job is added)
+			delay = time.Hour
+		} else {
+			diff := *nextWake - now
+			if diff <= 0 {
+				delay = 0
+			} else {
+				delay = time.Duration(diff) * time.Millisecond
+			}
+		}
+
+		timer.Reset(delay)
+
 		select {
 		case <-stopChan:
 			return
-		case <-ticker.C:
+		case <-cs.wakeChan: // wake on new job or update
+			if !timer.Stop() {
+				select {
+				case <-timer.C:
+				default:
+				}
+			}
+			continue
+		case <-timer.C:
 			cs.checkJobs()
 		}
 	}
@@ -190,14 +228,21 @@ func (cs *CronService) executeJobByID(jobID string) {
 	cs.mu.RUnlock()
 
 	if callbackJob == nil {
+		log.Printf("[cron] job %s not found, skipping", jobID)
 		return
 	}
 
+	// Log job execution start
+	log.Printf("[cron] ▶ executing job '%s' (id: %s, schedule: %s, channel: %s)",
+		callbackJob.Name, jobID, callbackJob.Schedule.Kind, callbackJob.Payload.Channel)
+
 	var err error
 	if cs.onJob != nil {
 		_, err = cs.onJob(callbackJob)
 	}
 
+	execDuration := time.Now().UnixMilli() - startTime
+
 	// Now acquire lock to update state
 	cs.mu.Lock()
 	defer cs.mu.Unlock()
@@ -220,22 +265,35 @@ func (cs *CronService) executeJobByID(jobID string) {
 	if err != nil {
 		job.State.LastStatus = "error"
 		job.State.LastError = err.Error()
+		log.Printf("[cron] ✗ job '%s' failed after %dms: %v", job.Name, execDuration, err)
 	} else {
 		job.State.LastStatus = "ok"
 		job.State.LastError = ""
 	}
 
 	// Compute next run time
+	var nextRunStr string
 	if job.Schedule.Kind == "at" {
 		if job.DeleteAfterRun {
 			cs.removeJobUnsafe(job.ID)
+			nextRunStr = "(deleted)"
 		} else {
 			job.Enabled = false
 			job.State.NextRunAtMS = nil
+			nextRunStr = "(disabled)"
 		}
 	} else {
 		nextRun := cs.computeNextRun(&job.Schedule, time.Now().UnixMilli())
 		job.State.NextRunAtMS = nextRun
+		if nextRun != nil {
+			nextRunStr = time.UnixMilli(*nextRun).Format("2006-01-02 15:04:05")
+		} else {
+			nextRunStr = "(none)"
+		}
+	}
+
+	if err == nil {
+		log.Printf("[cron] ✓ job '%s' completed in %dms, next run: %s", job.Name, execDuration, nextRunStr)
 	}
 
 	if err := cs.saveStoreUnsafe(); err != nil {
@@ -244,22 +302,19 @@ func (cs *CronService) executeJobByID(jobID string) {
 }
 
 func (cs *CronService) computeNextRun(schedule *CronSchedule, nowMS int64) *int64 {
-	if schedule.Kind == "at" {
+	switch schedule.Kind {
+	case "at":
 		if schedule.AtMS != nil && *schedule.AtMS > nowMS {
 			return schedule.AtMS
 		}
 		return nil
-	}
-
-	if schedule.Kind == "every" {
+	case "every":
 		if schedule.EveryMS == nil || *schedule.EveryMS <= 0 {
 			return nil
 		}
 		next := nowMS + *schedule.EveryMS
 		return &next
-	}
-
-	if schedule.Kind == "cron" {
+	case "cron":
 		if schedule.Expr == "" {
 			return nil
 		}
@@ -274,9 +329,19 @@ func (cs *CronService) computeNextRun(schedule *CronSchedule, nowMS int64) *int6
 
 		nextMS := nextTime.UnixMilli()
 		return &nextMS
+	default:
+		log.Printf("[cron] unknown schedule kind '%s'", schedule.Kind)
+		return nil
 	}
+}
 
-	return nil
+// wake up the loop to re-evaluate next wake time immediately (e.g. after add/update/remove jobs)
+func (cs *CronService) notify() {
+	select {
+	case cs.wakeChan <- struct{}{}:
+	default:
+		// if the channel is full, it means the loop will wake up soon anyway, so we can skip sending
+	}
 }
 
 func (cs *CronService) recomputeNextRuns() {
@@ -380,6 +445,8 @@ func (cs *CronService) AddJob(
 		return nil, err
 	}
 
+	cs.notify()
+
 	return &job, nil
 }
 
@@ -391,6 +458,9 @@ func (cs *CronService) UpdateJob(job *CronJob) error {
 		if cs.store.Jobs[i].ID == job.ID {
 			cs.store.Jobs[i] = *job
 			cs.store.Jobs[i].UpdatedAtMS = time.Now().UnixMilli()
+
+			cs.notify()
+
 			return cs.saveStoreUnsafe()
 		}
 	}
@@ -421,6 +491,8 @@ func (cs *CronService) removeJobUnsafe(jobID string) bool {
 		}
 	}
 
+	cs.notify()
+
 	return removed
 }
 
@@ -443,6 +515,9 @@ func (cs *CronService) EnableJob(jobID string, enabled bool) *CronJob {
 			if err := cs.saveStoreUnsafe(); err != nil {
 				log.Printf("[cron] failed to save store after enable: %v", err)
 			}
+
+			cs.notify()
+
 			return job
 		}
 	}
diff --git a/pkg/cron/service_test.go b/pkg/cron/service_test.go
index 1a0dd1829..c55e62174 100644
--- a/pkg/cron/service_test.go
+++ b/pkg/cron/service_test.go
@@ -1,10 +1,13 @@
 package cron
 
 import (
+	"fmt"
 	"os"
 	"path/filepath"
 	"runtime"
+	"sync"
 	"testing"
+	"time"
 )
 
 func TestSaveStore_FilePermissions(t *testing.T) {
@@ -36,3 +39,199 @@ func TestSaveStore_FilePermissions(t *testing.T) {
 func int64Ptr(v int64) *int64 {
 	return &v
 }
+
+func setupService(handler JobHandler) (*CronService, string) {
+	tmpFile := fmt.Sprintf("test_cron_%d.json", time.Now().UnixNano())
+	cs := NewCronService(tmpFile, handler)
+	return cs, tmpFile
+}
+
+func TestCronService_CRUD(t *testing.T) {
+	cs, path := setupService(nil)
+	defer os.Remove(path)
+
+	// Test AddJob
+	at := time.Now().Add(time.Hour).UnixMilli()
+	job, err := cs.AddJob("Task1", CronSchedule{Kind: "at", AtMS: &at}, "msg", true, "ch", "to")
+	if err != nil || job.ID == "" {
+		t.Fatalf("AddJob failed: %v", err)
+	}
+
+	// Test ListJobs
+	if len(cs.ListJobs(true)) != 1 {
+		t.Error("ListJobs should return 1 job")
+	}
+
+	// Test UpdateJob
+	job.Name = "UpdatedName"
+	err = cs.UpdateJob(job)
+	if err != nil || cs.store.Jobs[0].Name != "UpdatedName" {
+		t.Error("UpdateJob failed")
+	}
+
+	// Test EnableJob
+	cs.EnableJob(job.ID, false)
+	if cs.store.Jobs[0].Enabled != false || cs.store.Jobs[0].State.NextRunAtMS != nil {
+		t.Error("EnableJob(false) failed to clear state")
+	}
+
+	// Test RemoveJob
+	removed := cs.RemoveJob(job.ID)
+	if !removed || len(cs.store.Jobs) != 0 {
+		t.Error("RemoveJob failed")
+	}
+}
+
+// 2. Test Cron Expression Calculation Logic
+func TestCronService_ComputeNextRun(t *testing.T) {
+	cs, path := setupService(nil)
+	defer os.Remove(path)
+
+	now := time.Date(2024, 1, 1, 12, 0, 0, 0, time.UTC).UnixMilli()
+
+	tests := []struct {
+		name     string
+		schedule CronSchedule
+		wantNil  bool
+	}{
+		{"Valid Cron", CronSchedule{Kind: "cron", Expr: "0 * * * *"}, false},
+		{"Invalid Cron", CronSchedule{Kind: "cron", Expr: "invalid"}, true},
+		{"Every MS", CronSchedule{Kind: "every", EveryMS: int64Ptr(5000)}, false},
+		{"At Future", CronSchedule{Kind: "at", AtMS: int64Ptr(now + 1000)}, false},
+		{"At Past", CronSchedule{Kind: "at", AtMS: int64Ptr(now - 1000)}, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := cs.computeNextRun(&tt.schedule, now)
+			if (got == nil) != tt.wantNil {
+				t.Errorf("%s: got %v, wantNil %v", tt.name, got, tt.wantNil)
+			}
+		})
+	}
+}
+
+// 3. Test Execution Flow
+func TestCronService_ExecutionFlow(t *testing.T) {
+	var mu sync.Mutex
+	executedJobs := make(map[string]bool)
+
+	handler := func(job *CronJob) (string, error) {
+		mu.Lock()
+		executedJobs[job.ID] = true
+		mu.Unlock()
+		return "ok", nil
+	}
+
+	cs, path := setupService(handler)
+	defer os.Remove(path)
+
+	// Start the service
+	if err := cs.Start(); err != nil {
+		t.Fatalf("Start failed: %v", err)
+	}
+	defer cs.Stop()
+
+	// Add a job then runs 100ms from now
+	target := time.Now().Add(100 * time.Millisecond).UnixMilli()
+	job, _ := cs.AddJob("FastJob", CronSchedule{Kind: "at", AtMS: &target}, "", false, "", "")
+
+	// Check for job execution with a timeout
+	success := false
+	for range 20 {
+		mu.Lock()
+		if executedJobs[job.ID] {
+			success = true
+			mu.Unlock()
+			break
+		}
+		mu.Unlock()
+		time.Sleep(100 * time.Millisecond)
+	}
+
+	if !success {
+		t.Error("Job was not executed in time")
+	}
+
+	// check that the job is removed after execution (DeleteAfterRun = true)
+	status := cs.Status()
+	if status["jobs"].(int) != 0 {
+		t.Errorf("Job should be deleted after run, got count: %v", status["jobs"])
+	}
+}
+
+func TestCronService_PersistenceIntegrity(t *testing.T) {
+	tmpFile := "persist_test.json"
+	defer os.Remove(tmpFile)
+
+	// write a job and persist
+	cs1 := NewCronService(tmpFile, nil)
+	at := int64(2000000000000)
+	cs1.AddJob("PersistMe", CronSchedule{Kind: "at", AtMS: &at}, "payload", true, "ch1", "")
+
+	// check file exists
+	if _, err := os.Stat(tmpFile); os.IsNotExist(err) {
+		t.Fatal("Store file was not created")
+	}
+
+	// reload and check data integrity
+	cs2 := NewCronService(tmpFile, nil)
+	if err := cs2.Load(); err != nil {
+		t.Fatalf("Failed to load store: %v", err)
+	}
+
+	jobs := cs2.ListJobs(true)
+	if len(jobs) != 1 || jobs[0].Name != "PersistMe" {
+		t.Errorf("Data corruption after reload. Got: %+v", jobs)
+	}
+
+	// test loading invalid JSON
+	os.WriteFile(tmpFile, []byte("{invalid json}"), 0o644)
+	cs3 := NewCronService(tmpFile, nil)
+	err := cs3.loadStore()
+	if err == nil {
+		t.Error("Should return error when loading invalid JSON")
+	}
+}
+
+func TestCronService_ConcurrentAccess(t *testing.T) {
+	cs, path := setupService(nil)
+	defer os.Remove(path)
+
+	cs.Start()
+	defer cs.Stop()
+
+	var wg sync.WaitGroup
+	workers := 10
+	iterations := 50
+
+	wg.Add(workers * 2)
+
+	// add jobs concurrently
+	for i := range workers {
+		go func(id int) {
+			defer wg.Done()
+			for j := range iterations {
+				at := time.Now().Add(time.Hour).UnixMilli()
+				cs.AddJob(fmt.Sprintf("Job-%d-%d", id, j), CronSchedule{Kind: "at", AtMS: &at}, "", false, "", "")
+				time.Sleep(100 * time.Microsecond)
+			}
+		}(i)
+	}
+
+	// read and update jobs concurrently
+	for range workers {
+		go func() {
+			defer wg.Done()
+			for j := range iterations {
+				jobs := cs.ListJobs(true)
+				if len(jobs) > 0 {
+					cs.EnableJob(jobs[0].ID, j%2 == 0)
+				}
+				time.Sleep(100 * time.Microsecond)
+			}
+		}()
+	}
+
+	wg.Wait()
+}
diff --git a/pkg/env.go b/pkg/env.go
new file mode 100644
index 000000000..b9a77dab2
--- /dev/null
+++ b/pkg/env.go
@@ -0,0 +1,12 @@
+// all environment variables including default values put here
+
+package pkg
+
+const (
+	Logo = "🦞"
+	// AppName is the name of the app
+	AppName = "PicoClaw"
+
+	DefaultPicoClawHome = ".picoclaw"
+	WorkspaceName       = "workspace"
+)
diff --git a/pkg/fileutil/file.go b/pkg/fileutil/file.go
index 7ca872374..22374ac3d 100644
--- a/pkg/fileutil/file.go
+++ b/pkg/fileutil/file.go
@@ -117,3 +117,11 @@ func WriteFileAtomic(path string, data []byte, perm os.FileMode) error {
 	cleanup = false
 	return nil
 }
+
+func CopyFile(src, dst string, perm os.FileMode) error {
+	data, err := os.ReadFile(src)
+	if err != nil {
+		return err
+	}
+	return WriteFileAtomic(dst, data, perm)
+}
diff --git a/pkg/gateway/channel_matrix.go b/pkg/gateway/channel_matrix.go
new file mode 100644
index 000000000..f753c60e2
--- /dev/null
+++ b/pkg/gateway/channel_matrix.go
@@ -0,0 +1,21 @@
+//go:build !mipsle && !netbsd
+
+package gateway
+
+import (
+	// Matrix currently pulls in mautrix crypto and modernc sqlite transitively.
+	//
+	// We exclude it on:
+	// - linux/mipsle: mautrix crypto falls back to libolm when the `goolm` build
+	//   tag is unavailable, and modernc.org/sqlite/modernc.org/libc also lacks a
+	//   working build path for our mipsle + softfloat target.
+	// - netbsd/*: modernc.org/sqlite v1.46.1 fails to compile due to broken
+	//   generated mutex code on NetBSD (for example sqlite_netbsd_amd64.go calls
+	//   mu.enter/mu.leave, but the generated mutex type does not define them).
+	//
+	// This means Matrix is currently unavailable on those targets. The proper
+	// long-term fix is to split Matrix basic support from its E2EE/sqlite-backed
+	// crypto path, or to upgrade/replace the upstream sqlite dependency once the
+	// affected targets are supported.
+	_ "github.com/sipeed/picoclaw/pkg/channels/matrix"
+)
diff --git a/pkg/gateway/gateway.go b/pkg/gateway/gateway.go
new file mode 100644
index 000000000..03d7dfe0c
--- /dev/null
+++ b/pkg/gateway/gateway.go
@@ -0,0 +1,671 @@
+package gateway
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"sync"
+	"sync/atomic"
+	"syscall"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/agent"
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/channels"
+	_ "github.com/sipeed/picoclaw/pkg/channels/dingtalk"
+	_ "github.com/sipeed/picoclaw/pkg/channels/discord"
+	_ "github.com/sipeed/picoclaw/pkg/channels/feishu"
+	_ "github.com/sipeed/picoclaw/pkg/channels/irc"
+	_ "github.com/sipeed/picoclaw/pkg/channels/line"
+	_ "github.com/sipeed/picoclaw/pkg/channels/maixcam"
+	_ "github.com/sipeed/picoclaw/pkg/channels/onebot"
+	_ "github.com/sipeed/picoclaw/pkg/channels/pico"
+	_ "github.com/sipeed/picoclaw/pkg/channels/qq"
+	_ "github.com/sipeed/picoclaw/pkg/channels/slack"
+	_ "github.com/sipeed/picoclaw/pkg/channels/telegram"
+	_ "github.com/sipeed/picoclaw/pkg/channels/wecom"
+	_ "github.com/sipeed/picoclaw/pkg/channels/weixin"
+	_ "github.com/sipeed/picoclaw/pkg/channels/whatsapp"
+	_ "github.com/sipeed/picoclaw/pkg/channels/whatsapp_native"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/cron"
+	"github.com/sipeed/picoclaw/pkg/devices"
+	"github.com/sipeed/picoclaw/pkg/health"
+	"github.com/sipeed/picoclaw/pkg/heartbeat"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/state"
+	"github.com/sipeed/picoclaw/pkg/tools"
+	"github.com/sipeed/picoclaw/pkg/voice"
+)
+
+const (
+	serviceShutdownTimeout  = 30 * time.Second
+	providerReloadTimeout   = 30 * time.Second
+	gracefulShutdownTimeout = 15 * time.Second
+
+	logPath   = "logs"
+	panicFile = "gateway_panic.log"
+	logFile   = "gateway.log"
+)
+
+type services struct {
+	CronService      *cron.CronService
+	HeartbeatService *heartbeat.HeartbeatService
+	MediaStore       media.MediaStore
+	ChannelManager   *channels.Manager
+	DeviceService    *devices.Service
+	HealthServer     *health.Server
+	manualReloadChan chan struct{}
+	reloading        atomic.Bool
+}
+
+type startupBlockedProvider struct {
+	reason string
+}
+
+func (p *startupBlockedProvider) Chat(
+	_ context.Context,
+	_ []providers.Message,
+	_ []providers.ToolDefinition,
+	_ string,
+	_ map[string]any,
+) (*providers.LLMResponse, error) {
+	return nil, fmt.Errorf("%s", p.reason)
+}
+
+func (p *startupBlockedProvider) GetDefaultModel() string {
+	return ""
+}
+
+// Run starts the gateway runtime using the configuration loaded from configPath.
+func Run(debug bool, homePath, configPath string, allowEmptyStartup bool) error {
+	panicPath := filepath.Join(homePath, logPath, panicFile)
+	panicFunc, err := logger.InitPanic(panicPath)
+	if err != nil {
+		return fmt.Errorf("error initializing panic log: %w", err)
+	}
+	defer panicFunc()
+
+	if err = logger.EnableFileLogging(filepath.Join(homePath, logPath, logFile)); err != nil {
+		panic(fmt.Sprintf("error enabling file logging: %v", err))
+	}
+	defer logger.DisableFileLogging()
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		return fmt.Errorf("error loading config: %w", err)
+	}
+
+	logger.SetLevelFromString(cfg.Gateway.LogLevel)
+
+	if debug {
+		logger.SetLevel(logger.DEBUG)
+		fmt.Println("🔍 Debug mode enabled")
+	}
+
+	provider, modelID, err := createStartupProvider(cfg, allowEmptyStartup)
+	if err != nil {
+		return fmt.Errorf("error creating provider: %w", err)
+	}
+
+	if modelID != "" {
+		cfg.Agents.Defaults.ModelName = modelID
+	}
+
+	msgBus := bus.NewMessageBus()
+	agentLoop := agent.NewAgentLoop(cfg, msgBus, provider)
+
+	fmt.Println("\n📦 Agent Status:")
+	startupInfo := agentLoop.GetStartupInfo()
+	toolsInfo := startupInfo["tools"].(map[string]any)
+	skillsInfo := startupInfo["skills"].(map[string]any)
+	fmt.Printf("  • Tools: %d loaded\n", toolsInfo["count"])
+	fmt.Printf("  • Skills: %d/%d available\n", skillsInfo["available"], skillsInfo["total"])
+
+	logger.InfoCF("agent", "Agent initialized",
+		map[string]any{
+			"tools_count":      toolsInfo["count"],
+			"skills_total":     skillsInfo["total"],
+			"skills_available": skillsInfo["available"],
+		})
+
+	runningServices, err := setupAndStartServices(cfg, agentLoop, msgBus)
+	if err != nil {
+		return err
+	}
+
+	// Setup manual reload channel for /reload endpoint
+	manualReloadChan := make(chan struct{}, 1)
+	runningServices.manualReloadChan = manualReloadChan
+	reloadTrigger := func() error {
+		if !runningServices.reloading.CompareAndSwap(false, true) {
+			return fmt.Errorf("reload already in progress")
+		}
+		select {
+		case manualReloadChan <- struct{}{}:
+			return nil
+		default:
+			// Should not happen, but reset flag if channel is full
+			runningServices.reloading.Store(false)
+			return fmt.Errorf("reload already queued")
+		}
+	}
+	runningServices.HealthServer.SetReloadFunc(reloadTrigger)
+	agentLoop.SetReloadFunc(reloadTrigger)
+
+	fmt.Printf("✓ Gateway started on %s:%d\n", cfg.Gateway.Host, cfg.Gateway.Port)
+	fmt.Println("Press Ctrl+C to stop")
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	go agentLoop.Run(ctx)
+
+	var configReloadChan <-chan *config.Config
+	stopWatch := func() {}
+	if cfg.Gateway.HotReload {
+		configReloadChan, stopWatch = setupConfigWatcherPolling(configPath, debug)
+		logger.Info("Config hot reload enabled")
+	}
+	defer stopWatch()
+
+	sigChan := make(chan os.Signal, 1)
+	signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
+
+	for {
+		select {
+		case <-sigChan:
+			logger.Info("Shutting down...")
+			shutdownGateway(runningServices, agentLoop, provider, true)
+			return nil
+		case newCfg := <-configReloadChan:
+			if !runningServices.reloading.CompareAndSwap(false, true) {
+				logger.Warn("Config reload skipped: another reload is in progress")
+				continue
+			}
+			err := executeReload(ctx, agentLoop, newCfg, &provider, runningServices, msgBus, allowEmptyStartup)
+			if err != nil {
+				logger.Errorf("Config reload failed: %v", err)
+			}
+		case <-manualReloadChan:
+			logger.Info("Manual reload triggered via /reload endpoint")
+			newCfg, err := config.LoadConfig(configPath)
+			if err != nil {
+				logger.Errorf("Error loading config for manual reload: %v", err)
+				runningServices.reloading.Store(false)
+				continue
+			}
+			if err = newCfg.ValidateModelList(); err != nil {
+				logger.Errorf("Config validation failed: %v", err)
+				runningServices.reloading.Store(false)
+				continue
+			}
+			err = executeReload(ctx, agentLoop, newCfg, &provider, runningServices, msgBus, allowEmptyStartup)
+			if err != nil {
+				logger.Errorf("Manual reload failed: %v", err)
+			} else {
+				logger.Info("Manual reload completed successfully")
+			}
+		}
+	}
+}
+
+func executeReload(
+	ctx context.Context,
+	agentLoop *agent.AgentLoop,
+	newCfg *config.Config,
+	provider *providers.LLMProvider,
+	runningServices *services,
+	msgBus *bus.MessageBus,
+	allowEmptyStartup bool,
+) error {
+	defer runningServices.reloading.Store(false)
+	return handleConfigReload(ctx, agentLoop, newCfg, provider, runningServices, msgBus, allowEmptyStartup)
+}
+
+func createStartupProvider(
+	cfg *config.Config,
+	allowEmptyStartup bool,
+) (providers.LLMProvider, string, error) {
+	modelName := cfg.Agents.Defaults.GetModelName()
+	if modelName == "" && allowEmptyStartup {
+		reason := "no default model configured; gateway started in limited mode"
+		fmt.Printf("⚠ Warning: %s\n", reason)
+		logger.WarnCF("gateway", "Gateway started without default model", map[string]any{
+			"limited_mode": true,
+		})
+		return &startupBlockedProvider{reason: reason}, "", nil
+	}
+
+	return providers.CreateProvider(cfg)
+}
+
+func setupAndStartServices(
+	cfg *config.Config,
+	agentLoop *agent.AgentLoop,
+	msgBus *bus.MessageBus,
+) (*services, error) {
+	runningServices := &services{}
+
+	execTimeout := time.Duration(cfg.Tools.Cron.ExecTimeoutMinutes) * time.Minute
+	var err error
+	runningServices.CronService, err = setupCronTool(
+		agentLoop,
+		msgBus,
+		cfg.WorkspacePath(),
+		cfg.Agents.Defaults.RestrictToWorkspace,
+		execTimeout,
+		cfg,
+	)
+	if err != nil {
+		return nil, fmt.Errorf("error setting up cron service: %w", err)
+	}
+	if err = runningServices.CronService.Start(); err != nil {
+		return nil, fmt.Errorf("error starting cron service: %w", err)
+	}
+	fmt.Println("✓ Cron service started")
+
+	runningServices.HeartbeatService = heartbeat.NewHeartbeatService(
+		cfg.WorkspacePath(),
+		cfg.Heartbeat.Interval,
+		cfg.Heartbeat.Enabled,
+	)
+	runningServices.HeartbeatService.SetBus(msgBus)
+	runningServices.HeartbeatService.SetHandler(createHeartbeatHandler(agentLoop))
+	if err = runningServices.HeartbeatService.Start(); err != nil {
+		return nil, fmt.Errorf("error starting heartbeat service: %w", err)
+	}
+	fmt.Println("✓ Heartbeat service started")
+
+	runningServices.MediaStore = media.NewFileMediaStoreWithCleanup(media.MediaCleanerConfig{
+		Enabled:  cfg.Tools.MediaCleanup.Enabled,
+		MaxAge:   time.Duration(cfg.Tools.MediaCleanup.MaxAge) * time.Minute,
+		Interval: time.Duration(cfg.Tools.MediaCleanup.Interval) * time.Minute,
+	})
+	if fms, ok := runningServices.MediaStore.(*media.FileMediaStore); ok {
+		fms.Start()
+	}
+
+	runningServices.ChannelManager, err = channels.NewManager(cfg, msgBus, runningServices.MediaStore)
+	if err != nil {
+		if fms, ok := runningServices.MediaStore.(*media.FileMediaStore); ok {
+			fms.Stop()
+		}
+		return nil, fmt.Errorf("error creating channel manager: %w", err)
+	}
+
+	agentLoop.SetChannelManager(runningServices.ChannelManager)
+	agentLoop.SetMediaStore(runningServices.MediaStore)
+
+	if transcriber := voice.DetectTranscriber(cfg); transcriber != nil {
+		agentLoop.SetTranscriber(transcriber)
+		logger.InfoCF("voice", "Transcription enabled (agent-level)", map[string]any{"provider": transcriber.Name()})
+	}
+
+	enabledChannels := runningServices.ChannelManager.GetEnabledChannels()
+	if len(enabledChannels) > 0 {
+		fmt.Printf("✓ Channels enabled: %s\n", enabledChannels)
+	} else {
+		fmt.Println("⚠ Warning: No channels enabled")
+	}
+
+	addr := fmt.Sprintf("%s:%d", cfg.Gateway.Host, cfg.Gateway.Port)
+	runningServices.HealthServer = health.NewServer(cfg.Gateway.Host, cfg.Gateway.Port)
+	runningServices.ChannelManager.SetupHTTPServer(addr, runningServices.HealthServer)
+
+	if err = runningServices.ChannelManager.StartAll(context.Background()); err != nil {
+		return nil, fmt.Errorf("error starting channels: %w", err)
+	}
+
+	fmt.Printf(
+		"✓ Health endpoints available at http://%s:%d/health, /ready and /reload (POST)\n",
+		cfg.Gateway.Host,
+		cfg.Gateway.Port,
+	)
+
+	stateManager := state.NewManager(cfg.WorkspacePath())
+	runningServices.DeviceService = devices.NewService(devices.Config{
+		Enabled:    cfg.Devices.Enabled,
+		MonitorUSB: cfg.Devices.MonitorUSB,
+	}, stateManager)
+	runningServices.DeviceService.SetBus(msgBus)
+	if err = runningServices.DeviceService.Start(context.Background()); err != nil {
+		logger.ErrorCF("device", "Error starting device service", map[string]any{"error": err.Error()})
+	} else if cfg.Devices.Enabled {
+		fmt.Println("✓ Device event service started")
+	}
+
+	return runningServices, nil
+}
+
+func stopAndCleanupServices(runningServices *services, shutdownTimeout time.Duration, isReload bool) {
+	shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), shutdownTimeout)
+	defer shutdownCancel()
+
+	// reload should not stop channel manager
+	if !isReload && runningServices.ChannelManager != nil {
+		runningServices.ChannelManager.StopAll(shutdownCtx)
+	}
+	if runningServices.DeviceService != nil {
+		runningServices.DeviceService.Stop()
+	}
+	if runningServices.HeartbeatService != nil {
+		runningServices.HeartbeatService.Stop()
+	}
+	if runningServices.CronService != nil {
+		runningServices.CronService.Stop()
+	}
+	if runningServices.MediaStore != nil {
+		if fms, ok := runningServices.MediaStore.(*media.FileMediaStore); ok {
+			fms.Stop()
+		}
+	}
+}
+
+func shutdownGateway(
+	runningServices *services,
+	agentLoop *agent.AgentLoop,
+	provider providers.LLMProvider,
+	fullShutdown bool,
+) {
+	if cp, ok := provider.(providers.StatefulProvider); ok && fullShutdown {
+		cp.Close()
+	}
+
+	stopAndCleanupServices(runningServices, gracefulShutdownTimeout, false)
+
+	agentLoop.Stop()
+	agentLoop.Close()
+
+	logger.Info("✓ Gateway stopped")
+}
+
+func handleConfigReload(
+	ctx context.Context,
+	al *agent.AgentLoop,
+	newCfg *config.Config,
+	providerRef *providers.LLMProvider,
+	runningServices *services,
+	msgBus *bus.MessageBus,
+	allowEmptyStartup bool,
+) error {
+	logger.Info("🔄 Config file changed, reloading...")
+
+	newModel := newCfg.Agents.Defaults.ModelName
+
+	logger.Infof(" New model is '%s', recreating provider...", newModel)
+
+	logger.Info("  Stopping all services...")
+	stopAndCleanupServices(runningServices, serviceShutdownTimeout, true)
+
+	newProvider, newModelID, err := createStartupProvider(newCfg, allowEmptyStartup)
+	if err != nil {
+		logger.Errorf("  ⚠ Error creating new provider: %v", err)
+		logger.Warn("  Attempting to restart services with old provider and config...")
+		if restartErr := restartServices(al, runningServices, msgBus); restartErr != nil {
+			logger.Errorf("  ⚠ Failed to restart services: %v", restartErr)
+		}
+		return fmt.Errorf("error creating new provider: %w", err)
+	}
+
+	if newModelID != "" {
+		newCfg.Agents.Defaults.ModelName = newModelID
+	}
+
+	reloadCtx, reloadCancel := context.WithTimeout(context.Background(), providerReloadTimeout)
+	defer reloadCancel()
+
+	if err := al.ReloadProviderAndConfig(reloadCtx, newProvider, newCfg); err != nil {
+		logger.Errorf("  ⚠ Error reloading agent loop: %v", err)
+		if cp, ok := newProvider.(providers.StatefulProvider); ok {
+			cp.Close()
+		}
+		logger.Warn("  Attempting to restart services with old provider and config...")
+		if restartErr := restartServices(al, runningServices, msgBus); restartErr != nil {
+			logger.Errorf("  ⚠ Failed to restart services: %v", restartErr)
+		}
+		return fmt.Errorf("error reloading agent loop: %w", err)
+	}
+
+	*providerRef = newProvider
+
+	logger.Info("  Restarting all services with new configuration...")
+	if err := restartServices(al, runningServices, msgBus); err != nil {
+		logger.Errorf("  ⚠ Error restarting services: %v", err)
+		return fmt.Errorf("error restarting services: %w", err)
+	}
+
+	logger.Info("  ✓ Provider, configuration, and services reloaded successfully (thread-safe)")
+	return nil
+}
+
+func restartServices(
+	al *agent.AgentLoop,
+	runningServices *services,
+	msgBus *bus.MessageBus,
+) error {
+	cfg := al.GetConfig()
+
+	execTimeout := time.Duration(cfg.Tools.Cron.ExecTimeoutMinutes) * time.Minute
+	var err error
+	runningServices.CronService, err = setupCronTool(
+		al,
+		msgBus,
+		cfg.WorkspacePath(),
+		cfg.Agents.Defaults.RestrictToWorkspace,
+		execTimeout,
+		cfg,
+	)
+	if err != nil {
+		return fmt.Errorf("error restarting cron service: %w", err)
+	}
+	if err = runningServices.CronService.Start(); err != nil {
+		return fmt.Errorf("error restarting cron service: %w", err)
+	}
+	fmt.Println("  ✓ Cron service restarted")
+
+	runningServices.HeartbeatService = heartbeat.NewHeartbeatService(
+		cfg.WorkspacePath(),
+		cfg.Heartbeat.Interval,
+		cfg.Heartbeat.Enabled,
+	)
+	runningServices.HeartbeatService.SetBus(msgBus)
+	runningServices.HeartbeatService.SetHandler(createHeartbeatHandler(al))
+	if err = runningServices.HeartbeatService.Start(); err != nil {
+		return fmt.Errorf("error restarting heartbeat service: %w", err)
+	}
+	fmt.Println("  ✓ Heartbeat service restarted")
+
+	runningServices.MediaStore = media.NewFileMediaStoreWithCleanup(media.MediaCleanerConfig{
+		Enabled:  cfg.Tools.MediaCleanup.Enabled,
+		MaxAge:   time.Duration(cfg.Tools.MediaCleanup.MaxAge) * time.Minute,
+		Interval: time.Duration(cfg.Tools.MediaCleanup.Interval) * time.Minute,
+	})
+	if fms, ok := runningServices.MediaStore.(*media.FileMediaStore); ok {
+		fms.Start()
+	}
+	al.SetMediaStore(runningServices.MediaStore)
+
+	runningServices.ChannelManager, err = channels.NewManager(cfg, msgBus, runningServices.MediaStore)
+	if err != nil {
+		return fmt.Errorf("error recreating channel manager: %w", err)
+	}
+	al.SetChannelManager(runningServices.ChannelManager)
+
+	enabledChannels := runningServices.ChannelManager.GetEnabledChannels()
+	if len(enabledChannels) > 0 {
+		fmt.Printf("  ✓ Channels enabled: %s\n", enabledChannels)
+	} else {
+		fmt.Println("  ⚠ Warning: No channels enabled")
+	}
+
+	addr := fmt.Sprintf("%s:%d", cfg.Gateway.Host, cfg.Gateway.Port)
+	// Reuse existing HealthServer to preserve reloadFunc
+	if runningServices.HealthServer == nil {
+		runningServices.HealthServer = health.NewServer(cfg.Gateway.Host, cfg.Gateway.Port)
+	}
+	runningServices.ChannelManager.SetupHTTPServer(addr, runningServices.HealthServer)
+
+	if err = runningServices.ChannelManager.Reload(context.Background(), cfg); err != nil {
+		return fmt.Errorf("error reload channels: %w", err)
+	}
+	fmt.Println("  ✓ Channels restarted.")
+
+	stateManager := state.NewManager(cfg.WorkspacePath())
+	runningServices.DeviceService = devices.NewService(devices.Config{
+		Enabled:    cfg.Devices.Enabled,
+		MonitorUSB: cfg.Devices.MonitorUSB,
+	}, stateManager)
+	runningServices.DeviceService.SetBus(msgBus)
+	if err := runningServices.DeviceService.Start(context.Background()); err != nil {
+		logger.WarnCF("device", "Failed to restart device service", map[string]any{"error": err.Error()})
+	} else if cfg.Devices.Enabled {
+		fmt.Println("  ✓ Device event service restarted")
+	}
+
+	transcriber := voice.DetectTranscriber(cfg)
+	al.SetTranscriber(transcriber)
+	if transcriber != nil {
+		logger.InfoCF("voice", "Transcription re-enabled (agent-level)", map[string]any{"provider": transcriber.Name()})
+	} else {
+		logger.InfoCF("voice", "Transcription disabled", nil)
+	}
+
+	return nil
+}
+
+func setupConfigWatcherPolling(configPath string, debug bool) (chan *config.Config, func()) {
+	configChan := make(chan *config.Config, 1)
+	stop := make(chan struct{})
+	var wg sync.WaitGroup
+
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+
+		lastModTime := getFileModTime(configPath)
+		lastSize := getFileSize(configPath)
+
+		ticker := time.NewTicker(2 * time.Second)
+		defer ticker.Stop()
+
+		for {
+			select {
+			case <-ticker.C:
+				currentModTime := getFileModTime(configPath)
+				currentSize := getFileSize(configPath)
+
+				if currentModTime.After(lastModTime) || currentSize != lastSize {
+					if debug {
+						logger.Debugf("🔍 Config file change detected")
+					}
+
+					time.Sleep(500 * time.Millisecond)
+
+					lastModTime = currentModTime
+					lastSize = currentSize
+
+					newCfg, err := config.LoadConfig(configPath)
+					if err != nil {
+						logger.Errorf("⚠ Error loading new config: %v", err)
+						logger.Warn("  Using previous valid config")
+						continue
+					}
+
+					if err := newCfg.ValidateModelList(); err != nil {
+						logger.Errorf("  ⚠ New config validation failed: %v", err)
+						logger.Warn("  Using previous valid config")
+						continue
+					}
+
+					logger.Info("✓ Config file validated and loaded")
+
+					select {
+					case configChan <- newCfg:
+					default:
+						logger.Warn("⚠ Previous config reload still in progress, skipping")
+					}
+				}
+			case <-stop:
+				return
+			}
+		}
+	}()
+
+	stopFunc := func() {
+		close(stop)
+		wg.Wait()
+	}
+
+	return configChan, stopFunc
+}
+
+func getFileModTime(path string) time.Time {
+	info, err := os.Stat(path)
+	if err != nil {
+		return time.Time{}
+	}
+	return info.ModTime()
+}
+
+func getFileSize(path string) int64 {
+	info, err := os.Stat(path)
+	if err != nil {
+		return 0
+	}
+	return info.Size()
+}
+
+func setupCronTool(
+	agentLoop *agent.AgentLoop,
+	msgBus *bus.MessageBus,
+	workspace string,
+	restrict bool,
+	execTimeout time.Duration,
+	cfg *config.Config,
+) (*cron.CronService, error) {
+	cronStorePath := filepath.Join(workspace, "cron", "jobs.json")
+
+	cronService := cron.NewCronService(cronStorePath, nil)
+
+	var cronTool *tools.CronTool
+	if cfg.Tools.IsToolEnabled("cron") {
+		var err error
+		cronTool, err = tools.NewCronTool(cronService, agentLoop, msgBus, workspace, restrict, execTimeout, cfg)
+		if err != nil {
+			return nil, fmt.Errorf("critical error during CronTool initialization: %w", err)
+		}
+
+		agentLoop.RegisterTool(cronTool)
+	}
+
+	if cronTool != nil {
+		cronService.SetOnJob(func(job *cron.CronJob) (string, error) {
+			result := cronTool.ExecuteJob(context.Background(), job)
+			return result, nil
+		})
+	}
+
+	return cronService, nil
+}
+
+func createHeartbeatHandler(agentLoop *agent.AgentLoop) func(prompt, channel, chatID string) *tools.ToolResult {
+	return func(prompt, channel, chatID string) *tools.ToolResult {
+		if channel == "" || chatID == "" {
+			channel, chatID = "cli", "direct"
+		}
+
+		response, err := agentLoop.ProcessHeartbeat(context.Background(), prompt, channel, chatID)
+		if err != nil {
+			return tools.ErrorResult(fmt.Sprintf("Heartbeat error: %v", err))
+		}
+		if response == "HEARTBEAT_OK" {
+			return tools.SilentResult("Heartbeat OK")
+		}
+		return tools.SilentResult(response)
+	}
+}
diff --git a/pkg/health/server.go b/pkg/health/server.go
index 5609ebdf6..fe20e4b94 100644
--- a/pkg/health/server.go
+++ b/pkg/health/server.go
@@ -6,16 +6,18 @@ import (
 	"fmt"
 	"maps"
 	"net/http"
+	"os"
 	"sync"
 	"time"
 )
 
 type Server struct {
-	server    *http.Server
-	mu        sync.RWMutex
-	ready     bool
-	checks    map[string]Check
-	startTime time.Time
+	server     *http.Server
+	mu         sync.RWMutex
+	ready      bool
+	checks     map[string]Check
+	startTime  time.Time
+	reloadFunc func() error
 }
 
 type Check struct {
@@ -29,6 +31,7 @@ type StatusResponse struct {
 	Status string           `json:"status"`
 	Uptime string           `json:"uptime"`
 	Checks map[string]Check `json:"checks,omitempty"`
+	Pid    int              `json:"pid"`
 }
 
 func NewServer(host string, port int) *Server {
@@ -41,6 +44,7 @@ func NewServer(host string, port int) *Server {
 
 	mux.HandleFunc("/health", s.healthHandler)
 	mux.HandleFunc("/ready", s.readyHandler)
+	mux.HandleFunc("/reload", s.reloadHandler)
 
 	addr := fmt.Sprintf("%s:%d", host, port)
 	s.server = &http.Server{
@@ -104,6 +108,44 @@ func (s *Server) RegisterCheck(name string, checkFn func() (bool, string)) {
 	}
 }
 
+// SetReloadFunc sets the callback function for config reload.
+func (s *Server) SetReloadFunc(fn func() error) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.reloadFunc = fn
+}
+
+func (s *Server) reloadHandler(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusMethodNotAllowed)
+		json.NewEncoder(w).Encode(map[string]string{"error": "method not allowed, use POST"})
+		return
+	}
+
+	s.mu.Lock()
+	reloadFunc := s.reloadFunc
+	s.mu.Unlock()
+
+	if reloadFunc == nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusServiceUnavailable)
+		json.NewEncoder(w).Encode(map[string]string{"error": "reload not configured"})
+		return
+	}
+
+	if err := reloadFunc(); err != nil {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusInternalServerError)
+		json.NewEncoder(w).Encode(map[string]string{"error": err.Error()})
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(http.StatusOK)
+	json.NewEncoder(w).Encode(map[string]string{"status": "reload triggered"})
+}
+
 func (s *Server) healthHandler(w http.ResponseWriter, r *http.Request) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(http.StatusOK)
@@ -112,6 +154,7 @@ func (s *Server) healthHandler(w http.ResponseWriter, r *http.Request) {
 	resp := StatusResponse{
 		Status: "ok",
 		Uptime: uptime.String(),
+		Pid:    os.Getpid(),
 	}
 
 	json.NewEncoder(w).Encode(resp)
@@ -155,11 +198,12 @@ func (s *Server) readyHandler(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
-// RegisterOnMux registers /health and /ready handlers onto the given mux.
+// RegisterOnMux registers /health, /ready and /reload handlers onto the given mux.
 // This allows the health endpoints to be served by a shared HTTP server.
 func (s *Server) RegisterOnMux(mux *http.ServeMux) {
 	mux.HandleFunc("/health", s.healthHandler)
 	mux.HandleFunc("/ready", s.readyHandler)
+	mux.HandleFunc("/reload", s.reloadHandler)
 }
 
 func statusString(ok bool) string {
diff --git a/pkg/heartbeat/service.go b/pkg/heartbeat/service.go
index 09c93fc6b..5dda78ea9 100644
--- a/pkg/heartbeat/service.go
+++ b/pkg/heartbeat/service.go
@@ -26,6 +26,7 @@ import (
 const (
 	minIntervalMinutes     = 5
 	defaultIntervalMinutes = 30
+	userTasksMarker        = "Add your heartbeat tasks below this line:"
 )
 
 // HeartbeatHandler is the function type for handling heartbeat.
@@ -232,7 +233,7 @@ func (hs *HeartbeatService) buildPrompt() string {
 	}
 
 	content := string(data)
-	if len(content) == 0 {
+	if !heartbeatHasUserTasks(content) {
 		return ""
 	}
 
@@ -284,6 +285,32 @@ Add your heartbeat tasks below this line:
 	}
 }
 
+func heartbeatHasUserTasks(content string) bool {
+	trimmed := strings.TrimSpace(content)
+	if trimmed == "" {
+		return false
+	}
+
+	markerIdx := strings.Index(content, userTasksMarker)
+	if markerIdx < 0 {
+		return true
+	}
+
+	tasksSection := content[markerIdx+len(userTasksMarker):]
+	for _, line := range strings.Split(tasksSection, "\n") {
+		trimmedLine := strings.TrimSpace(line)
+		if trimmedLine == "" {
+			continue
+		}
+		if strings.HasPrefix(trimmedLine, "#") {
+			continue
+		}
+		return true
+	}
+
+	return false
+}
+
 // sendResponse sends the heartbeat response to the last channel
 func (hs *HeartbeatService) sendResponse(response string) {
 	hs.mu.RLock()
diff --git a/pkg/heartbeat/service_test.go b/pkg/heartbeat/service_test.go
index a7aef8c3a..309b4378f 100644
--- a/pkg/heartbeat/service_test.go
+++ b/pkg/heartbeat/service_test.go
@@ -3,6 +3,7 @@ package heartbeat
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
@@ -47,79 +48,63 @@ func TestExecuteHeartbeat_Async(t *testing.T) {
 	}
 }
 
-func TestExecuteHeartbeat_Error(t *testing.T) {
-	tmpDir, err := os.MkdirTemp("", "heartbeat-test-*")
-	if err != nil {
-		t.Fatalf("Failed to create temp dir: %v", err)
-	}
-	defer os.RemoveAll(tmpDir)
-
-	hs := NewHeartbeatService(tmpDir, 30, true)
-	hs.stopChan = make(chan struct{}) // Enable for testing
-
-	hs.SetHandler(func(prompt, channel, chatID string) *tools.ToolResult {
-		return &tools.ToolResult{
-			ForLLM:  "Heartbeat failed: connection error",
-			ForUser: "",
-			Silent:  false,
-			IsError: true,
-			Async:   false,
-		}
-	})
-
-	// Create HEARTBEAT.md
-	os.WriteFile(filepath.Join(tmpDir, "HEARTBEAT.md"), []byte("Test task"), 0o644)
-
-	hs.executeHeartbeat()
-
-	// Check log file for error message
-	logFile := filepath.Join(tmpDir, "heartbeat.log")
-	data, err := os.ReadFile(logFile)
-	if err != nil {
-		t.Fatalf("Failed to read log file: %v", err)
+func TestExecuteHeartbeat_ResultLogging(t *testing.T) {
+	tests := []struct {
+		name    string
+		result  *tools.ToolResult
+		wantLog string
+	}{
+		{
+			name: "error result",
+			result: &tools.ToolResult{
+				ForLLM:  "Heartbeat failed: connection error",
+				ForUser: "",
+				Silent:  false,
+				IsError: true,
+				Async:   false,
+			},
+			wantLog: "error message",
+		},
+		{
+			name: "silent result",
+			result: &tools.ToolResult{
+				ForLLM:  "Heartbeat completed successfully",
+				ForUser: "",
+				Silent:  true,
+				IsError: false,
+				Async:   false,
+			},
+			wantLog: "completion message",
+		},
 	}
 
-	logContent := string(data)
-	if logContent == "" {
-		t.Error("Expected log file to contain error message")
-	}
-}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tmpDir, err := os.MkdirTemp("", "heartbeat-test-*")
+			if err != nil {
+				t.Fatalf("Failed to create temp dir: %v", err)
+			}
+			defer os.RemoveAll(tmpDir)
 
-func TestExecuteHeartbeat_Silent(t *testing.T) {
-	tmpDir, err := os.MkdirTemp("", "heartbeat-test-*")
-	if err != nil {
-		t.Fatalf("Failed to create temp dir: %v", err)
-	}
-	defer os.RemoveAll(tmpDir)
+			hs := NewHeartbeatService(tmpDir, 30, true)
+			hs.stopChan = make(chan struct{}) // Enable for testing
 
-	hs := NewHeartbeatService(tmpDir, 30, true)
-	hs.stopChan = make(chan struct{}) // Enable for testing
+			hs.SetHandler(func(prompt, channel, chatID string) *tools.ToolResult {
+				return tt.result
+			})
 
-	hs.SetHandler(func(prompt, channel, chatID string) *tools.ToolResult {
-		return &tools.ToolResult{
-			ForLLM:  "Heartbeat completed successfully",
-			ForUser: "",
-			Silent:  true,
-			IsError: false,
-			Async:   false,
-		}
-	})
+			os.WriteFile(filepath.Join(tmpDir, "HEARTBEAT.md"), []byte("Test task"), 0o644)
+			hs.executeHeartbeat()
 
-	// Create HEARTBEAT.md
-	os.WriteFile(filepath.Join(tmpDir, "HEARTBEAT.md"), []byte("Test task"), 0o644)
-
-	hs.executeHeartbeat()
-
-	// Check log file for completion message
-	logFile := filepath.Join(tmpDir, "heartbeat.log")
-	data, err := os.ReadFile(logFile)
-	if err != nil {
-		t.Fatalf("Failed to read log file: %v", err)
-	}
-
-	logContent := string(data)
-	if logContent == "" {
-		t.Error("Expected log file to contain completion message")
+			logFile := filepath.Join(tmpDir, "heartbeat.log")
+			data, err := os.ReadFile(logFile)
+			if err != nil {
+				t.Fatalf("Failed to read log file: %v", err)
+			}
+			if string(data) == "" {
+				t.Errorf("Expected log file to contain %s", tt.wantLog)
+			}
+		})
 	}
 }
 
@@ -219,3 +204,47 @@ func TestHeartbeatFilePath(t *testing.T) {
 		t.Errorf("Expected HEARTBEAT.md at %s, but it doesn't exist", expectedPath)
 	}
 }
+
+func TestBuildPrompt_DefaultTemplateStaysIdle(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "heartbeat-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	hs := NewHeartbeatService(tmpDir, 30, true)
+	hs.createDefaultHeartbeatTemplate()
+
+	if prompt := hs.buildPrompt(); prompt != "" {
+		t.Fatalf("buildPrompt() = %q, want empty prompt for untouched default template", prompt)
+	}
+}
+
+func TestBuildPrompt_UserTasksAfterMarkerProducePrompt(t *testing.T) {
+	tmpDir, err := os.MkdirTemp("", "heartbeat-test-*")
+	if err != nil {
+		t.Fatalf("Failed to create temp dir: %v", err)
+	}
+	defer os.RemoveAll(tmpDir)
+
+	hs := NewHeartbeatService(tmpDir, 30, true)
+	hs.createDefaultHeartbeatTemplate()
+
+	path := filepath.Join(tmpDir, "HEARTBEAT.md")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("Failed to read HEARTBEAT.md: %v", err)
+	}
+	updated := string(data) + "\n- Check unread Feishu messages\n"
+	if err := os.WriteFile(path, []byte(updated), 0o644); err != nil {
+		t.Fatalf("Failed to update HEARTBEAT.md: %v", err)
+	}
+
+	prompt := hs.buildPrompt()
+	if prompt == "" {
+		t.Fatal("buildPrompt() = empty, want non-empty prompt when user tasks are present")
+	}
+	if !strings.Contains(prompt, "Check unread Feishu messages") {
+		t.Fatalf("prompt = %q, want user task content", prompt)
+	}
+}
diff --git a/pkg/identity/identity.go b/pkg/identity/identity.go
index 6bc09c210..045725a8d 100644
--- a/pkg/identity/identity.go
+++ b/pkg/identity/identity.go
@@ -59,6 +59,9 @@ func MatchAllowed(sender bus.SenderInfo, allowed string) bool {
 		}
 	}
 
+	// Keep track of explicit username format
+	isAtUsername := strings.HasPrefix(allowed, "@")
+
 	// Strip leading "@" for username matching
 	trimmed := strings.TrimPrefix(allowed, "@")
 
@@ -75,11 +78,9 @@ func MatchAllowed(sender bus.SenderInfo, allowed string) bool {
 		return true
 	}
 
-	// Match against Username
-	if sender.Username != "" {
-		if sender.Username == trimmed || sender.Username == allowedUser {
-			return true
-		}
+	// Match against Username only when explicitly requested via "@username"
+	if isAtUsername && sender.Username != "" && sender.Username == trimmed {
+		return true
 	}
 
 	// Match compound sender format against allowed parts
@@ -93,13 +94,18 @@ func MatchAllowed(sender bus.SenderInfo, allowed string) bool {
 	return false
 }
 
-// isNumeric returns true if s consists entirely of digits.
+// isNumeric returns true if s consists entirely of digits, allowing for an optional leading minus sign
+// (required for Telegram group/channel IDs like -1001234567890).
 func isNumeric(s string) bool {
 	if s == "" {
 		return false
 	}
-	for _, r := range s {
-		if r < '0' || r > '9' {
+	start := 0
+	if s[0] == '-' && len(s) > 1 {
+		start = 1
+	}
+	for i := start; i < len(s); i++ {
+		if s[i] < '0' || s[i] > '9' {
 			return false
 		}
 	}
diff --git a/pkg/identity/identity_test.go b/pkg/identity/identity_test.go
index 3d24bd794..c60402d19 100644
--- a/pkg/identity/identity_test.go
+++ b/pkg/identity/identity_test.go
@@ -97,6 +97,15 @@ func TestMatchAllowed(t *testing.T) {
 			allowed: "654321",
 			want:    false,
 		},
+		{
+			name: "negative numeric ID matches PlatformID",
+			sender: bus.SenderInfo{
+				Platform:   "telegram",
+				PlatformID: "-1001234567890",
+			},
+			allowed: "-1001234567890",
+			want:    true,
+		},
 		// Username matching
 		{
 			name:    "@username matches Username",
@@ -104,6 +113,16 @@ func TestMatchAllowed(t *testing.T) {
 			allowed: "@alice",
 			want:    true,
 		},
+		{
+			name: "plain entry does not match username",
+			sender: bus.SenderInfo{
+				Platform:   "discord",
+				PlatformID: "999999",
+				Username:   "123456",
+			},
+			allowed: "123456",
+			want:    false,
+		},
 		{
 			name:    "@username does not match",
 			sender:  telegramSender,
@@ -123,6 +142,16 @@ func TestMatchAllowed(t *testing.T) {
 			allowed: "999|alice",
 			want:    true,
 		},
+		{
+			name: "compound matches by ID when username differs",
+			sender: bus.SenderInfo{
+				Platform:   "discord",
+				PlatformID: "123456",
+				Username:   "not123456",
+			},
+			allowed: "123456|alice",
+			want:    true,
+		},
 		{
 			name:    "compound does not match",
 			sender:  telegramSender,
@@ -218,6 +247,9 @@ func TestIsNumeric(t *testing.T) {
 		{"abc", false},
 		{"12a34", false},
 		{"telegram", false},
+		{"-1001234567890", true},
+		{"-", false},
+		{"-12a34", false},
 	}
 
 	for _, tt := range tests {
diff --git a/pkg/logger/logger.go b/pkg/logger/logger.go
index 56dc87a53..eeb1436de 100644
--- a/pkg/logger/logger.go
+++ b/pkg/logger/logger.go
@@ -1,24 +1,25 @@
 package logger
 
 import (
-	"encoding/json"
 	"fmt"
-	"log"
 	"os"
+	"path/filepath"
 	"runtime"
+	"strconv"
 	"strings"
 	"sync"
-	"time"
+
+	"github.com/rs/zerolog"
 )
 
-type LogLevel int
+type LogLevel = zerolog.Level
 
 const (
-	DEBUG LogLevel = iota
-	INFO
-	WARN
-	ERROR
-	FATAL
+	DEBUG = zerolog.DebugLevel
+	INFO  = zerolog.InfoLevel
+	WARN  = zerolog.WarnLevel
+	ERROR = zerolog.ErrorLevel
+	FATAL = zerolog.FatalLevel
 )
 
 var (
@@ -31,34 +32,72 @@ var (
 	}
 
 	currentLevel = INFO
-	logger       *Logger
+	logger       zerolog.Logger
+	fileLogger   zerolog.Logger
+	logFile      *os.File
 	once         sync.Once
 	mu           sync.RWMutex
 )
 
-type Logger struct {
-	file *os.File
-}
-
-type LogEntry struct {
-	Level     string         `json:"level"`
-	Timestamp string         `json:"timestamp"`
-	Component string         `json:"component,omitempty"`
-	Message   string         `json:"message"`
-	Fields    map[string]any `json:"fields,omitempty"`
-	Caller    string         `json:"caller,omitempty"`
-}
-
 func init() {
 	once.Do(func() {
-		logger = &Logger{}
+		zerolog.SetGlobalLevel(zerolog.InfoLevel)
+
+		consoleWriter := zerolog.ConsoleWriter{
+			Out:        os.Stdout,
+			TimeFormat: "15:04:05", // TODO: make it configurable???
+
+			// Custom formatter to handle multiline strings and JSON objects
+			FormatFieldValue: formatFieldValue,
+		}
+
+		logger = zerolog.New(consoleWriter).With().Timestamp().Caller().Logger()
+		fileLogger = zerolog.Logger{}
 	})
 }
 
+func formatFieldValue(i any) string {
+	var s string
+
+	switch val := i.(type) {
+	case string:
+		s = val
+	case []byte:
+		s = string(val)
+	default:
+		return fmt.Sprintf("%v", i)
+	}
+
+	if unquoted, err := strconv.Unquote(s); err == nil {
+		s = unquoted
+	}
+
+	if strings.Contains(s, "\n") {
+		return fmt.Sprintf("\n%s", s)
+	}
+
+	if strings.Contains(s, " ") {
+		if (strings.HasPrefix(s, "{") && strings.HasSuffix(s, "}")) ||
+			(strings.HasPrefix(s, "[") && strings.HasSuffix(s, "]")) {
+			return s
+		}
+		return fmt.Sprintf("%q", s)
+	}
+
+	return s
+}
+
 func SetLevel(level LogLevel) {
 	mu.Lock()
 	defer mu.Unlock()
 	currentLevel = level
+	zerolog.SetGlobalLevel(level)
+}
+
+func SetConsoleLevel(level LogLevel) {
+	mu.Lock()
+	defer mu.Unlock()
+	logger = logger.Level(level)
 }
 
 func GetLevel() LogLevel {
@@ -67,21 +106,56 @@ func GetLevel() LogLevel {
 	return currentLevel
 }
 
+// ParseLevel converts a case-insensitive level name to a LogLevel.
+// Returns the level and true if valid, or (INFO, false) if unrecognized.
+func ParseLevel(s string) (LogLevel, bool) {
+	switch strings.ToLower(strings.TrimSpace(s)) {
+	case "debug":
+		return DEBUG, true
+	case "info":
+		return INFO, true
+	case "warn", "warning":
+		return WARN, true
+	case "error":
+		return ERROR, true
+	case "fatal":
+		return FATAL, true
+	default:
+		return INFO, false
+	}
+}
+
+// SetLevelFromString sets the log level from a string value.
+// If the string is empty or not a recognized level name, the current level is kept.
+func SetLevelFromString(s string) {
+	if s == "" {
+		return
+	}
+	if level, ok := ParseLevel(s); ok {
+		SetLevel(level)
+	}
+}
+
 func EnableFileLogging(filePath string) error {
 	mu.Lock()
 	defer mu.Unlock()
 
-	file, err := os.OpenFile(filePath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
+	if err := os.MkdirAll(filepath.Dir(filePath), 0o755); err != nil {
+		return fmt.Errorf("failed to create log directory: %w", err)
+	}
+
+	newFile, err := os.OpenFile(filePath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
 	if err != nil {
 		return fmt.Errorf("failed to open log file: %w", err)
 	}
 
-	if logger.file != nil {
-		logger.file.Close()
+	// Close old file if exists
+	if logFile != nil {
+		logFile.Close()
 	}
 
-	logger.file = file
-	log.Println("File logging enabled:", filePath)
+	logFile = newFile
+	fileLogger = zerolog.New(logFile).With().Timestamp().Caller().Logger()
 	return nil
 }
 
@@ -89,10 +163,58 @@ func DisableFileLogging() {
 	mu.Lock()
 	defer mu.Unlock()
 
-	if logger.file != nil {
-		logger.file.Close()
-		logger.file = nil
-		log.Println("File logging disabled")
+	if logFile != nil {
+		logFile.Close()
+		logFile = nil
+	}
+	fileLogger = zerolog.Logger{}
+}
+
+func getCallerSkip() int {
+	for i := 2; i < 15; i++ {
+		pc, file, _, ok := runtime.Caller(i)
+		if !ok {
+			continue
+		}
+
+		fn := runtime.FuncForPC(pc)
+		if fn == nil {
+			continue
+		}
+
+		// bypass common loggers
+		if strings.HasSuffix(file, "/logger.go") ||
+			strings.HasSuffix(file, "/logger_3rd_party.go") ||
+			strings.HasSuffix(file, "/log.go") {
+			continue
+		}
+
+		funcName := fn.Name()
+		if strings.HasPrefix(funcName, "runtime.") {
+			continue
+		}
+
+		return i - 1
+	}
+
+	return 3
+}
+
+//nolint:zerologlint
+func getEvent(logger zerolog.Logger, level LogLevel) *zerolog.Event {
+	switch level {
+	case zerolog.DebugLevel:
+		return logger.Debug()
+	case zerolog.InfoLevel:
+		return logger.Info()
+	case zerolog.WarnLevel:
+		return logger.Warn()
+	case zerolog.ErrorLevel:
+		return logger.Error()
+	case zerolog.FatalLevel:
+		return logger.Fatal()
+	default:
+		return logger.Info()
 	}
 }
 
@@ -101,63 +223,55 @@ func logMessage(level LogLevel, component string, message string, fields map[str
 		return
 	}
 
-	entry := LogEntry{
-		Level:     logLevelNames[level],
-		Timestamp: time.Now().UTC().Format(time.RFC3339),
-		Component: component,
-		Message:   message,
-		Fields:    fields,
+	skip := getCallerSkip()
+
+	event := getEvent(logger, level)
+
+	if component != "" {
+		event.Str("component", component)
 	}
 
-	if pc, file, line, ok := runtime.Caller(2); ok {
-		fn := runtime.FuncForPC(pc)
-		if fn != nil {
-			entry.Caller = fmt.Sprintf("%s:%d (%s)", file, line, fn.Name())
+	appendFields(event, fields)
+	event.CallerSkipFrame(skip).Msg(message)
+
+	// Also log to file if enabled
+	if fileLogger.GetLevel() != zerolog.NoLevel {
+		fileEvent := getEvent(fileLogger, level)
+
+		if component != "" {
+			fileEvent.Str("component", component)
 		}
+		// fileEvent.Str("caller", fmt.Sprintf("%s:%d (%s)", callerFile, callerLine, callerFunc))
+
+		appendFields(fileEvent, fields)
+		fileEvent.CallerSkipFrame(skip).Msg(message)
 	}
 
-	if logger.file != nil {
-		jsonData, err := json.Marshal(entry)
-		if err == nil {
-			logger.file.Write(append(jsonData, '\n'))
-		}
-	}
-
-	var fieldStr string
-	if len(fields) > 0 {
-		fieldStr = " " + formatFields(fields)
-	} else {
-		fieldStr = ""
-	}
-
-	logLine := fmt.Sprintf("[%s] [%s]%s %s%s",
-		entry.Timestamp,
-		logLevelNames[level],
-		formatComponent(component),
-		message,
-		fieldStr,
-	)
-
-	log.Println(logLine)
-
 	if level == FATAL {
 		os.Exit(1)
 	}
 }
 
-func formatComponent(component string) string {
-	if component == "" {
-		return ""
-	}
-	return fmt.Sprintf(" %s:", component)
-}
-
-func formatFields(fields map[string]any) string {
-	parts := make([]string, 0, len(fields))
+func appendFields(event *zerolog.Event, fields map[string]any) {
 	for k, v := range fields {
-		parts = append(parts, fmt.Sprintf("%s=%v", k, v))
+		// Type switch to avoid double JSON serialization of strings
+		switch val := v.(type) {
+		case error:
+			event.Str(k, val.Error())
+		case string:
+			event.Str(k, val)
+		case int:
+			event.Int(k, val)
+		case int64:
+			event.Int64(k, val)
+		case float64:
+			event.Float64(k, val)
+		case bool:
+			event.Bool(k, val)
+		default:
+			event.Interface(k, v) // Fallback for struct, slice and maps
+		}
 	}
-	return fmt.Sprintf("{%s}", strings.Join(parts, ", "))
 }
 
 func Debug(message string) {
@@ -168,6 +282,10 @@ func DebugC(component string, message string) {
 	logMessage(DEBUG, component, message, nil)
 }
 
+func Debugf(message string, ss ...any) {
+	logMessage(DEBUG, "", fmt.Sprintf(message, ss...), nil)
+}
+
 func DebugF(message string, fields map[string]any) {
 	logMessage(DEBUG, "", message, fields)
 }
@@ -188,6 +306,10 @@ func InfoF(message string, fields map[string]any) {
 	logMessage(INFO, "", message, fields)
 }
 
+func Infof(message string, ss ...any) {
+	logMessage(INFO, "", fmt.Sprintf(message, ss...), nil)
+}
+
 func InfoCF(component string, message string, fields map[string]any) {
 	logMessage(INFO, component, message, fields)
 }
@@ -216,6 +338,10 @@ func ErrorC(component string, message string) {
 	logMessage(ERROR, component, message, nil)
 }
 
+func Errorf(message string, ss ...any) {
+	logMessage(ERROR, "", fmt.Sprintf(message, ss...), nil)
+}
+
 func ErrorF(message string, fields map[string]any) {
 	logMessage(ERROR, "", message, fields)
 }
@@ -232,6 +358,10 @@ func FatalC(component string, message string) {
 	logMessage(FATAL, component, message, nil)
 }
 
+func Fatalf(message string, ss ...any) {
+	logMessage(FATAL, "", fmt.Sprintf(message, ss...), nil)
+}
+
 func FatalF(message string, fields map[string]any) {
 	logMessage(FATAL, "", message, fields)
 }
diff --git a/pkg/logger/logger_3rd_party.go b/pkg/logger/logger_3rd_party.go
new file mode 100644
index 000000000..d0cb178c5
--- /dev/null
+++ b/pkg/logger/logger_3rd_party.go
@@ -0,0 +1,108 @@
+// this file is for compatible with 3rd party loggers, should not be called in PicoClaw project
+
+package logger
+
+import (
+	"fmt"
+	"regexp"
+)
+
+// botTokenRe matches the bot ID prefix and the secret part of a Telegram bot token.
+// Groups: 1 = "bot<id>:", 2 = first 4 chars of secret, 3 = middle, 4 = last 4 chars.
+var botTokenRe = regexp.MustCompile(`(bot\d+:)([A-Za-z0-9_-]{4})[A-Za-z0-9_-]{12,}([A-Za-z0-9_-]{4})`)
+
+// maskSecrets replaces any embedded bot tokens in s with a redacted placeholder
+// that keeps the first and last 4 characters of the secret for identification.
+func maskSecrets(s string) string {
+	return botTokenRe.ReplaceAllString(s, "${1}${2}****${3}")
+}
+
+// Logger implements common Logger interface
+type Logger struct {
+	component string
+	levels    map[int]LogLevel
+}
+
+// Debug logs debug messages
+func (b *Logger) Debug(v ...any) {
+	logMessage(DEBUG, b.component, maskSecrets(fmt.Sprint(v...)), nil)
+}
+
+// Info logs info messages
+func (b *Logger) Info(v ...any) {
+	logMessage(INFO, b.component, maskSecrets(fmt.Sprint(v...)), nil)
+}
+
+// Warn logs warning messages
+func (b *Logger) Warn(v ...any) {
+	logMessage(WARN, b.component, maskSecrets(fmt.Sprint(v...)), nil)
+}
+
+// Error logs error messages
+func (b *Logger) Error(v ...any) {
+	logMessage(ERROR, b.component, maskSecrets(fmt.Sprint(v...)), nil)
+}
+
+// Debugf logs formatted debug messages
+func (b *Logger) Debugf(format string, v ...any) {
+	logMessage(DEBUG, b.component, maskSecrets(fmt.Sprintf(format, v...)), nil)
+}
+
+// Infof logs formatted info messages
+func (b *Logger) Infof(format string, v ...any) {
+	logMessage(INFO, b.component, maskSecrets(fmt.Sprintf(format, v...)), nil)
+}
+
+// Warnf logs formatted warning messages
+func (b *Logger) Warnf(format string, v ...any) {
+	logMessage(WARN, b.component, maskSecrets(fmt.Sprintf(format, v...)), nil)
+}
+
+// Warningf logs formatted warning messages
+func (b *Logger) Warningf(format string, v ...any) {
+	logMessage(WARN, b.component, maskSecrets(fmt.Sprintf(format, v...)), nil)
+}
+
+// Errorf logs formatted error messages
+func (b *Logger) Errorf(format string, v ...any) {
+	logMessage(ERROR, b.component, maskSecrets(fmt.Sprintf(format, v...)), nil)
+}
+
+// Fatalf logs formatted fatal messages and exits
+func (b *Logger) Fatalf(format string, v ...any) {
+	logMessage(FATAL, b.component, maskSecrets(fmt.Sprintf(format, v...)), nil)
+}
+
+// Log logs a message at a given level with caller information
+// the func name must be this because 3rd party loggers expect this
+// msgL: message level (DEBUG, INFO, WARN, ERROR, FATAL)
+// caller: unused parameter reserved for compatibility
+// format: format string
+// a: format arguments
+//
+//nolint:goprintffuncname
+func (b *Logger) Log(msgL, caller int, format string, a ...any) {
+	level := LogLevel(msgL)
+	if b.levels != nil {
+		if lvl, ok := b.levels[msgL]; ok {
+			level = lvl
+		}
+	}
+	logMessage(level, b.component, maskSecrets(fmt.Sprintf(format, a...)), nil)
+}
+
+// Sync flushes log buffer (no-op for this implementation)
+func (b *Logger) Sync() error {
+	return nil
+}
+
+// WithLevels sets log levels mapping for this logger
+func (b *Logger) WithLevels(levels map[int]LogLevel) *Logger {
+	b.levels = levels
+	return b
+}
+
+// NewLogger creates a new logger instance with optional component name
+func NewLogger(component string) *Logger {
+	return &Logger{component: component}
+}
diff --git a/pkg/logger/logger_test.go b/pkg/logger/logger_test.go
index 6e6f8dfa8..6ad3a8dd6 100644
--- a/pkg/logger/logger_test.go
+++ b/pkg/logger/logger_test.go
@@ -1,7 +1,12 @@
 package logger
 
 import (
+	"bytes"
+	"encoding/json"
+	"errors"
 	"testing"
+
+	"github.com/rs/zerolog"
 )
 
 func TestLogLevelFiltering(t *testing.T) {
@@ -123,17 +128,240 @@ func TestLoggerHelperFunctions(t *testing.T) {
 	SetLevel(INFO)
 
 	Debug("This should not log")
+	Debugf("this should not log")
 	Info("This should log")
 	Warn("This should log")
 	Error("This should log")
 
 	InfoC("test", "Component message")
 	InfoF("Fields message", map[string]any{"key": "value"})
+	Infof("test from %v", "Infof")
 
 	WarnC("test", "Warning with component")
 	ErrorF("Error with fields", map[string]any{"error": "test"})
+	Errorf("test from %v", "Errorf")
 
 	SetLevel(DEBUG)
 	DebugC("test", "Debug with component")
+	Debugf("test from %v", "Debugf")
 	WarnF("Warning with fields", map[string]any{"key": "value"})
 }
+
+func TestFormatFieldValue(t *testing.T) {
+	tests := []struct {
+		name     string
+		input    any
+		expected string
+	}{
+		// Basic types test (default case of the switch)
+		{
+			name:     "Integer Type",
+			input:    42,
+			expected: "42",
+		},
+		{
+			name:     "Boolean Type",
+			input:    true,
+			expected: "true",
+		},
+		{
+			name:     "Unsupported Struct Type",
+			input:    struct{ A int }{A: 1},
+			expected: "{1}",
+		},
+
+		// Simple strings and byte slices test
+		{
+			name:     "Simple string without spaces",
+			input:    "simple_value",
+			expected: "simple_value",
+		},
+		{
+			name:     "Simple byte slice",
+			input:    []byte("byte_value"),
+			expected: "byte_value",
+		},
+
+		// Unquoting test (strconv.Unquote)
+		{
+			name:     "Quoted string",
+			input:    `"quoted_value"`,
+			expected: "quoted_value",
+		},
+
+		// Strings with newline (\n) test
+		{
+			name:     "String with newline",
+			input:    "line1\nline2",
+			expected: "\nline1\nline2",
+		},
+		{
+			name:     "Quoted string with newline (Unquote -> newline)",
+			input:    `"line1\nline2"`, // Escaped \n that Unquote will resolve
+			expected: "\nline1\nline2",
+		},
+
+		// Strings with spaces test (which should be quoted)
+		{
+			name:     "String with spaces",
+			input:    "hello world",
+			expected: `"hello world"`,
+		},
+		{
+			name:     "Quoted string with spaces (Unquote -> has spaces -> Re-quote)",
+			input:    `"hello world"`,
+			expected: `"hello world"`,
+		},
+
+		// JSON formats test (strings with spaces that start/end with brackets)
+		{
+			name:     "Valid JSON object",
+			input:    `{"key": "value"}`,
+			expected: `{"key": "value"}`,
+		},
+		{
+			name:     "Valid JSON array",
+			input:    `[1, 2, "three"]`,
+			expected: `[1, 2, "three"]`,
+		},
+		{
+			name:     "Fake JSON (starts with { but doesn't end with })",
+			input:    `{"key": "value"`, // Missing closing bracket, has spaces
+			expected: `"{\"key\": \"value\""`,
+		},
+		{
+			name:     "Empty JSON (object)",
+			input:    `{ }`,
+			expected: `{ }`,
+		},
+
+		// 7. Edge Cases
+		{
+			name:     "Empty string",
+			input:    "",
+			expected: "",
+		},
+		{
+			name:     "Whitespace only string",
+			input:    "   ",
+			expected: `"   "`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			actual := formatFieldValue(tt.input)
+			if actual != tt.expected {
+				t.Errorf("formatFieldValue() = %q, expected %q", actual, tt.expected)
+			}
+		})
+	}
+}
+
+func TestDefaultLevelIsInfo(t *testing.T) {
+	// The package-level default (before any SetLevel call) should be INFO.
+	// Because earlier tests may have changed it, we just verify the constant is wired correctly.
+	if logLevelNames[INFO] != "INFO" {
+		t.Errorf("INFO constant mapped to %q, want \"INFO\"", logLevelNames[INFO])
+	}
+}
+
+func TestParseLevelValid(t *testing.T) {
+	tests := []struct {
+		input string
+		want  LogLevel
+	}{
+		{"debug", DEBUG},
+		{"DEBUG", DEBUG},
+		{"Debug", DEBUG},
+		{"info", INFO},
+		{"INFO", INFO},
+		{"warn", WARN},
+		{"WARN", WARN},
+		{"warning", WARN},
+		{"WARNING", WARN},
+		{"error", ERROR},
+		{"ERROR", ERROR},
+		{"fatal", FATAL},
+		{"FATAL", FATAL},
+		{"  info  ", INFO},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			got, ok := ParseLevel(tt.input)
+			if !ok {
+				t.Fatalf("ParseLevel(%q) returned ok=false, want true", tt.input)
+			}
+			if got != tt.want {
+				t.Errorf("ParseLevel(%q) = %v, want %v", tt.input, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestParseLevelInvalid(t *testing.T) {
+	tests := []string{"", "garbage", "verbose", "trace", "critical"}
+
+	for _, input := range tests {
+		t.Run(input, func(t *testing.T) {
+			_, ok := ParseLevel(input)
+			if ok {
+				t.Errorf("ParseLevel(%q) returned ok=true, want false", input)
+			}
+		})
+	}
+}
+
+func TestSetLevelFromString(t *testing.T) {
+	initialLevel := GetLevel()
+	defer SetLevel(initialLevel)
+
+	// Valid string changes the level
+	SetLevel(INFO)
+	SetLevelFromString("error")
+	if got := GetLevel(); got != ERROR {
+		t.Errorf("after SetLevelFromString(\"error\"): GetLevel() = %v, want ERROR", got)
+	}
+
+	// Empty string is a no-op
+	SetLevelFromString("")
+	if got := GetLevel(); got != ERROR {
+		t.Errorf("after SetLevelFromString(\"\"): GetLevel() = %v, want ERROR (unchanged)", got)
+	}
+
+	// Invalid string is a no-op
+	SetLevelFromString("garbage")
+	if got := GetLevel(); got != ERROR {
+		t.Errorf("after SetLevelFromString(\"garbage\"): GetLevel() = %v, want ERROR (unchanged)", got)
+	}
+
+	// Case-insensitive
+	SetLevelFromString("FATAL")
+	if got := GetLevel(); got != FATAL {
+		t.Errorf("after SetLevelFromString(\"FATAL\"): GetLevel() = %v, want FATAL", got)
+	}
+}
+
+func TestAppendFields_ErrorUsesErrorString(t *testing.T) {
+	var buf bytes.Buffer
+	l := zerolog.New(&buf)
+
+	event := l.Info()
+	appendFields(event, map[string]any{"error": errors.New("transcription request failed")})
+	event.Msg("test")
+
+	lines := bytes.Split(bytes.TrimSpace(buf.Bytes()), []byte("\n"))
+	if len(lines) == 0 {
+		t.Fatal("expected log output, got none")
+	}
+
+	var got map[string]any
+	if err := json.Unmarshal(lines[0], &got); err != nil {
+		t.Fatalf("unmarshal log line: %v", err)
+	}
+
+	if got["error"] != "transcription request failed" {
+		t.Fatalf("error field = %#v, want %q", got["error"], "transcription request failed")
+	}
+}
diff --git a/pkg/logger/panic.go b/pkg/logger/panic.go
new file mode 100644
index 000000000..e53e4351a
--- /dev/null
+++ b/pkg/logger/panic.go
@@ -0,0 +1,36 @@
+package logger
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime/debug"
+	"time"
+)
+
+func InitPanic(filePath string) (func(), error) {
+	if err := os.MkdirAll(filepath.Dir(filePath), 0o755); err != nil {
+		return nil, fmt.Errorf("failed to create log directory: %w", err)
+	}
+	writer := initPanicFile(filePath)
+	if writer == nil {
+		return nil, fmt.Errorf("failed to create log file: %s", filePath)
+	}
+	return func() {
+		defer writer.Close()
+		if err := recover(); err != nil {
+			now := time.Now().Format("2006-01-02 15:04:05")
+			stack := debug.Stack()
+			logMsg := "\n\n====================\n[" + now + "] PANIC OCCURRED: " + fmt.Sprintf(
+				"%v",
+				err,
+			) + "\n" + string(
+				stack,
+			)
+
+			writer.Write([]byte(logMsg))
+
+			os.Exit(1)
+		}
+	}, nil
+}
diff --git a/pkg/logger/panic_unix.go b/pkg/logger/panic_unix.go
new file mode 100644
index 000000000..48f393b45
--- /dev/null
+++ b/pkg/logger/panic_unix.go
@@ -0,0 +1,22 @@
+//go:build !windows
+
+package logger
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"golang.org/x/sys/unix"
+)
+
+func initPanicFile(panicFile string) io.WriteCloser {
+	file, err := os.OpenFile(panicFile, os.O_WRONLY|os.O_CREATE|os.O_APPEND|os.O_SYNC, 0o600)
+	if err != nil {
+		panic(fmt.Sprintf("error in open panic: %v", err))
+	}
+	if err = unix.Dup2(int(file.Fd()), int(os.Stderr.Fd())); err != nil {
+		panic(fmt.Sprintf("error in syscall.Dup2: %v", err))
+	}
+	return file
+}
diff --git a/pkg/logger/panic_win.go b/pkg/logger/panic_win.go
new file mode 100644
index 000000000..1e6eead02
--- /dev/null
+++ b/pkg/logger/panic_win.go
@@ -0,0 +1,25 @@
+//go:build windows
+// +build windows
+
+package logger
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"golang.org/x/sys/windows"
+)
+
+func initPanicFile(panicFile string) io.WriteCloser {
+	file, err := os.OpenFile(panicFile, os.O_WRONLY|os.O_CREATE|os.O_SYNC|os.O_APPEND, 0o600)
+	if err != nil {
+		panic(fmt.Sprintf("error in open panic: %v", err))
+	}
+	err = windows.SetStdHandle(windows.STD_ERROR_HANDLE, windows.Handle(file.Fd()))
+	if err != nil {
+		panic(fmt.Sprintf("Failed to redirect stderr to file: %v", err))
+	}
+	os.Stderr = file
+	return file
+}
diff --git a/pkg/mcp/manager.go b/pkg/mcp/manager.go
new file mode 100644
index 000000000..7b63cc979
--- /dev/null
+++ b/pkg/mcp/manager.go
@@ -0,0 +1,532 @@
+package mcp
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// headerTransport is an http.RoundTripper that adds custom headers to requests
+type headerTransport struct {
+	base    http.RoundTripper
+	headers map[string]string
+}
+
+func (t *headerTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	// Clone the request to avoid modifying the original
+	req = req.Clone(req.Context())
+
+	// Add custom headers
+	for key, value := range t.headers {
+		req.Header.Set(key, value)
+	}
+
+	// Use the base transport
+	base := t.base
+	if base == nil {
+		base = http.DefaultTransport
+	}
+	return base.RoundTrip(req)
+}
+
+// loadEnvFile loads environment variables from a file in .env format
+// Each line should be in the format: KEY=value
+// Lines starting with # are comments
+// Empty lines are ignored
+func loadEnvFile(path string) (map[string]string, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("failed to open env file: %w", err)
+	}
+	defer file.Close()
+
+	envVars := make(map[string]string)
+	scanner := bufio.NewScanner(file)
+	lineNum := 0
+
+	for scanner.Scan() {
+		lineNum++
+		line := strings.TrimSpace(scanner.Text())
+
+		// Skip empty lines and comments
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+
+		// Parse KEY=value
+		parts := strings.SplitN(line, "=", 2)
+		if len(parts) != 2 {
+			return nil, fmt.Errorf("invalid format at line %d: %s", lineNum, line)
+		}
+
+		key := strings.TrimSpace(parts[0])
+		value := strings.TrimSpace(parts[1])
+
+		if key == "" {
+			return nil, fmt.Errorf("invalid format at line %d: empty key", lineNum)
+		}
+
+		// Remove surrounding quotes if present
+		if len(value) >= 2 {
+			if (value[0] == '"' && value[len(value)-1] == '"') ||
+				(value[0] == '\'' && value[len(value)-1] == '\'') {
+				value = value[1 : len(value)-1]
+			}
+		}
+
+		envVars[key] = value
+	}
+
+	if err := scanner.Err(); err != nil {
+		return nil, fmt.Errorf("error reading env file: %w", err)
+	}
+
+	return envVars, nil
+}
+
+// ServerConnection represents a connection to an MCP server
+type ServerConnection struct {
+	Name    string
+	Client  *mcp.Client
+	Session *mcp.ClientSession
+	Tools   []*mcp.Tool
+}
+
+// Manager manages multiple MCP server connections
+type Manager struct {
+	servers map[string]*ServerConnection
+	mu      sync.RWMutex
+	closed  atomic.Bool    // changed from bool to atomic.Bool to avoid TOCTOU race
+	wg      sync.WaitGroup // tracks in-flight CallTool calls
+}
+
+// NewManager creates a new MCP manager
+func NewManager() *Manager {
+	return &Manager{
+		servers: make(map[string]*ServerConnection),
+	}
+}
+
+// LoadFromConfig loads MCP servers from configuration
+func (m *Manager) LoadFromConfig(ctx context.Context, cfg *config.Config) error {
+	return m.LoadFromMCPConfig(ctx, cfg.Tools.MCP, cfg.WorkspacePath())
+}
+
+// LoadFromMCPConfig loads MCP servers from MCP configuration and workspace path.
+// This is the minimal dependency version that doesn't require the full Config object.
+func (m *Manager) LoadFromMCPConfig(
+	ctx context.Context,
+	mcpCfg config.MCPConfig,
+	workspacePath string,
+) error {
+	if !mcpCfg.Enabled {
+		logger.InfoCF("mcp", "MCP integration is disabled", nil)
+		return nil
+	}
+
+	if len(mcpCfg.Servers) == 0 {
+		logger.InfoCF("mcp", "No MCP servers configured", nil)
+		return nil
+	}
+
+	logger.InfoCF("mcp", "Initializing MCP servers",
+		map[string]any{
+			"count": len(mcpCfg.Servers),
+		})
+
+	var wg sync.WaitGroup
+	errs := make(chan error, len(mcpCfg.Servers))
+	enabledCount := 0
+
+	for name, serverCfg := range mcpCfg.Servers {
+		if !serverCfg.Enabled {
+			logger.DebugCF("mcp", "Skipping disabled server",
+				map[string]any{
+					"server": name,
+				})
+			continue
+		}
+
+		enabledCount++
+		wg.Add(1)
+		go func(name string, serverCfg config.MCPServerConfig, workspace string) {
+			defer wg.Done()
+
+			// Resolve relative envFile paths relative to workspace
+			if serverCfg.EnvFile != "" && !filepath.IsAbs(serverCfg.EnvFile) {
+				if workspace == "" {
+					err := fmt.Errorf(
+						"workspace path is empty while resolving relative envFile %q for server %s",
+						serverCfg.EnvFile,
+						name,
+					)
+					logger.ErrorCF("mcp", "Invalid MCP server configuration",
+						map[string]any{
+							"server":   name,
+							"env_file": serverCfg.EnvFile,
+							"error":    err.Error(),
+						})
+					errs <- err
+					return
+				}
+				serverCfg.EnvFile = filepath.Join(workspace, serverCfg.EnvFile)
+			}
+
+			if err := m.ConnectServer(ctx, name, serverCfg); err != nil {
+				logger.ErrorCF("mcp", "Failed to connect to MCP server",
+					map[string]any{
+						"server": name,
+						"error":  err.Error(),
+					})
+				errs <- fmt.Errorf("failed to connect to server %s: %w", name, err)
+			}
+		}(name, serverCfg, workspacePath)
+	}
+
+	wg.Wait()
+	close(errs)
+
+	// Collect errors
+	var allErrors []error
+	for err := range errs {
+		allErrors = append(allErrors, err)
+	}
+
+	connectedCount := len(m.GetServers())
+
+	// If all enabled servers failed to connect, return aggregated error
+	if enabledCount > 0 && connectedCount == 0 {
+		logger.ErrorCF("mcp", "All MCP servers failed to connect",
+			map[string]any{
+				"failed": len(allErrors),
+				"total":  enabledCount,
+			})
+		return errors.Join(allErrors...)
+	}
+
+	if len(allErrors) > 0 {
+		logger.WarnCF("mcp", "Some MCP servers failed to connect",
+			map[string]any{
+				"failed":    len(allErrors),
+				"connected": connectedCount,
+				"total":     enabledCount,
+			})
+		// Don't fail completely if some servers successfully connected
+	}
+
+	logger.InfoCF("mcp", "MCP server initialization complete",
+		map[string]any{
+			"connected": connectedCount,
+			"total":     enabledCount,
+		})
+
+	return nil
+}
+
+// ConnectServer connects to a single MCP server
+func (m *Manager) ConnectServer(
+	ctx context.Context,
+	name string,
+	cfg config.MCPServerConfig,
+) error {
+	logger.InfoCF("mcp", "Connecting to MCP server",
+		map[string]any{
+			"server":     name,
+			"command":    cfg.Command,
+			"args_count": len(cfg.Args),
+		})
+
+	// Create client
+	client := mcp.NewClient(&mcp.Implementation{
+		Name:    "picoclaw",
+		Version: "1.0.0",
+	}, nil)
+
+	// Create transport based on configuration
+	// Auto-detect transport type if not explicitly specified
+	var transport mcp.Transport
+	transportType := cfg.Type
+
+	// Auto-detect: if URL is provided, use SSE; if command is provided, use stdio
+	if transportType == "" {
+		if cfg.URL != "" {
+			transportType = "sse"
+		} else if cfg.Command != "" {
+			transportType = "stdio"
+		} else {
+			return fmt.Errorf("either URL or command must be provided")
+		}
+	}
+
+	switch transportType {
+	case "sse", "http":
+		if cfg.URL == "" {
+			return fmt.Errorf("URL is required for SSE/HTTP transport")
+		}
+		logger.DebugCF("mcp", "Using SSE/HTTP transport",
+			map[string]any{
+				"server": name,
+				"url":    cfg.URL,
+			})
+
+		sseTransport := &mcp.StreamableClientTransport{
+			Endpoint: cfg.URL,
+		}
+
+		// Add custom headers if provided
+		if len(cfg.Headers) > 0 {
+			// Create a custom HTTP client with header-injecting transport
+			sseTransport.HTTPClient = &http.Client{
+				Transport: &headerTransport{
+					base:    http.DefaultTransport,
+					headers: cfg.Headers,
+				},
+			}
+			logger.DebugCF("mcp", "Added custom HTTP headers",
+				map[string]any{
+					"server":       name,
+					"header_count": len(cfg.Headers),
+				})
+		}
+
+		transport = sseTransport
+	case "stdio":
+		if cfg.Command == "" {
+			return fmt.Errorf("command is required for stdio transport")
+		}
+		logger.DebugCF("mcp", "Using stdio transport",
+			map[string]any{
+				"server":  name,
+				"command": cfg.Command,
+			})
+		// Create command with context
+		cmd := exec.CommandContext(ctx, cfg.Command, cfg.Args...)
+
+		// Build environment variables with proper override semantics
+		// Use a map to ensure config variables override file variables
+		envMap := make(map[string]string)
+
+		// Start with parent process environment
+		for _, e := range cmd.Environ() {
+			if idx := strings.Index(e, "="); idx > 0 {
+				envMap[e[:idx]] = e[idx+1:]
+			}
+		}
+
+		// Load environment variables from file if specified
+		if cfg.EnvFile != "" {
+			envVars, err := loadEnvFile(cfg.EnvFile)
+			if err != nil {
+				return fmt.Errorf("failed to load env file %s: %w", cfg.EnvFile, err)
+			}
+			for k, v := range envVars {
+				envMap[k] = v
+			}
+			logger.DebugCF("mcp", "Loaded environment variables from file",
+				map[string]any{
+					"server":    name,
+					"envFile":   cfg.EnvFile,
+					"var_count": len(envVars),
+				})
+		}
+
+		// Environment variables from config override those from file
+		for k, v := range cfg.Env {
+			envMap[k] = v
+		}
+
+		// Convert map to slice
+		env := make([]string, 0, len(envMap))
+		for k, v := range envMap {
+			env = append(env, fmt.Sprintf("%s=%s", k, v))
+		}
+		cmd.Env = env
+
+		transport = &mcp.CommandTransport{Command: cmd}
+	default:
+		return fmt.Errorf(
+			"unsupported transport type: %s (supported: stdio, sse, http)",
+			transportType,
+		)
+	}
+
+	// Connect to server
+	session, err := client.Connect(ctx, transport, nil)
+	if err != nil {
+		return fmt.Errorf("failed to connect: %w", err)
+	}
+
+	// Get server info
+	initResult := session.InitializeResult()
+	logger.InfoCF("mcp", "Connected to MCP server",
+		map[string]any{
+			"server":        name,
+			"serverName":    initResult.ServerInfo.Name,
+			"serverVersion": initResult.ServerInfo.Version,
+			"protocol":      initResult.ProtocolVersion,
+		})
+
+	// List available tools if supported
+	var tools []*mcp.Tool
+	if initResult.Capabilities.Tools != nil {
+		for tool, err := range session.Tools(ctx, nil) {
+			if err != nil {
+				logger.WarnCF("mcp", "Error listing tool",
+					map[string]any{
+						"server": name,
+						"error":  err.Error(),
+					})
+				continue
+			}
+			tools = append(tools, tool)
+		}
+
+		logger.InfoCF("mcp", "Listed tools from MCP server",
+			map[string]any{
+				"server":    name,
+				"toolCount": len(tools),
+			})
+	}
+
+	// Store connection
+	m.mu.Lock()
+	m.servers[name] = &ServerConnection{
+		Name:    name,
+		Client:  client,
+		Session: session,
+		Tools:   tools,
+	}
+	m.mu.Unlock()
+
+	return nil
+}
+
+// GetServers returns all connected servers
+func (m *Manager) GetServers() map[string]*ServerConnection {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	result := make(map[string]*ServerConnection, len(m.servers))
+	for k, v := range m.servers {
+		result[k] = v
+	}
+	return result
+}
+
+// GetServer returns a specific server connection
+func (m *Manager) GetServer(name string) (*ServerConnection, bool) {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	conn, ok := m.servers[name]
+	return conn, ok
+}
+
+// CallTool calls a tool on a specific server
+func (m *Manager) CallTool(
+	ctx context.Context,
+	serverName, toolName string,
+	arguments map[string]any,
+) (*mcp.CallToolResult, error) {
+	// Check if closed before acquiring lock (fast path)
+	if m.closed.Load() {
+		return nil, fmt.Errorf("manager is closed")
+	}
+
+	m.mu.RLock()
+	// Double-check after acquiring lock to prevent TOCTOU race
+	if m.closed.Load() {
+		m.mu.RUnlock()
+		return nil, fmt.Errorf("manager is closed")
+	}
+	conn, ok := m.servers[serverName]
+	if ok {
+		m.wg.Add(1) // Add to WaitGroup while holding the lock
+	}
+	m.mu.RUnlock()
+
+	if !ok {
+		return nil, fmt.Errorf("server %s not found", serverName)
+	}
+	defer m.wg.Done()
+
+	params := &mcp.CallToolParams{
+		Name:      toolName,
+		Arguments: arguments,
+	}
+
+	result, err := conn.Session.CallTool(ctx, params)
+	if err != nil {
+		return nil, fmt.Errorf("failed to call tool: %w", err)
+	}
+
+	return result, nil
+}
+
+// Close closes all server connections
+func (m *Manager) Close() error {
+	// Use Swap to atomically set closed=true and get the previous value
+	// This prevents TOCTOU race with CallTool's closed check
+	if m.closed.Swap(true) {
+		return nil // already closed
+	}
+
+	// Wait for all in-flight CallTool calls to finish before closing sessions
+	// After closed=true is set, no new CallTool can start (they check closed first)
+	m.wg.Wait()
+
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	logger.InfoCF("mcp", "Closing all MCP server connections",
+		map[string]any{
+			"count": len(m.servers),
+		})
+
+	var errs []error
+	for name, conn := range m.servers {
+		if err := conn.Session.Close(); err != nil {
+			logger.ErrorCF("mcp", "Failed to close server connection",
+				map[string]any{
+					"server": name,
+					"error":  err.Error(),
+				})
+			errs = append(errs, fmt.Errorf("server %s: %w", name, err))
+		}
+	}
+
+	m.servers = make(map[string]*ServerConnection)
+
+	if len(errs) > 0 {
+		return fmt.Errorf("failed to close %d server(s): %w", len(errs), errors.Join(errs...))
+	}
+
+	return nil
+}
+
+// GetAllTools returns all tools from all connected servers
+func (m *Manager) GetAllTools() map[string][]*mcp.Tool {
+	m.mu.RLock()
+	defer m.mu.RUnlock()
+
+	result := make(map[string][]*mcp.Tool)
+	for name, conn := range m.servers {
+		if len(conn.Tools) > 0 {
+			result[name] = conn.Tools
+		}
+	}
+	return result
+}
diff --git a/pkg/mcp/manager_test.go b/pkg/mcp/manager_test.go
new file mode 100644
index 000000000..f353942ab
--- /dev/null
+++ b/pkg/mcp/manager_test.go
@@ -0,0 +1,308 @@
+package mcp
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestLoadEnvFile(t *testing.T) {
+	tests := []struct {
+		name      string
+		content   string
+		expected  map[string]string
+		expectErr bool
+	}{
+		{
+			name: "basic env file",
+			content: `API_KEY=secret123
+DATABASE_URL=postgres://localhost/db
+PORT=8080`,
+			expected: map[string]string{
+				"API_KEY":      "secret123",
+				"DATABASE_URL": "postgres://localhost/db",
+				"PORT":         "8080",
+			},
+			expectErr: false,
+		},
+		{
+			name: "with comments and empty lines",
+			content: `# This is a comment
+API_KEY=secret123
+
+# Another comment
+DATABASE_URL=postgres://localhost/db
+
+PORT=8080`,
+			expected: map[string]string{
+				"API_KEY":      "secret123",
+				"DATABASE_URL": "postgres://localhost/db",
+				"PORT":         "8080",
+			},
+			expectErr: false,
+		},
+		{
+			name: "with quoted values",
+			content: `API_KEY="secret with spaces"
+NAME='single quoted'
+PLAIN=no-quotes`,
+			expected: map[string]string{
+				"API_KEY": "secret with spaces",
+				"NAME":    "single quoted",
+				"PLAIN":   "no-quotes",
+			},
+			expectErr: false,
+		},
+		{
+			name: "with spaces around equals",
+			content: `API_KEY = secret123
+DATABASE_URL= postgres://localhost/db
+PORT =8080`,
+			expected: map[string]string{
+				"API_KEY":      "secret123",
+				"DATABASE_URL": "postgres://localhost/db",
+				"PORT":         "8080",
+			},
+			expectErr: false,
+		},
+		{
+			name:      "invalid format - no equals",
+			content:   `INVALID_LINE`,
+			expectErr: true,
+		},
+		{
+			name:      "empty file",
+			content:   ``,
+			expected:  map[string]string{},
+			expectErr: false,
+		},
+		{
+			name: "only comments",
+			content: `# Comment 1
+# Comment 2`,
+			expected:  map[string]string{},
+			expectErr: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tmpDir := t.TempDir()
+			envFile := filepath.Join(tmpDir, ".env")
+
+			if err := os.WriteFile(envFile, []byte(tt.content), 0o644); err != nil {
+				t.Fatalf("Failed to create test file: %v", err)
+			}
+
+			result, err := loadEnvFile(envFile)
+
+			if tt.expectErr {
+				if err == nil {
+					t.Errorf("Expected error but got none")
+				}
+				return
+			}
+
+			if err != nil {
+				t.Errorf("Unexpected error: %v", err)
+				return
+			}
+
+			if len(result) != len(tt.expected) {
+				t.Errorf("Expected %d variables, got %d", len(tt.expected), len(result))
+			}
+
+			for key, expectedValue := range tt.expected {
+				if actualValue, ok := result[key]; !ok {
+					t.Errorf("Expected key %s not found", key)
+				} else if actualValue != expectedValue {
+					t.Errorf("For key %s: expected %q, got %q", key, expectedValue, actualValue)
+				}
+			}
+		})
+	}
+}
+
+func TestLoadEnvFileNotFound(t *testing.T) {
+	_, err := loadEnvFile("/nonexistent/file.env")
+	if err == nil {
+		t.Error("Expected error for nonexistent file")
+	}
+}
+
+func TestEnvFilePriority(t *testing.T) {
+	// Create a temporary .env file
+	tmpDir := t.TempDir()
+	envFile := filepath.Join(tmpDir, ".env")
+
+	envContent := `API_KEY=from_file
+DATABASE_URL=from_file
+SHARED_VAR=from_file`
+
+	if err := os.WriteFile(envFile, []byte(envContent), 0o644); err != nil {
+		t.Fatalf("Failed to create .env file: %v", err)
+	}
+
+	// Load envFile
+	envVars, err := loadEnvFile(envFile)
+	if err != nil {
+		t.Fatalf("Failed to load env file: %v", err)
+	}
+
+	// Verify envFile variables
+	if envVars["API_KEY"] != "from_file" {
+		t.Errorf("Expected API_KEY=from_file, got %s", envVars["API_KEY"])
+	}
+
+	// Simulate config.Env overriding envFile
+	configEnv := map[string]string{
+		"SHARED_VAR": "from_config",
+		"NEW_VAR":    "from_config",
+	}
+
+	// Merge: envFile first, then config overrides
+	merged := make(map[string]string)
+	for k, v := range envVars {
+		merged[k] = v
+	}
+	for k, v := range configEnv {
+		merged[k] = v
+	}
+
+	// Verify priority: config.Env should override envFile
+	if merged["SHARED_VAR"] != "from_config" {
+		t.Errorf(
+			"Expected SHARED_VAR=from_config (config should override file), got %s",
+			merged["SHARED_VAR"],
+		)
+	}
+	if merged["API_KEY"] != "from_file" {
+		t.Errorf("Expected API_KEY=from_file, got %s", merged["API_KEY"])
+	}
+	if merged["NEW_VAR"] != "from_config" {
+		t.Errorf("Expected NEW_VAR=from_config, got %s", merged["NEW_VAR"])
+	}
+}
+
+func TestLoadFromMCPConfig_EmptyWorkspaceWithRelativeEnvFile(t *testing.T) {
+	mgr := NewManager()
+
+	mcpCfg := config.MCPConfig{
+		ToolConfig: config.ToolConfig{
+			Enabled: true,
+		},
+		Servers: map[string]config.MCPServerConfig{
+			"test-server": {
+				Enabled: true,
+				Command: "echo",
+				Args:    []string{"ok"},
+				EnvFile: ".env",
+			},
+		},
+	}
+
+	err := mgr.LoadFromMCPConfig(context.Background(), mcpCfg, "")
+	if err == nil {
+		t.Fatal("expected error for relative env_file with empty workspace path, got nil")
+	}
+
+	if !strings.Contains(err.Error(), "workspace path is empty") {
+		t.Fatalf("expected workspace path validation error, got: %v", err)
+	}
+}
+
+func TestNewManager_InitialState(t *testing.T) {
+	mgr := NewManager()
+	if mgr == nil {
+		t.Fatal("expected manager instance, got nil")
+	}
+	if len(mgr.GetServers()) != 0 {
+		t.Fatalf("expected no servers on new manager, got %d", len(mgr.GetServers()))
+	}
+}
+
+func TestLoadFromMCPConfig_DisabledOrEmptyServers(t *testing.T) {
+	mgr := NewManager()
+
+	err := mgr.LoadFromMCPConfig(
+		context.Background(),
+		config.MCPConfig{ToolConfig: config.ToolConfig{Enabled: false}},
+		"/tmp",
+	)
+	if err != nil {
+		t.Fatalf("expected nil error when MCP disabled, got: %v", err)
+	}
+
+	err = mgr.LoadFromMCPConfig(
+		context.Background(),
+		config.MCPConfig{ToolConfig: config.ToolConfig{Enabled: true}},
+		"/tmp",
+	)
+	if err != nil {
+		t.Fatalf("expected nil error when no servers configured, got: %v", err)
+	}
+}
+
+func TestGetServers_ReturnsCopy(t *testing.T) {
+	mgr := NewManager()
+	mgr.servers["s1"] = &ServerConnection{Name: "s1"}
+
+	servers := mgr.GetServers()
+	delete(servers, "s1")
+
+	if _, ok := mgr.GetServer("s1"); !ok {
+		t.Fatal("expected internal manager state to remain unchanged")
+	}
+}
+
+func TestGetAllTools_FiltersEmptyTools(t *testing.T) {
+	mgr := NewManager()
+	mgr.servers["empty"] = &ServerConnection{Name: "empty", Tools: nil}
+	mgr.servers["with-tools"] = &ServerConnection{Name: "with-tools", Tools: []*sdkmcp.Tool{{}}}
+
+	all := mgr.GetAllTools()
+	if _, ok := all["empty"]; ok {
+		t.Fatal("expected server without tools to be excluded")
+	}
+	if _, ok := all["with-tools"]; !ok {
+		t.Fatal("expected server with tools to be included")
+	}
+}
+
+func TestCallTool_ErrorsForClosedOrMissingServer(t *testing.T) {
+	t.Run("manager closed", func(t *testing.T) {
+		mgr := NewManager()
+		mgr.closed.Store(true)
+
+		_, err := mgr.CallTool(context.Background(), "s1", "tool", nil)
+		if err == nil || !strings.Contains(err.Error(), "manager is closed") {
+			t.Fatalf("expected manager closed error, got: %v", err)
+		}
+	})
+
+	t.Run("server missing", func(t *testing.T) {
+		mgr := NewManager()
+
+		_, err := mgr.CallTool(context.Background(), "missing", "tool", nil)
+		if err == nil || !strings.Contains(err.Error(), "not found") {
+			t.Fatalf("expected server not found error, got: %v", err)
+		}
+	})
+}
+
+func TestClose_IdempotentOnEmptyManager(t *testing.T) {
+	mgr := NewManager()
+
+	if err := mgr.Close(); err != nil {
+		t.Fatalf("first close should succeed, got: %v", err)
+	}
+	if err := mgr.Close(); err != nil {
+		t.Fatalf("second close should be idempotent, got: %v", err)
+	}
+}
diff --git a/pkg/media/store.go b/pkg/media/store.go
index 30220986c..78cff8bb6 100644
--- a/pkg/media/store.go
+++ b/pkg/media/store.go
@@ -11,11 +11,25 @@ import (
 	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
+// CleanupPolicy controls how the MediaStore treats the underlying file when
+// a ref is released or expires.
+type CleanupPolicy string
+
+const (
+	// CleanupPolicyDeleteOnCleanup means the file is store-managed and may be
+	// deleted once the final ref for that path is gone.
+	CleanupPolicyDeleteOnCleanup CleanupPolicy = "delete_on_cleanup"
+	// CleanupPolicyForgetOnly means the store should only drop ref mappings and
+	// must never delete the underlying file.
+	CleanupPolicyForgetOnly CleanupPolicy = "forget_only"
+)
+
 // MediaMeta holds metadata about a stored media file.
 type MediaMeta struct {
-	Filename    string
-	ContentType string
-	Source      string // "telegram", "discord", "tool:image-gen", etc.
+	Filename      string
+	ContentType   string
+	Source        string        // "telegram", "discord", "tool:image-gen", etc.
+	CleanupPolicy CleanupPolicy // defaults to CleanupPolicyDeleteOnCleanup
 }
 
 // MediaStore manages the lifecycle of media files associated with processing scopes.
@@ -23,6 +37,7 @@ type MediaStore interface {
 	// Store registers an existing local file under the given scope.
 	// Returns a ref identifier (e.g. "media://<id>").
 	// Store does not move or copy the file; it only records the mapping.
+	// If meta.CleanupPolicy is empty, CleanupPolicyDeleteOnCleanup is assumed.
 	Store(localPath string, meta MediaMeta, scope string) (ref string, err error)
 
 	// Resolve returns the local file path for a given ref.
@@ -43,6 +58,11 @@ type mediaEntry struct {
 	storedAt time.Time
 }
 
+type pathRefState struct {
+	refCount       int
+	deleteEligible bool
+}
+
 // MediaCleanerConfig configures the background TTL cleanup.
 type MediaCleanerConfig struct {
 	Enabled  bool
@@ -57,6 +77,8 @@ type FileMediaStore struct {
 	refs        map[string]mediaEntry
 	scopeToRefs map[string]map[string]struct{}
 	refToScope  map[string]string
+	refToPath   map[string]string
+	pathStates  map[string]pathRefState
 
 	cleanerCfg MediaCleanerConfig
 	stop       chan struct{}
@@ -71,6 +93,8 @@ func NewFileMediaStore() *FileMediaStore {
 		refs:        make(map[string]mediaEntry),
 		scopeToRefs: make(map[string]map[string]struct{}),
 		refToScope:  make(map[string]string),
+		refToPath:   make(map[string]string),
+		pathStates:  make(map[string]pathRefState),
 		nowFunc:     time.Now,
 	}
 }
@@ -81,6 +105,8 @@ func NewFileMediaStoreWithCleanup(cfg MediaCleanerConfig) *FileMediaStore {
 		refs:        make(map[string]mediaEntry),
 		scopeToRefs: make(map[string]map[string]struct{}),
 		refToScope:  make(map[string]string),
+		refToPath:   make(map[string]string),
+		pathStates:  make(map[string]pathRefState),
 		cleanerCfg:  cfg,
 		stop:        make(chan struct{}),
 		nowFunc:     time.Now,
@@ -94,6 +120,7 @@ func (s *FileMediaStore) Store(localPath string, meta MediaMeta, scope string) (
 	}
 
 	ref := "media://" + uuid.New().String()
+	meta.CleanupPolicy = normalizeCleanupPolicy(meta.CleanupPolicy)
 
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -104,6 +131,18 @@ func (s *FileMediaStore) Store(localPath string, meta MediaMeta, scope string) (
 	}
 	s.scopeToRefs[scope][ref] = struct{}{}
 	s.refToScope[ref] = scope
+	s.refToPath[ref] = localPath
+
+	pathState := s.pathStates[localPath]
+	if pathState.refCount == 0 {
+		pathState.deleteEligible = meta.CleanupPolicy == CleanupPolicyDeleteOnCleanup
+	} else if meta.CleanupPolicy == CleanupPolicyForgetOnly {
+		// Be conservative: once a path is borrowed externally, never let this
+		// lifecycle auto-delete it even if store-managed refs also exist.
+		pathState.deleteEligible = false
+	}
+	pathState.refCount++
+	s.pathStates[localPath] = pathState
 
 	return ref, nil
 }
@@ -134,7 +173,8 @@ func (s *FileMediaStore) ResolveWithMeta(ref string) (string, MediaMeta, error)
 
 // ReleaseAll removes all files under the given scope and cleans up mappings.
 // Phase 1 (under lock): remove entries from maps.
-// Phase 2 (no lock): delete files from disk.
+// Phase 2 (no lock): delete store-managed files from disk once their final
+// path ref is gone.
 func (s *FileMediaStore) ReleaseAll(scope string) error {
 	// Phase 1: collect paths and remove from maps under lock
 	var paths []string
@@ -147,11 +187,13 @@ func (s *FileMediaStore) ReleaseAll(scope string) error {
 	}
 
 	for ref := range refs {
+		fallbackPath := ""
 		if entry, exists := s.refs[ref]; exists {
-			paths = append(paths, entry.path)
+			fallbackPath = entry.path
+		}
+		if removablePath, shouldDelete := s.releaseRefLocked(ref, fallbackPath); shouldDelete {
+			paths = append(paths, removablePath)
 		}
-		delete(s.refs, ref)
-		delete(s.refToScope, ref)
 	}
 	delete(s.scopeToRefs, scope)
 	s.mu.Unlock()
@@ -171,7 +213,7 @@ func (s *FileMediaStore) ReleaseAll(scope string) error {
 
 // CleanExpired removes all entries older than MaxAge.
 // Phase 1 (under lock): identify expired entries and remove from maps.
-// Phase 2 (no lock): delete files from disk to minimize lock contention.
+// Phase 2 (no lock): delete store-managed files from disk to minimize lock contention.
 func (s *FileMediaStore) CleanExpired() int {
 	if s.cleanerCfg.MaxAge <= 0 {
 		return 0
@@ -179,8 +221,8 @@ func (s *FileMediaStore) CleanExpired() int {
 
 	// Phase 1: collect expired entries under lock
 	type expiredEntry struct {
-		ref  string
-		path string
+		ref        string
+		deletePath string
 	}
 
 	s.mu.Lock()
@@ -189,8 +231,6 @@ func (s *FileMediaStore) CleanExpired() int {
 
 	for ref, entry := range s.refs {
 		if entry.storedAt.Before(cutoff) {
-			expired = append(expired, expiredEntry{ref: ref, path: entry.path})
-
 			if scope, ok := s.refToScope[ref]; ok {
 				if scopeRefs, ok := s.scopeToRefs[scope]; ok {
 					delete(scopeRefs, ref)
@@ -200,17 +240,23 @@ func (s *FileMediaStore) CleanExpired() int {
 				}
 			}
 
-			delete(s.refs, ref)
-			delete(s.refToScope, ref)
+			expiredItem := expiredEntry{ref: ref}
+			if deletePath, shouldDelete := s.releaseRefLocked(ref, entry.path); shouldDelete {
+				expiredItem.deletePath = deletePath
+			}
+			expired = append(expired, expiredItem)
 		}
 	}
 	s.mu.Unlock()
 
 	// Phase 2: delete files without holding the lock
 	for _, e := range expired {
-		if err := os.Remove(e.path); err != nil && !os.IsNotExist(err) {
+		if e.deletePath == "" {
+			continue
+		}
+		if err := os.Remove(e.deletePath); err != nil && !os.IsNotExist(err) {
 			logger.WarnCF("media", "cleanup: failed to remove file", map[string]any{
-				"path":  e.path,
+				"path":  e.deletePath,
 				"error": err.Error(),
 			})
 		}
@@ -219,6 +265,45 @@ func (s *FileMediaStore) CleanExpired() int {
 	return len(expired)
 }
 
+func normalizeCleanupPolicy(policy CleanupPolicy) CleanupPolicy {
+	switch policy {
+	case "", CleanupPolicyDeleteOnCleanup:
+		return CleanupPolicyDeleteOnCleanup
+	case CleanupPolicyForgetOnly:
+		return CleanupPolicyForgetOnly
+	default:
+		return CleanupPolicyDeleteOnCleanup
+	}
+}
+
+func (s *FileMediaStore) releaseRefLocked(ref, fallbackPath string) (string, bool) {
+	path := fallbackPath
+	if storedPath, ok := s.refToPath[ref]; ok {
+		path = storedPath
+		delete(s.refToPath, ref)
+	}
+
+	delete(s.refs, ref)
+	delete(s.refToScope, ref)
+
+	if path == "" {
+		return "", false
+	}
+
+	pathState, ok := s.pathStates[path]
+	if !ok {
+		return "", false
+	}
+	if pathState.refCount <= 1 {
+		delete(s.pathStates, path)
+		return path, pathState.deleteEligible
+	}
+
+	pathState.refCount--
+	s.pathStates[path] = pathState
+	return "", false
+}
+
 // Start begins the background cleanup goroutine if cleanup is enabled.
 // Safe to call multiple times; only the first call starts the goroutine.
 func (s *FileMediaStore) Start() {
diff --git a/pkg/media/store_test.go b/pkg/media/store_test.go
index 1dcfdf350..dabcc3142 100644
--- a/pkg/media/store_test.go
+++ b/pkg/media/store_test.go
@@ -77,6 +77,106 @@ func TestReleaseAll(t *testing.T) {
 	}
 }
 
+func TestReleaseAllForgetOnlyKeepsFile(t *testing.T) {
+	dir := t.TempDir()
+	store := NewFileMediaStore()
+
+	path := createTempFile(t, dir, "workspace.txt")
+	ref, err := store.Store(path, MediaMeta{
+		Source:        "test",
+		CleanupPolicy: CleanupPolicyForgetOnly,
+	}, "scope1")
+	if err != nil {
+		t.Fatalf("Store failed: %v", err)
+	}
+
+	if err := store.ReleaseAll("scope1"); err != nil {
+		t.Fatalf("ReleaseAll failed: %v", err)
+	}
+
+	if _, err := store.Resolve(ref); err == nil {
+		t.Error("forget-only ref should be unresolvable after release")
+	}
+	if _, err := os.Stat(path); err != nil {
+		t.Errorf("forget-only file should remain on disk: %v", err)
+	}
+}
+
+func TestReleaseAllSharedPathDeletesOnFinalRefOnly(t *testing.T) {
+	dir := t.TempDir()
+	store := NewFileMediaStore()
+
+	path := createTempFile(t, dir, "shared.jpg")
+	refA, err := store.Store(path, MediaMeta{
+		Source:        "test",
+		CleanupPolicy: CleanupPolicyDeleteOnCleanup,
+	}, "scopeA")
+	if err != nil {
+		t.Fatalf("Store(scopeA) failed: %v", err)
+	}
+	refB, err := store.Store(path, MediaMeta{
+		Source:        "test",
+		CleanupPolicy: CleanupPolicyDeleteOnCleanup,
+	}, "scopeB")
+	if err != nil {
+		t.Fatalf("Store(scopeB) failed: %v", err)
+	}
+
+	if err := store.ReleaseAll("scopeA"); err != nil {
+		t.Fatalf("ReleaseAll(scopeA) failed: %v", err)
+	}
+
+	if _, err := store.Resolve(refA); err == nil {
+		t.Error("refA should be unresolvable after ReleaseAll(scopeA)")
+	}
+	if _, err := store.Resolve(refB); err != nil {
+		t.Fatalf("refB should still resolve: %v", err)
+	}
+	if _, err := os.Stat(path); err != nil {
+		t.Errorf("shared file should remain until final ref is released: %v", err)
+	}
+
+	if err := store.ReleaseAll("scopeB"); err != nil {
+		t.Fatalf("ReleaseAll(scopeB) failed: %v", err)
+	}
+	if _, err := os.Stat(path); !os.IsNotExist(err) {
+		t.Error("shared file should be deleted after final ref is released")
+	}
+}
+
+func TestReleaseAllMixedPoliciesKeepsFile(t *testing.T) {
+	dir := t.TempDir()
+	store := NewFileMediaStore()
+
+	path := createTempFile(t, dir, "shared.txt")
+	if _, err := store.Store(path, MediaMeta{
+		Source:        "test",
+		CleanupPolicy: CleanupPolicyDeleteOnCleanup,
+	}, "owned"); err != nil {
+		t.Fatalf("Store(owned) failed: %v", err)
+	}
+	if _, err := store.Store(path, MediaMeta{
+		Source:        "test",
+		CleanupPolicy: CleanupPolicyForgetOnly,
+	}, "borrowed"); err != nil {
+		t.Fatalf("Store(borrowed) failed: %v", err)
+	}
+
+	if err := store.ReleaseAll("owned"); err != nil {
+		t.Fatalf("ReleaseAll(owned) failed: %v", err)
+	}
+	if _, err := os.Stat(path); err != nil {
+		t.Fatalf("mixed-policy file should remain after owned ref release: %v", err)
+	}
+
+	if err := store.ReleaseAll("borrowed"); err != nil {
+		t.Fatalf("ReleaseAll(borrowed) failed: %v", err)
+	}
+	if _, err := os.Stat(path); err != nil {
+		t.Errorf("mixed-policy path should not be auto-deleted: %v", err)
+	}
+}
+
 func TestMultiScopeIsolation(t *testing.T) {
 	dir := t.TempDir()
 	store := NewFileMediaStore()
@@ -293,6 +393,35 @@ func TestCleanExpiredRemovesOldEntries(t *testing.T) {
 	}
 }
 
+func TestCleanExpiredForgetOnlyKeepsFile(t *testing.T) {
+	dir := t.TempDir()
+	now := time.Now()
+	store := newTestStoreWithCleanup(10 * time.Minute)
+	store.nowFunc = func() time.Time { return now.Add(-20 * time.Minute) }
+
+	path := createTempFile(t, dir, "workspace.txt")
+	ref, err := store.Store(path, MediaMeta{
+		Source:        "test",
+		CleanupPolicy: CleanupPolicyForgetOnly,
+	}, "scope1")
+	if err != nil {
+		t.Fatalf("Store failed: %v", err)
+	}
+
+	store.nowFunc = func() time.Time { return now }
+	removed := store.CleanExpired()
+
+	if removed != 1 {
+		t.Errorf("expected 1 removed, got %d", removed)
+	}
+	if _, err := store.Resolve(ref); err == nil {
+		t.Error("expired forget-only ref should be unresolvable")
+	}
+	if _, err := os.Stat(path); err != nil {
+		t.Errorf("forget-only file should remain on disk: %v", err)
+	}
+}
+
 func TestCleanExpiredKeepsNonExpired(t *testing.T) {
 	dir := t.TempDir()
 	now := time.Now()
@@ -346,6 +475,53 @@ func TestCleanExpiredMixedAges(t *testing.T) {
 	}
 }
 
+func TestCleanExpiredSharedPathDeletesOnFinalRefOnly(t *testing.T) {
+	dir := t.TempDir()
+	now := time.Now()
+	store := newTestStoreWithCleanup(10 * time.Minute)
+
+	path := createTempFile(t, dir, "shared.jpg")
+
+	store.nowFunc = func() time.Time { return now.Add(-20 * time.Minute) }
+	oldRef, err := store.Store(path, MediaMeta{
+		Source:        "test",
+		CleanupPolicy: CleanupPolicyDeleteOnCleanup,
+	}, "scope-old")
+	if err != nil {
+		t.Fatalf("Store(old) failed: %v", err)
+	}
+
+	store.nowFunc = func() time.Time { return now }
+	freshRef, err := store.Store(path, MediaMeta{
+		Source:        "test",
+		CleanupPolicy: CleanupPolicyDeleteOnCleanup,
+	}, "scope-fresh")
+	if err != nil {
+		t.Fatalf("Store(fresh) failed: %v", err)
+	}
+
+	removed := store.CleanExpired()
+	if removed != 1 {
+		t.Errorf("expected 1 removed, got %d", removed)
+	}
+	if _, err := store.Resolve(oldRef); err == nil {
+		t.Error("old ref should be gone after cleanup")
+	}
+	if _, err := store.Resolve(freshRef); err != nil {
+		t.Fatalf("fresh ref should still resolve: %v", err)
+	}
+	if _, err := os.Stat(path); err != nil {
+		t.Errorf("shared file should remain while fresh ref exists: %v", err)
+	}
+
+	if err := store.ReleaseAll("scope-fresh"); err != nil {
+		t.Fatalf("ReleaseAll(scope-fresh) failed: %v", err)
+	}
+	if _, err := os.Stat(path); !os.IsNotExist(err) {
+		t.Error("shared file should be deleted after final ref is released")
+	}
+}
+
 func TestCleanExpiredCleansEmptyScopes(t *testing.T) {
 	dir := t.TempDir()
 	now := time.Now()
diff --git a/pkg/media/tempdir.go b/pkg/media/tempdir.go
new file mode 100644
index 000000000..45942b34f
--- /dev/null
+++ b/pkg/media/tempdir.go
@@ -0,0 +1,13 @@
+package media
+
+import (
+	"os"
+	"path/filepath"
+)
+
+const TempDirName = "picoclaw_media"
+
+// TempDir returns the shared temporary directory used for downloaded media.
+func TempDir() string {
+	return filepath.Join(os.TempDir(), TempDirName)
+}
diff --git a/pkg/memory/jsonl.go b/pkg/memory/jsonl.go
new file mode 100644
index 000000000..afe374166
--- /dev/null
+++ b/pkg/memory/jsonl.go
@@ -0,0 +1,460 @@
+package memory
+
+import (
+	"bufio"
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"hash/fnv"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/fileutil"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+const (
+	// numLockShards is the fixed number of mutexes used to serialize
+	// per-session access. Using a sharded array instead of a map keeps
+	// memory bounded regardless of how many sessions are created over
+	// the lifetime of the process — important for a long-running daemon.
+	numLockShards = 64
+
+	// maxLineSize is the maximum size of a single JSON line in a .jsonl
+	// file. Tool results (read_file, web search, etc.) can be large, so
+	// we set a generous limit. The scanner starts at 64 KB and grows
+	// only as needed up to this cap.
+	maxLineSize = 10 * 1024 * 1024 // 10 MB
+)
+
+// sessionMeta holds per-session metadata stored in a .meta.json file.
+type sessionMeta struct {
+	Key       string    `json:"key"`
+	Summary   string    `json:"summary"`
+	Skip      int       `json:"skip"`
+	Count     int       `json:"count"`
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+// JSONLStore implements Store using append-only JSONL files.
+//
+// Each session is stored as two files:
+//
+//	{sanitized_key}.jsonl      — one JSON-encoded message per line, append-only
+//	{sanitized_key}.meta.json  — session metadata (summary, logical truncation offset)
+//
+// Messages are never physically deleted from the JSONL file. Instead,
+// TruncateHistory records a "skip" offset in the metadata file and
+// GetHistory ignores lines before that offset. This keeps all writes
+// append-only, which is both fast and crash-safe.
+type JSONLStore struct {
+	dir   string
+	locks [numLockShards]sync.Mutex
+}
+
+// NewJSONLStore creates a new JSONL-backed store rooted at dir.
+func NewJSONLStore(dir string) (*JSONLStore, error) {
+	err := os.MkdirAll(dir, 0o755)
+	if err != nil {
+		return nil, fmt.Errorf("memory: create directory: %w", err)
+	}
+	return &JSONLStore{dir: dir}, nil
+}
+
+// sessionLock returns a mutex for the given session key.
+// Keys are mapped to a fixed pool of shards via FNV hash, so
+// memory usage is O(1) regardless of total session count.
+func (s *JSONLStore) sessionLock(key string) *sync.Mutex {
+	h := fnv.New32a()
+	h.Write([]byte(key))
+	return &s.locks[h.Sum32()%numLockShards]
+}
+
+func (s *JSONLStore) jsonlPath(key string) string {
+	return filepath.Join(s.dir, sanitizeKey(key)+".jsonl")
+}
+
+func (s *JSONLStore) metaPath(key string) string {
+	return filepath.Join(s.dir, sanitizeKey(key)+".meta.json")
+}
+
+// sanitizeKey converts a session key to a safe filename component.
+// Mirrors pkg/session.sanitizeFilename so that migration paths match.
+// Replaces ':' with '_' (session key separator) and '/' and '\' with '_'
+// so composite IDs (e.g. Telegram forum "chatID/threadID", Slack "channel/thread_ts")
+// do not create subdirectories or break on Windows.
+func sanitizeKey(key string) string {
+	s := strings.ReplaceAll(key, ":", "_")
+	s = strings.ReplaceAll(s, "/", "_")
+	s = strings.ReplaceAll(s, "\\", "_")
+	return s
+}
+
+// readMeta loads the metadata file for a session.
+// Returns a zero-value sessionMeta if the file does not exist.
+func (s *JSONLStore) readMeta(key string) (sessionMeta, error) {
+	data, err := os.ReadFile(s.metaPath(key))
+	if os.IsNotExist(err) {
+		return sessionMeta{Key: key}, nil
+	}
+	if err != nil {
+		return sessionMeta{}, fmt.Errorf("memory: read meta: %w", err)
+	}
+	var meta sessionMeta
+	err = json.Unmarshal(data, &meta)
+	if err != nil {
+		return sessionMeta{}, fmt.Errorf("memory: decode meta: %w", err)
+	}
+	return meta, nil
+}
+
+// writeMeta atomically writes the metadata file using the project's
+// standard WriteFileAtomic (temp + fsync + rename).
+func (s *JSONLStore) writeMeta(key string, meta sessionMeta) error {
+	data, err := json.MarshalIndent(meta, "", "  ")
+	if err != nil {
+		return fmt.Errorf("memory: encode meta: %w", err)
+	}
+	return fileutil.WriteFileAtomic(s.metaPath(key), data, 0o644)
+}
+
+// readMessages reads valid JSON lines from a .jsonl file, skipping
+// the first `skip` lines without unmarshaling them. This avoids the
+// cost of json.Unmarshal on logically truncated messages.
+// Malformed trailing lines (e.g. from a crash) are silently skipped.
+func readMessages(path string, skip int) ([]providers.Message, error) {
+	f, err := os.Open(path)
+	if os.IsNotExist(err) {
+		return []providers.Message{}, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("memory: open jsonl: %w", err)
+	}
+	defer f.Close()
+
+	var msgs []providers.Message
+	scanner := bufio.NewScanner(f)
+	// Allow large lines for tool results (read_file, web search, etc.).
+	scanner.Buffer(make([]byte, 0, 64*1024), maxLineSize)
+
+	lineNum := 0
+	for scanner.Scan() {
+		line := scanner.Bytes()
+		if len(line) == 0 {
+			continue
+		}
+		lineNum++
+		if lineNum <= skip {
+			continue
+		}
+		var msg providers.Message
+		if err := json.Unmarshal(line, &msg); err != nil {
+			// Corrupt line — likely a partial write from a crash.
+			// Log so operators know data was skipped, but don't
+			// fail the entire read; this is the standard JSONL
+			// recovery pattern.
+			log.Printf("memory: skipping corrupt line %d in %s: %v",
+				lineNum, filepath.Base(path), err)
+			continue
+		}
+		msgs = append(msgs, msg)
+	}
+	if scanner.Err() != nil {
+		return nil, fmt.Errorf("memory: scan jsonl: %w", scanner.Err())
+	}
+
+	if msgs == nil {
+		msgs = []providers.Message{}
+	}
+	return msgs, nil
+}
+
+// countLines counts the total number of non-empty lines in a .jsonl file.
+// Used by TruncateHistory to reconcile a stale meta.Count without
+// the overhead of unmarshaling every message.
+func countLines(path string) (int, error) {
+	f, err := os.Open(path)
+	if os.IsNotExist(err) {
+		return 0, nil
+	}
+	if err != nil {
+		return 0, fmt.Errorf("memory: open jsonl: %w", err)
+	}
+	defer f.Close()
+
+	n := 0
+	scanner := bufio.NewScanner(f)
+	scanner.Buffer(make([]byte, 0, 64*1024), maxLineSize)
+	for scanner.Scan() {
+		if len(scanner.Bytes()) > 0 {
+			n++
+		}
+	}
+	return n, scanner.Err()
+}
+
+func (s *JSONLStore) AddMessage(
+	_ context.Context, sessionKey, role, content string,
+) error {
+	return s.addMsg(sessionKey, providers.Message{
+		Role:    role,
+		Content: content,
+	})
+}
+
+func (s *JSONLStore) AddFullMessage(
+	_ context.Context, sessionKey string, msg providers.Message,
+) error {
+	return s.addMsg(sessionKey, msg)
+}
+
+// addMsg is the shared implementation for AddMessage and AddFullMessage.
+func (s *JSONLStore) addMsg(sessionKey string, msg providers.Message) error {
+	l := s.sessionLock(sessionKey)
+	l.Lock()
+	defer l.Unlock()
+
+	// Append the message as a single JSON line.
+	line, err := json.Marshal(msg)
+	if err != nil {
+		return fmt.Errorf("memory: marshal message: %w", err)
+	}
+	line = append(line, '\n')
+
+	f, err := os.OpenFile(
+		s.jsonlPath(sessionKey),
+		os.O_CREATE|os.O_WRONLY|os.O_APPEND,
+		0o644,
+	)
+	if err != nil {
+		return fmt.Errorf("memory: open jsonl for append: %w", err)
+	}
+	_, writeErr := f.Write(line)
+	if writeErr != nil {
+		f.Close()
+		return fmt.Errorf("memory: append message: %w", writeErr)
+	}
+	// Flush to physical storage before closing. This matches the
+	// durability guarantee of writeMeta and rewriteJSONL (which use
+	// WriteFileAtomic with fsync). Without Sync, a power loss could
+	// leave the append in the kernel page cache only — lost on reboot.
+	if syncErr := f.Sync(); syncErr != nil {
+		f.Close()
+		return fmt.Errorf("memory: sync jsonl: %w", syncErr)
+	}
+	if closeErr := f.Close(); closeErr != nil {
+		return fmt.Errorf("memory: close jsonl: %w", closeErr)
+	}
+
+	// Update metadata.
+	meta, err := s.readMeta(sessionKey)
+	if err != nil {
+		return err
+	}
+	now := time.Now()
+	if meta.Count == 0 && meta.CreatedAt.IsZero() {
+		meta.CreatedAt = now
+	}
+	meta.Count++
+	meta.UpdatedAt = now
+
+	return s.writeMeta(sessionKey, meta)
+}
+
+func (s *JSONLStore) GetHistory(
+	_ context.Context, sessionKey string,
+) ([]providers.Message, error) {
+	l := s.sessionLock(sessionKey)
+	l.Lock()
+	defer l.Unlock()
+
+	meta, err := s.readMeta(sessionKey)
+	if err != nil {
+		return nil, err
+	}
+
+	// Pass meta.Skip so readMessages skips those lines without
+	// unmarshaling them — avoids wasted CPU on truncated messages.
+	msgs, err := readMessages(s.jsonlPath(sessionKey), meta.Skip)
+	if err != nil {
+		return nil, err
+	}
+
+	return msgs, nil
+}
+
+func (s *JSONLStore) GetSummary(
+	_ context.Context, sessionKey string,
+) (string, error) {
+	l := s.sessionLock(sessionKey)
+	l.Lock()
+	defer l.Unlock()
+
+	meta, err := s.readMeta(sessionKey)
+	if err != nil {
+		return "", err
+	}
+	return meta.Summary, nil
+}
+
+func (s *JSONLStore) SetSummary(
+	_ context.Context, sessionKey, summary string,
+) error {
+	l := s.sessionLock(sessionKey)
+	l.Lock()
+	defer l.Unlock()
+
+	meta, err := s.readMeta(sessionKey)
+	if err != nil {
+		return err
+	}
+	now := time.Now()
+	if meta.CreatedAt.IsZero() {
+		meta.CreatedAt = now
+	}
+	meta.Summary = summary
+	meta.UpdatedAt = now
+
+	return s.writeMeta(sessionKey, meta)
+}
+
+func (s *JSONLStore) TruncateHistory(
+	_ context.Context, sessionKey string, keepLast int,
+) error {
+	l := s.sessionLock(sessionKey)
+	l.Lock()
+	defer l.Unlock()
+
+	meta, err := s.readMeta(sessionKey)
+	if err != nil {
+		return err
+	}
+
+	// Always reconcile meta.Count with the actual line count on disk.
+	// A crash between the JSONL append and the meta update in addMsg
+	// leaves meta.Count stale (e.g. file has 101 lines but meta says
+	// 100). Counting lines is cheap — no unmarshal, just a scan — and
+	// TruncateHistory is not a hot path, so always re-count.
+	n, countErr := countLines(s.jsonlPath(sessionKey))
+	if countErr != nil {
+		return countErr
+	}
+	meta.Count = n
+
+	if keepLast <= 0 {
+		meta.Skip = meta.Count
+	} else {
+		effective := meta.Count - meta.Skip
+		if keepLast < effective {
+			meta.Skip = meta.Count - keepLast
+		}
+	}
+	meta.UpdatedAt = time.Now()
+
+	return s.writeMeta(sessionKey, meta)
+}
+
+func (s *JSONLStore) SetHistory(
+	_ context.Context,
+	sessionKey string,
+	history []providers.Message,
+) error {
+	l := s.sessionLock(sessionKey)
+	l.Lock()
+	defer l.Unlock()
+
+	meta, err := s.readMeta(sessionKey)
+	if err != nil {
+		return err
+	}
+	now := time.Now()
+	if meta.CreatedAt.IsZero() {
+		meta.CreatedAt = now
+	}
+	meta.Skip = 0
+	meta.Count = len(history)
+	meta.UpdatedAt = now
+
+	// Write meta BEFORE rewriting the JSONL file. If we crash between
+	// the two writes, meta has Skip=0 and the old file is still intact,
+	// so GetHistory reads from line 1 — returning "too many" messages
+	// rather than losing data. The next SetHistory call corrects this.
+	err = s.writeMeta(sessionKey, meta)
+	if err != nil {
+		return err
+	}
+
+	return s.rewriteJSONL(sessionKey, history)
+}
+
+// Compact physically rewrites the JSONL file, dropping all logically
+// skipped lines. This reclaims disk space that accumulates after
+// repeated TruncateHistory calls.
+//
+// It is safe to call at any time; if there is nothing to compact
+// (skip == 0) the method returns immediately.
+func (s *JSONLStore) Compact(
+	_ context.Context, sessionKey string,
+) error {
+	l := s.sessionLock(sessionKey)
+	l.Lock()
+	defer l.Unlock()
+
+	meta, err := s.readMeta(sessionKey)
+	if err != nil {
+		return err
+	}
+	if meta.Skip == 0 {
+		return nil
+	}
+
+	// Read only the active messages, skipping truncated lines
+	// without unmarshaling them.
+	active, err := readMessages(s.jsonlPath(sessionKey), meta.Skip)
+	if err != nil {
+		return err
+	}
+
+	// Write meta BEFORE rewriting the JSONL file. If the process
+	// crashes between the two writes, meta has Skip=0 and the old
+	// (uncompacted) file is still intact, so GetHistory reads from
+	// line 1 — returning previously-truncated messages rather than
+	// losing data. The next Compact or TruncateHistory corrects this.
+	meta.Skip = 0
+	meta.Count = len(active)
+	meta.UpdatedAt = time.Now()
+
+	err = s.writeMeta(sessionKey, meta)
+	if err != nil {
+		return err
+	}
+
+	return s.rewriteJSONL(sessionKey, active)
+}
+
+// rewriteJSONL atomically replaces the JSONL file with the given messages
+// using the project's standard WriteFileAtomic (temp + fsync + rename).
+func (s *JSONLStore) rewriteJSONL(
+	sessionKey string, msgs []providers.Message,
+) error {
+	var buf bytes.Buffer
+	for i, msg := range msgs {
+		line, err := json.Marshal(msg)
+		if err != nil {
+			return fmt.Errorf("memory: marshal message %d: %w", i, err)
+		}
+		buf.Write(line)
+		buf.WriteByte('\n')
+	}
+	return fileutil.WriteFileAtomic(s.jsonlPath(sessionKey), buf.Bytes(), 0o644)
+}
+
+func (s *JSONLStore) Close() error {
+	return nil
+}
diff --git a/pkg/memory/jsonl_test.go b/pkg/memory/jsonl_test.go
new file mode 100644
index 000000000..356ff14ff
--- /dev/null
+++ b/pkg/memory/jsonl_test.go
@@ -0,0 +1,835 @@
+package memory
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func newTestStore(t *testing.T) *JSONLStore {
+	t.Helper()
+	store, err := NewJSONLStore(t.TempDir())
+	if err != nil {
+		t.Fatalf("NewJSONLStore: %v", err)
+	}
+	return store
+}
+
+func TestNewJSONLStore_CreatesDirectory(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "nested", "sessions")
+	store, err := NewJSONLStore(dir)
+	if err != nil {
+		t.Fatalf("NewJSONLStore: %v", err)
+	}
+	defer store.Close()
+
+	info, err := os.Stat(dir)
+	if err != nil {
+		t.Fatalf("Stat: %v", err)
+	}
+	if !info.IsDir() {
+		t.Errorf("expected directory, got file")
+	}
+}
+
+func TestAddMessage_BasicRoundtrip(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	err := store.AddMessage(ctx, "s1", "user", "hello")
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+	err = store.AddMessage(ctx, "s1", "assistant", "hi there")
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "s1")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 2 {
+		t.Fatalf("expected 2 messages, got %d", len(history))
+	}
+	if history[0].Role != "user" || history[0].Content != "hello" {
+		t.Errorf("msg[0] = %+v", history[0])
+	}
+	if history[1].Role != "assistant" || history[1].Content != "hi there" {
+		t.Errorf("msg[1] = %+v", history[1])
+	}
+}
+
+func TestAddMessage_AutoCreatesSession(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	// Adding a message to a non-existent session should work.
+	err := store.AddMessage(ctx, "new-session", "user", "first message")
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "new-session")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 1 {
+		t.Fatalf("expected 1 message, got %d", len(history))
+	}
+}
+
+func TestAddFullMessage_WithToolCalls(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	msg := providers.Message{
+		Role:    "assistant",
+		Content: "Let me search that.",
+		ToolCalls: []providers.ToolCall{
+			{
+				ID:   "call_abc",
+				Type: "function",
+				Function: &providers.FunctionCall{
+					Name:      "web_search",
+					Arguments: `{"q":"golang jsonl"}`,
+				},
+			},
+		},
+	}
+
+	err := store.AddFullMessage(ctx, "tc", msg)
+	if err != nil {
+		t.Fatalf("AddFullMessage: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "tc")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 1 {
+		t.Fatalf("expected 1, got %d", len(history))
+	}
+	if len(history[0].ToolCalls) != 1 {
+		t.Fatalf("expected 1 tool call, got %d", len(history[0].ToolCalls))
+	}
+	tc := history[0].ToolCalls[0]
+	if tc.ID != "call_abc" {
+		t.Errorf("tool call ID = %q", tc.ID)
+	}
+	if tc.Function == nil || tc.Function.Name != "web_search" {
+		t.Errorf("tool call function = %+v", tc.Function)
+	}
+}
+
+func TestAddFullMessage_ToolCallID(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	msg := providers.Message{
+		Role:       "tool",
+		Content:    "search results here",
+		ToolCallID: "call_abc",
+	}
+
+	err := store.AddFullMessage(ctx, "tr", msg)
+	if err != nil {
+		t.Fatalf("AddFullMessage: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "tr")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 1 {
+		t.Fatalf("expected 1, got %d", len(history))
+	}
+	if history[0].ToolCallID != "call_abc" {
+		t.Errorf("ToolCallID = %q", history[0].ToolCallID)
+	}
+}
+
+func TestGetHistory_EmptySession(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	history, err := store.GetHistory(ctx, "nonexistent")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if history == nil {
+		t.Fatal("expected non-nil empty slice")
+	}
+	if len(history) != 0 {
+		t.Errorf("expected 0 messages, got %d", len(history))
+	}
+}
+
+func TestGetHistory_Ordering(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	for i := 0; i < 5; i++ {
+		err := store.AddMessage(
+			ctx, "order",
+			"user",
+			string(rune('a'+i)),
+		)
+		if err != nil {
+			t.Fatalf("AddMessage(%d): %v", i, err)
+		}
+	}
+
+	history, err := store.GetHistory(ctx, "order")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 5 {
+		t.Fatalf("expected 5, got %d", len(history))
+	}
+	for i := 0; i < 5; i++ {
+		expected := string(rune('a' + i))
+		if history[i].Content != expected {
+			t.Errorf("msg[%d].Content = %q, want %q", i, history[i].Content, expected)
+		}
+	}
+}
+
+func TestSetSummary_GetSummary(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	// No summary yet.
+	summary, err := store.GetSummary(ctx, "s1")
+	if err != nil {
+		t.Fatalf("GetSummary: %v", err)
+	}
+	if summary != "" {
+		t.Errorf("expected empty, got %q", summary)
+	}
+
+	// Set a summary.
+	err = store.SetSummary(ctx, "s1", "talked about Go")
+	if err != nil {
+		t.Fatalf("SetSummary: %v", err)
+	}
+
+	summary, err = store.GetSummary(ctx, "s1")
+	if err != nil {
+		t.Fatalf("GetSummary: %v", err)
+	}
+	if summary != "talked about Go" {
+		t.Errorf("summary = %q", summary)
+	}
+
+	// Update summary.
+	err = store.SetSummary(ctx, "s1", "updated summary")
+	if err != nil {
+		t.Fatalf("SetSummary: %v", err)
+	}
+
+	summary, err = store.GetSummary(ctx, "s1")
+	if err != nil {
+		t.Fatalf("GetSummary: %v", err)
+	}
+	if summary != "updated summary" {
+		t.Errorf("summary = %q", summary)
+	}
+}
+
+func TestTruncateHistory_KeepLast(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	for i := 0; i < 10; i++ {
+		err := store.AddMessage(
+			ctx, "trunc",
+			"user",
+			string(rune('a'+i)),
+		)
+		if err != nil {
+			t.Fatalf("AddMessage: %v", err)
+		}
+	}
+
+	err := store.TruncateHistory(ctx, "trunc", 4)
+	if err != nil {
+		t.Fatalf("TruncateHistory: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "trunc")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 4 {
+		t.Fatalf("expected 4, got %d", len(history))
+	}
+	// Should be the last 4: g, h, i, j
+	if history[0].Content != "g" {
+		t.Errorf("first kept = %q, want 'g'", history[0].Content)
+	}
+	if history[3].Content != "j" {
+		t.Errorf("last kept = %q, want 'j'", history[3].Content)
+	}
+}
+
+func TestTruncateHistory_KeepZero(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	for i := 0; i < 5; i++ {
+		err := store.AddMessage(ctx, "empty", "user", "msg")
+		if err != nil {
+			t.Fatalf("AddMessage: %v", err)
+		}
+	}
+
+	err := store.TruncateHistory(ctx, "empty", 0)
+	if err != nil {
+		t.Fatalf("TruncateHistory: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "empty")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 0 {
+		t.Errorf("expected 0, got %d", len(history))
+	}
+}
+
+func TestTruncateHistory_KeepMoreThanExists(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	for i := 0; i < 3; i++ {
+		err := store.AddMessage(ctx, "few", "user", "msg")
+		if err != nil {
+			t.Fatalf("AddMessage: %v", err)
+		}
+	}
+
+	// Keep 100, but only 3 exist — should keep all.
+	err := store.TruncateHistory(ctx, "few", 100)
+	if err != nil {
+		t.Fatalf("TruncateHistory: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "few")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 3 {
+		t.Errorf("expected 3, got %d", len(history))
+	}
+}
+
+func TestSetHistory_ReplacesAll(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	// Add some initial messages.
+	for i := 0; i < 5; i++ {
+		err := store.AddMessage(ctx, "replace", "user", "old")
+		if err != nil {
+			t.Fatalf("AddMessage: %v", err)
+		}
+	}
+
+	// Replace with new history.
+	newHistory := []providers.Message{
+		{Role: "user", Content: "new1"},
+		{Role: "assistant", Content: "new2"},
+	}
+	err := store.SetHistory(ctx, "replace", newHistory)
+	if err != nil {
+		t.Fatalf("SetHistory: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "replace")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 2 {
+		t.Fatalf("expected 2, got %d", len(history))
+	}
+	if history[0].Content != "new1" || history[1].Content != "new2" {
+		t.Errorf("history = %+v", history)
+	}
+}
+
+func TestSetHistory_ResetsSkip(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	// Add messages and truncate.
+	for i := 0; i < 10; i++ {
+		err := store.AddMessage(ctx, "skip-reset", "user", "old")
+		if err != nil {
+			t.Fatalf("AddMessage: %v", err)
+		}
+	}
+	err := store.TruncateHistory(ctx, "skip-reset", 3)
+	if err != nil {
+		t.Fatalf("TruncateHistory: %v", err)
+	}
+
+	// SetHistory should reset skip to 0.
+	newHistory := []providers.Message{
+		{Role: "user", Content: "fresh"},
+	}
+	err = store.SetHistory(ctx, "skip-reset", newHistory)
+	if err != nil {
+		t.Fatalf("SetHistory: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "skip-reset")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 1 {
+		t.Fatalf("expected 1, got %d", len(history))
+	}
+	if history[0].Content != "fresh" {
+		t.Errorf("content = %q", history[0].Content)
+	}
+}
+
+func TestColonInKey(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	err := store.AddMessage(ctx, "telegram:123", "user", "hi")
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "telegram:123")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 1 {
+		t.Fatalf("expected 1, got %d", len(history))
+	}
+
+	// Verify the file is named with underscore.
+	jsonlFile := filepath.Join(store.dir, "telegram_123.jsonl")
+	if _, statErr := os.Stat(jsonlFile); statErr != nil {
+		t.Errorf("expected file %s to exist: %v", jsonlFile, statErr)
+	}
+}
+
+func TestCompact_RemovesSkippedMessages(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	// Write 10 messages, then truncate to keep last 3.
+	for i := 0; i < 10; i++ {
+		err := store.AddMessage(ctx, "compact", "user", string(rune('a'+i)))
+		if err != nil {
+			t.Fatalf("AddMessage: %v", err)
+		}
+	}
+	err := store.TruncateHistory(ctx, "compact", 3)
+	if err != nil {
+		t.Fatalf("TruncateHistory: %v", err)
+	}
+
+	// Before compact: file still has 10 lines.
+	allOnDisk, err := readMessages(store.jsonlPath("compact"), 0)
+	if err != nil {
+		t.Fatalf("readMessages: %v", err)
+	}
+	if len(allOnDisk) != 10 {
+		t.Fatalf("before compact: expected 10 on disk, got %d", len(allOnDisk))
+	}
+
+	// Compact.
+	err = store.Compact(ctx, "compact")
+	if err != nil {
+		t.Fatalf("Compact: %v", err)
+	}
+
+	// After compact: file should have only 3 lines.
+	allOnDisk, err = readMessages(store.jsonlPath("compact"), 0)
+	if err != nil {
+		t.Fatalf("readMessages: %v", err)
+	}
+	if len(allOnDisk) != 3 {
+		t.Fatalf("after compact: expected 3 on disk, got %d", len(allOnDisk))
+	}
+
+	// GetHistory should still return the same 3 messages.
+	history, err := store.GetHistory(ctx, "compact")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 3 {
+		t.Fatalf("expected 3, got %d", len(history))
+	}
+	if history[0].Content != "h" || history[2].Content != "j" {
+		t.Errorf("wrong content: %+v", history)
+	}
+}
+
+func TestCompact_NoOpWhenNoSkip(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	for i := 0; i < 5; i++ {
+		err := store.AddMessage(ctx, "noop", "user", "msg")
+		if err != nil {
+			t.Fatalf("AddMessage: %v", err)
+		}
+	}
+
+	// Compact without prior truncation — should be a no-op.
+	err := store.Compact(ctx, "noop")
+	if err != nil {
+		t.Fatalf("Compact: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "noop")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 5 {
+		t.Errorf("expected 5, got %d", len(history))
+	}
+}
+
+func TestCompact_ThenAppend(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	for i := 0; i < 8; i++ {
+		err := store.AddMessage(ctx, "cap", "user", string(rune('a'+i)))
+		if err != nil {
+			t.Fatalf("AddMessage: %v", err)
+		}
+	}
+
+	err := store.TruncateHistory(ctx, "cap", 2)
+	if err != nil {
+		t.Fatalf("TruncateHistory: %v", err)
+	}
+	err = store.Compact(ctx, "cap")
+	if err != nil {
+		t.Fatalf("Compact: %v", err)
+	}
+
+	// Append after compaction should work correctly.
+	err = store.AddMessage(ctx, "cap", "user", "new")
+	if err != nil {
+		t.Fatalf("AddMessage after compact: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "cap")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 3 {
+		t.Fatalf("expected 3, got %d", len(history))
+	}
+	// g, h (kept from truncation), new (appended after compaction).
+	if history[0].Content != "g" {
+		t.Errorf("first = %q, want 'g'", history[0].Content)
+	}
+	if history[2].Content != "new" {
+		t.Errorf("last = %q, want 'new'", history[2].Content)
+	}
+}
+
+func TestTruncateHistory_StaleMetaCount(t *testing.T) {
+	// Simulates a crash between JSONL append and meta update in addMsg:
+	// file has N+1 lines but meta.Count is still N. TruncateHistory must
+	// reconcile with the real line count so that keepLast is accurate.
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	// Write 10 messages normally (meta.Count = 10).
+	for i := 0; i < 10; i++ {
+		err := store.AddMessage(ctx, "stale", "user", string(rune('a'+i)))
+		if err != nil {
+			t.Fatalf("AddMessage: %v", err)
+		}
+	}
+
+	// Simulate crash: append a line to JSONL but do NOT update meta.
+	// This leaves meta.Count = 10 while the file has 11 lines.
+	jsonlPath := store.jsonlPath("stale")
+	f, err := os.OpenFile(jsonlPath, os.O_WRONLY|os.O_APPEND, 0o644)
+	if err != nil {
+		t.Fatalf("open for append: %v", err)
+	}
+	_, err = f.WriteString(`{"role":"user","content":"orphan"}` + "\n")
+	if err != nil {
+		t.Fatalf("write orphan: %v", err)
+	}
+	f.Close()
+
+	// TruncateHistory(keepLast=4) should keep the last 4 of 11 lines,
+	// not the last 4 of 10.
+	err = store.TruncateHistory(ctx, "stale", 4)
+	if err != nil {
+		t.Fatalf("TruncateHistory: %v", err)
+	}
+
+	history, err := store.GetHistory(ctx, "stale")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 4 {
+		t.Fatalf("expected 4, got %d", len(history))
+	}
+	// Last 4 of [a,b,c,d,e,f,g,h,i,j,orphan] = [h,i,j,orphan]
+	if history[0].Content != "h" {
+		t.Errorf("first kept = %q, want 'h'", history[0].Content)
+	}
+	if history[3].Content != "orphan" {
+		t.Errorf("last kept = %q, want 'orphan'", history[3].Content)
+	}
+}
+
+func TestCrashRecovery_PartialLine(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	// Write a valid message first.
+	err := store.AddMessage(ctx, "crash", "user", "valid")
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+
+	// Simulate a crash by appending a partial JSON line directly.
+	jsonlPath := store.jsonlPath("crash")
+	f, err := os.OpenFile(jsonlPath, os.O_WRONLY|os.O_APPEND, 0o644)
+	if err != nil {
+		t.Fatalf("open for append: %v", err)
+	}
+	_, err = f.WriteString(`{"role":"user","content":"incomple`)
+	if err != nil {
+		t.Fatalf("write partial: %v", err)
+	}
+	f.Close()
+
+	// GetHistory should return only the valid message.
+	history, err := store.GetHistory(ctx, "crash")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 1 {
+		t.Fatalf("expected 1 valid message, got %d", len(history))
+	}
+	if history[0].Content != "valid" {
+		t.Errorf("content = %q", history[0].Content)
+	}
+}
+
+func TestPersistence_AcrossInstances(t *testing.T) {
+	dir := t.TempDir()
+	ctx := context.Background()
+
+	// Write with first instance.
+	store1, err := NewJSONLStore(dir)
+	if err != nil {
+		t.Fatalf("NewJSONLStore: %v", err)
+	}
+	err = store1.AddMessage(ctx, "persist", "user", "remember me")
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+	err = store1.SetSummary(ctx, "persist", "a test session")
+	if err != nil {
+		t.Fatalf("SetSummary: %v", err)
+	}
+	store1.Close()
+
+	// Read with second instance.
+	store2, err := NewJSONLStore(dir)
+	if err != nil {
+		t.Fatalf("NewJSONLStore: %v", err)
+	}
+	defer store2.Close()
+
+	history, err := store2.GetHistory(ctx, "persist")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 1 || history[0].Content != "remember me" {
+		t.Errorf("history = %+v", history)
+	}
+
+	summary, err := store2.GetSummary(ctx, "persist")
+	if err != nil {
+		t.Fatalf("GetSummary: %v", err)
+	}
+	if summary != "a test session" {
+		t.Errorf("summary = %q", summary)
+	}
+}
+
+func TestConcurrent_AddAndRead(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	var wg sync.WaitGroup
+	const goroutines = 10
+	const msgsPerGoroutine = 20
+
+	// Concurrent writes.
+	for g := 0; g < goroutines; g++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for i := 0; i < msgsPerGoroutine; i++ {
+				_ = store.AddMessage(ctx, "concurrent", "user", "msg")
+			}
+		}()
+	}
+	wg.Wait()
+
+	history, err := store.GetHistory(ctx, "concurrent")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	expected := goroutines * msgsPerGoroutine
+	if len(history) != expected {
+		t.Errorf("expected %d messages, got %d", expected, len(history))
+	}
+}
+
+func TestConcurrent_SummarizeRace(t *testing.T) {
+	// Simulates the #704 race: one goroutine adds messages while
+	// another truncates + sets summary — like summarizeSession().
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	// Seed with some messages.
+	for i := 0; i < 20; i++ {
+		err := store.AddMessage(ctx, "race", "user", "seed")
+		if err != nil {
+			t.Fatalf("AddMessage: %v", err)
+		}
+	}
+
+	var wg sync.WaitGroup
+
+	// Writer goroutine (main agent loop).
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for i := 0; i < 50; i++ {
+			_ = store.AddMessage(ctx, "race", "user", "new")
+		}
+	}()
+
+	// Summarizer goroutine (background task).
+	wg.Add(1)
+	go func() {
+		defer wg.Done()
+		for i := 0; i < 10; i++ {
+			_ = store.SetSummary(ctx, "race", "summary")
+			_ = store.TruncateHistory(ctx, "race", 5)
+		}
+	}()
+
+	wg.Wait()
+
+	// Verify the store is still in a consistent state.
+	_, err := store.GetHistory(ctx, "race")
+	if err != nil {
+		t.Fatalf("GetHistory after race: %v", err)
+	}
+	_, err = store.GetSummary(ctx, "race")
+	if err != nil {
+		t.Fatalf("GetSummary after race: %v", err)
+	}
+}
+
+func TestMultipleSessions_Isolation(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	err := store.AddMessage(ctx, "s1", "user", "msg for s1")
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+	err = store.AddMessage(ctx, "s2", "user", "msg for s2")
+	if err != nil {
+		t.Fatalf("AddMessage: %v", err)
+	}
+
+	h1, err := store.GetHistory(ctx, "s1")
+	if err != nil {
+		t.Fatalf("GetHistory s1: %v", err)
+	}
+	h2, err := store.GetHistory(ctx, "s2")
+	if err != nil {
+		t.Fatalf("GetHistory s2: %v", err)
+	}
+
+	if len(h1) != 1 || h1[0].Content != "msg for s1" {
+		t.Errorf("s1 history = %+v", h1)
+	}
+	if len(h2) != 1 || h2[0].Content != "msg for s2" {
+		t.Errorf("s2 history = %+v", h2)
+	}
+}
+
+func BenchmarkAddMessage(b *testing.B) {
+	dir := b.TempDir()
+	store, err := NewJSONLStore(dir)
+	if err != nil {
+		b.Fatalf("NewJSONLStore: %v", err)
+	}
+	defer store.Close()
+	ctx := context.Background()
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_ = store.AddMessage(ctx, "bench", "user", "benchmark message content")
+	}
+}
+
+func BenchmarkGetHistory_100(b *testing.B) {
+	dir := b.TempDir()
+	store, err := NewJSONLStore(dir)
+	if err != nil {
+		b.Fatalf("NewJSONLStore: %v", err)
+	}
+	defer store.Close()
+	ctx := context.Background()
+
+	for i := 0; i < 100; i++ {
+		_ = store.AddMessage(ctx, "bench", "user", "message content")
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = store.GetHistory(ctx, "bench")
+	}
+}
+
+func BenchmarkGetHistory_1000(b *testing.B) {
+	dir := b.TempDir()
+	store, err := NewJSONLStore(dir)
+	if err != nil {
+		b.Fatalf("NewJSONLStore: %v", err)
+	}
+	defer store.Close()
+	ctx := context.Background()
+
+	for i := 0; i < 1000; i++ {
+		_ = store.AddMessage(ctx, "bench", "user", "message content")
+	}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = store.GetHistory(ctx, "bench")
+	}
+}
diff --git a/pkg/memory/migration.go b/pkg/memory/migration.go
new file mode 100644
index 000000000..b64c62a9f
--- /dev/null
+++ b/pkg/memory/migration.go
@@ -0,0 +1,114 @@
+package memory
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// jsonSession mirrors pkg/session.Session for migration purposes.
+type jsonSession struct {
+	Key      string              `json:"key"`
+	Messages []providers.Message `json:"messages"`
+	Summary  string              `json:"summary,omitempty"`
+	Created  time.Time           `json:"created"`
+	Updated  time.Time           `json:"updated"`
+}
+
+// MigrateFromJSON reads legacy sessions/*.json files from sessionsDir,
+// writes them into the Store, and renames each migrated file to
+// .json.migrated as a backup. Returns the number of sessions migrated.
+//
+// Files that fail to parse are logged and skipped. Already-migrated
+// files (.json.migrated) are ignored, making the function idempotent.
+func MigrateFromJSON(
+	ctx context.Context, sessionsDir string, store Store,
+) (int, error) {
+	entries, err := os.ReadDir(sessionsDir)
+	if os.IsNotExist(err) {
+		return 0, nil
+	}
+	if err != nil {
+		return 0, fmt.Errorf("memory: read sessions dir: %w", err)
+	}
+
+	migrated := 0
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+		name := entry.Name()
+		if !strings.HasSuffix(name, ".json") {
+			continue
+		}
+		// Skip JSONL metadata files. They are part of the new storage format,
+		// not legacy session snapshots, and re-importing them would overwrite
+		// the paired .jsonl history with an empty message list.
+		if strings.HasSuffix(name, ".meta.json") {
+			continue
+		}
+		// Skip already-migrated files.
+		if strings.HasSuffix(name, ".migrated") {
+			continue
+		}
+
+		srcPath := filepath.Join(sessionsDir, name)
+
+		data, readErr := os.ReadFile(srcPath)
+		if readErr != nil {
+			log.Printf("memory: migrate: skip %s: %v", name, readErr)
+			continue
+		}
+
+		var sess jsonSession
+		if parseErr := json.Unmarshal(data, &sess); parseErr != nil {
+			log.Printf("memory: migrate: skip %s: %v", name, parseErr)
+			continue
+		}
+
+		// Use the key from the JSON content, not the filename.
+		// Filenames are sanitized (":" → "_") but keys are not.
+		key := sess.Key
+		if key == "" {
+			key = strings.TrimSuffix(name, ".json")
+		}
+
+		// Use SetHistory (atomic replace) instead of per-message
+		// AddFullMessage. This makes migration idempotent: if the
+		// process crashes after writing messages but before the
+		// rename below, a retry replaces the partial data cleanly
+		// instead of duplicating messages.
+		if setErr := store.SetHistory(ctx, key, sess.Messages); setErr != nil {
+			return migrated, fmt.Errorf(
+				"memory: migrate %s: set history: %w",
+				name, setErr,
+			)
+		}
+
+		if sess.Summary != "" {
+			if sumErr := store.SetSummary(ctx, key, sess.Summary); sumErr != nil {
+				return migrated, fmt.Errorf(
+					"memory: migrate %s: set summary: %w",
+					name, sumErr,
+				)
+			}
+		}
+
+		// Rename to .migrated as backup (not delete).
+		renameErr := os.Rename(srcPath, srcPath+".migrated")
+		if renameErr != nil {
+			log.Printf("memory: migrate: rename %s: %v", name, renameErr)
+		}
+
+		migrated++
+	}
+
+	return migrated, nil
+}
diff --git a/pkg/memory/migration_test.go b/pkg/memory/migration_test.go
new file mode 100644
index 000000000..4466c96f9
--- /dev/null
+++ b/pkg/memory/migration_test.go
@@ -0,0 +1,436 @@
+package memory
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func writeJSONSession(
+	t *testing.T, dir string, filename string, sess jsonSession,
+) {
+	t.Helper()
+	data, err := json.MarshalIndent(sess, "", "  ")
+	if err != nil {
+		t.Fatalf("marshal session: %v", err)
+	}
+	err = os.WriteFile(filepath.Join(dir, filename), data, 0o644)
+	if err != nil {
+		t.Fatalf("write session file: %v", err)
+	}
+}
+
+func TestMigrateFromJSON_Basic(t *testing.T) {
+	sessionsDir := t.TempDir()
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	writeJSONSession(t, sessionsDir, "test.json", jsonSession{
+		Key: "test",
+		Messages: []providers.Message{
+			{Role: "user", Content: "hello"},
+			{Role: "assistant", Content: "hi"},
+		},
+		Summary: "A greeting.",
+		Created: time.Now(),
+		Updated: time.Now(),
+	})
+
+	count, err := MigrateFromJSON(ctx, sessionsDir, store)
+	if err != nil {
+		t.Fatalf("MigrateFromJSON: %v", err)
+	}
+	if count != 1 {
+		t.Errorf("expected 1 migrated, got %d", count)
+	}
+
+	history, err := store.GetHistory(ctx, "test")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 2 {
+		t.Fatalf("expected 2 messages, got %d", len(history))
+	}
+	if history[0].Content != "hello" || history[1].Content != "hi" {
+		t.Errorf("unexpected messages: %+v", history)
+	}
+
+	summary, err := store.GetSummary(ctx, "test")
+	if err != nil {
+		t.Fatalf("GetSummary: %v", err)
+	}
+	if summary != "A greeting." {
+		t.Errorf("summary = %q", summary)
+	}
+}
+
+func TestMigrateFromJSON_WithToolCalls(t *testing.T) {
+	sessionsDir := t.TempDir()
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	writeJSONSession(t, sessionsDir, "tools.json", jsonSession{
+		Key: "tools",
+		Messages: []providers.Message{
+			{
+				Role:    "assistant",
+				Content: "Searching...",
+				ToolCalls: []providers.ToolCall{
+					{
+						ID:   "call_1",
+						Type: "function",
+						Function: &providers.FunctionCall{
+							Name:      "web_search",
+							Arguments: `{"q":"test"}`,
+						},
+					},
+				},
+			},
+			{
+				Role:       "tool",
+				Content:    "result",
+				ToolCallID: "call_1",
+			},
+		},
+		Created: time.Now(),
+		Updated: time.Now(),
+	})
+
+	count, err := MigrateFromJSON(ctx, sessionsDir, store)
+	if err != nil {
+		t.Fatalf("MigrateFromJSON: %v", err)
+	}
+	if count != 1 {
+		t.Errorf("expected 1, got %d", count)
+	}
+
+	history, err := store.GetHistory(ctx, "tools")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 2 {
+		t.Fatalf("expected 2 messages, got %d", len(history))
+	}
+	if len(history[0].ToolCalls) != 1 {
+		t.Fatalf("expected 1 tool call, got %d", len(history[0].ToolCalls))
+	}
+	if history[0].ToolCalls[0].Function.Name != "web_search" {
+		t.Errorf("function = %q", history[0].ToolCalls[0].Function.Name)
+	}
+	if history[1].ToolCallID != "call_1" {
+		t.Errorf("ToolCallID = %q", history[1].ToolCallID)
+	}
+}
+
+func TestMigrateFromJSON_MultipleFiles(t *testing.T) {
+	sessionsDir := t.TempDir()
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	for i := 0; i < 3; i++ {
+		key := string(rune('a' + i))
+		writeJSONSession(t, sessionsDir, key+".json", jsonSession{
+			Key:      key,
+			Messages: []providers.Message{{Role: "user", Content: "msg " + key}},
+			Created:  time.Now(),
+			Updated:  time.Now(),
+		})
+	}
+
+	count, err := MigrateFromJSON(ctx, sessionsDir, store)
+	if err != nil {
+		t.Fatalf("MigrateFromJSON: %v", err)
+	}
+	if count != 3 {
+		t.Errorf("expected 3, got %d", count)
+	}
+
+	for i := 0; i < 3; i++ {
+		key := string(rune('a' + i))
+		history, histErr := store.GetHistory(ctx, key)
+		if histErr != nil {
+			t.Fatalf("GetHistory(%q): %v", key, histErr)
+		}
+		if len(history) != 1 {
+			t.Errorf("session %q: expected 1 msg, got %d", key, len(history))
+		}
+	}
+}
+
+func TestMigrateFromJSON_InvalidJSON(t *testing.T) {
+	sessionsDir := t.TempDir()
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	// One valid, one invalid.
+	writeJSONSession(t, sessionsDir, "good.json", jsonSession{
+		Key:      "good",
+		Messages: []providers.Message{{Role: "user", Content: "ok"}},
+		Created:  time.Now(),
+		Updated:  time.Now(),
+	})
+	err := os.WriteFile(
+		filepath.Join(sessionsDir, "bad.json"),
+		[]byte("{invalid json"),
+		0o644,
+	)
+	if err != nil {
+		t.Fatalf("write bad file: %v", err)
+	}
+
+	count, err := MigrateFromJSON(ctx, sessionsDir, store)
+	if err != nil {
+		t.Fatalf("MigrateFromJSON: %v", err)
+	}
+	if count != 1 {
+		t.Errorf("expected 1 (bad file skipped), got %d", count)
+	}
+
+	history, err := store.GetHistory(ctx, "good")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 1 {
+		t.Errorf("expected 1 message, got %d", len(history))
+	}
+}
+
+func TestMigrateFromJSON_RenamesFiles(t *testing.T) {
+	sessionsDir := t.TempDir()
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	writeJSONSession(t, sessionsDir, "rename.json", jsonSession{
+		Key:      "rename",
+		Messages: []providers.Message{{Role: "user", Content: "hi"}},
+		Created:  time.Now(),
+		Updated:  time.Now(),
+	})
+
+	_, err := MigrateFromJSON(ctx, sessionsDir, store)
+	if err != nil {
+		t.Fatalf("MigrateFromJSON: %v", err)
+	}
+
+	// Original .json should not exist.
+	_, statErr := os.Stat(filepath.Join(sessionsDir, "rename.json"))
+	if !os.IsNotExist(statErr) {
+		t.Error("rename.json should have been renamed")
+	}
+	// .json.migrated should exist.
+	_, statErr = os.Stat(
+		filepath.Join(sessionsDir, "rename.json.migrated"),
+	)
+	if statErr != nil {
+		t.Errorf("rename.json.migrated should exist: %v", statErr)
+	}
+}
+
+func TestMigrateFromJSON_Idempotent(t *testing.T) {
+	sessionsDir := t.TempDir()
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	writeJSONSession(t, sessionsDir, "idem.json", jsonSession{
+		Key:      "idem",
+		Messages: []providers.Message{{Role: "user", Content: "once"}},
+		Created:  time.Now(),
+		Updated:  time.Now(),
+	})
+
+	count1, err := MigrateFromJSON(ctx, sessionsDir, store)
+	if err != nil {
+		t.Fatalf("first migration: %v", err)
+	}
+	if count1 != 1 {
+		t.Errorf("first run: expected 1, got %d", count1)
+	}
+
+	// Second run should find only .migrated files, skip them.
+	count2, err := MigrateFromJSON(ctx, sessionsDir, store)
+	if err != nil {
+		t.Fatalf("second migration: %v", err)
+	}
+	if count2 != 0 {
+		t.Errorf("second run: expected 0, got %d", count2)
+	}
+
+	history, err := store.GetHistory(ctx, "idem")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 1 {
+		t.Errorf("expected 1 message, got %d", len(history))
+	}
+}
+
+func TestMigrateFromJSON_ColonInKey(t *testing.T) {
+	sessionsDir := t.TempDir()
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	// File is named telegram_123 (sanitized), but the key inside is telegram:123.
+	writeJSONSession(t, sessionsDir, "telegram_123.json", jsonSession{
+		Key:      "telegram:123",
+		Messages: []providers.Message{{Role: "user", Content: "from telegram"}},
+		Created:  time.Now(),
+		Updated:  time.Now(),
+	})
+
+	count, err := MigrateFromJSON(ctx, sessionsDir, store)
+	if err != nil {
+		t.Fatalf("MigrateFromJSON: %v", err)
+	}
+	if count != 1 {
+		t.Errorf("expected 1, got %d", count)
+	}
+
+	// Accessible via the original key "telegram:123".
+	history, err := store.GetHistory(ctx, "telegram:123")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 1 {
+		t.Fatalf("expected 1 message, got %d", len(history))
+	}
+	if history[0].Content != "from telegram" {
+		t.Errorf("content = %q", history[0].Content)
+	}
+
+	// In the file-based store, "telegram:123" and "telegram_123" both
+	// sanitize to the same filename, so they share storage. This is
+	// expected — the colon-to-underscore mapping is a one-way function.
+	history2, err := store.GetHistory(ctx, "telegram_123")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history2) != 1 {
+		t.Errorf("expected 1 (same file), got %d", len(history2))
+	}
+}
+
+func TestMigrateFromJSON_RetryAfterCrash(t *testing.T) {
+	// Simulates a crash during migration: first run writes messages
+	// but doesn't rename the .json file. Second run must replace
+	// (not duplicate) the messages thanks to SetHistory semantics.
+	sessionsDir := t.TempDir()
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	writeJSONSession(t, sessionsDir, "retry.json", jsonSession{
+		Key: "retry",
+		Messages: []providers.Message{
+			{Role: "user", Content: "one"},
+			{Role: "assistant", Content: "two"},
+		},
+		Created: time.Now(),
+		Updated: time.Now(),
+	})
+
+	// First migration succeeds — writes messages and renames file.
+	count, err := MigrateFromJSON(ctx, sessionsDir, store)
+	if err != nil {
+		t.Fatalf("first migration: %v", err)
+	}
+	if count != 1 {
+		t.Fatalf("expected 1, got %d", count)
+	}
+
+	// Simulate "crash before rename": restore the .json file.
+	src := filepath.Join(sessionsDir, "retry.json.migrated")
+	dst := filepath.Join(sessionsDir, "retry.json")
+	if renameErr := os.Rename(src, dst); renameErr != nil {
+		t.Fatalf("restore .json: %v", renameErr)
+	}
+
+	// Second migration should re-import without duplicating messages.
+	count, err = MigrateFromJSON(ctx, sessionsDir, store)
+	if err != nil {
+		t.Fatalf("second migration: %v", err)
+	}
+	if count != 1 {
+		t.Fatalf("expected 1, got %d", count)
+	}
+
+	history, err := store.GetHistory(ctx, "retry")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	// Must be exactly 2 messages (not 4 from duplication).
+	if len(history) != 2 {
+		t.Fatalf("expected 2 messages (no duplicates), got %d", len(history))
+	}
+	if history[0].Content != "one" || history[1].Content != "two" {
+		t.Errorf("unexpected messages: %+v", history)
+	}
+}
+
+func TestMigrateFromJSON_NonexistentDir(t *testing.T) {
+	store := newTestStore(t)
+	ctx := context.Background()
+
+	count, err := MigrateFromJSON(ctx, "/nonexistent/path", store)
+	if err != nil {
+		t.Fatalf("MigrateFromJSON: %v", err)
+	}
+	if count != 0 {
+		t.Errorf("expected 0, got %d", count)
+	}
+}
+
+func TestMigrateFromJSON_SkipsMetaJSONFiles(t *testing.T) {
+	sessionsDir := t.TempDir()
+	store, err := NewJSONLStore(sessionsDir)
+	if err != nil {
+		t.Fatalf("NewJSONLStore: %v", err)
+	}
+	ctx := context.Background()
+
+	if addErr := store.AddMessage(ctx, "agent:main:pico:direct:pico:test", "user", "keep me"); addErr != nil {
+		t.Fatalf("AddMessage: %v", addErr)
+	}
+	if summaryErr := store.SetSummary(ctx, "agent:main:pico:direct:pico:test", "keep summary"); summaryErr != nil {
+		t.Fatalf("SetSummary: %v", summaryErr)
+	}
+
+	metaPath := filepath.Join(sessionsDir, "agent_main_pico_direct_pico_test.meta.json")
+	if _, statErr := os.Stat(metaPath); statErr != nil {
+		t.Fatalf("meta file missing before migration: %v", statErr)
+	}
+
+	count, err := MigrateFromJSON(ctx, sessionsDir, store)
+	if err != nil {
+		t.Fatalf("MigrateFromJSON: %v", err)
+	}
+	if count != 0 {
+		t.Fatalf("expected 0 migrated, got %d", count)
+	}
+
+	history, err := store.GetHistory(ctx, "agent:main:pico:direct:pico:test")
+	if err != nil {
+		t.Fatalf("GetHistory: %v", err)
+	}
+	if len(history) != 1 || history[0].Content != "keep me" {
+		t.Fatalf("history = %+v, want preserved single message", history)
+	}
+
+	summary, err := store.GetSummary(ctx, "agent:main:pico:direct:pico:test")
+	if err != nil {
+		t.Fatalf("GetSummary: %v", err)
+	}
+	if summary != "keep summary" {
+		t.Fatalf("summary = %q, want %q", summary, "keep summary")
+	}
+
+	if _, statErr := os.Stat(metaPath); statErr != nil {
+		t.Fatalf("meta file should remain in place: %v", statErr)
+	}
+	if _, statErr := os.Stat(metaPath + ".migrated"); !os.IsNotExist(statErr) {
+		t.Fatalf("meta file should not be renamed, stat err = %v", statErr)
+	}
+}
diff --git a/pkg/memory/store.go b/pkg/memory/store.go
new file mode 100644
index 000000000..b6e11707d
--- /dev/null
+++ b/pkg/memory/store.go
@@ -0,0 +1,42 @@
+package memory
+
+import (
+	"context"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// Store defines an interface for persistent session storage.
+// Each method is an atomic operation — there is no separate Save() call.
+type Store interface {
+	// AddMessage appends a simple text message to a session.
+	AddMessage(ctx context.Context, sessionKey, role, content string) error
+
+	// AddFullMessage appends a complete message (with tool calls, etc.) to a session.
+	AddFullMessage(ctx context.Context, sessionKey string, msg providers.Message) error
+
+	// GetHistory returns all messages for a session in insertion order.
+	// Returns an empty slice (not nil) if the session does not exist.
+	GetHistory(ctx context.Context, sessionKey string) ([]providers.Message, error)
+
+	// GetSummary returns the conversation summary for a session.
+	// Returns an empty string if no summary exists.
+	GetSummary(ctx context.Context, sessionKey string) (string, error)
+
+	// SetSummary updates the conversation summary for a session.
+	SetSummary(ctx context.Context, sessionKey, summary string) error
+
+	// TruncateHistory removes all but the last keepLast messages from a session.
+	// If keepLast <= 0, all messages are removed.
+	TruncateHistory(ctx context.Context, sessionKey string, keepLast int) error
+
+	// SetHistory replaces all messages in a session with the provided history.
+	SetHistory(ctx context.Context, sessionKey string, history []providers.Message) error
+
+	// Compact reclaims storage by physically removing logically truncated
+	// data. Backends that do not accumulate dead data may return nil.
+	Compact(ctx context.Context, sessionKey string) error
+
+	// Close releases any resources held by the store.
+	Close() error
+}
diff --git a/pkg/migrate/internal/common.go b/pkg/migrate/internal/common.go
index c77ab9f26..65a87adc4 100644
--- a/pkg/migrate/internal/common.go
+++ b/pkg/migrate/internal/common.go
@@ -5,20 +5,23 @@ import (
 	"io"
 	"os"
 	"path/filepath"
+
+	"github.com/sipeed/picoclaw/pkg"
+	"github.com/sipeed/picoclaw/pkg/config"
 )
 
 func ResolveTargetHome(override string) (string, error) {
 	if override != "" {
 		return ExpandHome(override), nil
 	}
-	if envHome := os.Getenv("PICOCLAW_HOME"); envHome != "" {
+	if envHome := os.Getenv(config.EnvHome); envHome != "" {
 		return ExpandHome(envHome), nil
 	}
 	home, err := os.UserHomeDir()
 	if err != nil {
 		return "", fmt.Errorf("resolving home directory: %w", err)
 	}
-	return filepath.Join(home, ".picoclaw"), nil
+	return filepath.Join(home, pkg.DefaultPicoClawHome), nil
 }
 
 func ExpandHome(path string) string {
diff --git a/pkg/migrate/internal/common_test.go b/pkg/migrate/internal/common_test.go
index a089157f5..a67293c19 100644
--- a/pkg/migrate/internal/common_test.go
+++ b/pkg/migrate/internal/common_test.go
@@ -118,64 +118,55 @@ func TestPlanWorkspaceMigration(t *testing.T) {
 	assert.GreaterOrEqual(t, len(actions), 1)
 }
 
-func TestPlanWorkspaceMigrationWithExistingDestination(t *testing.T) {
-	tmpDir := t.TempDir()
-	srcWorkspace := filepath.Join(tmpDir, "src", "workspace")
-	dstWorkspace := filepath.Join(tmpDir, "dst", "workspace")
+func TestPlanWorkspaceMigrationExistingFile(t *testing.T) {
+	tests := []struct {
+		name           string
+		force          bool
+		wantActionType ActionType
+	}{
+		{
+			name:           "backup when not forced",
+			force:          false,
+			wantActionType: ActionBackup,
+		},
+		{
+			name:           "copy when forced",
+			force:          true,
+			wantActionType: ActionCopy,
+		},
+	}
 
-	err := os.MkdirAll(srcWorkspace, 0o755)
-	require.NoError(t, err)
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tmpDir := t.TempDir()
+			srcWorkspace := filepath.Join(tmpDir, "src", "workspace")
+			dstWorkspace := filepath.Join(tmpDir, "dst", "workspace")
 
-	err = os.MkdirAll(dstWorkspace, 0o755)
-	require.NoError(t, err)
+			err := os.MkdirAll(srcWorkspace, 0o755)
+			require.NoError(t, err)
 
-	err = os.WriteFile(filepath.Join(srcWorkspace, "file1.txt"), []byte("source"), 0o644)
-	require.NoError(t, err)
+			err = os.MkdirAll(dstWorkspace, 0o755)
+			require.NoError(t, err)
 
-	err = os.WriteFile(filepath.Join(dstWorkspace, "file1.txt"), []byte("existing"), 0o644)
-	require.NoError(t, err)
+			err = os.WriteFile(filepath.Join(srcWorkspace, "file1.txt"), []byte("source"), 0o644)
+			require.NoError(t, err)
 
-	actions, err := PlanWorkspaceMigration(
-		srcWorkspace,
-		dstWorkspace,
-		[]string{"file1.txt"},
-		[]string{},
-		false,
-	)
-	require.NoError(t, err)
+			err = os.WriteFile(filepath.Join(dstWorkspace, "file1.txt"), []byte("existing"), 0o644)
+			require.NoError(t, err)
 
-	require.GreaterOrEqual(t, len(actions), 1)
-	assert.Equal(t, ActionBackup, actions[0].Type)
-}
+			actions, err := PlanWorkspaceMigration(
+				srcWorkspace,
+				dstWorkspace,
+				[]string{"file1.txt"},
+				[]string{},
+				tt.force,
+			)
+			require.NoError(t, err)
 
-func TestPlanWorkspaceMigrationForce(t *testing.T) {
-	tmpDir := t.TempDir()
-	srcWorkspace := filepath.Join(tmpDir, "src", "workspace")
-	dstWorkspace := filepath.Join(tmpDir, "dst", "workspace")
-
-	err := os.MkdirAll(srcWorkspace, 0o755)
-	require.NoError(t, err)
-
-	err = os.MkdirAll(dstWorkspace, 0o755)
-	require.NoError(t, err)
-
-	err = os.WriteFile(filepath.Join(srcWorkspace, "file1.txt"), []byte("source"), 0o644)
-	require.NoError(t, err)
-
-	err = os.WriteFile(filepath.Join(dstWorkspace, "file1.txt"), []byte("existing"), 0o644)
-	require.NoError(t, err)
-
-	actions, err := PlanWorkspaceMigration(
-		srcWorkspace,
-		dstWorkspace,
-		[]string{"file1.txt"},
-		[]string{},
-		true,
-	)
-	require.NoError(t, err)
-
-	require.GreaterOrEqual(t, len(actions), 1)
-	assert.Equal(t, ActionCopy, actions[0].Type)
+			require.GreaterOrEqual(t, len(actions), 1)
+			assert.Equal(t, tt.wantActionType, actions[0].Type)
+		})
+	}
 }
 
 func TestPlanWorkspaceMigrationNonExistentSource(t *testing.T) {
diff --git a/pkg/migrate/sources/openclaw/common.go b/pkg/migrate/sources/openclaw/common.go
index dddd98089..938f15b80 100644
--- a/pkg/migrate/sources/openclaw/common.go
+++ b/pkg/migrate/sources/openclaw/common.go
@@ -4,7 +4,6 @@ var migrateableFiles = []string{
 	"AGENTS.md",
 	"SOUL.md",
 	"USER.md",
-	"TOOLS.md",
 	"HEARTBEAT.md",
 }
 
@@ -14,16 +13,16 @@ var migrateableDirs = []string{
 }
 
 var supportedChannels = map[string]bool{
-	"whatsapp":  true,
-	"telegram":  true,
-	"feishu":    true,
-	"discord":   true,
-	"maixcam":   true,
-	"qq":        true,
-	"dingtalk":  true,
-	"slack":     true,
-	"line":      true,
-	"onebot":    true,
-	"wecom":     true,
-	"wecom_app": true,
+	"whatsapp": true,
+	"telegram": true,
+	"feishu":   true,
+	"discord":  true,
+	"maixcam":  true,
+	"qq":       true,
+	"dingtalk": true,
+	"slack":    true,
+	"matrix":   true,
+	"line":     true,
+	"onebot":   true,
+	"wecom":    true,
 }
diff --git a/pkg/migrate/sources/openclaw/openclaw_config.go b/pkg/migrate/sources/openclaw/openclaw_config.go
index 39ad48fad..b56194b3d 100644
--- a/pkg/migrate/sources/openclaw/openclaw_config.go
+++ b/pkg/migrate/sources/openclaw/openclaw_config.go
@@ -132,11 +132,12 @@ type OpenClawChannels struct {
 }
 
 type OpenClawTelegramConfig struct {
-	BotToken    *string  `json:"botToken"`
-	AllowFrom   []string `json:"allowFrom"`
-	GroupPolicy *string  `json:"groupPolicy"`
-	DmPolicy    *string  `json:"dmPolicy"`
-	Enabled     *bool    `json:"enabled"`
+	BotToken      *string  `json:"botToken"`
+	AllowFrom     []string `json:"allowFrom"`
+	GroupPolicy   *string  `json:"groupPolicy"`
+	DmPolicy      *string  `json:"dmPolicy"`
+	Enabled       *bool    `json:"enabled"`
+	UseMarkdownV2 *bool    `json:"useMarkdownV2"`
 }
 
 type OpenClawDiscordConfig struct {
@@ -371,6 +372,8 @@ func (c *OpenClawConfig) IsChannelEnabled(name string) bool {
 		return c.Channels.Discord == nil || c.Channels.Discord.Enabled == nil || *c.Channels.Discord.Enabled
 	case "slack":
 		return c.Channels.Slack == nil || c.Channels.Slack.Enabled == nil || *c.Channels.Slack.Enabled
+	case "matrix":
+		return c.Channels.Matrix == nil || c.Channels.Matrix.Enabled == nil || *c.Channels.Matrix.Enabled
 	case "whatsapp":
 		return c.Channels.WhatsApp == nil || c.Channels.WhatsApp.Enabled == nil || *c.Channels.WhatsApp.Enabled
 	case "feishu":
@@ -397,6 +400,11 @@ func GetChannelAllowFrom(ch any) []string {
 			return nil
 		}
 		return c.AllowFrom
+	case *OpenClawMatrixConfig:
+		if c == nil {
+			return nil
+		}
+		return c.AllowFrom
 	case *OpenClawWhatsAppConfig:
 		if c == nil {
 			return nil
@@ -627,6 +635,7 @@ type ChannelsConfig struct {
 	QQ       QQConfig       `json:"qq"`
 	DingTalk DingTalkConfig `json:"dingtalk"`
 	Slack    SlackConfig    `json:"slack"`
+	Matrix   MatrixConfig   `json:"matrix"`
 	LINE     LINEConfig     `json:"line"`
 }
 
@@ -637,10 +646,11 @@ type WhatsAppConfig struct {
 }
 
 type TelegramConfig struct {
-	Enabled   bool     `json:"enabled"`
-	Token     string   `json:"token"`
-	Proxy     string   `json:"proxy"`
-	AllowFrom []string `json:"allow_from"`
+	Enabled       bool     `json:"enabled"`
+	Token         string   `json:"token"`
+	Proxy         string   `json:"proxy"`
+	AllowFrom     []string `json:"allow_from"`
+	UseMarkdownV2 bool     `json:"use_markdown_v2"`
 }
 
 type FeishuConfig struct {
@@ -687,6 +697,14 @@ type SlackConfig struct {
 	AllowFrom []string `json:"allow_from"`
 }
 
+type MatrixConfig struct {
+	Enabled     bool     `json:"enabled"`
+	Homeserver  string   `json:"homeserver"`
+	UserID      string   `json:"user_id"`
+	AccessToken string   `json:"access_token"`
+	AllowFrom   []string `json:"allow_from"`
+}
+
 type LINEConfig struct {
 	Enabled            bool     `json:"enabled"`
 	ChannelSecret      string   `json:"channel_secret"`
@@ -717,16 +735,18 @@ type WebToolsConfig struct {
 }
 
 type BraveConfig struct {
-	Enabled    bool   `json:"enabled"`
-	APIKey     string `json:"api_key"`
-	MaxResults int    `json:"max_results"`
+	Enabled    bool     `json:"enabled"`
+	APIKey     string   `json:"api_key"`
+	APIKeys    []string `json:"api_keys"`
+	MaxResults int      `json:"max_results"`
 }
 
 type TavilyConfig struct {
-	Enabled    bool   `json:"enabled"`
-	APIKey     string `json:"api_key"`
-	BaseURL    string `json:"base_url"`
-	MaxResults int    `json:"max_results"`
+	Enabled    bool     `json:"enabled"`
+	APIKey     string   `json:"api_key"`
+	APIKeys    []string `json:"api_keys"`
+	BaseURL    string   `json:"base_url"`
+	MaxResults int      `json:"max_results"`
 }
 
 type DuckDuckGoConfig struct {
@@ -735,9 +755,10 @@ type DuckDuckGoConfig struct {
 }
 
 type PerplexityConfig struct {
-	Enabled    bool   `json:"enabled"`
-	APIKey     string `json:"api_key"`
-	MaxResults int    `json:"max_results"`
+	Enabled    bool     `json:"enabled"`
+	APIKey     string   `json:"api_key"`
+	APIKeys    []string `json:"api_keys"`
+	MaxResults int      `json:"max_results"`
 }
 
 type CronConfig struct {
@@ -758,9 +779,11 @@ func (c *OpenClawConfig) convertChannels(warnings *[]string) ChannelsConfig {
 
 	if c.Channels.Telegram != nil {
 		enabled := c.Channels.Telegram.Enabled == nil || *c.Channels.Telegram.Enabled
+		useMarkdownV2 := c.Channels.Telegram.UseMarkdownV2 != nil && *c.Channels.Telegram.UseMarkdownV2
 		channels.Telegram = TelegramConfig{
-			Enabled:   enabled,
-			AllowFrom: c.Channels.Telegram.AllowFrom,
+			Enabled:       enabled,
+			AllowFrom:     c.Channels.Telegram.AllowFrom,
+			UseMarkdownV2: useMarkdownV2,
 		}
 		if c.Channels.Telegram.BotToken != nil {
 			channels.Telegram.Token = *c.Channels.Telegram.BotToken
@@ -862,12 +885,26 @@ func (c *OpenClawConfig) convertChannels(warnings *[]string) ChannelsConfig {
 		}
 	}
 
+	if c.Channels.Matrix != nil && supportedChannels["matrix"] {
+		enabled := c.Channels.Matrix.Enabled == nil || *c.Channels.Matrix.Enabled
+		channels.Matrix = MatrixConfig{
+			Enabled:   enabled,
+			AllowFrom: c.Channels.Matrix.AllowFrom,
+		}
+		if c.Channels.Matrix.Homeserver != nil {
+			channels.Matrix.Homeserver = *c.Channels.Matrix.Homeserver
+		}
+		if c.Channels.Matrix.UserID != nil {
+			channels.Matrix.UserID = *c.Channels.Matrix.UserID
+		}
+		if c.Channels.Matrix.AccessToken != nil {
+			channels.Matrix.AccessToken = *c.Channels.Matrix.AccessToken
+		}
+	}
+
 	if c.Channels.Signal != nil {
 		*warnings = append(*warnings, "Channel 'signal': No PicoClaw adapter available")
 	}
-	if c.Channels.Matrix != nil {
-		*warnings = append(*warnings, "Channel 'matrix': No PicoClaw adapter available")
-	}
 	if c.Channels.IRC != nil {
 		*warnings = append(*warnings, "Channel 'irc': No PicoClaw adapter available")
 	}
@@ -944,13 +981,16 @@ func (c *PicoClawConfig) ToStandardConfig() *config.Config {
 	cfg.Agents.Defaults.ModelFallbacks = c.Agents.Defaults.ModelFallbacks
 
 	for _, m := range c.ModelList {
-		cfg.ModelList = append(cfg.ModelList, config.ModelConfig{
+		mc := &config.ModelConfig{
 			ModelName: m.ModelName,
 			Model:     m.Model,
 			APIBase:   m.APIBase,
-			APIKey:    m.APIKey,
 			Proxy:     m.Proxy,
-		})
+		}
+		if m.APIKey != "" {
+			mc.SetAPIKey(m.APIKey)
+		}
+		cfg.ModelList = append(cfg.ModelList, mc)
 	}
 
 	cfg.Channels = c.Channels.ToStandardChannels()
@@ -983,51 +1023,107 @@ func (c ChannelsConfig) ToStandardChannels() config.ChannelsConfig {
 			Enabled:   c.WhatsApp.Enabled,
 			BridgeURL: c.WhatsApp.BridgeURL,
 		},
-		Telegram: config.TelegramConfig{
-			Enabled: c.Telegram.Enabled,
-			Token:   c.Telegram.Token,
-			Proxy:   c.Telegram.Proxy,
-		},
-		Feishu: config.FeishuConfig{
-			Enabled:           c.Feishu.Enabled,
-			AppID:             c.Feishu.AppID,
-			AppSecret:         c.Feishu.AppSecret,
-			EncryptKey:        c.Feishu.EncryptKey,
-			VerificationToken: c.Feishu.VerificationToken,
-		},
-		Discord: config.DiscordConfig{
-			Enabled:     c.Discord.Enabled,
-			Token:       c.Discord.Token,
-			MentionOnly: c.Discord.MentionOnly,
-		},
+		Telegram: func() config.TelegramConfig {
+			tc := config.TelegramConfig{
+				Enabled: c.Telegram.Enabled,
+				Proxy:   c.Telegram.Proxy,
+			}
+			if c.Telegram.Token != "" {
+				tc.SetToken(c.Telegram.Token)
+			}
+			return tc
+		}(),
+		Feishu: func() config.FeishuConfig {
+			fc := config.FeishuConfig{
+				Enabled: c.Feishu.Enabled,
+				AppID:   c.Feishu.AppID,
+			}
+			if c.Feishu.AppSecret != "" {
+				fc.SetAppSecret(c.Feishu.AppSecret)
+			}
+			if c.Feishu.EncryptKey != "" {
+				fc.SetEncryptKey(c.Feishu.EncryptKey)
+			}
+			if c.Feishu.VerificationToken != "" {
+				fc.SetVerificationToken(c.Feishu.VerificationToken)
+			}
+			return fc
+		}(),
+		Discord: func() config.DiscordConfig {
+			dc := config.DiscordConfig{
+				Enabled:     c.Discord.Enabled,
+				MentionOnly: c.Discord.MentionOnly,
+			}
+			if c.Discord.Token != "" {
+				dc.SetToken(c.Discord.Token)
+			}
+			return dc
+		}(),
 		MaixCam: config.MaixCamConfig{
 			Enabled: c.MaixCam.Enabled,
 			Host:    c.MaixCam.Host,
 			Port:    c.MaixCam.Port,
 		},
-		QQ: config.QQConfig{
-			Enabled:   c.QQ.Enabled,
-			AppID:     c.QQ.AppID,
-			AppSecret: c.QQ.AppSecret,
-		},
-		DingTalk: config.DingTalkConfig{
-			Enabled:      c.DingTalk.Enabled,
-			ClientID:     c.DingTalk.ClientID,
-			ClientSecret: c.DingTalk.ClientSecret,
-		},
-		Slack: config.SlackConfig{
-			Enabled:  c.Slack.Enabled,
-			BotToken: c.Slack.BotToken,
-			AppToken: c.Slack.AppToken,
-		},
-		LINE: config.LINEConfig{
-			Enabled:            c.LINE.Enabled,
-			ChannelSecret:      c.LINE.ChannelSecret,
-			ChannelAccessToken: c.LINE.ChannelAccessToken,
-			WebhookHost:        c.LINE.WebhookHost,
-			WebhookPort:        c.LINE.WebhookPort,
-			WebhookPath:        c.LINE.WebhookPath,
-		},
+		QQ: func() config.QQConfig {
+			qc := config.QQConfig{
+				Enabled: c.QQ.Enabled,
+				AppID:   c.QQ.AppID,
+			}
+			if c.QQ.AppSecret != "" {
+				qc.SetAppSecret(c.QQ.AppSecret)
+			}
+			return qc
+		}(),
+		DingTalk: func() config.DingTalkConfig {
+			dt := config.DingTalkConfig{
+				Enabled:  c.DingTalk.Enabled,
+				ClientID: c.DingTalk.ClientID,
+			}
+			if c.DingTalk.ClientSecret != "" {
+				dt.SetClientSecret(c.DingTalk.ClientSecret)
+			}
+			return dt
+		}(),
+		Slack: func() config.SlackConfig {
+			sc := config.SlackConfig{
+				Enabled: c.Slack.Enabled,
+			}
+			if c.Slack.BotToken != "" {
+				sc.SetBotToken(c.Slack.BotToken)
+			}
+			if c.Slack.AppToken != "" {
+				sc.SetAppToken(c.Slack.AppToken)
+			}
+			return sc
+		}(),
+		Matrix: func() config.MatrixConfig {
+			mc := config.MatrixConfig{
+				Enabled:      c.Matrix.Enabled,
+				Homeserver:   c.Matrix.Homeserver,
+				UserID:       c.Matrix.UserID,
+				AllowFrom:    c.Matrix.AllowFrom,
+				JoinOnInvite: true,
+			}
+			if c.Matrix.AccessToken != "" {
+				mc.SetAccessToken(c.Matrix.AccessToken)
+			}
+			return mc
+		}(),
+		LINE: func() config.LINEConfig {
+			lc := config.LINEConfig{
+				Enabled:     c.LINE.Enabled,
+				WebhookHost: c.LINE.WebhookHost,
+				WebhookPort: c.LINE.WebhookPort,
+				WebhookPath: c.LINE.WebhookPath,
+			}
+			if c.LINE.ChannelSecret != "" {
+				lc.SetChannelSecret(c.LINE.ChannelSecret)
+			}
+			if c.LINE.ChannelAccessToken != "" {
+				lc.SetChannelAccessToken(c.LINE.ChannelAccessToken)
+			}
+			return lc
+		}(),
 	}
 }
 
@@ -1039,29 +1135,44 @@ func (c GatewayConfig) ToStandardGateway() config.GatewayConfig {
 }
 
 func (c ToolsConfig) ToStandardTools() config.ToolsConfig {
+	brave := config.BraveConfig{
+		Enabled:    c.Web.Brave.Enabled,
+		MaxResults: c.Web.Brave.MaxResults,
+	}
+	if c.Web.Brave.APIKey != "" {
+		brave.SetAPIKey(c.Web.Brave.APIKey)
+	}
+	if len(c.Web.Brave.APIKeys) > 0 {
+		brave.SetAPIKeys(c.Web.Brave.APIKeys)
+	}
+
+	tavily := config.TavilyConfig{
+		Enabled:    c.Web.Tavily.Enabled,
+		BaseURL:    c.Web.Tavily.BaseURL,
+		MaxResults: c.Web.Tavily.MaxResults,
+	}
+	if c.Web.Tavily.APIKey != "" {
+		tavily.SetAPIKey(c.Web.Tavily.APIKey)
+	}
+
+	perplexity := config.PerplexityConfig{
+		Enabled:    c.Web.Perplexity.Enabled,
+		MaxResults: c.Web.Perplexity.MaxResults,
+	}
+	if c.Web.Perplexity.APIKey != "" {
+		perplexity.SetAPIKey(c.Web.Perplexity.APIKey)
+	}
+
 	return config.ToolsConfig{
 		Web: config.WebToolsConfig{
-			Brave: config.BraveConfig{
-				Enabled:    c.Web.Brave.Enabled,
-				APIKey:     c.Web.Brave.APIKey,
-				MaxResults: c.Web.Brave.MaxResults,
-			},
-			Tavily: config.TavilyConfig{
-				Enabled:    c.Web.Tavily.Enabled,
-				APIKey:     c.Web.Tavily.APIKey,
-				BaseURL:    c.Web.Tavily.BaseURL,
-				MaxResults: c.Web.Tavily.MaxResults,
-			},
+			Brave:  brave,
+			Tavily: tavily,
 			DuckDuckGo: config.DuckDuckGoConfig{
 				Enabled:    c.Web.DuckDuckGo.Enabled,
 				MaxResults: c.Web.DuckDuckGo.MaxResults,
 			},
-			Perplexity: config.PerplexityConfig{
-				Enabled:    c.Web.Perplexity.Enabled,
-				APIKey:     c.Web.Perplexity.APIKey,
-				MaxResults: c.Web.Perplexity.MaxResults,
-			},
-			Proxy: c.Web.Proxy,
+			Perplexity: perplexity,
+			Proxy:      c.Web.Proxy,
 		},
 		Cron: config.CronToolsConfig{
 			ExecTimeoutMinutes: c.Cron.ExecTimeoutMinutes,
@@ -1069,6 +1180,7 @@ func (c ToolsConfig) ToStandardTools() config.ToolsConfig {
 		Exec: config.ExecConfig{
 			EnableDenyPatterns: c.Exec.EnableDenyPatterns,
 			CustomDenyPatterns: c.Exec.CustomDenyPatterns,
+			AllowRemote:        config.DefaultConfig().Tools.Exec.AllowRemote,
 		},
 	}
 }
diff --git a/pkg/migrate/sources/openclaw/openclaw_config_test.go b/pkg/migrate/sources/openclaw/openclaw_config_test.go
index 7d884522c..350b29776 100644
--- a/pkg/migrate/sources/openclaw/openclaw_config_test.go
+++ b/pkg/migrate/sources/openclaw/openclaw_config_test.go
@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
@@ -289,6 +290,20 @@ func TestConvertToPicoClaw(t *testing.T) {
 	}
 }
 
+func TestToStandardConfig_ExecAllowRemoteDefaultsTrue(t *testing.T) {
+	cfg := (&PicoClawConfig{
+		Tools: ToolsConfig{
+			Exec: ExecConfig{
+				EnableDenyPatterns: true,
+			},
+		},
+	}).ToStandardConfig()
+
+	if !cfg.Tools.Exec.AllowRemote {
+		t.Fatal("ToStandardConfig() should preserve the default tools.exec.allow_remote=true")
+	}
+}
+
 func TestConvertToPicoClawWithQQAndDingTalk(t *testing.T) {
 	tmpDir := t.TempDir()
 	configPath := filepath.Join(tmpDir, "openclaw.json")
@@ -375,6 +390,96 @@ func TestConvertToPicoClawWithQQAndDingTalk(t *testing.T) {
 	}
 }
 
+func TestConvertToPicoClawWithMatrix(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+
+	testConfig := `{
+		"channels": {
+			"matrix": {
+				"enabled": true,
+				"homeserver": "https://matrix.example.com",
+				"userId": "@bot:matrix.example.com",
+				"accessToken": "syt_test_token",
+				"allowFrom": ["@alice:matrix.example.com"]
+			}
+		}
+	}`
+
+	err := os.WriteFile(configPath, []byte(testConfig), 0o644)
+	if err != nil {
+		t.Fatalf("failed to write test config: %v", err)
+	}
+
+	cfg, err := LoadOpenClawConfig(configPath)
+	if err != nil {
+		t.Fatalf("failed to load config: %v", err)
+	}
+
+	picoCfg, warnings, err := cfg.ConvertToPicoClaw("")
+	if err != nil {
+		t.Fatalf("failed to convert config: %v", err)
+	}
+
+	if !picoCfg.Channels.Matrix.Enabled {
+		t.Error("matrix should be enabled")
+	}
+	if picoCfg.Channels.Matrix.Homeserver != "https://matrix.example.com" {
+		t.Errorf("expected matrix homeserver, got %q", picoCfg.Channels.Matrix.Homeserver)
+	}
+	if picoCfg.Channels.Matrix.UserID != "@bot:matrix.example.com" {
+		t.Errorf("expected matrix user_id, got %q", picoCfg.Channels.Matrix.UserID)
+	}
+	if picoCfg.Channels.Matrix.AccessToken != "syt_test_token" {
+		t.Errorf("expected matrix access_token, got %q", picoCfg.Channels.Matrix.AccessToken)
+	}
+	if len(picoCfg.Channels.Matrix.AllowFrom) != 1 ||
+		picoCfg.Channels.Matrix.AllowFrom[0] != "@alice:matrix.example.com" {
+		t.Errorf("unexpected matrix allow_from: %#v", picoCfg.Channels.Matrix.AllowFrom)
+	}
+
+	for _, w := range warnings {
+		if strings.Contains(w, "Channel 'matrix'") {
+			t.Fatalf("matrix should no longer be reported as unsupported, warning=%q", w)
+		}
+	}
+}
+
+func TestConvertToPicoClawWithMatrixDisabled(t *testing.T) {
+	tmpDir := t.TempDir()
+	configPath := filepath.Join(tmpDir, "openclaw.json")
+
+	testConfig := `{
+		"channels": {
+			"matrix": {
+				"enabled": false,
+				"homeserver": "https://matrix.example.com",
+				"userId": "@bot:matrix.example.com",
+				"accessToken": "syt_test_token"
+			}
+		}
+	}`
+
+	err := os.WriteFile(configPath, []byte(testConfig), 0o644)
+	if err != nil {
+		t.Fatalf("failed to write test config: %v", err)
+	}
+
+	cfg, err := LoadOpenClawConfig(configPath)
+	if err != nil {
+		t.Fatalf("failed to load config: %v", err)
+	}
+
+	picoCfg, _, err := cfg.ConvertToPicoClaw("")
+	if err != nil {
+		t.Fatalf("failed to convert config: %v", err)
+	}
+
+	if picoCfg.Channels.Matrix.Enabled {
+		t.Error("matrix should respect enabled=false from source config")
+	}
+}
+
 func TestOpenClawAgentModel(t *testing.T) {
 	model := &OpenClawAgentModel{
 		Primary:   strPtr("anthropic/claude-3-opus"),
@@ -425,6 +530,9 @@ func TestChannelEnabled(t *testing.T) {
 	if !cfg.IsChannelEnabled("slack") {
 		t.Error("slack should be enabled (explicitly set)")
 	}
+	if !cfg.IsChannelEnabled("matrix") {
+		t.Error("matrix should be enabled (nil config defaults to enabled)")
+	}
 	if cfg.IsChannelEnabled("line") {
 		t.Error("line should return false (not in switch cases)")
 	}
@@ -589,7 +697,7 @@ func TestToStandardConfig(t *testing.T) {
 	for _, m := range stdCfg.ModelList {
 		if m.ModelName == "claude-sonnet-4-20250514" {
 			foundModel = true
-			foundAPIKey = m.APIKey
+			foundAPIKey = m.APIKey()
 			break
 		}
 	}
@@ -603,8 +711,8 @@ func TestToStandardConfig(t *testing.T) {
 	if !stdCfg.Channels.Telegram.Enabled {
 		t.Error("telegram should be enabled")
 	}
-	if stdCfg.Channels.Telegram.Token != "test-token" {
-		t.Errorf("expected token 'test-token', got '%s'", stdCfg.Channels.Telegram.Token)
+	if stdCfg.Channels.Telegram.Token() != "test-token" {
+		t.Errorf("expected token 'test-token', got '%s'", stdCfg.Channels.Telegram.Token())
 	}
 
 	if stdCfg.Gateway.Port != 8080 {
diff --git a/pkg/migrate/sources/openclaw/openclaw_handler.go b/pkg/migrate/sources/openclaw/openclaw_handler.go
index aaff119f1..5e5241268 100644
--- a/pkg/migrate/sources/openclaw/openclaw_handler.go
+++ b/pkg/migrate/sources/openclaw/openclaw_handler.go
@@ -10,6 +10,11 @@ import (
 	"github.com/sipeed/picoclaw/pkg/migrate/internal"
 )
 
+// OpenclawHomeEnvVar is the environment variable that overrides the source
+// openclaw home directory when migrating from openclaw to picoclaw.
+// Default: ~/.openclaw
+const OpenclawHomeEnvVar = "OPENCLAW_HOME"
+
 var providerMapping = map[string]string{
 	"anthropic":  "anthropic",
 	"claude":     "anthropic",
@@ -112,7 +117,7 @@ func resolveSourceHome(override string) (string, error) {
 	if override != "" {
 		return internal.ExpandHome(override), nil
 	}
-	if envHome := os.Getenv("OPENCLAW_HOME"); envHome != "" {
+	if envHome := os.Getenv(OpenclawHomeEnvVar); envHome != "" {
 		return internal.ExpandHome(envHome), nil
 	}
 	home, err := os.UserHomeDir()
diff --git a/pkg/providers/anthropic/provider.go b/pkg/providers/anthropic/provider.go
index 1bb15f771..d4ceaab2c 100644
--- a/pkg/providers/anthropic/provider.go
+++ b/pkg/providers/anthropic/provider.go
@@ -23,7 +23,10 @@ type (
 	ToolFunctionDefinition = protocoltypes.ToolFunctionDefinition
 )
 
-const defaultBaseURL = "https://api.anthropic.com"
+const (
+	defaultBaseURL      = "https://api.anthropic.com"
+	anthropicBetaHeader = "oauth-2025-04-20"
+)
 
 type Provider struct {
 	client      *anthropic.Client
@@ -31,6 +34,9 @@ type Provider struct {
 	baseURL     string
 }
 
+// SupportsThinking implements providers.ThinkingCapable.
+func (p *Provider) SupportsThinking() bool { return true }
+
 func NewProvider(token string) *Provider {
 	return NewProviderWithBaseURL(token, "")
 }
@@ -77,7 +83,10 @@ func (p *Provider) Chat(
 		if err != nil {
 			return nil, fmt.Errorf("refreshing token: %w", err)
 		}
-		opts = append(opts, option.WithAuthToken(tok))
+		opts = append(opts,
+			option.WithAuthToken(tok),
+			option.WithHeader("anthropic-beta", anthropicBetaHeader),
+		)
 	}
 
 	params, err := buildParams(messages, tools, model, options)
@@ -85,6 +94,11 @@ func (p *Provider) Chat(
 		return nil, err
 	}
 
+	// OAuth/setup-tokens require streaming; API keys use non-streaming.
+	if p.tokenSource != nil {
+		return p.chatStreaming(ctx, params, opts)
+	}
+
 	resp, err := p.client.Messages.New(ctx, params, opts...)
 	if err != nil {
 		return nil, fmt.Errorf("claude API call: %w", err)
@@ -93,6 +107,28 @@ func (p *Provider) Chat(
 	return parseResponse(resp), nil
 }
 
+func (p *Provider) chatStreaming(
+	ctx context.Context,
+	params anthropic.MessageNewParams,
+	opts []option.RequestOption,
+) (*LLMResponse, error) {
+	stream := p.client.Messages.NewStreaming(ctx, params, opts...)
+	defer stream.Close()
+
+	var msg anthropic.Message
+	for stream.Next() {
+		event := stream.Current()
+		if err := msg.Accumulate(event); err != nil {
+			return nil, fmt.Errorf("claude streaming accumulate: %w", err)
+		}
+	}
+	if err := stream.Err(); err != nil {
+		return nil, fmt.Errorf("claude API call: %w", err)
+	}
+
+	return parseResponse(&msg), nil
+}
+
 func (p *Provider) GetDefaultModel() string {
 	return "claude-sonnet-4.6"
 }
@@ -144,7 +180,20 @@ func buildParams(
 					blocks = append(blocks, anthropic.NewTextBlock(msg.Content))
 				}
 				for _, tc := range msg.ToolCalls {
-					blocks = append(blocks, anthropic.NewToolUseBlock(tc.ID, tc.Arguments, tc.Name))
+					// Skip tool calls with empty names to avoid API errors
+					if tc.Name == "" {
+						continue
+					}
+					args := tc.Arguments
+					if args == nil && tc.Function != nil && tc.Function.Arguments != "" {
+						if err := json.Unmarshal([]byte(tc.Function.Arguments), &args); err != nil {
+							args = map[string]any{}
+						}
+					}
+					if args == nil {
+						args = map[string]any{}
+					}
+					blocks = append(blocks, anthropic.NewToolUseBlock(tc.ID, args, tc.Name))
 				}
 				anthropicMessages = append(anthropicMessages, anthropic.NewAssistantMessage(blocks...))
 			} else {
@@ -164,8 +213,12 @@ func buildParams(
 		maxTokens = int64(mt)
 	}
 
+	// Normalize model ID: Anthropic API uses hyphens (claude-sonnet-4-6),
+	// but config may use dots (claude-sonnet-4.6).
+	apiModel := strings.ReplaceAll(model, ".", "-")
+
 	params := anthropic.MessageNewParams{
-		Model:     anthropic.Model(model),
+		Model:     anthropic.Model(apiModel),
 		Messages:  anthropicMessages,
 		MaxTokens: maxTokens,
 	}
@@ -182,9 +235,80 @@ func buildParams(
 		params.Tools = translateTools(tools)
 	}
 
+	// Extended Thinking / Adaptive Thinking
+	// The thinking_level value directly determines the API parameter format:
+	//   "adaptive" → {thinking: {type: "adaptive"}} + output_config.effort
+	//   "low/medium/high/xhigh" → {thinking: {type: "enabled", budget_tokens: N}}
+	if level, ok := options["thinking_level"].(string); ok && level != "" && level != "off" {
+		applyThinkingConfig(&params, level)
+	}
+
 	return params, nil
 }
 
+// applyThinkingConfig sets thinking parameters based on the level value.
+// "adaptive" uses the adaptive thinking API (Claude 4.6+).
+// All other levels use budget_tokens which is universally supported.
+//
+// Anthropic API constraint: temperature must not be set when thinking is enabled.
+// budget_tokens must be strictly less than max_tokens.
+func applyThinkingConfig(params *anthropic.MessageNewParams, level string) {
+	// Anthropic API rejects requests with temperature set alongside thinking.
+	// Reset to zero value (omitted from JSON serialization).
+	if params.Temperature.Valid() {
+		log.Printf("anthropic: temperature cleared because thinking is enabled (level=%s)", level)
+	}
+	params.Temperature = anthropic.MessageNewParams{}.Temperature
+
+	if level == "adaptive" {
+		adaptive := anthropic.NewThinkingConfigAdaptiveParam()
+		params.Thinking = anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive}
+		params.OutputConfig = anthropic.OutputConfigParam{
+			Effort: anthropic.OutputConfigEffortHigh,
+		}
+		return
+	}
+
+	budget := int64(levelToBudget(level))
+	if budget <= 0 {
+		return
+	}
+
+	// budget_tokens must be < max_tokens; clamp to respect user's max_tokens setting.
+	if budget >= params.MaxTokens {
+		log.Printf("anthropic: budget_tokens (%d) clamped to %d (max_tokens-1)", budget, params.MaxTokens-1)
+		budget = params.MaxTokens - 1
+	} else if budget > params.MaxTokens*80/100 {
+		log.Printf("anthropic: thinking budget (%d) exceeds 80%% of max_tokens (%d), output may be truncated",
+			budget, params.MaxTokens)
+	}
+	params.Thinking = anthropic.ThinkingConfigParamOfEnabled(budget)
+}
+
+// levelToBudget maps a thinking level to budget_tokens.
+// Values are based on Anthropic's recommendations and community best practices:
+//
+//	low    =  4,096  — simple reasoning, quick debugging (Claude Code "think")
+//	medium = 16,384  — Anthropic recommended sweet spot for most tasks
+//	high   = 32,000  — complex architecture, deep analysis (diminishing returns above this)
+//	xhigh  = 64,000  — extreme reasoning, research problems, benchmarks
+//
+// Note: For Claude 4.6+, prefer adaptive thinking over manual budget_tokens.
+func levelToBudget(level string) int {
+	switch level {
+	case "low":
+		return 4096
+	case "medium":
+		return 16384
+	case "high":
+		return 32000
+	case "xhigh":
+		return 64000
+	default:
+		return 0
+	}
+}
+
 func translateTools(tools []ToolDefinition) []anthropic.ToolUnionParam {
 	result := make([]anthropic.ToolUnionParam, 0, len(tools))
 	for _, t := range tools {
@@ -213,10 +337,14 @@ func translateTools(tools []ToolDefinition) []anthropic.ToolUnionParam {
 
 func parseResponse(resp *anthropic.Message) *LLMResponse {
 	var content strings.Builder
+	var reasoning strings.Builder
 	var toolCalls []ToolCall
 
 	for _, block := range resp.Content {
 		switch block.Type {
+		case "thinking":
+			tb := block.AsThinking()
+			reasoning.WriteString(tb.Thinking)
 		case "text":
 			tb := block.AsText()
 			content.WriteString(tb.Text)
@@ -247,6 +375,7 @@ func parseResponse(resp *anthropic.Message) *LLMResponse {
 
 	return &LLMResponse{
 		Content:      content.String(),
+		Reasoning:    reasoning.String(),
 		ToolCalls:    toolCalls,
 		FinishReason: finishReason,
 		Usage: &UsageInfo{
diff --git a/pkg/providers/anthropic/provider_test.go b/pkg/providers/anthropic/provider_test.go
index 3d21c1d0b..b1aed17b5 100644
--- a/pkg/providers/anthropic/provider_test.go
+++ b/pkg/providers/anthropic/provider_test.go
@@ -21,8 +21,8 @@ func TestBuildParams_BasicMessage(t *testing.T) {
 	if err != nil {
 		t.Fatalf("buildParams() error: %v", err)
 	}
-	if string(params.Model) != "claude-sonnet-4.6" {
-		t.Errorf("Model = %q, want %q", params.Model, "claude-sonnet-4.6")
+	if string(params.Model) != "claude-sonnet-4-6" {
+		t.Errorf("Model = %q, want %q", params.Model, "claude-sonnet-4-6")
 	}
 	if params.MaxTokens != 1024 {
 		t.Errorf("MaxTokens = %d, want 1024", params.MaxTokens)
@@ -262,6 +262,65 @@ func TestProvider_ChatUsesTokenSource(t *testing.T) {
 	}
 }
 
+func TestProvider_ChatStreamingRoundTrip(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/messages" {
+			http.Error(w, "not found", http.StatusNotFound)
+			return
+		}
+		if got := r.Header.Get("Authorization"); got != "Bearer refreshed-token" {
+			t.Errorf("Authorization = %q, want %q", got, "Bearer refreshed-token")
+		}
+		if got := r.Header.Get("Anthropic-Beta"); got != anthropicBetaHeader {
+			t.Errorf("Anthropic-Beta = %q, want %q", got, anthropicBetaHeader)
+		}
+
+		w.Header().Set("Content-Type", "text/event-stream")
+		flusher, _ := w.(http.Flusher)
+
+		events := []string{
+			"event: message_start\ndata: {\"type\":\"message_start\",\"message\":{\"id\":\"msg_stream\",\"type\":\"message\",\"role\":\"assistant\",\"content\":[],\"model\":\"claude-sonnet-4-6\",\"stop_reason\":null,\"usage\":{\"input_tokens\":12,\"output_tokens\":0}}}\n\n",
+			"event: content_block_start\ndata: {\"type\":\"content_block_start\",\"index\":0,\"content_block\":{\"type\":\"text\",\"text\":\"\"}}\n\n",
+			"event: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\"Hello\"}}\n\n",
+			"event: content_block_delta\ndata: {\"type\":\"content_block_delta\",\"index\":0,\"delta\":{\"type\":\"text_delta\",\"text\":\" world\"}}\n\n",
+			"event: content_block_stop\ndata: {\"type\":\"content_block_stop\",\"index\":0}\n\n",
+			"event: message_delta\ndata: {\"type\":\"message_delta\",\"delta\":{\"stop_reason\":\"end_turn\"},\"usage\":{\"output_tokens\":5}}\n\n",
+			"event: message_stop\ndata: {\"type\":\"message_stop\"}\n\n",
+		}
+		for _, e := range events {
+			w.Write([]byte(e))
+			if flusher != nil {
+				flusher.Flush()
+			}
+		}
+	}))
+	defer server.Close()
+
+	p := NewProviderWithTokenSourceAndBaseURL("stale-token", func() (string, error) {
+		return "refreshed-token", nil
+	}, server.URL)
+
+	resp, err := p.Chat(
+		t.Context(),
+		[]Message{{Role: "user", Content: "Hello"}},
+		nil,
+		"claude-sonnet-4.6",
+		map[string]any{},
+	)
+	if err != nil {
+		t.Fatalf("Chat() error: %v", err)
+	}
+	if resp.Content != "Hello world" {
+		t.Errorf("Content = %q, want %q", resp.Content, "Hello world")
+	}
+	if resp.FinishReason != "stop" {
+		t.Errorf("FinishReason = %q, want %q", resp.FinishReason, "stop")
+	}
+	if resp.Usage.CompletionTokens != 5 {
+		t.Errorf("CompletionTokens = %d, want 5", resp.Usage.CompletionTokens)
+	}
+}
+
 func createAnthropicTestClient(baseURL, token string) *anthropic.Client {
 	c := anthropic.NewClient(
 		anthropicoption.WithAuthToken(token),
diff --git a/pkg/providers/anthropic/thinking_test.go b/pkg/providers/anthropic/thinking_test.go
new file mode 100644
index 000000000..e69a3869e
--- /dev/null
+++ b/pkg/providers/anthropic/thinking_test.go
@@ -0,0 +1,212 @@
+package anthropicprovider
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/anthropics/anthropic-sdk-go"
+)
+
+func TestApplyThinkingConfig_Adaptive(t *testing.T) {
+	params := anthropic.MessageNewParams{
+		MaxTokens:   16000,
+		Temperature: anthropic.Float(0.7),
+	}
+	applyThinkingConfig(&params, "adaptive")
+
+	if params.Thinking.OfAdaptive == nil {
+		t.Fatal("expected adaptive thinking")
+	}
+	if params.Thinking.OfEnabled != nil {
+		t.Error("should not set enabled thinking in adaptive mode")
+	}
+	if params.OutputConfig.Effort != anthropic.OutputConfigEffortHigh {
+		t.Errorf("effort = %q, want %q", params.OutputConfig.Effort, anthropic.OutputConfigEffortHigh)
+	}
+	if params.Temperature.Valid() {
+		t.Error("temperature should be cleared when thinking is enabled")
+	}
+}
+
+func TestApplyThinkingConfig_BudgetLevels(t *testing.T) {
+	tests := []struct {
+		level      string
+		wantBudget int64
+	}{
+		{"low", 4096},
+		{"medium", 16384},
+		{"high", 32000},
+		{"xhigh", 64000},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.level, func(t *testing.T) {
+			params := anthropic.MessageNewParams{
+				MaxTokens:   200000,
+				Temperature: anthropic.Float(0.5),
+			}
+			applyThinkingConfig(&params, tt.level)
+
+			if params.Thinking.OfEnabled == nil {
+				t.Fatal("expected enabled thinking")
+			}
+			if params.Thinking.OfAdaptive != nil {
+				t.Error("should not set adaptive thinking")
+			}
+			if params.Thinking.OfEnabled.BudgetTokens != tt.wantBudget {
+				t.Errorf("budget_tokens = %d, want %d", params.Thinking.OfEnabled.BudgetTokens, tt.wantBudget)
+			}
+			if params.OutputConfig.Effort != "" {
+				t.Errorf("effort = %q, want empty", params.OutputConfig.Effort)
+			}
+			if params.Temperature.Valid() {
+				t.Error("temperature should be cleared when thinking is enabled")
+			}
+		})
+	}
+}
+
+func TestApplyThinkingConfig_BudgetClamp(t *testing.T) {
+	// budget_tokens must be < max_tokens; clamp budget down to respect user's max_tokens.
+	params := anthropic.MessageNewParams{MaxTokens: 4096}
+	applyThinkingConfig(&params, "high") // budget=32000 > maxTokens=4096
+
+	if params.Thinking.OfEnabled == nil {
+		t.Fatal("expected enabled thinking")
+	}
+	if params.Thinking.OfEnabled.BudgetTokens != 4095 {
+		t.Errorf("budget_tokens = %d, want 4095 (maxTokens-1)", params.Thinking.OfEnabled.BudgetTokens)
+	}
+	if params.MaxTokens != 4096 {
+		t.Errorf("max_tokens should not be modified, got %d", params.MaxTokens)
+	}
+}
+
+func TestApplyThinkingConfig_UnknownLevel(t *testing.T) {
+	params := anthropic.MessageNewParams{MaxTokens: 16000}
+	applyThinkingConfig(&params, "unknown")
+
+	if params.Thinking.OfEnabled != nil {
+		t.Error("should not set enabled thinking for unknown level")
+	}
+	if params.Thinking.OfAdaptive != nil {
+		t.Error("should not set adaptive thinking for unknown level")
+	}
+}
+
+func TestLevelToBudget(t *testing.T) {
+	tests := []struct {
+		name  string
+		level string
+		want  int
+	}{
+		{"low", "low", 4096},
+		{"medium", "medium", 16384},
+		{"high", "high", 32000},
+		{"xhigh", "xhigh", 64000},
+		{"off", "off", 0},
+		{"empty", "", 0},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := levelToBudget(tt.level); got != tt.want {
+				t.Errorf("levelToBudget(%q) = %d, want %d", tt.level, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestBuildParams_ThinkingClearsTemperature(t *testing.T) {
+	msgs := []Message{{Role: "user", Content: "hello"}}
+	opts := map[string]any{
+		"max_tokens":     200000,
+		"temperature":    0.8,
+		"thinking_level": "medium",
+	}
+
+	params, err := buildParams(msgs, nil, "claude-sonnet-4-6", opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if params.Temperature.Valid() {
+		t.Error("temperature should be cleared when thinking_level is set")
+	}
+	if params.Thinking.OfEnabled == nil {
+		t.Fatal("expected enabled thinking")
+	}
+	if params.Thinking.OfEnabled.BudgetTokens != 16384 {
+		t.Errorf("budget_tokens = %d, want 16384", params.Thinking.OfEnabled.BudgetTokens)
+	}
+}
+
+// unmarshalBlocks constructs []ContentBlockUnion via JSON round-trip so that
+// the internal JSON.raw field is populated (required by AsText/AsThinking).
+func unmarshalBlocks(t *testing.T, jsonStr string) []anthropic.ContentBlockUnion {
+	t.Helper()
+	var blocks []anthropic.ContentBlockUnion
+	if err := json.Unmarshal([]byte(jsonStr), &blocks); err != nil {
+		t.Fatalf("unmarshalBlocks: %v", err)
+	}
+	return blocks
+}
+
+func TestParseResponse_ThinkingBlock(t *testing.T) {
+	resp := &anthropic.Message{
+		Content: unmarshalBlocks(t, `[
+			{"type":"thinking","thinking":"Let me reason step by step...","signature":"sig"},
+			{"type":"text","text":"The answer is 42."}
+		]`),
+		StopReason: anthropic.StopReasonEndTurn,
+	}
+
+	result := parseResponse(resp)
+
+	if result.Reasoning != "Let me reason step by step..." {
+		t.Errorf("Reasoning = %q, want thinking content", result.Reasoning)
+	}
+	if result.Content != "The answer is 42." {
+		t.Errorf("Content = %q, want text content", result.Content)
+	}
+	if result.FinishReason != "stop" {
+		t.Errorf("FinishReason = %q, want stop", result.FinishReason)
+	}
+}
+
+func TestParseResponse_NoThinkingBlock(t *testing.T) {
+	resp := &anthropic.Message{
+		Content: unmarshalBlocks(t, `[
+			{"type":"text","text":"Just a normal response."}
+		]`),
+		StopReason: anthropic.StopReasonEndTurn,
+	}
+
+	result := parseResponse(resp)
+
+	if result.Reasoning != "" {
+		t.Errorf("Reasoning = %q, want empty", result.Reasoning)
+	}
+	if result.Content != "Just a normal response." {
+		t.Errorf("Content = %q, want text content", result.Content)
+	}
+}
+
+func TestBuildParams_NoThinkingKeepsTemperature(t *testing.T) {
+	msgs := []Message{{Role: "user", Content: "hello"}}
+	opts := map[string]any{
+		"temperature": 0.8,
+	}
+
+	params, err := buildParams(msgs, nil, "claude-sonnet-4-6", opts)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if !params.Temperature.Valid() {
+		t.Error("temperature should be preserved when thinking is not set")
+	}
+	if params.Temperature.Value != 0.8 {
+		t.Errorf("temperature = %f, want 0.8", params.Temperature.Value)
+	}
+}
diff --git a/pkg/providers/anthropic_messages/provider.go b/pkg/providers/anthropic_messages/provider.go
new file mode 100644
index 000000000..6a1c473dd
--- /dev/null
+++ b/pkg/providers/anthropic_messages/provider.go
@@ -0,0 +1,437 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package anthropicmessages
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
+)
+
+type (
+	ToolCall               = protocoltypes.ToolCall
+	FunctionCall           = protocoltypes.FunctionCall
+	LLMResponse            = protocoltypes.LLMResponse
+	UsageInfo              = protocoltypes.UsageInfo
+	Message                = protocoltypes.Message
+	ToolDefinition         = protocoltypes.ToolDefinition
+	ToolFunctionDefinition = protocoltypes.ToolFunctionDefinition
+)
+
+const (
+	defaultAPIVersion     = "2023-06-01"
+	defaultBaseURL        = "https://api.anthropic.com/v1"
+	defaultRequestTimeout = 120 * time.Second
+)
+
+// Provider implements Anthropic Messages API via HTTP (without SDK).
+// It supports custom endpoints that use Anthropic's native message format.
+type Provider struct {
+	apiKey     string
+	apiBase    string
+	httpClient *http.Client
+}
+
+// NewProvider creates a new Anthropic Messages API provider.
+func NewProvider(apiKey, apiBase string) *Provider {
+	return NewProviderWithTimeout(apiKey, apiBase, 0)
+}
+
+// NewProviderWithTimeout creates a provider with custom request timeout.
+func NewProviderWithTimeout(apiKey, apiBase string, timeoutSeconds int) *Provider {
+	baseURL := normalizeBaseURL(apiBase)
+	timeout := defaultRequestTimeout
+	if timeoutSeconds > 0 {
+		timeout = time.Duration(timeoutSeconds) * time.Second
+	}
+
+	return &Provider{
+		apiKey:  apiKey,
+		apiBase: baseURL,
+		httpClient: &http.Client{
+			Timeout: timeout,
+		},
+	}
+}
+
+// Chat sends messages to the Anthropic Messages API and returns the response.
+func (p *Provider) Chat(
+	ctx context.Context,
+	messages []Message,
+	tools []ToolDefinition,
+	model string,
+	options map[string]any,
+) (*LLMResponse, error) {
+	if p.apiKey == "" {
+		return nil, fmt.Errorf("API key not configured")
+	}
+
+	// Build request body
+	requestBody, err := buildRequestBody(messages, tools, model, options)
+	if err != nil {
+		return nil, fmt.Errorf("building request body: %w", err)
+	}
+
+	// Serialize to JSON
+	jsonBody, err := json.Marshal(requestBody)
+	if err != nil {
+		return nil, fmt.Errorf("serializing request body: %w", err)
+	}
+
+	// Build request URL
+	endpointURL, err := url.JoinPath(p.apiBase, "messages")
+	if err != nil {
+		return nil, fmt.Errorf("building endpoint URL: %w", err)
+	}
+
+	// Create HTTP request
+	req, err := http.NewRequestWithContext(ctx, "POST", endpointURL, bytes.NewReader(jsonBody))
+	if err != nil {
+		return nil, fmt.Errorf("creating HTTP request: %w", err)
+	}
+
+	// Set headers
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-API-Key", p.apiKey) //nolint:canonicalheader // Anthropic API requires exact header name
+	req.Header.Set("Anthropic-Version", defaultAPIVersion)
+
+	// Execute request
+	resp, err := p.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("executing HTTP request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	// Read response body
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("reading response body: %w", err)
+	}
+
+	// Check for HTTP errors with detailed messages
+	switch resp.StatusCode {
+	case http.StatusUnauthorized:
+		return nil, fmt.Errorf("authentication failed (401): check your API key")
+	case http.StatusTooManyRequests:
+		return nil, fmt.Errorf("rate limited (429): %s", string(body))
+	case http.StatusBadRequest:
+		return nil, fmt.Errorf("bad request (400): %s", string(body))
+	case http.StatusNotFound:
+		return nil, fmt.Errorf("endpoint not found (404): %s", string(body))
+	case http.StatusInternalServerError:
+		return nil, fmt.Errorf("internal server error (500): %s", string(body))
+	case http.StatusServiceUnavailable:
+		return nil, fmt.Errorf("service unavailable (503): %s", string(body))
+	default:
+		if resp.StatusCode != http.StatusOK {
+			return nil, fmt.Errorf("API request failed with status %d: %s", resp.StatusCode, string(body))
+		}
+	}
+
+	// Parse response
+	return parseResponseBody(body)
+}
+
+// GetDefaultModel returns the default model for this provider.
+func (p *Provider) GetDefaultModel() string {
+	return "claude-sonnet-4.6"
+}
+
+// buildRequestBody converts internal message format to Anthropic Messages API format.
+func buildRequestBody(
+	messages []Message,
+	tools []ToolDefinition,
+	model string,
+	options map[string]any,
+) (map[string]any, error) {
+	// max_tokens is required and guaranteed by agent loop
+	maxTokens, ok := asInt(options["max_tokens"])
+	if !ok {
+		return nil, fmt.Errorf("max_tokens is required in options")
+	}
+
+	result := map[string]any{
+		"model":      model,
+		"max_tokens": int64(maxTokens),
+		"messages":   []any{},
+	}
+
+	// Set temperature from options
+	if temp, ok := asFloat(options["temperature"]); ok {
+		result["temperature"] = temp
+	}
+
+	// Process messages
+	var systemPrompt string
+	var apiMessages []any
+
+	for _, msg := range messages {
+		switch msg.Role {
+		case "system":
+			// Accumulate system messages
+			if systemPrompt != "" {
+				systemPrompt += "\n\n" + msg.Content
+			} else {
+				systemPrompt = msg.Content
+			}
+
+		case "user":
+			if msg.ToolCallID != "" {
+				// Tool result message — merge into previous user message if it contains tool_results
+				toolResultBlock := map[string]any{
+					"type":        "tool_result",
+					"tool_use_id": msg.ToolCallID,
+					"content":     msg.Content,
+				}
+				if len(apiMessages) > 0 {
+					if prev, ok := apiMessages[len(apiMessages)-1].(map[string]any); ok && prev["role"] == "user" {
+						if content, ok := prev["content"].([]map[string]any); ok {
+							prev["content"] = append(content, toolResultBlock)
+							continue
+						}
+					}
+				}
+				apiMessages = append(apiMessages, map[string]any{
+					"role":    "user",
+					"content": []map[string]any{toolResultBlock},
+				})
+			} else {
+				// Regular user message
+				apiMessages = append(apiMessages, map[string]any{
+					"role":    "user",
+					"content": msg.Content,
+				})
+			}
+
+		case "assistant":
+			content := []any{}
+
+			// Add text content if present
+			if msg.Content != "" {
+				content = append(content, map[string]any{
+					"type": "text",
+					"text": msg.Content,
+				})
+			}
+
+			// Add tool_use blocks
+			for _, tc := range msg.ToolCalls {
+				if strings.TrimSpace(tc.Name) == "" {
+					continue
+				}
+
+				// Handle nil Arguments (GLM-4 may return null input)
+				input := tc.Arguments
+				if input == nil {
+					input = map[string]any{}
+				}
+
+				toolUse := map[string]any{
+					"type":  "tool_use",
+					"id":    tc.ID,
+					"name":  tc.Name,
+					"input": input,
+				}
+				content = append(content, toolUse)
+			}
+
+			apiMessages = append(apiMessages, map[string]any{
+				"role":    "assistant",
+				"content": content,
+			})
+
+		case "tool":
+			// Tool result (alternative format) — merge into previous user message if it contains tool_results
+			toolResultBlock := map[string]any{
+				"type":        "tool_result",
+				"tool_use_id": msg.ToolCallID,
+				"content":     msg.Content,
+			}
+			if len(apiMessages) > 0 {
+				if prev, ok := apiMessages[len(apiMessages)-1].(map[string]any); ok && prev["role"] == "user" {
+					if content, ok := prev["content"].([]map[string]any); ok {
+						prev["content"] = append(content, toolResultBlock)
+						continue
+					}
+				}
+			}
+			apiMessages = append(apiMessages, map[string]any{
+				"role":    "user",
+				"content": []map[string]any{toolResultBlock},
+			})
+		}
+	}
+
+	result["messages"] = apiMessages
+
+	// Set system prompt if present
+	if systemPrompt != "" {
+		result["system"] = systemPrompt
+	}
+
+	// Add tools if present
+	if len(tools) > 0 {
+		result["tools"] = buildTools(tools)
+	}
+
+	return result, nil
+}
+
+// buildTools converts tool definitions to Anthropic format.
+func buildTools(tools []ToolDefinition) []any {
+	result := make([]any, len(tools))
+	for i, tool := range tools {
+		toolDef := map[string]any{
+			"name":         tool.Function.Name,
+			"description":  tool.Function.Description,
+			"input_schema": tool.Function.Parameters,
+		}
+		result[i] = toolDef
+	}
+	return result
+}
+
+// parseResponseBody parses Anthropic Messages API response.
+func parseResponseBody(body []byte) (*LLMResponse, error) {
+	var resp anthropicMessageResponse
+	if err := json.Unmarshal(body, &resp); err != nil {
+		return nil, fmt.Errorf("parsing JSON response: %w", err)
+	}
+
+	// Extract content and tool calls
+	var content strings.Builder
+	toolCalls := make([]ToolCall, 0) // Initialize as empty slice (not nil) for consistent JSON serialization
+
+	for _, block := range resp.Content {
+		switch block.Type {
+		case "text":
+			content.WriteString(block.Text)
+		case "tool_use":
+			argsJSON, _ := json.Marshal(block.Input)
+			toolCalls = append(toolCalls, ToolCall{
+				ID:        block.ID,
+				Name:      block.Name,
+				Arguments: block.Input,
+				Function: &FunctionCall{
+					Name:      block.Name,
+					Arguments: string(argsJSON),
+				},
+			})
+		}
+	}
+
+	// Map stop_reason
+	finishReason := "stop"
+	switch resp.StopReason {
+	case "tool_use":
+		finishReason = "tool_calls"
+	case "max_tokens":
+		finishReason = "length"
+	case "end_turn":
+		finishReason = "stop"
+	case "stop_sequence":
+		finishReason = "stop"
+	}
+
+	return &LLMResponse{
+		Content:      content.String(),
+		ToolCalls:    toolCalls,
+		FinishReason: finishReason,
+		Usage: &UsageInfo{
+			PromptTokens:     int(resp.Usage.InputTokens),
+			CompletionTokens: int(resp.Usage.OutputTokens),
+			TotalTokens:      int(resp.Usage.InputTokens + resp.Usage.OutputTokens),
+		},
+	}, nil
+}
+
+// normalizeBaseURL ensures the base URL is properly formatted.
+// It removes /v1 suffix if present (to avoid duplication) and always appends /v1.
+// This handles edge cases like "https://api.example.com/v1/proxy" correctly.
+func normalizeBaseURL(apiBase string) string {
+	base := strings.TrimSpace(apiBase)
+	if base == "" {
+		return defaultBaseURL
+	}
+
+	// Remove trailing slashes
+	base = strings.TrimRight(base, "/")
+
+	// Remove /v1 suffix if present (will be re-added)
+	// This prevents duplication for URLs like "https://api.example.com/v1/proxy"
+	if before, ok := strings.CutSuffix(base, "/v1"); ok {
+		base = before
+	}
+
+	// Ensure we don't have an empty string after cutting
+	if base == "" {
+		return defaultBaseURL
+	}
+
+	// Add /v1 suffix (required by Anthropic Messages API)
+	return base + "/v1"
+}
+
+// Helper functions for type conversion
+
+func asInt(v any) (int, bool) {
+	switch val := v.(type) {
+	case int:
+		return val, true
+	case float64:
+		return int(val), true
+	case int64:
+		return int(val), true
+	default:
+		return 0, false
+	}
+}
+
+func asFloat(v any) (float64, bool) {
+	switch val := v.(type) {
+	case float64:
+		return val, true
+	case int:
+		return float64(val), true
+	case int64:
+		return float64(val), true
+	default:
+		return 0, false
+	}
+}
+
+// Anthropic API response structures
+
+type anthropicMessageResponse struct {
+	ID         string         `json:"id"`
+	Type       string         `json:"type"`
+	Role       string         `json:"role"`
+	Content    []contentBlock `json:"content"`
+	StopReason string         `json:"stop_reason"`
+	Model      string         `json:"model"`
+	Usage      usageInfo      `json:"usage"`
+}
+
+type contentBlock struct {
+	Type  string         `json:"type"`
+	Text  string         `json:"text,omitempty"`
+	ID    string         `json:"id,omitempty"`
+	Name  string         `json:"name,omitempty"`
+	Input map[string]any `json:"input,omitempty"`
+}
+
+type usageInfo struct {
+	InputTokens  int64 `json:"input_tokens"`
+	OutputTokens int64 `json:"output_tokens"`
+}
diff --git a/pkg/providers/anthropic_messages/provider_test.go b/pkg/providers/anthropic_messages/provider_test.go
new file mode 100644
index 000000000..39bc48117
--- /dev/null
+++ b/pkg/providers/anthropic_messages/provider_test.go
@@ -0,0 +1,757 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package anthropicmessages
+
+import (
+	"context"
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestBuildRequestBody(t *testing.T) {
+	tests := []struct {
+		name     string
+		messages []Message
+		tools    []ToolDefinition
+		model    string
+		options  map[string]any
+		want     map[string]any
+		wantErr  bool
+	}{
+		{
+			name: "basic user message",
+			messages: []Message{
+				{Role: "user", Content: "Hello, world!"},
+			},
+			model: "test-model",
+			options: map[string]any{
+				"max_tokens": 8192,
+			},
+			want: map[string]any{
+				"model":      "test-model",
+				"max_tokens": int64(8192),
+				"messages": []any{
+					map[string]any{
+						"role":    "user",
+						"content": "Hello, world!",
+					},
+				},
+			},
+		},
+		{
+			name: "user and assistant messages",
+			messages: []Message{
+				{Role: "user", Content: "What is 2+2?"},
+				{Role: "assistant", Content: "4"},
+			},
+			model: "test-model",
+			options: map[string]any{
+				"max_tokens": 8192,
+			},
+			want: map[string]any{
+				"model":      "test-model",
+				"max_tokens": int64(8192),
+				"messages": []any{
+					map[string]any{
+						"role":    "user",
+						"content": "What is 2+2?",
+					},
+					map[string]any{
+						"role": "assistant",
+						"content": []any{
+							map[string]any{
+								"type": "text",
+								"text": "4",
+							},
+						},
+					},
+				},
+			},
+		},
+		{
+			name: "with system message",
+			messages: []Message{
+				{Role: "system", Content: "You are a helpful assistant."},
+				{Role: "user", Content: "Hello"},
+			},
+			model: "test-model",
+			options: map[string]any{
+				"max_tokens": 8192,
+			},
+			want: map[string]any{
+				"model":      "test-model",
+				"max_tokens": int64(8192),
+				"system":     "You are a helpful assistant.",
+				"messages": []any{
+					map[string]any{
+						"role":    "user",
+						"content": "Hello",
+					},
+				},
+			},
+		},
+		{
+			name: "with custom max_tokens and temperature",
+			messages: []Message{
+				{Role: "user", Content: "Test"},
+			},
+			model: "test-model",
+			options: map[string]any{
+				"max_tokens":  2048,
+				"temperature": 0.5,
+			},
+			want: map[string]any{
+				"model":       "test-model",
+				"max_tokens":  int64(2048),
+				"temperature": 0.5,
+				"messages": []any{
+					map[string]any{
+						"role":    "user",
+						"content": "Test",
+					},
+				},
+			},
+		},
+		{
+			name: "missing max_tokens returns error",
+			messages: []Message{
+				{Role: "user", Content: "Test"},
+			},
+			model:   "test-model",
+			options: map[string]any{},
+			want:    nil,
+			wantErr: true,
+		},
+		{
+			name: "with tools",
+			messages: []Message{
+				{Role: "user", Content: "What's the weather?"},
+			},
+			tools: []ToolDefinition{
+				{
+					Function: ToolFunctionDefinition{
+						Name:        "get_weather",
+						Description: "Get current weather",
+						Parameters: map[string]any{
+							"type": "object",
+							"properties": map[string]any{
+								"location": map[string]any{
+									"type":        "string",
+									"description": "City name",
+								},
+							},
+						},
+					},
+				},
+			},
+			model: "test-model",
+			options: map[string]any{
+				"max_tokens": 8192,
+			},
+			want: map[string]any{
+				"model":      "test-model",
+				"max_tokens": int64(8192),
+				"messages": []any{
+					map[string]any{
+						"role":    "user",
+						"content": "What's the weather?",
+					},
+				},
+				"tools": []any{
+					map[string]any{
+						"name":        "get_weather",
+						"description": "Get current weather",
+						"input_schema": map[string]any{
+							"type": "object",
+							"properties": map[string]any{
+								"location": map[string]any{
+									"type":        "string",
+									"description": "City name",
+								},
+							},
+						},
+					},
+				},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := buildRequestBody(tt.messages, tt.tools, tt.model, tt.options)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("buildRequestBody() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if !reflect.DeepEqual(got, tt.want) {
+				gotJSON, _ := json.MarshalIndent(got, "", "  ")
+				wantJSON, _ := json.MarshalIndent(tt.want, "", "  ")
+				t.Errorf("buildRequestBody() mismatch:\ngot:\n%s\nwant:\n%s", gotJSON, wantJSON)
+			}
+		})
+	}
+}
+
+func TestParseResponseBody(t *testing.T) {
+	tests := []struct {
+		name    string
+		body    []byte
+		want    *LLMResponse
+		wantErr bool
+	}{
+		{
+			name: "basic text response",
+			body: []byte(`{
+				"id": "msg-123",
+				"type": "message",
+				"role": "assistant",
+				"content": [
+					{"type": "text", "text": "Hello, how can I help?"}
+				],
+				"stop_reason": "end_turn",
+				"model": "test-model",
+				"usage": {
+					"input_tokens": 10,
+					"output_tokens": 5
+				}
+			}`),
+			want: &LLMResponse{
+				Content:      "Hello, how can I help?",
+				ToolCalls:    []ToolCall{},
+				FinishReason: "stop",
+				Usage: &UsageInfo{
+					PromptTokens:     10,
+					CompletionTokens: 5,
+					TotalTokens:      15,
+				},
+				Reasoning:        "",
+				ReasoningDetails: nil,
+			},
+			wantErr: false,
+		},
+		{
+			name: "response with tool use",
+			body: []byte(`{
+				"id": "msg-456",
+				"type": "message",
+				"role": "assistant",
+				"content": [
+					{"type": "text", "text": "I'll check the weather for you."},
+					{
+						"type": "tool_use",
+						"id": "toolu-123",
+						"name": "get_weather",
+						"input": {"location": "Tokyo"}
+					}
+				],
+				"stop_reason": "tool_use",
+				"model": "test-model",
+				"usage": {
+					"input_tokens": 20,
+					"output_tokens": 15
+				}
+			}`),
+			want: &LLMResponse{
+				Content: "I'll check the weather for you.",
+				ToolCalls: []ToolCall{
+					{
+						ID:   "toolu-123",
+						Name: "get_weather",
+						Arguments: map[string]any{
+							"location": "Tokyo",
+						},
+						Function: &FunctionCall{
+							Name:      "get_weather",
+							Arguments: `{"location":"Tokyo"}`,
+						},
+					},
+				},
+				FinishReason: "tool_calls",
+				Usage: &UsageInfo{
+					PromptTokens:     20,
+					CompletionTokens: 15,
+					TotalTokens:      35,
+				},
+				Reasoning:        "",
+				ReasoningDetails: nil,
+			},
+			wantErr: false,
+		},
+		{
+			name:    "invalid JSON",
+			body:    []byte(`invalid json`),
+			want:    nil,
+			wantErr: true,
+		},
+		{
+			name: "max_tokens stop reason",
+			body: []byte(`{
+				"id": "msg-789",
+				"type": "message",
+				"role": "assistant",
+				"content": [
+					{"type": "text", "text": "Partial response"}
+				],
+				"stop_reason": "max_tokens",
+				"model": "test-model",
+				"usage": {
+					"input_tokens": 100,
+					"output_tokens": 4096
+				}
+			}`),
+			want: &LLMResponse{
+				Content:      "Partial response",
+				ToolCalls:    []ToolCall{},
+				FinishReason: "length",
+				Usage: &UsageInfo{
+					PromptTokens:     100,
+					CompletionTokens: 4096,
+					TotalTokens:      4196,
+				},
+				Reasoning:        "",
+				ReasoningDetails: nil,
+			},
+			wantErr: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := parseResponseBody(tt.body)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("parseResponseBody() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if err != nil {
+				return
+			}
+
+			// Compare individual fields
+			if got.Content != tt.want.Content {
+				t.Errorf("Content = %q, want %q", got.Content, tt.want.Content)
+			}
+			if got.FinishReason != tt.want.FinishReason {
+				t.Errorf("FinishReason = %q, want %q", got.FinishReason, tt.want.FinishReason)
+			}
+			if got.Usage == nil && tt.want.Usage != nil {
+				t.Errorf("Usage = nil, want non-nil")
+			} else if got.Usage != nil && tt.want.Usage == nil {
+				t.Errorf("Usage = non-nil, want nil")
+			} else if got.Usage != nil && tt.want.Usage != nil {
+				if got.Usage.PromptTokens != tt.want.Usage.PromptTokens {
+					t.Errorf("Usage.PromptTokens = %d, want %d", got.Usage.PromptTokens, tt.want.Usage.PromptTokens)
+				}
+				if got.Usage.CompletionTokens != tt.want.Usage.CompletionTokens {
+					t.Errorf("Usage.CompletionTokens = %d, want %d",
+						got.Usage.CompletionTokens, tt.want.Usage.CompletionTokens)
+				}
+				if got.Usage.TotalTokens != tt.want.Usage.TotalTokens {
+					t.Errorf("Usage.TotalTokens = %d, want %d", got.Usage.TotalTokens, tt.want.Usage.TotalTokens)
+				}
+			}
+			if len(got.ToolCalls) != len(tt.want.ToolCalls) {
+				t.Errorf("ToolCalls length = %d, want %d", len(got.ToolCalls), len(tt.want.ToolCalls))
+			} else {
+				for i := range got.ToolCalls {
+					if got.ToolCalls[i].ID != tt.want.ToolCalls[i].ID {
+						t.Errorf("ToolCalls[%d].ID = %q, want %q",
+							i, got.ToolCalls[i].ID, tt.want.ToolCalls[i].ID)
+					}
+					if got.ToolCalls[i].Name != tt.want.ToolCalls[i].Name {
+						t.Errorf("ToolCalls[%d].Name = %q, want %q",
+							i, got.ToolCalls[i].Name, tt.want.ToolCalls[i].Name)
+					}
+				}
+			}
+		})
+	}
+}
+
+func TestNormalizeBaseURL(t *testing.T) {
+	tests := []struct {
+		name     string
+		apiBase  string
+		expected string
+	}{
+		{
+			name:     "empty string defaults to official API",
+			apiBase:  "",
+			expected: "https://api.anthropic.com/v1",
+		},
+		{
+			name:     "URL without /v1 gets it appended",
+			apiBase:  "https://api.example.com/anthropic",
+			expected: "https://api.example.com/anthropic/v1",
+		},
+		{
+			name:     "URL with /v1 remains unchanged",
+			apiBase:  "https://api.example.com/v1",
+			expected: "https://api.example.com/v1",
+		},
+		{
+			name:     "URL with trailing slash gets cleaned",
+			apiBase:  "https://api.example.com/anthropic/",
+			expected: "https://api.example.com/anthropic/v1",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := normalizeBaseURL(tt.apiBase)
+			if got != tt.expected {
+				t.Errorf("normalizeBaseURL(%q) = %q, want %q", tt.apiBase, got, tt.expected)
+			}
+		})
+	}
+}
+
+func TestNewProvider(t *testing.T) {
+	provider := NewProvider("test-key", "https://api.example.com")
+	if provider == nil {
+		t.Fatal("NewProvider() returned nil")
+	}
+	if provider.apiKey != "test-key" {
+		t.Errorf("provider.apiKey = %q, want %q", provider.apiKey, "test-key")
+	}
+	if provider.apiBase != "https://api.example.com/v1" {
+		t.Errorf("provider.apiBase = %q, want %q", provider.apiBase, "https://api.example.com/v1")
+	}
+}
+
+func TestGetDefaultModel(t *testing.T) {
+	provider := NewProvider("test-key", "")
+	got := provider.GetDefaultModel()
+	expected := "claude-sonnet-4.6"
+	if got != expected {
+		t.Errorf("GetDefaultModel() = %q, want %q", got, expected)
+	}
+}
+
+// TestBuildRequestBodyEdgeCases tests edge cases for buildRequestBody.
+func TestBuildRequestBodyEdgeCases(t *testing.T) {
+	tests := []struct {
+		name     string
+		messages []Message
+		tools    []ToolDefinition
+		model    string
+		options  map[string]any
+		wantErr  bool
+	}{
+		{
+			name:     "empty message list",
+			messages: []Message{},
+			model:    "test-model",
+			options: map[string]any{
+				"max_tokens": 8192,
+			},
+			wantErr: false,
+		},
+		{
+			name: "very long system message",
+			messages: []Message{
+				{Role: "system", Content: strings.Repeat("This is a very long system prompt. ", 1000)},
+				{Role: "user", Content: "Hello"},
+			},
+			model: "test-model",
+			options: map[string]any{
+				"max_tokens": 8192,
+			},
+			wantErr: false,
+		},
+		{
+			name: "multiple consecutive system messages",
+			messages: []Message{
+				{Role: "system", Content: "First system message"},
+				{Role: "system", Content: "Second system message"},
+				{Role: "system", Content: "Third system message"},
+				{Role: "user", Content: "Hello"},
+			},
+			model: "test-model",
+			options: map[string]any{
+				"max_tokens": 8192,
+			},
+			wantErr: false,
+		},
+		{
+			name: "tool result without tool call",
+			messages: []Message{
+				{Role: "user", Content: "Use a tool"},
+				{Role: "assistant", Content: "", ToolCalls: []ToolCall{
+					{ID: "tool-1", Name: "test_tool", Arguments: map[string]any{"arg": "value"}},
+				}},
+				{Role: "user", ToolCallID: "tool-1", Content: "Tool result"},
+			},
+			model: "test-model",
+			options: map[string]any{
+				"max_tokens": 8192,
+			},
+			wantErr: false,
+		},
+		{
+			name: "skip tool calls with empty names",
+			messages: []Message{
+				{Role: "assistant", Content: "Calling tool", ToolCalls: []ToolCall{
+					{ID: "tool-empty", Name: "", Arguments: map[string]any{"ignored": true}},
+					{ID: "tool-valid", Name: "test_tool", Arguments: map[string]any{"arg": "value"}},
+				}},
+			},
+			model: "test-model",
+			options: map[string]any{
+				"max_tokens": 8192,
+			},
+			wantErr: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := buildRequestBody(tt.messages, tt.tools, tt.model, tt.options)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("buildRequestBody() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if err != nil {
+				return
+			}
+
+			// Verify basic structure
+			if got == nil {
+				t.Error("buildRequestBody() returned nil")
+				return
+			}
+			if got["model"] != tt.model {
+				t.Errorf("model = %v, want %v", got["model"], tt.model)
+			}
+
+			if tt.name == "skip tool calls with empty names" {
+				messages, ok := got["messages"].([]any)
+				if !ok || len(messages) != 1 {
+					t.Fatalf("messages = %#v, want single assistant message", got["messages"])
+				}
+
+				assistantMsg, ok := messages[0].(map[string]any)
+				if !ok {
+					t.Fatalf("assistant message = %#v, want map", messages[0])
+				}
+
+				content, ok := assistantMsg["content"].([]any)
+				if !ok {
+					t.Fatalf("assistant content = %#v, want []any", assistantMsg["content"])
+				}
+				if len(content) != 2 {
+					t.Fatalf("assistant content length = %d, want 2", len(content))
+				}
+
+				toolUse, ok := content[1].(map[string]any)
+				if !ok {
+					t.Fatalf("tool_use block = %#v, want map", content[1])
+				}
+				if gotName := toolUse["name"]; gotName != "test_tool" {
+					t.Fatalf("tool_use name = %v, want %q", gotName, "test_tool")
+				}
+				if gotID := toolUse["id"]; gotID != "tool-valid" {
+					t.Fatalf("tool_use id = %v, want %q", gotID, "tool-valid")
+				}
+			}
+		})
+	}
+}
+
+func TestBuildRequestBody_ConsecutiveToolResultsMerged(t *testing.T) {
+	// Consecutive tool results (role "tool") should be merged into a single "user" message
+	messages := []Message{
+		{Role: "user", Content: "Use tools"},
+		{Role: "assistant", Content: "", ToolCalls: []ToolCall{
+			{ID: "t1", Name: "tool_a", Arguments: map[string]any{"x": 1}},
+			{ID: "t2", Name: "tool_b", Arguments: map[string]any{"y": 2}},
+		}},
+		{Role: "tool", ToolCallID: "t1", Content: "result1"},
+		{Role: "tool", ToolCallID: "t2", Content: "result2"},
+	}
+
+	got, err := buildRequestBody(messages, nil, "test-model", map[string]any{"max_tokens": 8192})
+	if err != nil {
+		t.Fatalf("buildRequestBody() error: %v", err)
+	}
+
+	apiMessages, ok := got["messages"].([]any)
+	if !ok {
+		t.Fatalf("messages is not []any")
+	}
+
+	// Expect: user, assistant, user (merged tool results)
+	if len(apiMessages) != 3 {
+		for i, m := range apiMessages {
+			t.Logf("message[%d]: %+v", i, m)
+		}
+		t.Fatalf("expected 3 API messages, got %d", len(apiMessages))
+	}
+
+	// The third message should be a user message with 2 tool_result blocks
+	toolResultMsg, ok := apiMessages[2].(map[string]any)
+	if !ok {
+		t.Fatalf("tool result message is not map[string]any")
+	}
+	if toolResultMsg["role"] != "user" {
+		t.Errorf("expected role 'user', got %v", toolResultMsg["role"])
+	}
+	content, ok := toolResultMsg["content"].([]map[string]any)
+	if !ok {
+		t.Fatalf("content is not []map[string]any: %T", toolResultMsg["content"])
+	}
+	if len(content) != 2 {
+		t.Fatalf("expected 2 tool_result blocks, got %d", len(content))
+	}
+	if content[0]["tool_use_id"] != "t1" {
+		t.Errorf("first tool_result tool_use_id = %v, want t1", content[0]["tool_use_id"])
+	}
+	if content[1]["tool_use_id"] != "t2" {
+		t.Errorf("second tool_result tool_use_id = %v, want t2", content[1]["tool_use_id"])
+	}
+}
+
+func TestBuildRequestBody_UserToolResultsMerged(t *testing.T) {
+	// Consecutive tool results using role "user" with ToolCallID should also be merged
+	messages := []Message{
+		{Role: "user", Content: "Use tools"},
+		{Role: "assistant", Content: "", ToolCalls: []ToolCall{
+			{ID: "t1", Name: "tool_a", Arguments: map[string]any{"x": 1}},
+			{ID: "t2", Name: "tool_b", Arguments: map[string]any{"y": 2}},
+		}},
+		{Role: "user", ToolCallID: "t1", Content: "result1"},
+		{Role: "user", ToolCallID: "t2", Content: "result2"},
+	}
+
+	got, err := buildRequestBody(messages, nil, "test-model", map[string]any{"max_tokens": 8192})
+	if err != nil {
+		t.Fatalf("buildRequestBody() error: %v", err)
+	}
+
+	apiMessages, ok := got["messages"].([]any)
+	if !ok {
+		t.Fatalf("messages is not []any")
+	}
+
+	// Expect: user, assistant, user (merged tool results)
+	if len(apiMessages) != 3 {
+		t.Fatalf("expected 3 API messages, got %d", len(apiMessages))
+	}
+
+	toolResultMsg := apiMessages[2].(map[string]any)
+	content, ok := toolResultMsg["content"].([]map[string]any)
+	if !ok {
+		t.Fatalf("content is not []map[string]any: %T", toolResultMsg["content"])
+	}
+	if len(content) != 2 {
+		t.Fatalf("expected 2 tool_result blocks, got %d", len(content))
+	}
+}
+
+// TestParseResponseBodyEdgeCases tests edge cases for parseResponseBody.
+func TestParseResponseBodyEdgeCases(t *testing.T) {
+	tests := []struct {
+		name    string
+		body    []byte
+		wantErr bool
+		check   func(*testing.T, *LLMResponse)
+	}{
+		{
+			name: "empty content blocks",
+			body: []byte(`{
+				"id": "msg-empty",
+				"type": "message",
+				"role": "assistant",
+				"content": [],
+				"stop_reason": "end_turn",
+				"model": "test-model",
+				"usage": {"input_tokens": 5, "output_tokens": 0}
+			}`),
+			wantErr: false,
+			check: func(t *testing.T, resp *LLMResponse) {
+				if resp.Content != "" {
+					t.Errorf("Content = %q, want empty string", resp.Content)
+				}
+				if len(resp.ToolCalls) != 0 {
+					t.Errorf("ToolCalls length = %d, want 0", len(resp.ToolCalls))
+				}
+			},
+		},
+		{
+			name: "multiple tool use blocks",
+			body: []byte(`{
+				"id": "msg-multi",
+				"type": "message",
+				"role": "assistant",
+				"content": [
+					{"type": "tool_use", "id": "tool-1", "name": "func1", "input": {"arg": "val1"}},
+					{"type": "tool_use", "id": "tool-2", "name": "func2", "input": {"arg": "val2"}}
+				],
+				"stop_reason": "tool_use",
+				"model": "test-model",
+				"usage": {"input_tokens": 10, "output_tokens": 20}
+			}`),
+			wantErr: false,
+			check: func(t *testing.T, resp *LLMResponse) {
+				if len(resp.ToolCalls) != 2 {
+					t.Errorf("ToolCalls length = %d, want 2", len(resp.ToolCalls))
+				}
+			},
+		},
+		{
+			name:    "malformed JSON response",
+			body:    []byte(`{invalid json`),
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := parseResponseBody(tt.body)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("parseResponseBody() error = %v, wantErr %v", err, tt.wantErr)
+				return
+			}
+			if tt.check != nil && err == nil {
+				tt.check(t, got)
+			}
+		})
+	}
+}
+
+// TestProviderChatErrors tests error handling in Chat.
+// Note: apiBase check removed as it's dead code - normalizeBaseURL() always provides a default.
+func TestProviderChatErrors(t *testing.T) {
+	tests := []struct {
+		name       string
+		apiKey     string
+		messages   []Message
+		wantErrMsg string
+	}{
+		{
+			name:       "missing API key",
+			apiKey:     "",
+			messages:   []Message{{Role: "user", Content: "Test"}},
+			wantErrMsg: "API key not configured",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Create provider using constructor to ensure proper initialization
+			provider := NewProvider(tt.apiKey, "https://api.example.com")
+
+			_, err := provider.Chat(context.Background(), tt.messages, nil, "test-model", nil)
+			if err == nil {
+				t.Fatal("Chat() expected error, got nil")
+			}
+			if err.Error() != tt.wantErrMsg {
+				t.Errorf("Chat() error = %q, want %q", err.Error(), tt.wantErrMsg)
+			}
+		})
+	}
+}
diff --git a/pkg/providers/antigravity_provider.go b/pkg/providers/antigravity_provider.go
index d4ee528b7..8a1890212 100644
--- a/pkg/providers/antigravity_provider.go
+++ b/pkg/providers/antigravity_provider.go
@@ -640,7 +640,10 @@ func FetchAntigravityProjectID(accessToken string) (string, error) {
 	}
 	defer resp.Body.Close()
 
-	body, _ := io.ReadAll(resp.Body)
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return "", fmt.Errorf("reading loadCodeAssist response: %w", err)
+	}
 	if resp.StatusCode != http.StatusOK {
 		return "", fmt.Errorf("loadCodeAssist failed: %s", string(body))
 	}
@@ -681,7 +684,10 @@ func FetchAntigravityModels(accessToken, projectID string) ([]AntigravityModelIn
 	}
 	defer resp.Body.Close()
 
-	body, _ := io.ReadAll(resp.Body)
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, fmt.Errorf("reading fetchAvailableModels response: %w", err)
+	}
 	if resp.StatusCode != http.StatusOK {
 		return nil, fmt.Errorf(
 			"fetchAvailableModels failed (HTTP %d): %s",
diff --git a/pkg/providers/azure/provider.go b/pkg/providers/azure/provider.go
new file mode 100644
index 000000000..e0ddbbde4
--- /dev/null
+++ b/pkg/providers/azure/provider.go
@@ -0,0 +1,150 @@
+package azure
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/providers/common"
+	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
+)
+
+type (
+	LLMResponse    = protocoltypes.LLMResponse
+	Message        = protocoltypes.Message
+	ToolDefinition = protocoltypes.ToolDefinition
+)
+
+const (
+	// azureAPIVersion is the Azure OpenAI API version used for all requests.
+	azureAPIVersion       = "2024-10-21"
+	defaultRequestTimeout = common.DefaultRequestTimeout
+)
+
+// Provider implements the LLM provider interface for Azure OpenAI endpoints.
+// It handles Azure-specific authentication (api-key header), URL construction
+// (deployment-based), and request body formatting (max_completion_tokens, no model field).
+type Provider struct {
+	apiKey     string
+	apiBase    string
+	httpClient *http.Client
+}
+
+// Option configures the Azure Provider.
+type Option func(*Provider)
+
+// WithRequestTimeout sets the HTTP request timeout.
+func WithRequestTimeout(timeout time.Duration) Option {
+	return func(p *Provider) {
+		if timeout > 0 {
+			p.httpClient.Timeout = timeout
+		}
+	}
+}
+
+// NewProvider creates a new Azure OpenAI provider.
+func NewProvider(apiKey, apiBase, proxy string, opts ...Option) *Provider {
+	p := &Provider{
+		apiKey:     apiKey,
+		apiBase:    strings.TrimRight(apiBase, "/"),
+		httpClient: common.NewHTTPClient(proxy),
+	}
+
+	for _, opt := range opts {
+		if opt != nil {
+			opt(p)
+		}
+	}
+
+	return p
+}
+
+// NewProviderWithTimeout creates a new Azure OpenAI provider with a custom request timeout in seconds.
+func NewProviderWithTimeout(apiKey, apiBase, proxy string, requestTimeoutSeconds int) *Provider {
+	return NewProvider(
+		apiKey, apiBase, proxy,
+		WithRequestTimeout(time.Duration(requestTimeoutSeconds)*time.Second),
+	)
+}
+
+// Chat sends a chat completion request to the Azure OpenAI endpoint.
+// The model parameter is used as the Azure deployment name in the URL.
+func (p *Provider) Chat(
+	ctx context.Context,
+	messages []Message,
+	tools []ToolDefinition,
+	model string,
+	options map[string]any,
+) (*LLMResponse, error) {
+	if p.apiBase == "" {
+		return nil, fmt.Errorf("Azure API base not configured")
+	}
+
+	// model is the deployment name for Azure OpenAI
+	deployment := model
+
+	// Build Azure-specific URL safely using url.JoinPath and query encoding
+	// to prevent path traversal or query injection via deployment names.
+	base, err := url.JoinPath(p.apiBase, "openai/deployments", deployment, "chat/completions")
+	if err != nil {
+		return nil, fmt.Errorf("failed to build Azure request URL: %w", err)
+	}
+	requestURL := base + "?api-version=" + azureAPIVersion
+
+	// Build request body — no "model" field (Azure infers from deployment URL)
+	requestBody := map[string]any{
+		"messages": common.SerializeMessages(messages),
+	}
+
+	if len(tools) > 0 {
+		requestBody["tools"] = tools
+		requestBody["tool_choice"] = "auto"
+	}
+
+	// Azure OpenAI always uses max_completion_tokens
+	if maxTokens, ok := common.AsInt(options["max_tokens"]); ok {
+		requestBody["max_completion_tokens"] = maxTokens
+	}
+
+	if temperature, ok := common.AsFloat(options["temperature"]); ok {
+		requestBody["temperature"] = temperature
+	}
+
+	jsonData, err := json.Marshal(requestBody)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal request: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", requestURL, bytes.NewReader(jsonData))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	// Azure uses api-key header instead of Authorization: Bearer
+	req.Header.Set("Content-Type", "application/json")
+	if p.apiKey != "" {
+		req.Header.Set("Api-Key", p.apiKey)
+	}
+
+	resp, err := p.httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to send request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, common.HandleErrorResponse(resp, p.apiBase)
+	}
+
+	return common.ReadAndParseResponse(resp, p.apiBase)
+}
+
+// GetDefaultModel returns an empty string as Azure deployments are user-configured.
+func (p *Provider) GetDefaultModel() string {
+	return ""
+}
diff --git a/pkg/providers/azure/provider_test.go b/pkg/providers/azure/provider_test.go
new file mode 100644
index 000000000..531b81296
--- /dev/null
+++ b/pkg/providers/azure/provider_test.go
@@ -0,0 +1,232 @@
+package azure
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+)
+
+// writeValidResponse writes a minimal valid Azure OpenAI chat completion response.
+func writeValidResponse(w http.ResponseWriter) {
+	resp := map[string]any{
+		"choices": []map[string]any{
+			{
+				"message":       map[string]any{"content": "ok"},
+				"finish_reason": "stop",
+			},
+		},
+	}
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(resp)
+}
+
+func TestProviderChat_AzureURLConstruction(t *testing.T) {
+	var capturedPath string
+	var capturedAPIVersion string
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		capturedPath = r.URL.Path
+		capturedAPIVersion = r.URL.Query().Get("api-version")
+		writeValidResponse(w)
+	}))
+	defer server.Close()
+
+	p := NewProvider("test-key", server.URL, "")
+	_, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "hi"}}, nil, "my-gpt5-deployment", nil)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	wantPath := "/openai/deployments/my-gpt5-deployment/chat/completions"
+	if capturedPath != wantPath {
+		t.Errorf("URL path = %q, want %q", capturedPath, wantPath)
+	}
+	if capturedAPIVersion != azureAPIVersion {
+		t.Errorf("api-version = %q, want %q", capturedAPIVersion, azureAPIVersion)
+	}
+}
+
+func TestProviderChat_AzureAuthHeader(t *testing.T) {
+	var capturedAPIKey string
+	var capturedAuth string
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		capturedAPIKey = r.Header.Get("Api-Key")
+		capturedAuth = r.Header.Get("Authorization")
+		writeValidResponse(w)
+	}))
+	defer server.Close()
+
+	p := NewProvider("test-azure-key", server.URL, "")
+	_, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "hi"}}, nil, "deployment", nil)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	if capturedAPIKey != "test-azure-key" {
+		t.Errorf("api-key header = %q, want %q", capturedAPIKey, "test-azure-key")
+	}
+	if capturedAuth != "" {
+		t.Errorf("Authorization header should be empty, got %q", capturedAuth)
+	}
+}
+
+func TestProviderChat_AzureOmitsModelFromBody(t *testing.T) {
+	var requestBody map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		json.NewDecoder(r.Body).Decode(&requestBody)
+		writeValidResponse(w)
+	}))
+	defer server.Close()
+
+	p := NewProvider("test-key", server.URL, "")
+	_, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "hi"}}, nil, "deployment", nil)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	if _, exists := requestBody["model"]; exists {
+		t.Error("request body should not contain 'model' field for Azure OpenAI")
+	}
+}
+
+func TestProviderChat_AzureUsesMaxCompletionTokens(t *testing.T) {
+	var requestBody map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		json.NewDecoder(r.Body).Decode(&requestBody)
+		writeValidResponse(w)
+	}))
+	defer server.Close()
+
+	p := NewProvider("test-key", server.URL, "")
+	_, err := p.Chat(
+		t.Context(),
+		[]Message{{Role: "user", Content: "hi"}},
+		nil,
+		"deployment",
+		map[string]any{"max_tokens": 2048},
+	)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	if _, exists := requestBody["max_completion_tokens"]; !exists {
+		t.Error("request body should contain 'max_completion_tokens'")
+	}
+	if _, exists := requestBody["max_tokens"]; exists {
+		t.Error("request body should not contain 'max_tokens'")
+	}
+}
+
+func TestProviderChat_AzureHTTPError(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		http.Error(w, `{"error":"unauthorized"}`, http.StatusUnauthorized)
+	}))
+	defer server.Close()
+
+	p := NewProvider("bad-key", server.URL, "")
+	_, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "hi"}}, nil, "deployment", nil)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+}
+
+func TestProviderChat_AzureParseToolCalls(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		resp := map[string]any{
+			"choices": []map[string]any{
+				{
+					"message": map[string]any{
+						"content": "",
+						"tool_calls": []map[string]any{
+							{
+								"id":   "call_1",
+								"type": "function",
+								"function": map[string]any{
+									"name":      "get_weather",
+									"arguments": `{"city":"Seattle"}`,
+								},
+							},
+						},
+					},
+					"finish_reason": "tool_calls",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	}))
+	defer server.Close()
+
+	p := NewProvider("test-key", server.URL, "")
+	out, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "weather?"}}, nil, "deployment", nil)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	if len(out.ToolCalls) != 1 {
+		t.Fatalf("len(ToolCalls) = %d, want 1", len(out.ToolCalls))
+	}
+	if out.ToolCalls[0].Name != "get_weather" {
+		t.Errorf("ToolCalls[0].Name = %q, want %q", out.ToolCalls[0].Name, "get_weather")
+	}
+}
+
+func TestProvider_AzureEmptyAPIBase(t *testing.T) {
+	p := NewProvider("test-key", "", "")
+	_, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "hi"}}, nil, "deployment", nil)
+	if err == nil {
+		t.Fatal("expected error for empty API base")
+	}
+}
+
+func TestProvider_AzureRequestTimeoutDefault(t *testing.T) {
+	p := NewProvider("test-key", "https://example.com", "")
+	if p.httpClient.Timeout != defaultRequestTimeout {
+		t.Errorf("timeout = %v, want %v", p.httpClient.Timeout, defaultRequestTimeout)
+	}
+}
+
+func TestProvider_AzureRequestTimeoutOverride(t *testing.T) {
+	p := NewProvider("test-key", "https://example.com", "", WithRequestTimeout(300*time.Second))
+	if p.httpClient.Timeout != 300*time.Second {
+		t.Errorf("timeout = %v, want %v", p.httpClient.Timeout, 300*time.Second)
+	}
+}
+
+func TestProvider_AzureNewProviderWithTimeout(t *testing.T) {
+	p := NewProviderWithTimeout("test-key", "https://example.com", "", 180)
+	if p.httpClient.Timeout != 180*time.Second {
+		t.Errorf("timeout = %v, want %v", p.httpClient.Timeout, 180*time.Second)
+	}
+}
+
+func TestProviderChat_AzureDeploymentNameEscaped(t *testing.T) {
+	var capturedPath string
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		capturedPath = r.URL.RawPath // use RawPath to see percent-encoding
+		if capturedPath == "" {
+			capturedPath = r.URL.Path
+		}
+		writeValidResponse(w)
+	}))
+	defer server.Close()
+
+	p := NewProvider("test-key", server.URL, "")
+
+	// Deployment name with characters that could cause path injection
+	_, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "hi"}}, nil, "my deploy/../../admin", nil)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	// The slash and special chars in the deployment name must be escaped, not treated as path separators
+	if capturedPath == "/openai/deployments/my deploy/../../admin/chat/completions" {
+		t.Fatal("deployment name was interpolated without escaping — path injection possible")
+	}
+}
diff --git a/pkg/providers/bedrock/provider_bedrock.go b/pkg/providers/bedrock/provider_bedrock.go
new file mode 100644
index 000000000..15c4f664e
--- /dev/null
+++ b/pkg/providers/bedrock/provider_bedrock.go
@@ -0,0 +1,582 @@
+//go:build bedrock
+
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+// Package bedrock implements the LLM provider interface for AWS Bedrock.
+// It uses the Bedrock Runtime Converse API for unified access to multiple
+// model families (Claude, Llama, Mistral, etc.) with tool/function calling support.
+package bedrock
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"log"
+	"math"
+	"strings"
+	"time"
+
+	"github.com/aws/aws-sdk-go-v2/aws"
+	"github.com/aws/aws-sdk-go-v2/config"
+	"github.com/aws/aws-sdk-go-v2/service/bedrockruntime"
+	"github.com/aws/aws-sdk-go-v2/service/bedrockruntime/document"
+	"github.com/aws/aws-sdk-go-v2/service/bedrockruntime/types"
+
+	"github.com/sipeed/picoclaw/pkg/providers/common"
+	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
+)
+
+type (
+	ToolCall               = protocoltypes.ToolCall
+	FunctionCall           = protocoltypes.FunctionCall
+	LLMResponse            = protocoltypes.LLMResponse
+	UsageInfo              = protocoltypes.UsageInfo
+	Message                = protocoltypes.Message
+	ToolDefinition         = protocoltypes.ToolDefinition
+	ToolFunctionDefinition = protocoltypes.ToolFunctionDefinition
+)
+
+// Provider implements the LLM provider interface for AWS Bedrock.
+type Provider struct {
+	client         *bedrockruntime.Client
+	region         string
+	requestTimeout time.Duration
+}
+
+// Option configures the Bedrock Provider.
+type Option func(*providerConfig)
+
+type providerConfig struct {
+	region         string
+	profile        string
+	baseEndpoint   string
+	requestTimeout time.Duration
+}
+
+// WithRegion sets the AWS region for Bedrock requests.
+func WithRegion(region string) Option {
+	return func(c *providerConfig) {
+		c.region = region
+	}
+}
+
+// WithProfile sets the AWS profile to use for credentials.
+func WithProfile(profile string) Option {
+	return func(c *providerConfig) {
+		c.profile = profile
+	}
+}
+
+// WithBaseEndpoint sets a custom Bedrock endpoint URL.
+// Example: https://bedrock-runtime.us-east-1.amazonaws.com
+func WithBaseEndpoint(endpoint string) Option {
+	return func(c *providerConfig) {
+		c.baseEndpoint = endpoint
+	}
+}
+
+// WithRequestTimeout sets the timeout for Bedrock API requests.
+func WithRequestTimeout(timeout time.Duration) Option {
+	return func(c *providerConfig) {
+		c.requestTimeout = timeout
+	}
+}
+
+// NewProvider creates a new AWS Bedrock provider.
+// It uses the default AWS credential chain (env vars, shared config, IAM roles, etc.).
+func NewProvider(ctx context.Context, opts ...Option) (*Provider, error) {
+	pc := &providerConfig{}
+	for _, opt := range opts {
+		opt(pc)
+	}
+
+	// Build AWS config options
+	var configOpts []func(*config.LoadOptions) error
+
+	if pc.region != "" {
+		configOpts = append(configOpts, config.WithRegion(pc.region))
+	}
+
+	if pc.profile != "" {
+		configOpts = append(configOpts, config.WithSharedConfigProfile(pc.profile))
+	}
+
+	// Load AWS config with automatic credential discovery
+	cfg, err := config.LoadDefaultConfig(ctx, configOpts...)
+	if err != nil {
+		return nil, fmt.Errorf("loading AWS config: %w", err)
+	}
+
+	// Validate region is set - required for Bedrock request signing
+	if cfg.Region == "" {
+		return nil, fmt.Errorf(
+			"AWS region not configured: set AWS_REGION, AWS_DEFAULT_REGION, or use WithRegion option",
+		)
+	}
+
+	// Build client options
+	var clientOpts []func(*bedrockruntime.Options)
+	if pc.baseEndpoint != "" {
+		clientOpts = append(clientOpts, func(o *bedrockruntime.Options) {
+			o.BaseEndpoint = aws.String(pc.baseEndpoint)
+		})
+	}
+
+	client := bedrockruntime.NewFromConfig(cfg, clientOpts...)
+
+	return &Provider{
+		client:         client,
+		region:         cfg.Region,
+		requestTimeout: pc.requestTimeout,
+	}, nil
+}
+
+// Chat sends messages to AWS Bedrock using the Converse API.
+func (p *Provider) Chat(
+	ctx context.Context,
+	messages []Message,
+	tools []ToolDefinition,
+	model string,
+	options map[string]any,
+) (*LLMResponse, error) {
+	// Apply request timeout if context doesn't already have a deadline.
+	// Use explicit timeout if set, otherwise fall back to common default.
+	effectiveTimeout := p.requestTimeout
+	if effectiveTimeout <= 0 {
+		effectiveTimeout = common.DefaultRequestTimeout
+	}
+	if _, hasDeadline := ctx.Deadline(); !hasDeadline {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, effectiveTimeout)
+		defer cancel()
+	}
+
+	// Build the Converse API input
+	input := &bedrockruntime.ConverseInput{
+		ModelId: aws.String(model),
+	}
+
+	// Convert messages to Bedrock format
+	bedrockMessages, systemPrompts := convertMessages(messages)
+	input.Messages = bedrockMessages
+
+	// Set system prompts if any
+	if len(systemPrompts) > 0 {
+		input.System = systemPrompts
+	}
+
+	// Set inference configuration only when options are provided
+	var inferenceConfig *types.InferenceConfiguration
+
+	if maxTokens, ok := common.AsInt(options["max_tokens"]); ok && maxTokens > 0 {
+		if inferenceConfig == nil {
+			inferenceConfig = &types.InferenceConfiguration{}
+		}
+		// Clamp to int32 range to avoid overflow
+		if maxTokens > math.MaxInt32 {
+			maxTokens = math.MaxInt32
+		}
+		inferenceConfig.MaxTokens = aws.Int32(int32(maxTokens))
+	}
+
+	if temp, ok := common.AsFloat(options["temperature"]); ok {
+		if inferenceConfig == nil {
+			inferenceConfig = &types.InferenceConfiguration{}
+		}
+		inferenceConfig.Temperature = aws.Float32(float32(temp))
+	}
+
+	if inferenceConfig != nil {
+		input.InferenceConfig = inferenceConfig
+	}
+
+	// Convert tools to Bedrock format
+	// Only set ToolConfig if at least one valid tool was produced
+	if len(tools) > 0 {
+		toolConfig := convertTools(tools)
+		if len(toolConfig.Tools) > 0 {
+			input.ToolConfig = toolConfig
+		}
+	}
+
+	// Call Bedrock Converse API
+	output, err := p.client.Converse(ctx, input)
+	if err != nil {
+		return nil, fmt.Errorf("bedrock converse: %w", err)
+	}
+
+	// Parse the response
+	return parseResponse(output)
+}
+
+// GetDefaultModel returns an empty string as Bedrock models are user-configured.
+func (p *Provider) GetDefaultModel() string {
+	return ""
+}
+
+// Region returns the AWS region configured for this Provider.
+func (p *Provider) Region() string {
+	return p.region
+}
+
+// convertMessages converts internal messages to Bedrock Converse format.
+// Returns the conversation messages and any system prompts separately.
+// Note: Bedrock requires all tool results for a given assistant turn to be in a single
+// user message with multiple ToolResultBlock content blocks. This function merges
+// consecutive tool result messages accordingly.
+func convertMessages(messages []Message) ([]types.Message, []types.SystemContentBlock) {
+	var bedrockMessages []types.Message
+	var systemPrompts []types.SystemContentBlock
+
+	// Helper to check if a message is a tool result
+	isToolResult := func(msg Message) bool {
+		return (msg.Role == "tool" || (msg.Role == "user" && msg.ToolCallID != "")) && msg.ToolCallID != ""
+	}
+
+	// Helper to create a tool result content block
+	makeToolResultBlock := func(msg Message) types.ContentBlock {
+		return &types.ContentBlockMemberToolResult{
+			Value: types.ToolResultBlock{
+				ToolUseId: aws.String(msg.ToolCallID),
+				Content: []types.ToolResultContentBlock{
+					&types.ToolResultContentBlockMemberText{
+						Value: msg.Content,
+					},
+				},
+			},
+		}
+	}
+
+	i := 0
+	for i < len(messages) {
+		msg := messages[i]
+
+		switch {
+		case msg.Role == "system":
+			// System messages go to the System field
+			systemPrompts = append(systemPrompts, &types.SystemContentBlockMemberText{
+				Value: msg.Content,
+			})
+			i++
+
+		case isToolResult(msg):
+			// Collect all consecutive tool results into a single user message
+			// Bedrock requires all tool results for a turn in one message
+			var toolResultBlocks []types.ContentBlock
+			for i < len(messages) && isToolResult(messages[i]) {
+				toolResultBlocks = append(toolResultBlocks, makeToolResultBlock(messages[i]))
+				i++
+			}
+			bedrockMessages = append(bedrockMessages, types.Message{
+				Role:    types.ConversationRoleUser,
+				Content: toolResultBlocks,
+			})
+
+		case msg.Role == "user":
+			// Regular user message (no ToolCallID)
+			content := buildUserContent(msg)
+			bedrockMessages = append(bedrockMessages, types.Message{
+				Role:    types.ConversationRoleUser,
+				Content: content,
+			})
+			i++
+
+		case msg.Role == "assistant":
+			content := buildAssistantContent(msg)
+			bedrockMessages = append(bedrockMessages, types.Message{
+				Role:    types.ConversationRoleAssistant,
+				Content: content,
+			})
+			i++
+
+		case msg.Role == "tool" && msg.ToolCallID == "":
+			// Tool message without ToolCallID - treat as regular user message
+			content := buildUserContent(msg)
+			bedrockMessages = append(bedrockMessages, types.Message{
+				Role:    types.ConversationRoleUser,
+				Content: content,
+			})
+			i++
+
+		default:
+			// Unknown role - skip
+			i++
+		}
+	}
+
+	return bedrockMessages, systemPrompts
+}
+
+// buildUserContent builds Bedrock content blocks for a user message.
+func buildUserContent(msg Message) []types.ContentBlock {
+	var content []types.ContentBlock
+
+	// Add text content
+	if msg.Content != "" {
+		content = append(content, &types.ContentBlockMemberText{
+			Value: msg.Content,
+		})
+	}
+
+	// Add images from Media field
+	for _, mediaURL := range msg.Media {
+		if strings.HasPrefix(mediaURL, "data:image/") {
+			// Parse data URL: data:image/jpeg;base64,<data>
+			parts := strings.SplitN(mediaURL, ",", 2)
+			if len(parts) != 2 {
+				continue
+			}
+
+			// Extract media type from "data:image/jpeg;base64"
+			mediaType := ""
+			header := parts[0]
+			if idx := strings.Index(header, "/"); idx != -1 {
+				end := strings.Index(header[idx:], ";")
+				if end == -1 {
+					end = len(header) - idx
+				}
+				mediaType = header[idx+1 : idx+end]
+			}
+
+			// Verify this is base64 encoded
+			if !strings.Contains(header, ";base64") {
+				continue // Skip non-base64 encoded data
+			}
+
+			// Map media type to Bedrock format
+			var format types.ImageFormat
+			switch mediaType {
+			case "jpeg", "jpg":
+				format = types.ImageFormatJpeg
+			case "png":
+				format = types.ImageFormatPng
+			case "gif":
+				format = types.ImageFormatGif
+			case "webp":
+				format = types.ImageFormatWebp
+			default:
+				continue // Skip unsupported formats
+			}
+
+			// Check size before decoding to prevent excessive memory allocation
+			// Bedrock has a ~20MB request limit; cap decoded images at 10MB
+			const maxImageSize = 10 * 1024 * 1024
+			decodedLen := base64.StdEncoding.DecodedLen(len(parts[1]))
+			if decodedLen > maxImageSize {
+				log.Printf("bedrock: skipping image exceeding size limit (%d bytes > %d)", decodedLen, maxImageSize)
+				continue
+			}
+
+			// Decode base64 data
+			imageData, err := base64.StdEncoding.DecodeString(parts[1])
+			if err != nil {
+				log.Printf("bedrock: failed to decode base64 image data: %v", err)
+				continue
+			}
+
+			content = append(content, &types.ContentBlockMemberImage{
+				Value: types.ImageBlock{
+					Format: format,
+					Source: &types.ImageSourceMemberBytes{
+						Value: imageData,
+					},
+				},
+			})
+		}
+	}
+
+	// Bedrock requires at least one content block; add empty text if needed
+	if len(content) == 0 {
+		content = append(content, &types.ContentBlockMemberText{Value: ""})
+	}
+
+	return content
+}
+
+// buildAssistantContent builds Bedrock content blocks for an assistant message.
+func buildAssistantContent(msg Message) []types.ContentBlock {
+	var content []types.ContentBlock
+
+	// Add text content if present
+	if msg.Content != "" {
+		content = append(content, &types.ContentBlockMemberText{
+			Value: msg.Content,
+		})
+	}
+
+	// Add tool use blocks
+	for _, tc := range msg.ToolCalls {
+		// Validate tool call ID - Bedrock requires non-empty ToolUseId
+		if strings.TrimSpace(tc.ID) == "" {
+			log.Printf("bedrock: skipping tool call with empty ID (name: %q)", tc.Name)
+			continue
+		}
+
+		// Resolve tool name: prefer tc.Name, fallback to tc.Function.Name
+		// (tc.Name/tc.Arguments are json:"-" and may be empty when from JSON)
+		toolName := tc.Name
+		if toolName == "" && tc.Function != nil {
+			toolName = tc.Function.Name
+		}
+		if strings.TrimSpace(toolName) == "" {
+			continue
+		}
+
+		// Resolve arguments: prefer tc.Arguments, fallback to parsing tc.Function.Arguments
+		args := tc.Arguments
+		if args == nil && tc.Function != nil && tc.Function.Arguments != "" {
+			if err := json.Unmarshal([]byte(tc.Function.Arguments), &args); err != nil {
+				log.Printf("bedrock: failed to parse Function.Arguments for tool %q: %v", toolName, err)
+				args = map[string]any{}
+			}
+		}
+		if args == nil {
+			args = map[string]any{}
+		}
+
+		// Convert arguments to a Bedrock document using NewLazyDocument
+		inputDoc := document.NewLazyDocument(args)
+
+		content = append(content, &types.ContentBlockMemberToolUse{
+			Value: types.ToolUseBlock{
+				ToolUseId: aws.String(tc.ID),
+				Name:      aws.String(toolName),
+				Input:     inputDoc,
+			},
+		})
+	}
+
+	// Bedrock requires at least one content block; add empty text if needed
+	if len(content) == 0 {
+		content = append(content, &types.ContentBlockMemberText{Value: ""})
+	}
+
+	return content
+}
+
+// convertTools converts tool definitions to Bedrock format.
+func convertTools(tools []ToolDefinition) *types.ToolConfiguration {
+	bedrockTools := make([]types.Tool, 0, len(tools))
+
+	for _, tool := range tools {
+		// Skip tools with empty names
+		if strings.TrimSpace(tool.Function.Name) == "" {
+			continue
+		}
+
+		// Ensure parameters is not nil - default to minimal object schema
+		params := tool.Function.Parameters
+		if params == nil {
+			params = map[string]any{
+				"type":       "object",
+				"properties": map[string]any{},
+			}
+		}
+
+		// Convert parameters schema to a Bedrock document
+		inputSchema := document.NewLazyDocument(params)
+
+		bedrockTools = append(bedrockTools, &types.ToolMemberToolSpec{
+			Value: types.ToolSpecification{
+				Name:        aws.String(tool.Function.Name),
+				Description: aws.String(tool.Function.Description),
+				InputSchema: &types.ToolInputSchemaMemberJson{
+					Value: inputSchema,
+				},
+			},
+		})
+	}
+
+	return &types.ToolConfiguration{
+		Tools: bedrockTools,
+	}
+}
+
+// parseResponse converts Bedrock Converse output to LLMResponse.
+func parseResponse(output *bedrockruntime.ConverseOutput) (*LLMResponse, error) {
+	var content strings.Builder
+	toolCalls := make([]ToolCall, 0)
+
+	// Process output content blocks
+	if output.Output != nil {
+		if msgOutput, ok := output.Output.(*types.ConverseOutputMemberMessage); ok {
+			for _, block := range msgOutput.Value.Content {
+				switch b := block.(type) {
+				case *types.ContentBlockMemberText:
+					content.WriteString(b.Value)
+
+				case *types.ContentBlockMemberToolUse:
+					// Unmarshal the document interface to a map
+					args := make(map[string]any)
+					if b.Value.Input != nil {
+						if err := b.Value.Input.UnmarshalSmithyDocument(&args); err != nil {
+							log.Printf("bedrock: failed to unmarshal tool input for tool %q (id %q): %v",
+								aws.ToString(b.Value.Name),
+								aws.ToString(b.Value.ToolUseId),
+								err,
+							)
+							args = make(map[string]any)
+						}
+					}
+
+					// Serialize arguments to JSON string for FunctionCall
+					argsJSON, err := json.Marshal(args)
+					if err != nil {
+						log.Printf("bedrock: failed to marshal tool arguments for tool %q (id %q): %v",
+							aws.ToString(b.Value.Name),
+							aws.ToString(b.Value.ToolUseId),
+							err,
+						)
+						argsJSON = []byte("{}")
+					}
+
+					toolCalls = append(toolCalls, ToolCall{
+						ID:        aws.ToString(b.Value.ToolUseId),
+						Name:      aws.ToString(b.Value.Name),
+						Arguments: args,
+						Function: &FunctionCall{
+							Name:      aws.ToString(b.Value.Name),
+							Arguments: string(argsJSON),
+						},
+					})
+				}
+			}
+		}
+	}
+
+	// Map stop reason
+	finishReason := "stop"
+	switch output.StopReason {
+	case types.StopReasonToolUse:
+		finishReason = "tool_calls"
+	case types.StopReasonMaxTokens:
+		finishReason = "length"
+	case types.StopReasonEndTurn:
+		finishReason = "stop"
+	case types.StopReasonStopSequence:
+		finishReason = "stop"
+	case types.StopReasonContentFiltered:
+		finishReason = "content_filter"
+	}
+
+	// Build usage info
+	var usage *UsageInfo
+	if output.Usage != nil {
+		usage = &UsageInfo{
+			PromptTokens:     int(aws.ToInt32(output.Usage.InputTokens)),
+			CompletionTokens: int(aws.ToInt32(output.Usage.OutputTokens)),
+			TotalTokens:      int(aws.ToInt32(output.Usage.InputTokens)) + int(aws.ToInt32(output.Usage.OutputTokens)),
+		}
+	}
+
+	return &LLMResponse{
+		Content:      content.String(),
+		ToolCalls:    toolCalls,
+		FinishReason: finishReason,
+		Usage:        usage,
+	}, nil
+}
diff --git a/pkg/providers/bedrock/provider_bedrock_test.go b/pkg/providers/bedrock/provider_bedrock_test.go
new file mode 100644
index 000000000..754d112ee
--- /dev/null
+++ b/pkg/providers/bedrock/provider_bedrock_test.go
@@ -0,0 +1,541 @@
+//go:build bedrock
+
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package bedrock
+
+import (
+	"testing"
+
+	"github.com/aws/aws-sdk-go-v2/aws"
+	"github.com/aws/aws-sdk-go-v2/service/bedrockruntime"
+	"github.com/aws/aws-sdk-go-v2/service/bedrockruntime/document"
+	"github.com/aws/aws-sdk-go-v2/service/bedrockruntime/types"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
+)
+
+func TestConvertMessages_SystemPrompts(t *testing.T) {
+	messages := []Message{
+		{Role: "system", Content: "You are a helpful assistant."},
+		{Role: "user", Content: "Hello"},
+	}
+
+	bedrockMsgs, systemPrompts := convertMessages(messages)
+
+	assert.Len(t, systemPrompts, 1)
+	assert.Len(t, bedrockMsgs, 1)
+
+	// Check system prompt
+	textBlock, ok := systemPrompts[0].(*types.SystemContentBlockMemberText)
+	require.True(t, ok)
+	assert.Equal(t, "You are a helpful assistant.", textBlock.Value)
+
+	// Check user message
+	assert.Equal(t, types.ConversationRoleUser, bedrockMsgs[0].Role)
+}
+
+func TestConvertMessages_UserMessage(t *testing.T) {
+	messages := []Message{
+		{Role: "user", Content: "What is 2+2?"},
+	}
+
+	bedrockMsgs, systemPrompts := convertMessages(messages)
+
+	assert.Empty(t, systemPrompts)
+	assert.Len(t, bedrockMsgs, 1)
+	assert.Equal(t, types.ConversationRoleUser, bedrockMsgs[0].Role)
+
+	textBlock, ok := bedrockMsgs[0].Content[0].(*types.ContentBlockMemberText)
+	require.True(t, ok)
+	assert.Equal(t, "What is 2+2?", textBlock.Value)
+}
+
+func TestConvertMessages_AssistantMessage(t *testing.T) {
+	messages := []Message{
+		{Role: "assistant", Content: "The answer is 4."},
+	}
+
+	bedrockMsgs, _ := convertMessages(messages)
+
+	assert.Len(t, bedrockMsgs, 1)
+	assert.Equal(t, types.ConversationRoleAssistant, bedrockMsgs[0].Role)
+
+	textBlock, ok := bedrockMsgs[0].Content[0].(*types.ContentBlockMemberText)
+	require.True(t, ok)
+	assert.Equal(t, "The answer is 4.", textBlock.Value)
+}
+
+func TestConvertMessages_ToolResult(t *testing.T) {
+	messages := []Message{
+		{Role: "tool", Content: "Result from tool", ToolCallID: "call_123"},
+	}
+
+	bedrockMsgs, _ := convertMessages(messages)
+
+	assert.Len(t, bedrockMsgs, 1)
+	assert.Equal(t, types.ConversationRoleUser, bedrockMsgs[0].Role)
+
+	toolResult, ok := bedrockMsgs[0].Content[0].(*types.ContentBlockMemberToolResult)
+	require.True(t, ok)
+	assert.Equal(t, "call_123", aws.ToString(toolResult.Value.ToolUseId))
+}
+
+func TestConvertMessages_MultipleToolResultsMerged(t *testing.T) {
+	// When an assistant makes multiple tool calls, all tool results must be
+	// merged into a single user message for Bedrock
+	messages := []Message{
+		{Role: "user", Content: "What's the weather in NYC and LA?"},
+		{
+			Role:    "assistant",
+			Content: "Let me check both cities.",
+			ToolCalls: []protocoltypes.ToolCall{
+				{ID: "call_nyc", Name: "get_weather", Arguments: map[string]any{"city": "NYC"}},
+				{ID: "call_la", Name: "get_weather", Arguments: map[string]any{"city": "LA"}},
+			},
+		},
+		{Role: "tool", Content: "NYC: 72°F, sunny", ToolCallID: "call_nyc"},
+		{Role: "tool", Content: "LA: 85°F, clear", ToolCallID: "call_la"},
+	}
+
+	bedrockMsgs, _ := convertMessages(messages)
+
+	// Should be: user message, assistant message, merged tool results (single user message)
+	assert.Len(t, bedrockMsgs, 3)
+
+	// First message: user
+	assert.Equal(t, types.ConversationRoleUser, bedrockMsgs[0].Role)
+
+	// Second message: assistant with tool calls
+	assert.Equal(t, types.ConversationRoleAssistant, bedrockMsgs[1].Role)
+
+	// Third message: merged tool results in single user message
+	assert.Equal(t, types.ConversationRoleUser, bedrockMsgs[2].Role)
+	assert.Len(t, bedrockMsgs[2].Content, 2) // Both tool results in one message
+
+	// Verify both tool results are present
+	result1, ok := bedrockMsgs[2].Content[0].(*types.ContentBlockMemberToolResult)
+	require.True(t, ok)
+	assert.Equal(t, "call_nyc", aws.ToString(result1.Value.ToolUseId))
+
+	result2, ok := bedrockMsgs[2].Content[1].(*types.ContentBlockMemberToolResult)
+	require.True(t, ok)
+	assert.Equal(t, "call_la", aws.ToString(result2.Value.ToolUseId))
+}
+
+func TestConvertMessages_AssistantWithToolCalls(t *testing.T) {
+	messages := []Message{
+		{
+			Role:    "assistant",
+			Content: "Let me calculate that.",
+			ToolCalls: []protocoltypes.ToolCall{
+				{
+					ID:        "call_456",
+					Name:      "calculator",
+					Arguments: map[string]any{"expression": "2+2"},
+				},
+			},
+		},
+	}
+
+	bedrockMsgs, _ := convertMessages(messages)
+
+	assert.Len(t, bedrockMsgs, 1)
+	assert.Len(t, bedrockMsgs[0].Content, 2) // text + tool use
+
+	// Check text content
+	textBlock, ok := bedrockMsgs[0].Content[0].(*types.ContentBlockMemberText)
+	require.True(t, ok)
+	assert.Equal(t, "Let me calculate that.", textBlock.Value)
+
+	// Check tool use
+	toolUse, ok := bedrockMsgs[0].Content[1].(*types.ContentBlockMemberToolUse)
+	require.True(t, ok)
+	assert.Equal(t, "call_456", aws.ToString(toolUse.Value.ToolUseId))
+	assert.Equal(t, "calculator", aws.ToString(toolUse.Value.Name))
+}
+
+func TestConvertTools_Basic(t *testing.T) {
+	tools := []ToolDefinition{
+		{
+			Function: protocoltypes.ToolFunctionDefinition{
+				Name:        "get_weather",
+				Description: "Get the current weather",
+				Parameters: map[string]any{
+					"type": "object",
+					"properties": map[string]any{
+						"location": map[string]any{"type": "string"},
+					},
+				},
+			},
+		},
+	}
+
+	toolConfig := convertTools(tools)
+
+	assert.NotNil(t, toolConfig)
+	assert.Len(t, toolConfig.Tools, 1)
+
+	toolSpec, ok := toolConfig.Tools[0].(*types.ToolMemberToolSpec)
+	require.True(t, ok)
+	assert.Equal(t, "get_weather", aws.ToString(toolSpec.Value.Name))
+	assert.Equal(t, "Get the current weather", aws.ToString(toolSpec.Value.Description))
+}
+
+func TestConvertTools_SkipsEmptyName(t *testing.T) {
+	tools := []ToolDefinition{
+		{
+			Function: protocoltypes.ToolFunctionDefinition{
+				Name:        "",
+				Description: "Empty name tool",
+			},
+		},
+		{
+			Function: protocoltypes.ToolFunctionDefinition{
+				Name:        "   ",
+				Description: "Whitespace name tool",
+			},
+		},
+		{
+			Function: protocoltypes.ToolFunctionDefinition{
+				Name:        "valid_tool",
+				Description: "Valid tool",
+			},
+		},
+	}
+
+	toolConfig := convertTools(tools)
+
+	assert.Len(t, toolConfig.Tools, 1)
+	toolSpec := toolConfig.Tools[0].(*types.ToolMemberToolSpec)
+	assert.Equal(t, "valid_tool", aws.ToString(toolSpec.Value.Name))
+}
+
+func TestConvertTools_NilParameters(t *testing.T) {
+	tools := []ToolDefinition{
+		{
+			Function: protocoltypes.ToolFunctionDefinition{
+				Name:        "simple_tool",
+				Description: "A tool with no parameters",
+				Parameters:  nil,
+			},
+		},
+	}
+
+	toolConfig := convertTools(tools)
+
+	assert.Len(t, toolConfig.Tools, 1)
+	// Should not panic and should create a valid tool
+}
+
+func TestBuildUserContent_TextOnly(t *testing.T) {
+	msg := Message{Content: "Hello world"}
+
+	content := buildUserContent(msg)
+
+	assert.Len(t, content, 1)
+	textBlock, ok := content[0].(*types.ContentBlockMemberText)
+	require.True(t, ok)
+	assert.Equal(t, "Hello world", textBlock.Value)
+}
+
+func TestBuildUserContent_WithImage(t *testing.T) {
+	// Base64-encoded 1x1 PNG (the provider doesn't validate image correctness,
+	// it just verifies the format and base64 decoding works)
+	b64Data := "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADUlEQVR4nGNgYAAAAAMAASsJTYQAAAAASUVORK5CYII="
+
+	msg := Message{
+		Content: "Look at this image",
+		Media:   []string{"data:image/png;base64," + b64Data},
+	}
+
+	content := buildUserContent(msg)
+
+	assert.Len(t, content, 2)
+
+	// Check text
+	textBlock, ok := content[0].(*types.ContentBlockMemberText)
+	require.True(t, ok)
+	assert.Equal(t, "Look at this image", textBlock.Value)
+
+	// Check image
+	imageBlock, ok := content[1].(*types.ContentBlockMemberImage)
+	require.True(t, ok)
+	assert.Equal(t, types.ImageFormatPng, imageBlock.Value.Format)
+}
+
+func TestBuildUserContent_SkipsInvalidBase64(t *testing.T) {
+	msg := Message{
+		Content: "Invalid image",
+		Media:   []string{"data:image/png;base64,not-valid-base64!!!"},
+	}
+
+	content := buildUserContent(msg)
+
+	// Should only have text, image should be skipped
+	assert.Len(t, content, 1)
+}
+
+func TestBuildUserContent_SkipsNonBase64Data(t *testing.T) {
+	msg := Message{
+		Content: "Non-base64 image",
+		Media:   []string{"data:image/png,raw-data-here"},
+	}
+
+	content := buildUserContent(msg)
+
+	// Should only have text, non-base64 image should be skipped
+	assert.Len(t, content, 1)
+}
+
+func TestBuildAssistantContent_SkipsEmptyToolName(t *testing.T) {
+	msg := Message{
+		Content: "Response",
+		ToolCalls: []protocoltypes.ToolCall{
+			{ID: "1", Name: "", Arguments: map[string]any{}},
+			{ID: "2", Name: "   ", Arguments: map[string]any{}},
+			{ID: "3", Name: "valid", Arguments: map[string]any{}},
+		},
+	}
+
+	content := buildAssistantContent(msg)
+
+	// Should have text + 1 valid tool
+	assert.Len(t, content, 2)
+}
+
+func TestBuildAssistantContent_NilArguments(t *testing.T) {
+	msg := Message{
+		ToolCalls: []protocoltypes.ToolCall{
+			{ID: "1", Name: "tool", Arguments: nil},
+		},
+	}
+
+	content := buildAssistantContent(msg)
+
+	assert.Len(t, content, 1)
+	toolUse, ok := content[0].(*types.ContentBlockMemberToolUse)
+	require.True(t, ok)
+	assert.NotNil(t, toolUse.Value.Input)
+}
+
+func TestBuildAssistantContent_FunctionFallback(t *testing.T) {
+	// When Name/Arguments are empty (json:"-"), should fallback to Function fields
+	msg := Message{
+		ToolCalls: []protocoltypes.ToolCall{
+			{
+				ID:   "1",
+				Name: "", // empty, should fallback to Function.Name
+				Function: &protocoltypes.FunctionCall{
+					Name:      "fallback_tool",
+					Arguments: `{"key":"value"}`,
+				},
+			},
+		},
+	}
+
+	content := buildAssistantContent(msg)
+
+	assert.Len(t, content, 1)
+	toolUse, ok := content[0].(*types.ContentBlockMemberToolUse)
+	require.True(t, ok)
+	assert.Equal(t, "fallback_tool", aws.ToString(toolUse.Value.Name))
+}
+
+func TestParseResponse_TextOnly(t *testing.T) {
+	output := &bedrockruntime.ConverseOutput{
+		Output: &types.ConverseOutputMemberMessage{
+			Value: types.Message{
+				Role: types.ConversationRoleAssistant,
+				Content: []types.ContentBlock{
+					&types.ContentBlockMemberText{Value: "Hello!"},
+				},
+			},
+		},
+		StopReason: types.StopReasonEndTurn,
+		Usage: &types.TokenUsage{
+			InputTokens:  aws.Int32(10),
+			OutputTokens: aws.Int32(5),
+		},
+	}
+
+	resp, err := parseResponse(output)
+
+	require.NoError(t, err)
+	assert.Equal(t, "Hello!", resp.Content)
+	assert.Equal(t, "stop", resp.FinishReason)
+	assert.Empty(t, resp.ToolCalls)
+	assert.Equal(t, 10, resp.Usage.PromptTokens)
+	assert.Equal(t, 5, resp.Usage.CompletionTokens)
+}
+
+func TestParseResponse_StopReasons(t *testing.T) {
+	tests := []struct {
+		stopReason     types.StopReason
+		expectedFinish string
+	}{
+		{types.StopReasonEndTurn, "stop"},
+		{types.StopReasonToolUse, "tool_calls"},
+		{types.StopReasonMaxTokens, "length"},
+		{types.StopReasonStopSequence, "stop"},
+		{types.StopReasonContentFiltered, "content_filter"},
+	}
+
+	for _, tt := range tests {
+		t.Run(string(tt.stopReason), func(t *testing.T) {
+			output := &bedrockruntime.ConverseOutput{
+				Output: &types.ConverseOutputMemberMessage{
+					Value: types.Message{
+						Content: []types.ContentBlock{
+							&types.ContentBlockMemberText{Value: "test"},
+						},
+					},
+				},
+				StopReason: tt.stopReason,
+			}
+
+			resp, err := parseResponse(output)
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.expectedFinish, resp.FinishReason)
+		})
+	}
+}
+
+func TestParseResponse_WithToolCalls(t *testing.T) {
+	// Note: document.NewLazyDocument has limitations with UnmarshalSmithyDocument in tests,
+	// so we test the structure extraction and verify Arguments gets populated (even if empty
+	// due to SDK limitations). The actual unmarshal works correctly at runtime.
+	toolInput := document.NewLazyDocument(map[string]any{
+		"location": "San Francisco",
+		"unit":     "celsius",
+	})
+
+	output := &bedrockruntime.ConverseOutput{
+		Output: &types.ConverseOutputMemberMessage{
+			Value: types.Message{
+				Role: types.ConversationRoleAssistant,
+				Content: []types.ContentBlock{
+					&types.ContentBlockMemberText{Value: "Let me check the weather."},
+					&types.ContentBlockMemberToolUse{
+						Value: types.ToolUseBlock{
+							ToolUseId: aws.String("call_weather_123"),
+							Name:      aws.String("get_weather"),
+							Input:     toolInput,
+						},
+					},
+				},
+			},
+		},
+		StopReason: types.StopReasonToolUse,
+		Usage: &types.TokenUsage{
+			InputTokens:  aws.Int32(20),
+			OutputTokens: aws.Int32(15),
+		},
+	}
+
+	resp, err := parseResponse(output)
+
+	require.NoError(t, err)
+	assert.Equal(t, "Let me check the weather.", resp.Content)
+	assert.Equal(t, "tool_calls", resp.FinishReason)
+	assert.Len(t, resp.ToolCalls, 1)
+
+	// Verify tool call ID and Name are extracted correctly
+	tc := resp.ToolCalls[0]
+	assert.Equal(t, "call_weather_123", tc.ID)
+	assert.Equal(t, "get_weather", tc.Name)
+
+	// Verify Function fields are also populated
+	require.NotNil(t, tc.Function)
+	assert.Equal(t, "get_weather", tc.Function.Name)
+
+	// Verify Arguments is not nil (content may vary due to SDK limitations in tests)
+	assert.NotNil(t, tc.Arguments)
+
+	// Verify usage
+	assert.Equal(t, 20, resp.Usage.PromptTokens)
+	assert.Equal(t, 15, resp.Usage.CompletionTokens)
+	assert.Equal(t, 35, resp.Usage.TotalTokens)
+}
+
+func TestParseResponse_MultipleToolCalls(t *testing.T) {
+	output := &bedrockruntime.ConverseOutput{
+		Output: &types.ConverseOutputMemberMessage{
+			Value: types.Message{
+				Role: types.ConversationRoleAssistant,
+				Content: []types.ContentBlock{
+					&types.ContentBlockMemberToolUse{
+						Value: types.ToolUseBlock{
+							ToolUseId: aws.String("call_1"),
+							Name:      aws.String("tool_a"),
+							Input:     document.NewLazyDocument(map[string]any{"arg": "value1"}),
+						},
+					},
+					&types.ContentBlockMemberToolUse{
+						Value: types.ToolUseBlock{
+							ToolUseId: aws.String("call_2"),
+							Name:      aws.String("tool_b"),
+							Input:     document.NewLazyDocument(map[string]any{"arg": "value2"}),
+						},
+					},
+				},
+			},
+		},
+		StopReason: types.StopReasonToolUse,
+	}
+
+	resp, err := parseResponse(output)
+
+	require.NoError(t, err)
+	assert.Equal(t, "tool_calls", resp.FinishReason)
+	assert.Len(t, resp.ToolCalls, 2)
+
+	// Verify tool call structure
+	assert.Equal(t, "call_1", resp.ToolCalls[0].ID)
+	assert.Equal(t, "tool_a", resp.ToolCalls[0].Name)
+	assert.NotNil(t, resp.ToolCalls[0].Arguments)
+	assert.NotNil(t, resp.ToolCalls[0].Function)
+	assert.Equal(t, "tool_a", resp.ToolCalls[0].Function.Name)
+
+	assert.Equal(t, "call_2", resp.ToolCalls[1].ID)
+	assert.Equal(t, "tool_b", resp.ToolCalls[1].Name)
+	assert.NotNil(t, resp.ToolCalls[1].Arguments)
+	assert.NotNil(t, resp.ToolCalls[1].Function)
+	assert.Equal(t, "tool_b", resp.ToolCalls[1].Function.Name)
+}
+
+func TestParseResponse_ToolCallWithNilInput(t *testing.T) {
+	output := &bedrockruntime.ConverseOutput{
+		Output: &types.ConverseOutputMemberMessage{
+			Value: types.Message{
+				Role: types.ConversationRoleAssistant,
+				Content: []types.ContentBlock{
+					&types.ContentBlockMemberToolUse{
+						Value: types.ToolUseBlock{
+							ToolUseId: aws.String("call_nil"),
+							Name:      aws.String("no_args_tool"),
+							Input:     nil,
+						},
+					},
+				},
+			},
+		},
+		StopReason: types.StopReasonToolUse,
+	}
+
+	resp, err := parseResponse(output)
+
+	require.NoError(t, err)
+	assert.Len(t, resp.ToolCalls, 1)
+	assert.Equal(t, "call_nil", resp.ToolCalls[0].ID)
+	assert.Equal(t, "no_args_tool", resp.ToolCalls[0].Name)
+	// Arguments should be empty map, not nil
+	assert.NotNil(t, resp.ToolCalls[0].Arguments)
+	assert.Empty(t, resp.ToolCalls[0].Arguments)
+}
diff --git a/pkg/providers/bedrock/provider_stub.go b/pkg/providers/bedrock/provider_stub.go
new file mode 100644
index 000000000..894d9f2ca
--- /dev/null
+++ b/pkg/providers/bedrock/provider_stub.go
@@ -0,0 +1,73 @@
+//go:build !bedrock
+
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+// Package bedrock provides a stub implementation when built without the bedrock tag.
+// To enable AWS Bedrock support, build with: go build -tags bedrock
+package bedrock
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
+)
+
+type (
+	LLMResponse    = protocoltypes.LLMResponse
+	Message        = protocoltypes.Message
+	ToolDefinition = protocoltypes.ToolDefinition
+)
+
+// Provider is a stub that returns an error when Bedrock support is not compiled in.
+type Provider struct{}
+
+// Option is a no-op when Bedrock is not enabled.
+type Option func(*providerConfig)
+
+type providerConfig struct{}
+
+// WithRegion is a no-op when Bedrock is not enabled.
+func WithRegion(region string) Option {
+	return func(c *providerConfig) {}
+}
+
+// WithProfile is a no-op when Bedrock is not enabled.
+func WithProfile(profile string) Option {
+	return func(c *providerConfig) {}
+}
+
+// WithBaseEndpoint is a no-op when Bedrock is not enabled.
+func WithBaseEndpoint(endpoint string) Option {
+	return func(c *providerConfig) {}
+}
+
+// WithRequestTimeout is a no-op when Bedrock is not enabled.
+func WithRequestTimeout(timeout time.Duration) Option {
+	return func(c *providerConfig) {}
+}
+
+// NewProvider returns an error indicating Bedrock support is not compiled in.
+func NewProvider(ctx context.Context, opts ...Option) (*Provider, error) {
+	return nil, fmt.Errorf("bedrock provider not available: build with -tags bedrock to enable AWS Bedrock support")
+}
+
+// Chat returns an error - this should never be called since NewProvider fails.
+func (p *Provider) Chat(
+	ctx context.Context,
+	messages []Message,
+	tools []ToolDefinition,
+	model string,
+	options map[string]any,
+) (*LLMResponse, error) {
+	return nil, fmt.Errorf("bedrock provider not available: build with -tags bedrock to enable AWS Bedrock support")
+}
+
+// GetDefaultModel returns an empty string.
+func (p *Provider) GetDefaultModel() string {
+	return ""
+}
diff --git a/pkg/providers/bedrock/provider_stub_test.go b/pkg/providers/bedrock/provider_stub_test.go
new file mode 100644
index 000000000..50ec8340f
--- /dev/null
+++ b/pkg/providers/bedrock/provider_stub_test.go
@@ -0,0 +1,35 @@
+//go:build !bedrock
+
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package bedrock
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestNewProvider_ReturnsStubError(t *testing.T) {
+	provider, err := NewProvider(context.Background())
+
+	assert.Nil(t, provider)
+	require.Error(t, err)
+	assert.True(t, strings.Contains(err.Error(), "build with -tags bedrock"),
+		"error should mention build tag requirement, got: %s", err.Error())
+}
+
+func TestNewProvider_WithOptions_ReturnsStubError(t *testing.T) {
+	provider, err := NewProvider(context.Background(), WithRegion("us-west-2"), WithProfile("test"))
+
+	assert.Nil(t, provider)
+	require.Error(t, err)
+	assert.True(t, strings.Contains(err.Error(), "build with -tags bedrock"),
+		"error should mention build tag requirement, got: %s", err.Error())
+}
diff --git a/pkg/providers/claude_cli_provider.go b/pkg/providers/claude_cli_provider.go
index 74ec33b98..40b581490 100644
--- a/pkg/providers/claude_cli_provider.go
+++ b/pkg/providers/claude_cli_provider.go
@@ -50,10 +50,18 @@ func (p *ClaudeCliProvider) Chat(
 	cmd.Stderr = &stderr
 
 	if err := cmd.Run(); err != nil {
-		if stderrStr := stderr.String(); stderrStr != "" {
+		stderrStr := strings.TrimSpace(stderr.String())
+		stdoutStr := strings.TrimSpace(stdout.String())
+		switch {
+		case stderrStr != "" && stdoutStr != "":
+			return nil, fmt.Errorf("claude cli error: %w\nstderr: %s\nstdout: %s", err, stderrStr, stdoutStr)
+		case stderrStr != "":
 			return nil, fmt.Errorf("claude cli error: %s", stderrStr)
+		case stdoutStr != "":
+			return nil, fmt.Errorf("claude cli error: %w\noutput: %s", err, stdoutStr)
+		default:
+			return nil, fmt.Errorf("claude cli error: %w", err)
 		}
-		return nil, fmt.Errorf("claude cli error: %w", err)
 	}
 
 	return p.parseClaudeCliResponse(stdout.String())
@@ -100,44 +108,12 @@ func (p *ClaudeCliProvider) buildSystemPrompt(messages []Message, tools []ToolDe
 	}
 
 	if len(tools) > 0 {
-		parts = append(parts, p.buildToolsPrompt(tools))
+		parts = append(parts, buildCLIToolsPrompt(tools))
 	}
 
 	return strings.Join(parts, "\n\n")
 }
 
-// buildToolsPrompt creates the tool definitions section for the system prompt.
-func (p *ClaudeCliProvider) buildToolsPrompt(tools []ToolDefinition) string {
-	var sb strings.Builder
-
-	sb.WriteString("## Available Tools\n\n")
-	sb.WriteString("When you need to use a tool, respond with ONLY a JSON object:\n\n")
-	sb.WriteString("```json\n")
-	sb.WriteString(
-		`{"tool_calls":[{"id":"call_xxx","type":"function","function":{"name":"tool_name","arguments":"{...}"}}]}`,
-	)
-	sb.WriteString("\n```\n\n")
-	sb.WriteString("CRITICAL: The 'arguments' field MUST be a JSON-encoded STRING.\n\n")
-	sb.WriteString("### Tool Definitions:\n\n")
-
-	for _, tool := range tools {
-		if tool.Type != "function" {
-			continue
-		}
-		sb.WriteString(fmt.Sprintf("#### %s\n", tool.Function.Name))
-		if tool.Function.Description != "" {
-			sb.WriteString(fmt.Sprintf("Description: %s\n", tool.Function.Description))
-		}
-		if len(tool.Function.Parameters) > 0 {
-			paramsJSON, _ := json.Marshal(tool.Function.Parameters)
-			sb.WriteString(fmt.Sprintf("Parameters:\n```json\n%s\n```\n", string(paramsJSON)))
-		}
-		sb.WriteString("\n")
-	}
-
-	return sb.String()
-}
-
 // parseClaudeCliResponse parses the JSON output from the claude CLI.
 func (p *ClaudeCliProvider) parseClaudeCliResponse(output string) (*LLMResponse, error) {
 	var resp claudeCliJSONResponse
diff --git a/pkg/providers/claude_cli_provider_test.go b/pkg/providers/claude_cli_provider_test.go
index 3a3cafaca..bc9960f0c 100644
--- a/pkg/providers/claude_cli_provider_test.go
+++ b/pkg/providers/claude_cli_provider_test.go
@@ -413,10 +413,10 @@ func TestChat_EmptyWorkspaceDoesNotSetDir(t *testing.T) {
 
 func TestCreateProvider_ClaudeCli(t *testing.T) {
 	cfg := config.DefaultConfig()
-	cfg.ModelList = []config.ModelConfig{
+	cfg.ModelList = []*config.ModelConfig{
 		{ModelName: "claude-sonnet-4.6", Model: "claude-cli/claude-sonnet-4.6", Workspace: "/test/ws"},
 	}
-	cfg.Agents.Defaults.Model = "claude-sonnet-4.6"
+	cfg.Agents.Defaults.ModelName = "claude-sonnet-4.6"
 
 	provider, _, err := CreateProvider(cfg)
 	if err != nil {
@@ -434,10 +434,10 @@ func TestCreateProvider_ClaudeCli(t *testing.T) {
 
 func TestCreateProvider_ClaudeCode(t *testing.T) {
 	cfg := config.DefaultConfig()
-	cfg.ModelList = []config.ModelConfig{
+	cfg.ModelList = []*config.ModelConfig{
 		{ModelName: "claude-code", Model: "claude-cli/claude-code"},
 	}
-	cfg.Agents.Defaults.Model = "claude-code"
+	cfg.Agents.Defaults.ModelName = "claude-code"
 
 	provider, _, err := CreateProvider(cfg)
 	if err != nil {
@@ -450,10 +450,10 @@ func TestCreateProvider_ClaudeCode(t *testing.T) {
 
 func TestCreateProvider_ClaudeCodec(t *testing.T) {
 	cfg := config.DefaultConfig()
-	cfg.ModelList = []config.ModelConfig{
+	cfg.ModelList = []*config.ModelConfig{
 		{ModelName: "claudecode", Model: "claude-cli/claudecode"},
 	}
-	cfg.Agents.Defaults.Model = "claudecode"
+	cfg.Agents.Defaults.ModelName = "claudecode"
 
 	provider, _, err := CreateProvider(cfg)
 	if err != nil {
@@ -466,10 +466,10 @@ func TestCreateProvider_ClaudeCodec(t *testing.T) {
 
 func TestCreateProvider_ClaudeCliDefaultWorkspace(t *testing.T) {
 	cfg := config.DefaultConfig()
-	cfg.ModelList = []config.ModelConfig{
+	cfg.ModelList = []*config.ModelConfig{
 		{ModelName: "claude-cli", Model: "claude-cli/claude-sonnet"},
 	}
-	cfg.Agents.Defaults.Model = "claude-cli"
+	cfg.Agents.Defaults.ModelName = "claude-cli"
 	cfg.Agents.Defaults.Workspace = ""
 
 	provider, _, err := CreateProvider(cfg)
@@ -660,12 +660,11 @@ func TestBuildSystemPrompt_ToolsOnlyNoSystem(t *testing.T) {
 // --- buildToolsPrompt tests ---
 
 func TestBuildToolsPrompt_SkipsNonFunction(t *testing.T) {
-	p := NewClaudeCliProvider("/workspace")
 	tools := []ToolDefinition{
 		{Type: "other", Function: ToolFunctionDefinition{Name: "skip_me"}},
 		{Type: "function", Function: ToolFunctionDefinition{Name: "include_me", Description: "Included"}},
 	}
-	got := p.buildToolsPrompt(tools)
+	got := buildCLIToolsPrompt(tools)
 	if strings.Contains(got, "skip_me") {
 		t.Error("buildToolsPrompt() should skip non-function tools")
 	}
@@ -675,11 +674,10 @@ func TestBuildToolsPrompt_SkipsNonFunction(t *testing.T) {
 }
 
 func TestBuildToolsPrompt_NoDescription(t *testing.T) {
-	p := NewClaudeCliProvider("/workspace")
 	tools := []ToolDefinition{
 		{Type: "function", Function: ToolFunctionDefinition{Name: "bare_tool"}},
 	}
-	got := p.buildToolsPrompt(tools)
+	got := buildCLIToolsPrompt(tools)
 	if !strings.Contains(got, "bare_tool") {
 		t.Error("should include tool name")
 	}
@@ -689,14 +687,13 @@ func TestBuildToolsPrompt_NoDescription(t *testing.T) {
 }
 
 func TestBuildToolsPrompt_NoParameters(t *testing.T) {
-	p := NewClaudeCliProvider("/workspace")
 	tools := []ToolDefinition{
 		{Type: "function", Function: ToolFunctionDefinition{
 			Name:        "no_params_tool",
 			Description: "A tool with no parameters",
 		}},
 	}
-	got := p.buildToolsPrompt(tools)
+	got := buildCLIToolsPrompt(tools)
 	if strings.Contains(got, "Parameters:") {
 		t.Error("should not include Parameters: section when nil")
 	}
diff --git a/pkg/providers/codex_cli_credentials.go b/pkg/providers/codex_cli_credentials.go
index 40f3ee2a1..c5b25f040 100644
--- a/pkg/providers/codex_cli_credentials.go
+++ b/pkg/providers/codex_cli_credentials.go
@@ -8,6 +8,11 @@ import (
 	"time"
 )
 
+// CodexHomeEnvVar is the environment variable that overrides the Codex CLI
+// home directory when resolving the codex auth.json credentials file.
+// Default: ~/.codex
+const CodexHomeEnvVar = "CODEX_HOME"
+
 // CodexCliAuth represents the ~/.codex/auth.json file structure.
 type CodexCliAuth struct {
 	Tokens struct {
@@ -69,7 +74,7 @@ func CreateCodexCliTokenSource() func() (string, string, error) {
 }
 
 func resolveCodexAuthPath() (string, error) {
-	codexHome := os.Getenv("CODEX_HOME")
+	codexHome := os.Getenv(CodexHomeEnvVar)
 	if codexHome == "" {
 		home, err := os.UserHomeDir()
 		if err != nil {
diff --git a/pkg/providers/codex_cli_provider.go b/pkg/providers/codex_cli_provider.go
index 4c783ece5..13f53ad9e 100644
--- a/pkg/providers/codex_cli_provider.go
+++ b/pkg/providers/codex_cli_provider.go
@@ -115,7 +115,7 @@ func (p *CodexCliProvider) buildPrompt(messages []Message, tools []ToolDefinitio
 	}
 
 	if len(tools) > 0 {
-		sb.WriteString(p.buildToolsPrompt(tools))
+		sb.WriteString(buildCLIToolsPrompt(tools))
 		sb.WriteString("\n\n")
 	}
 
@@ -128,38 +128,6 @@ func (p *CodexCliProvider) buildPrompt(messages []Message, tools []ToolDefinitio
 	return sb.String()
 }
 
-// buildToolsPrompt creates a tool definitions section for the prompt.
-func (p *CodexCliProvider) buildToolsPrompt(tools []ToolDefinition) string {
-	var sb strings.Builder
-
-	sb.WriteString("## Available Tools\n\n")
-	sb.WriteString("When you need to use a tool, respond with ONLY a JSON object:\n\n")
-	sb.WriteString("```json\n")
-	sb.WriteString(
-		`{"tool_calls":[{"id":"call_xxx","type":"function","function":{"name":"tool_name","arguments":"{...}"}}]}`,
-	)
-	sb.WriteString("\n```\n\n")
-	sb.WriteString("CRITICAL: The 'arguments' field MUST be a JSON-encoded STRING.\n\n")
-	sb.WriteString("### Tool Definitions:\n\n")
-
-	for _, tool := range tools {
-		if tool.Type != "function" {
-			continue
-		}
-		sb.WriteString(fmt.Sprintf("#### %s\n", tool.Function.Name))
-		if tool.Function.Description != "" {
-			sb.WriteString(fmt.Sprintf("Description: %s\n", tool.Function.Description))
-		}
-		if len(tool.Function.Parameters) > 0 {
-			paramsJSON, _ := json.Marshal(tool.Function.Parameters)
-			sb.WriteString(fmt.Sprintf("Parameters:\n```json\n%s\n```\n", string(paramsJSON)))
-		}
-		sb.WriteString("\n")
-	}
-
-	return sb.String()
-}
-
 // codexEvent represents a single JSONL event from `codex exec --json`.
 type codexEvent struct {
 	Type     string          `json:"type"`
diff --git a/pkg/providers/codex_cli_provider_test.go b/pkg/providers/codex_cli_provider_test.go
index 414e0844d..0f66e25f4 100644
--- a/pkg/providers/codex_cli_provider_test.go
+++ b/pkg/providers/codex_cli_provider_test.go
@@ -490,7 +490,7 @@ echo '{"type":"turn.completed"}'`
 	}
 
 	messages := []Message{{Role: "user", Content: "test"}}
-	_, err := p.Chat(context.Background(), messages, nil, "gpt-5.2-codex", nil)
+	_, err := p.Chat(context.Background(), messages, nil, "gpt-5.3-codex", nil)
 	if err != nil {
 		t.Fatalf("Chat() error: %v", err)
 	}
@@ -502,7 +502,7 @@ echo '{"type":"turn.completed"}'`
 	}
 	args := string(argsData)
 
-	if !strings.Contains(args, "-m gpt-5.2-codex") {
+	if !strings.Contains(args, "-m gpt-5.3-codex") {
 		t.Errorf("args should contain model flag, got: %s", args)
 	}
 	if !strings.Contains(args, "-C /tmp/test-workspace") {
diff --git a/pkg/providers/codex_provider.go b/pkg/providers/codex_provider.go
index 47618300a..4a6d61a4b 100644
--- a/pkg/providers/codex_provider.go
+++ b/pkg/providers/codex_provider.go
@@ -16,7 +16,7 @@ import (
 )
 
 const (
-	codexDefaultModel        = "gpt-5.2"
+	codexDefaultModel        = "gpt-5.3-codex"
 	codexDefaultInstructions = "You are Codex, a coding assistant."
 )
 
@@ -95,7 +95,10 @@ func (p *CodexProvider) Chat(
 		)
 	}
 
-	params := buildCodexParams(messages, tools, resolvedModel, options, p.enableWebSearch)
+	// Respect tools.web.prefer_native: only inject native search when the agent
+	// loop requested it (options["native_search"]), so prefer_native: false
+	useNativeSearch := p.enableWebSearch && (options["native_search"] == true)
+	params := buildCodexParams(messages, tools, resolvedModel, options, useNativeSearch)
 
 	stream := p.client.Responses.NewStreaming(ctx, params, opts...)
 	defer stream.Close()
@@ -157,6 +160,10 @@ func (p *CodexProvider) GetDefaultModel() string {
 	return codexDefaultModel
 }
 
+func (p *CodexProvider) SupportsNativeSearch() bool {
+	return p.enableWebSearch
+}
+
 func resolveCodexModel(model string) (string, string) {
 	m := strings.ToLower(strings.TrimSpace(model))
 	if m == "" {
diff --git a/pkg/providers/codex_provider_test.go b/pkg/providers/codex_provider_test.go
index 4157e53e9..3a0da5e3b 100644
--- a/pkg/providers/codex_provider_test.go
+++ b/pkg/providers/codex_provider_test.go
@@ -355,7 +355,9 @@ func TestCodexProvider_ChatRoundTrip(t *testing.T) {
 	provider.client = createOpenAITestClient(server.URL, "test-token", "acc-123")
 
 	messages := []Message{{Role: "user", Content: "Hello"}}
-	resp, err := provider.Chat(t.Context(), messages, nil, "gpt-4o", map[string]any{"max_tokens": 1024})
+	// Pass native_search so Codex injects built-in web search (mirrors agent loop when prefer_native is true).
+	opts := map[string]any{"max_tokens": 1024, "native_search": true}
+	resp, err := provider.Chat(t.Context(), messages, nil, "gpt-4o", opts)
 	if err != nil {
 		t.Fatalf("Chat() error: %v", err)
 	}
@@ -568,7 +570,7 @@ func TestCodexProvider_ChatRoundTrip_ModelFallbackFromUnsupported(t *testing.T)
 	provider.client = createOpenAITestClient(server.URL, "test-token", "acc-123")
 
 	messages := []Message{{Role: "user", Content: "Hello"}}
-	resp, err := provider.Chat(t.Context(), messages, nil, "gpt-5.2", nil)
+	resp, err := provider.Chat(t.Context(), messages, nil, "gpt-5.3-codex", nil)
 	if err != nil {
 		t.Fatalf("Chat() error: %v", err)
 	}
@@ -599,7 +601,7 @@ func TestResolveCodexModel(t *testing.T) {
 			wantFallback: true,
 		},
 		{name: "non-openai prefixed", input: "glm-4.7", wantModel: codexDefaultModel, wantFallback: true},
-		{name: "openai prefix", input: "openai/gpt-5.2", wantModel: "gpt-5.2", wantFallback: false},
+		{name: "openai prefix", input: "openai/gpt-5.3-codex", wantModel: "gpt-5.3-codex", wantFallback: false},
 		{name: "direct gpt", input: "gpt-4o", wantModel: "gpt-4o", wantFallback: false},
 	}
 
diff --git a/pkg/providers/common/common.go b/pkg/providers/common/common.go
new file mode 100644
index 000000000..90142fb8b
--- /dev/null
+++ b/pkg/providers/common/common.go
@@ -0,0 +1,420 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+// Package common provides shared utilities used by multiple LLM provider
+// implementations (openai_compat, azure, etc.).
+package common
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
+)
+
+// Re-export protocol types used across providers.
+type (
+	ToolCall               = protocoltypes.ToolCall
+	FunctionCall           = protocoltypes.FunctionCall
+	LLMResponse            = protocoltypes.LLMResponse
+	UsageInfo              = protocoltypes.UsageInfo
+	Message                = protocoltypes.Message
+	ToolDefinition         = protocoltypes.ToolDefinition
+	ToolFunctionDefinition = protocoltypes.ToolFunctionDefinition
+	ExtraContent           = protocoltypes.ExtraContent
+	GoogleExtra            = protocoltypes.GoogleExtra
+	ReasoningDetail        = protocoltypes.ReasoningDetail
+)
+
+const DefaultRequestTimeout = 120 * time.Second
+
+// NewHTTPClient creates an *http.Client with an optional proxy and the default timeout.
+func NewHTTPClient(proxy string) *http.Client {
+	client := &http.Client{
+		Timeout: DefaultRequestTimeout,
+	}
+	if proxy != "" {
+		parsed, err := url.Parse(proxy)
+		if err == nil {
+			// Preserve http.DefaultTransport settings (TLS, HTTP/2, timeouts, etc.)
+			if base, ok := http.DefaultTransport.(*http.Transport); ok {
+				tr := base.Clone()
+				tr.Proxy = http.ProxyURL(parsed)
+				client.Transport = tr
+			} else {
+				// Fallback: minimal transport if DefaultTransport is not *http.Transport.
+				client.Transport = &http.Transport{
+					Proxy: http.ProxyURL(parsed),
+				}
+			}
+		} else {
+			log.Printf("common: invalid proxy URL %q: %v", proxy, err)
+		}
+	}
+	return client
+}
+
+// --- Message serialization ---
+
+// openaiMessage is the wire-format message for OpenAI-compatible APIs.
+// It mirrors protocoltypes.Message but omits SystemParts, which is an
+// internal field that would be unknown to third-party endpoints.
+type openaiMessage struct {
+	Role             string     `json:"role"`
+	Content          string     `json:"content"`
+	ReasoningContent string     `json:"reasoning_content,omitempty"`
+	ToolCalls        []ToolCall `json:"tool_calls,omitempty"`
+	ToolCallID       string     `json:"tool_call_id,omitempty"`
+}
+
+// SerializeMessages converts internal Message structs to the OpenAI wire format.
+//   - Strips SystemParts (unknown to third-party endpoints)
+//   - Converts messages with Media to multipart content format (text + image_url parts)
+//   - Preserves ToolCallID, ToolCalls, and ReasoningContent for all messages
+func SerializeMessages(messages []Message) []any {
+	out := make([]any, 0, len(messages))
+	for _, m := range messages {
+		if len(m.Media) == 0 {
+			out = append(out, openaiMessage{
+				Role:             m.Role,
+				Content:          m.Content,
+				ReasoningContent: m.ReasoningContent,
+				ToolCalls:        m.ToolCalls,
+				ToolCallID:       m.ToolCallID,
+			})
+			continue
+		}
+
+		// Multipart content format for messages with media
+		parts := make([]map[string]any, 0, 1+len(m.Media))
+		if m.Content != "" {
+			parts = append(parts, map[string]any{
+				"type": "text",
+				"text": m.Content,
+			})
+		}
+		for _, mediaURL := range m.Media {
+			if strings.HasPrefix(mediaURL, "data:image/") {
+				parts = append(parts, map[string]any{
+					"type": "image_url",
+					"image_url": map[string]any{
+						"url": mediaURL,
+					},
+				})
+				continue
+			}
+
+			if format, data, ok := parseDataAudioURL(mediaURL); ok {
+				parts = append(parts, map[string]any{
+					"type": "input_audio",
+					"input_audio": map[string]any{
+						"data":   data,
+						"format": format,
+					},
+				})
+			}
+		}
+
+		msg := map[string]any{
+			"role":    m.Role,
+			"content": parts,
+		}
+		if m.ToolCallID != "" {
+			msg["tool_call_id"] = m.ToolCallID
+		}
+		if len(m.ToolCalls) > 0 {
+			msg["tool_calls"] = m.ToolCalls
+		}
+		if m.ReasoningContent != "" {
+			msg["reasoning_content"] = m.ReasoningContent
+		}
+		out = append(out, msg)
+	}
+	return out
+}
+
+func parseDataAudioURL(mediaURL string) (format, data string, ok bool) {
+	if !strings.HasPrefix(mediaURL, "data:audio/") {
+		return "", "", false
+	}
+
+	payload := strings.TrimPrefix(mediaURL, "data:audio/")
+	meta, data, found := strings.Cut(payload, ",")
+	if !found {
+		return "", "", false
+	}
+
+	format, _, _ = strings.Cut(meta, ";")
+	format = strings.TrimSpace(format)
+	data = strings.TrimSpace(data)
+	if format == "" || data == "" {
+		return "", "", false
+	}
+	return format, data, true
+}
+
+// --- Response parsing ---
+
+// ParseResponse parses a JSON chat completion response body into an LLMResponse.
+func ParseResponse(body io.Reader) (*LLMResponse, error) {
+	var apiResponse struct {
+		Choices []struct {
+			Message struct {
+				Content          string            `json:"content"`
+				ReasoningContent string            `json:"reasoning_content"`
+				Reasoning        string            `json:"reasoning"`
+				ReasoningDetails []ReasoningDetail `json:"reasoning_details"`
+				ToolCalls        []struct {
+					ID       string `json:"id"`
+					Type     string `json:"type"`
+					Function *struct {
+						Name      string          `json:"name"`
+						Arguments json.RawMessage `json:"arguments"`
+					} `json:"function"`
+					ExtraContent *struct {
+						Google *struct {
+							ThoughtSignature string `json:"thought_signature"`
+						} `json:"google"`
+					} `json:"extra_content"`
+				} `json:"tool_calls"`
+			} `json:"message"`
+			FinishReason string `json:"finish_reason"`
+		} `json:"choices"`
+		Usage *UsageInfo `json:"usage"`
+	}
+
+	if err := json.NewDecoder(body).Decode(&apiResponse); err != nil {
+		return nil, fmt.Errorf("failed to decode response: %w", err)
+	}
+
+	if len(apiResponse.Choices) == 0 {
+		return &LLMResponse{
+			Content:      "",
+			FinishReason: "stop",
+		}, nil
+	}
+
+	choice := apiResponse.Choices[0]
+	toolCalls := make([]ToolCall, 0, len(choice.Message.ToolCalls))
+	for _, tc := range choice.Message.ToolCalls {
+		arguments := make(map[string]any)
+		name := ""
+
+		// Extract thought_signature from Gemini/Google-specific extra content
+		thoughtSignature := ""
+		if tc.ExtraContent != nil && tc.ExtraContent.Google != nil {
+			thoughtSignature = tc.ExtraContent.Google.ThoughtSignature
+		}
+
+		if tc.Function != nil {
+			name = tc.Function.Name
+			arguments = DecodeToolCallArguments(tc.Function.Arguments, name)
+		}
+
+		toolCall := ToolCall{
+			ID:               tc.ID,
+			Name:             name,
+			Arguments:        arguments,
+			ThoughtSignature: thoughtSignature,
+		}
+
+		if thoughtSignature != "" {
+			toolCall.ExtraContent = &ExtraContent{
+				Google: &GoogleExtra{
+					ThoughtSignature: thoughtSignature,
+				},
+			}
+		}
+
+		toolCalls = append(toolCalls, toolCall)
+	}
+
+	return &LLMResponse{
+		Content:          choice.Message.Content,
+		ReasoningContent: choice.Message.ReasoningContent,
+		Reasoning:        choice.Message.Reasoning,
+		ReasoningDetails: choice.Message.ReasoningDetails,
+		ToolCalls:        toolCalls,
+		FinishReason:     normalizeFinishReason(choice.FinishReason),
+		Usage:            apiResponse.Usage,
+	}, nil
+}
+
+// normalizeFinishReason normalizes finish_reason values across providers.
+// Converts "length" to "truncated" for consistent handling.
+func normalizeFinishReason(reason string) string {
+	if reason == "length" {
+		return "truncated"
+	}
+	return reason
+}
+
+// DecodeToolCallArguments decodes a tool call's arguments from raw JSON.
+func DecodeToolCallArguments(raw json.RawMessage, name string) map[string]any {
+	arguments := make(map[string]any)
+	raw = bytes.TrimSpace(raw)
+	if len(raw) == 0 || bytes.Equal(raw, []byte("null")) {
+		return arguments
+	}
+
+	var decoded any
+	if err := json.Unmarshal(raw, &decoded); err != nil {
+		log.Printf("common: failed to decode tool call arguments payload for %q: %v", name, err)
+		arguments["raw"] = string(raw)
+		return arguments
+	}
+
+	switch v := decoded.(type) {
+	case string:
+		if strings.TrimSpace(v) == "" {
+			return arguments
+		}
+		if err := json.Unmarshal([]byte(v), &arguments); err != nil {
+			log.Printf("common: failed to decode tool call arguments for %q: %v", name, err)
+			arguments["raw"] = v
+		}
+		return arguments
+	case map[string]any:
+		return v
+	default:
+		log.Printf("common: unsupported tool call arguments type for %q: %T", name, decoded)
+		arguments["raw"] = string(raw)
+		return arguments
+	}
+}
+
+// --- HTTP response helpers ---
+
+// HandleErrorResponse reads a non-200 response body and returns an appropriate error.
+func HandleErrorResponse(resp *http.Response, apiBase string) error {
+	contentType := resp.Header.Get("Content-Type")
+	body, readErr := io.ReadAll(io.LimitReader(resp.Body, 256))
+	if readErr != nil {
+		return fmt.Errorf("failed to read response: %w", readErr)
+	}
+	if LooksLikeHTML(body, contentType) {
+		return WrapHTMLResponseError(resp.StatusCode, body, contentType, apiBase)
+	}
+	return fmt.Errorf(
+		"API request failed:\n  Status: %d\n  Body:   %s",
+		resp.StatusCode,
+		ResponsePreview(body, 128),
+	)
+}
+
+// ReadAndParseResponse peeks at the response body to detect HTML errors,
+// then parses the JSON response into an LLMResponse.
+func ReadAndParseResponse(resp *http.Response, apiBase string) (*LLMResponse, error) {
+	contentType := resp.Header.Get("Content-Type")
+	reader := bufio.NewReader(resp.Body)
+	prefix, err := reader.Peek(256)
+	if err != nil && err != io.EOF && err != bufio.ErrBufferFull {
+		return nil, fmt.Errorf("failed to inspect response: %w", err)
+	}
+	if LooksLikeHTML(prefix, contentType) {
+		return nil, WrapHTMLResponseError(resp.StatusCode, prefix, contentType, apiBase)
+	}
+	out, err := ParseResponse(reader)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse JSON response: %w", err)
+	}
+	return out, nil
+}
+
+// LooksLikeHTML checks if the response body appears to be HTML.
+func LooksLikeHTML(body []byte, contentType string) bool {
+	contentType = strings.ToLower(strings.TrimSpace(contentType))
+	if strings.Contains(contentType, "text/html") || strings.Contains(contentType, "application/xhtml+xml") {
+		return true
+	}
+	prefix := bytes.ToLower(leadingTrimmedPrefix(body, 128))
+	return bytes.HasPrefix(prefix, []byte("<!doctype html")) ||
+		bytes.HasPrefix(prefix, []byte("<html")) ||
+		bytes.HasPrefix(prefix, []byte("<head")) ||
+		bytes.HasPrefix(prefix, []byte("<body"))
+}
+
+// WrapHTMLResponseError creates a descriptive error for HTML responses.
+func WrapHTMLResponseError(statusCode int, body []byte, contentType, apiBase string) error {
+	respPreview := ResponsePreview(body, 128)
+	return fmt.Errorf(
+		"API request failed: %s returned HTML instead of JSON (content-type: %s); check api_base or proxy configuration.\n  Status: %d\n  Body:   %s",
+		apiBase,
+		contentType,
+		statusCode,
+		respPreview,
+	)
+}
+
+// ResponsePreview returns a truncated preview of response body for error messages.
+func ResponsePreview(body []byte, maxLen int) string {
+	trimmed := bytes.TrimSpace(body)
+	if len(trimmed) == 0 {
+		return "<empty>"
+	}
+	if len(trimmed) <= maxLen {
+		return string(trimmed)
+	}
+	return string(trimmed[:maxLen]) + "..."
+}
+
+func leadingTrimmedPrefix(body []byte, maxLen int) []byte {
+	i := 0
+	for i < len(body) {
+		switch body[i] {
+		case ' ', '\t', '\n', '\r', '\f', '\v':
+			i++
+		default:
+			end := i + maxLen
+			if end > len(body) {
+				end = len(body)
+			}
+			return body[i:end]
+		}
+	}
+	return nil
+}
+
+// --- Numeric helpers ---
+
+// AsInt converts various numeric types to int.
+func AsInt(v any) (int, bool) {
+	switch val := v.(type) {
+	case int:
+		return val, true
+	case int64:
+		return int(val), true
+	case float64:
+		return int(val), true
+	case float32:
+		return int(val), true
+	default:
+		return 0, false
+	}
+}
+
+// AsFloat converts various numeric types to float64.
+func AsFloat(v any) (float64, bool) {
+	switch val := v.(type) {
+	case float64:
+		return val, true
+	case float32:
+		return float64(val), true
+	case int:
+		return float64(val), true
+	case int64:
+		return float64(val), true
+	default:
+		return 0, false
+	}
+}
diff --git a/pkg/providers/common/common_test.go b/pkg/providers/common/common_test.go
new file mode 100644
index 000000000..79a637d48
--- /dev/null
+++ b/pkg/providers/common/common_test.go
@@ -0,0 +1,596 @@
+package common
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
+)
+
+// --- NewHTTPClient tests ---
+
+func TestNewHTTPClient_DefaultTimeout(t *testing.T) {
+	client := NewHTTPClient("")
+	if client.Timeout != DefaultRequestTimeout {
+		t.Errorf("timeout = %v, want %v", client.Timeout, DefaultRequestTimeout)
+	}
+}
+
+func TestNewHTTPClient_WithProxy(t *testing.T) {
+	client := NewHTTPClient("http://127.0.0.1:8080")
+	transport, ok := client.Transport.(*http.Transport)
+	if !ok || transport == nil {
+		t.Fatalf("expected http.Transport with proxy, got %T", client.Transport)
+	}
+	req := &http.Request{URL: &url.URL{Scheme: "https", Host: "api.example.com"}}
+	gotProxy, err := transport.Proxy(req)
+	if err != nil {
+		t.Fatalf("proxy function error: %v", err)
+	}
+	if gotProxy == nil || gotProxy.String() != "http://127.0.0.1:8080" {
+		t.Errorf("proxy = %v, want http://127.0.0.1:8080", gotProxy)
+	}
+}
+
+func TestNewHTTPClient_NoProxy(t *testing.T) {
+	client := NewHTTPClient("")
+	if client.Transport != nil {
+		t.Errorf("expected nil transport without proxy, got %T", client.Transport)
+	}
+}
+
+func TestNewHTTPClient_InvalidProxy(t *testing.T) {
+	// Should not panic, just log and return client without proxy
+	client := NewHTTPClient("://bad-url")
+	if client == nil {
+		t.Fatal("expected non-nil client even with invalid proxy")
+	}
+}
+
+// --- SerializeMessages tests ---
+
+func TestSerializeMessages_PlainText(t *testing.T) {
+	messages := []Message{
+		{Role: "user", Content: "hello"},
+		{Role: "assistant", Content: "hi", ReasoningContent: "thinking..."},
+	}
+	result := SerializeMessages(messages)
+
+	data, _ := json.Marshal(result)
+	var msgs []map[string]any
+	json.Unmarshal(data, &msgs)
+
+	if msgs[0]["content"] != "hello" {
+		t.Errorf("expected plain string content, got %v", msgs[0]["content"])
+	}
+	if msgs[1]["reasoning_content"] != "thinking..." {
+		t.Errorf("reasoning_content not preserved, got %v", msgs[1]["reasoning_content"])
+	}
+}
+
+func TestSerializeMessages_WithMedia(t *testing.T) {
+	messages := []Message{
+		{Role: "user", Content: "describe this", Media: []string{"data:image/png;base64,abc123"}},
+	}
+	result := SerializeMessages(messages)
+
+	data, _ := json.Marshal(result)
+	var msgs []map[string]any
+	json.Unmarshal(data, &msgs)
+
+	content, ok := msgs[0]["content"].([]any)
+	if !ok {
+		t.Fatalf("expected array content for media message, got %T", msgs[0]["content"])
+	}
+	if len(content) != 2 {
+		t.Fatalf("expected 2 content parts, got %d", len(content))
+	}
+}
+
+func TestSerializeMessages_WithAudioMedia(t *testing.T) {
+	messages := []Message{
+		{Role: "user", Content: "transcribe this", Media: []string{"data:audio/ogg;base64,abc123"}},
+	}
+	result := SerializeMessages(messages)
+
+	data, _ := json.Marshal(result)
+	var msgs []map[string]any
+	json.Unmarshal(data, &msgs)
+
+	content, ok := msgs[0]["content"].([]any)
+	if !ok {
+		t.Fatalf("expected array content for media message, got %T", msgs[0]["content"])
+	}
+	if len(content) != 2 {
+		t.Fatalf("expected 2 content parts, got %d", len(content))
+	}
+
+	audioPart, ok := content[1].(map[string]any)
+	if !ok {
+		t.Fatalf("expected audio content part to be an object, got %T", content[1])
+	}
+	if audioPart["type"] != "input_audio" {
+		t.Fatalf("audio part type = %v, want input_audio", audioPart["type"])
+	}
+
+	inputAudio, ok := audioPart["input_audio"].(map[string]any)
+	if !ok {
+		t.Fatalf("expected input_audio object, got %T", audioPart["input_audio"])
+	}
+	if inputAudio["format"] != "ogg" {
+		t.Fatalf("audio format = %v, want ogg", inputAudio["format"])
+	}
+	if inputAudio["data"] != "abc123" {
+		t.Fatalf("audio data = %v, want abc123", inputAudio["data"])
+	}
+}
+
+func TestSerializeMessages_MediaWithToolCallID(t *testing.T) {
+	messages := []Message{
+		{Role: "tool", Content: "result", Media: []string{"data:image/png;base64,xyz"}, ToolCallID: "call_1"},
+	}
+	result := SerializeMessages(messages)
+
+	data, _ := json.Marshal(result)
+	var msgs []map[string]any
+	json.Unmarshal(data, &msgs)
+
+	if msgs[0]["tool_call_id"] != "call_1" {
+		t.Errorf("tool_call_id not preserved, got %v", msgs[0]["tool_call_id"])
+	}
+}
+
+func TestSerializeMessages_StripsSystemParts(t *testing.T) {
+	messages := []Message{
+		{
+			Role:    "system",
+			Content: "you are helpful",
+			SystemParts: []protocoltypes.ContentBlock{
+				{Type: "text", Text: "you are helpful"},
+			},
+		},
+	}
+	result := SerializeMessages(messages)
+
+	data, _ := json.Marshal(result)
+	if strings.Contains(string(data), "system_parts") {
+		t.Error("system_parts should not appear in serialized output")
+	}
+}
+
+// --- ParseResponse tests ---
+
+func TestParseResponse_BasicContent(t *testing.T) {
+	body := `{"choices":[{"message":{"content":"hello world"},"finish_reason":"stop"}]}`
+	out, err := ParseResponse(strings.NewReader(body))
+	if err != nil {
+		t.Fatalf("ParseResponse() error = %v", err)
+	}
+	if out.Content != "hello world" {
+		t.Errorf("Content = %q, want %q", out.Content, "hello world")
+	}
+	if out.FinishReason != "stop" {
+		t.Errorf("FinishReason = %q, want %q", out.FinishReason, "stop")
+	}
+}
+
+func TestParseResponse_EmptyChoices(t *testing.T) {
+	body := `{"choices":[]}`
+	out, err := ParseResponse(strings.NewReader(body))
+	if err != nil {
+		t.Fatalf("ParseResponse() error = %v", err)
+	}
+	if out.Content != "" {
+		t.Errorf("Content = %q, want empty", out.Content)
+	}
+	if out.FinishReason != "stop" {
+		t.Errorf("FinishReason = %q, want %q", out.FinishReason, "stop")
+	}
+}
+
+func TestParseResponse_WithToolCalls(t *testing.T) {
+	body := `{"choices":[{"message":{"content":"","tool_calls":[{"id":"call_1","type":"function","function":{"name":"get_weather","arguments":"{\"city\":\"SF\"}"}}]},"finish_reason":"tool_calls"}]}`
+	out, err := ParseResponse(strings.NewReader(body))
+	if err != nil {
+		t.Fatalf("ParseResponse() error = %v", err)
+	}
+	if len(out.ToolCalls) != 1 {
+		t.Fatalf("len(ToolCalls) = %d, want 1", len(out.ToolCalls))
+	}
+	if out.ToolCalls[0].Name != "get_weather" {
+		t.Errorf("ToolCalls[0].Name = %q, want %q", out.ToolCalls[0].Name, "get_weather")
+	}
+	if out.ToolCalls[0].Arguments["city"] != "SF" {
+		t.Errorf("ToolCalls[0].Arguments[city] = %v, want SF", out.ToolCalls[0].Arguments["city"])
+	}
+}
+
+func TestParseResponse_WithUsage(t *testing.T) {
+	body := `{"choices":[{"message":{"content":"ok"},"finish_reason":"stop"}],"usage":{"prompt_tokens":10,"completion_tokens":5,"total_tokens":15}}`
+	out, err := ParseResponse(strings.NewReader(body))
+	if err != nil {
+		t.Fatalf("ParseResponse() error = %v", err)
+	}
+	if out.Usage == nil {
+		t.Fatal("Usage is nil")
+	}
+	if out.Usage.PromptTokens != 10 {
+		t.Errorf("PromptTokens = %d, want 10", out.Usage.PromptTokens)
+	}
+}
+
+func TestParseResponse_WithReasoningContent(t *testing.T) {
+	body := `{"choices":[{"message":{"content":"2","reasoning_content":"Let me think... 1+1=2"},"finish_reason":"stop"}]}`
+	out, err := ParseResponse(strings.NewReader(body))
+	if err != nil {
+		t.Fatalf("ParseResponse() error = %v", err)
+	}
+	if out.ReasoningContent != "Let me think... 1+1=2" {
+		t.Errorf("ReasoningContent = %q, want %q", out.ReasoningContent, "Let me think... 1+1=2")
+	}
+}
+
+func TestParseResponse_InvalidJSON(t *testing.T) {
+	_, err := ParseResponse(strings.NewReader("not json"))
+	if err == nil {
+		t.Fatal("expected error for invalid JSON")
+	}
+}
+
+// --- DecodeToolCallArguments tests ---
+
+func TestDecodeToolCallArguments_ObjectJSON(t *testing.T) {
+	raw := json.RawMessage(`{"city":"Seattle","units":"metric"}`)
+	args := DecodeToolCallArguments(raw, "test")
+	if args["city"] != "Seattle" {
+		t.Errorf("city = %v, want Seattle", args["city"])
+	}
+	if args["units"] != "metric" {
+		t.Errorf("units = %v, want metric", args["units"])
+	}
+}
+
+func TestDecodeToolCallArguments_StringJSON(t *testing.T) {
+	raw := json.RawMessage(`"{\"city\":\"SF\"}"`)
+	args := DecodeToolCallArguments(raw, "test")
+	if args["city"] != "SF" {
+		t.Errorf("city = %v, want SF", args["city"])
+	}
+}
+
+func TestDecodeToolCallArguments_EmptyInput(t *testing.T) {
+	args := DecodeToolCallArguments(nil, "test")
+	if len(args) != 0 {
+		t.Errorf("expected empty map, got %v", args)
+	}
+}
+
+func TestDecodeToolCallArguments_NullInput(t *testing.T) {
+	args := DecodeToolCallArguments(json.RawMessage(`null`), "test")
+	if len(args) != 0 {
+		t.Errorf("expected empty map, got %v", args)
+	}
+}
+
+func TestDecodeToolCallArguments_InvalidJSON(t *testing.T) {
+	args := DecodeToolCallArguments(json.RawMessage(`not-json`), "test")
+	if _, ok := args["raw"]; !ok {
+		t.Error("expected 'raw' fallback key for invalid JSON")
+	}
+}
+
+func TestDecodeToolCallArguments_EmptyStringJSON(t *testing.T) {
+	args := DecodeToolCallArguments(json.RawMessage(`"  "`), "test")
+	if len(args) != 0 {
+		t.Errorf("expected empty map for whitespace string, got %v", args)
+	}
+}
+
+// --- HandleErrorResponse tests ---
+
+func TestHandleErrorResponse_JSONError(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		w.Write([]byte(`{"error":"bad request"}`))
+	}))
+	defer server.Close()
+
+	resp, err := http.Get(server.URL)
+	if err != nil {
+		t.Fatalf("http.Get() error = %v", err)
+	}
+	defer resp.Body.Close()
+	err = HandleErrorResponse(resp, server.URL)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "400") {
+		t.Errorf("error should contain status code, got %v", err)
+	}
+	if strings.Contains(err.Error(), "HTML") {
+		t.Errorf("should not mention HTML for JSON error, got %v", err)
+	}
+}
+
+func TestHandleErrorResponse_HTMLError(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html")
+		w.WriteHeader(http.StatusBadGateway)
+		w.Write([]byte("<!DOCTYPE html><html><body>bad gateway</body></html>"))
+	}))
+	defer server.Close()
+
+	resp, err := http.Get(server.URL)
+	if err != nil {
+		t.Fatalf("http.Get() error = %v", err)
+	}
+	defer resp.Body.Close()
+	err = HandleErrorResponse(resp, server.URL)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "HTML instead of JSON") {
+		t.Errorf("expected HTML error message, got %v", err)
+	}
+}
+
+// --- ReadAndParseResponse tests ---
+
+func TestReadAndParseResponse_ValidJSON(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"choices":[{"message":{"content":"ok"},"finish_reason":"stop"}]}`))
+	}))
+	defer server.Close()
+
+	resp, err := http.Get(server.URL)
+	if err != nil {
+		t.Fatalf("http.Get() error = %v", err)
+	}
+	defer resp.Body.Close()
+	out, err := ReadAndParseResponse(resp, server.URL)
+	if err != nil {
+		t.Fatalf("ReadAndParseResponse() error = %v", err)
+	}
+	if out.Content != "ok" {
+		t.Errorf("Content = %q, want %q", out.Content, "ok")
+	}
+}
+
+func TestReadAndParseResponse_HTMLResponse(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html")
+		w.Write([]byte("<!DOCTYPE html><html><body>login page</body></html>"))
+	}))
+	defer server.Close()
+
+	resp, err := http.Get(server.URL)
+	if err != nil {
+		t.Fatalf("http.Get() error = %v", err)
+	}
+	defer resp.Body.Close()
+	_, err = ReadAndParseResponse(resp, server.URL)
+	if err == nil {
+		t.Fatal("expected error for HTML response")
+	}
+	if !strings.Contains(err.Error(), "HTML instead of JSON") {
+		t.Errorf("expected HTML error, got %v", err)
+	}
+}
+
+// --- LooksLikeHTML tests ---
+
+func TestLooksLikeHTML_ContentTypeHTML(t *testing.T) {
+	if !LooksLikeHTML(nil, "text/html; charset=utf-8") {
+		t.Error("expected true for text/html content type")
+	}
+}
+
+func TestLooksLikeHTML_ContentTypeXHTML(t *testing.T) {
+	if !LooksLikeHTML(nil, "application/xhtml+xml") {
+		t.Error("expected true for xhtml content type")
+	}
+}
+
+func TestLooksLikeHTML_BodyPrefix(t *testing.T) {
+	tests := []struct {
+		name string
+		body string
+	}{
+		{"doctype", "<!DOCTYPE html><html>"},
+		{"html tag", "<html><body>"},
+		{"head tag", "<head><title>"},
+		{"body tag", "<body>content"},
+		{"whitespace before", "  \n\t<!DOCTYPE html>"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if !LooksLikeHTML([]byte(tt.body), "application/json") {
+				t.Errorf("expected true for body %q", tt.body)
+			}
+		})
+	}
+}
+
+func TestLooksLikeHTML_NotHTML(t *testing.T) {
+	if LooksLikeHTML([]byte(`{"error":"bad"}`), "application/json") {
+		t.Error("expected false for JSON body")
+	}
+}
+
+// --- ResponsePreview tests ---
+
+func TestResponsePreview_Short(t *testing.T) {
+	got := ResponsePreview([]byte("hello"), 128)
+	if got != "hello" {
+		t.Errorf("got %q, want %q", got, "hello")
+	}
+}
+
+func TestResponsePreview_Truncated(t *testing.T) {
+	body := strings.Repeat("a", 200)
+	got := ResponsePreview([]byte(body), 128)
+	if len(got) != 131 { // 128 + "..."
+		t.Errorf("len = %d, want 131", len(got))
+	}
+	if !strings.HasSuffix(got, "...") {
+		t.Error("expected ... suffix")
+	}
+}
+
+func TestResponsePreview_Empty(t *testing.T) {
+	got := ResponsePreview([]byte(""), 128)
+	if got != "<empty>" {
+		t.Errorf("got %q, want %q", got, "<empty>")
+	}
+}
+
+func TestResponsePreview_Whitespace(t *testing.T) {
+	got := ResponsePreview([]byte("  \n\t  "), 128)
+	if got != "<empty>" {
+		t.Errorf("got %q, want %q for whitespace-only body", got, "<empty>")
+	}
+}
+
+// --- AsInt tests ---
+
+func TestAsInt(t *testing.T) {
+	tests := []struct {
+		name string
+		val  any
+		want int
+		ok   bool
+	}{
+		{"int", 42, 42, true},
+		{"int64", int64(99), 99, true},
+		{"float64", float64(512), 512, true},
+		{"float32", float32(256), 256, true},
+		{"string", "nope", 0, false},
+		{"nil", nil, 0, false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, ok := AsInt(tt.val)
+			if ok != tt.ok || got != tt.want {
+				t.Errorf("AsInt(%v) = (%d, %v), want (%d, %v)", tt.val, got, ok, tt.want, tt.ok)
+			}
+		})
+	}
+}
+
+// --- AsFloat tests ---
+
+func TestAsFloat(t *testing.T) {
+	tests := []struct {
+		name string
+		val  any
+		want float64
+		ok   bool
+	}{
+		{"float64", float64(0.7), 0.7, true},
+		{"float32", float32(0.5), float64(float32(0.5)), true},
+		{"int", 1, 1.0, true},
+		{"int64", int64(100), 100.0, true},
+		{"string", "nope", 0, false},
+		{"nil", nil, 0, false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, ok := AsFloat(tt.val)
+			if ok != tt.ok || got != tt.want {
+				t.Errorf("AsFloat(%v) = (%f, %v), want (%f, %v)", tt.val, got, ok, tt.want, tt.ok)
+			}
+		})
+	}
+}
+
+// --- WrapHTMLResponseError tests ---
+
+func TestWrapHTMLResponseError(t *testing.T) {
+	err := WrapHTMLResponseError(502, []byte("<html>bad</html>"), "text/html", "https://api.example.com")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	msg := err.Error()
+	if !strings.Contains(msg, "502") {
+		t.Errorf("expected status code in error, got %v", msg)
+	}
+	if !strings.Contains(msg, "https://api.example.com") {
+		t.Errorf("expected api base in error, got %v", msg)
+	}
+	if !strings.Contains(msg, "HTML instead of JSON") {
+		t.Errorf("expected HTML mention in error, got %v", msg)
+	}
+}
+
+// --- HandleErrorResponse with read failure ---
+
+func TestHandleErrorResponse_EmptyBody(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusInternalServerError)
+		// empty body
+	}))
+	defer server.Close()
+
+	resp, err := http.Get(server.URL)
+	if err != nil {
+		t.Fatalf("http.Get() error = %v", err)
+	}
+	defer resp.Body.Close()
+	err = HandleErrorResponse(resp, server.URL)
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "500") {
+		t.Errorf("expected status code, got %v", err)
+	}
+}
+
+// --- ReadAndParseResponse with invalid JSON ---
+
+func TestReadAndParseResponse_InvalidJSON(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte("not valid json"))
+	}))
+	defer server.Close()
+
+	resp, err := http.Get(server.URL)
+	if err != nil {
+		t.Fatalf("http.Get() error = %v", err)
+	}
+	defer resp.Body.Close()
+	_, err = ReadAndParseResponse(resp, server.URL)
+	if err == nil {
+		t.Fatal("expected error for invalid JSON")
+	}
+}
+
+// --- ParseResponse with thought_signature (Google/Gemini) ---
+
+func TestParseResponse_WithThoughtSignature(t *testing.T) {
+	body := `{"choices":[{"message":{"content":"","tool_calls":[{"id":"call_1","type":"function","function":{"name":"test_tool","arguments":"{}"},"extra_content":{"google":{"thought_signature":"sig123"}}}]},"finish_reason":"tool_calls"}]}`
+	out, err := ParseResponse(strings.NewReader(body))
+	if err != nil {
+		t.Fatalf("ParseResponse() error = %v", err)
+	}
+	if len(out.ToolCalls) != 1 {
+		t.Fatalf("len(ToolCalls) = %d, want 1", len(out.ToolCalls))
+	}
+	if out.ToolCalls[0].ThoughtSignature != "sig123" {
+		t.Errorf("ThoughtSignature = %q, want %q", out.ToolCalls[0].ThoughtSignature, "sig123")
+	}
+	if out.ToolCalls[0].ExtraContent == nil || out.ToolCalls[0].ExtraContent.Google == nil {
+		t.Fatal("ExtraContent.Google is nil")
+	}
+	if out.ToolCalls[0].ExtraContent.Google.ThoughtSignature != "sig123" {
+		t.Errorf("ExtraContent.Google.ThoughtSignature = %q, want %q",
+			out.ToolCalls[0].ExtraContent.Google.ThoughtSignature, "sig123")
+	}
+}
diff --git a/pkg/providers/factory.go b/pkg/providers/factory.go
index 11af14da4..354acafcb 100644
--- a/pkg/providers/factory.go
+++ b/pkg/providers/factory.go
@@ -1,323 +1,7 @@
 package providers
 
 import (
-	"fmt"
-	"strings"
-
 	"github.com/sipeed/picoclaw/pkg/auth"
-	"github.com/sipeed/picoclaw/pkg/config"
 )
 
-const defaultAnthropicAPIBase = "https://api.anthropic.com/v1"
-
 var getCredential = auth.GetCredential
-
-type providerType int
-
-const (
-	providerTypeHTTPCompat providerType = iota
-	providerTypeClaudeAuth
-	providerTypeCodexAuth
-	providerTypeCodexCLIToken
-	providerTypeClaudeCLI
-	providerTypeCodexCLI
-	providerTypeGitHubCopilot
-)
-
-type providerSelection struct {
-	providerType    providerType
-	apiKey          string
-	apiBase         string
-	proxy           string
-	model           string
-	workspace       string
-	connectMode     string
-	enableWebSearch bool
-}
-
-func resolveProviderSelection(cfg *config.Config) (providerSelection, error) {
-	model := cfg.Agents.Defaults.GetModelName()
-	providerName := strings.ToLower(cfg.Agents.Defaults.Provider)
-	lowerModel := strings.ToLower(model)
-
-	sel := providerSelection{
-		providerType: providerTypeHTTPCompat,
-		model:        model,
-	}
-
-	// First, prefer explicit provider configuration.
-	if providerName != "" {
-		switch providerName {
-		case "groq":
-			if cfg.Providers.Groq.APIKey != "" {
-				sel.apiKey = cfg.Providers.Groq.APIKey
-				sel.apiBase = cfg.Providers.Groq.APIBase
-				sel.proxy = cfg.Providers.Groq.Proxy
-				if sel.apiBase == "" {
-					sel.apiBase = "https://api.groq.com/openai/v1"
-				}
-			}
-		case "openai", "gpt":
-			if cfg.Providers.OpenAI.APIKey != "" || cfg.Providers.OpenAI.AuthMethod != "" {
-				sel.enableWebSearch = cfg.Providers.OpenAI.WebSearch
-				if cfg.Providers.OpenAI.AuthMethod == "codex-cli" {
-					sel.providerType = providerTypeCodexCLIToken
-					return sel, nil
-				}
-				if cfg.Providers.OpenAI.AuthMethod == "oauth" || cfg.Providers.OpenAI.AuthMethod == "token" {
-					sel.providerType = providerTypeCodexAuth
-					return sel, nil
-				}
-				sel.apiKey = cfg.Providers.OpenAI.APIKey
-				sel.apiBase = cfg.Providers.OpenAI.APIBase
-				sel.proxy = cfg.Providers.OpenAI.Proxy
-				if sel.apiBase == "" {
-					sel.apiBase = "https://api.openai.com/v1"
-				}
-			}
-		case "anthropic", "claude":
-			if cfg.Providers.Anthropic.APIKey != "" || cfg.Providers.Anthropic.AuthMethod != "" {
-				if cfg.Providers.Anthropic.AuthMethod == "oauth" || cfg.Providers.Anthropic.AuthMethod == "token" {
-					sel.apiBase = cfg.Providers.Anthropic.APIBase
-					if sel.apiBase == "" {
-						sel.apiBase = defaultAnthropicAPIBase
-					}
-					sel.providerType = providerTypeClaudeAuth
-					return sel, nil
-				}
-				sel.apiKey = cfg.Providers.Anthropic.APIKey
-				sel.apiBase = cfg.Providers.Anthropic.APIBase
-				sel.proxy = cfg.Providers.Anthropic.Proxy
-				if sel.apiBase == "" {
-					sel.apiBase = defaultAnthropicAPIBase
-				}
-			}
-		case "openrouter":
-			if cfg.Providers.OpenRouter.APIKey != "" {
-				sel.apiKey = cfg.Providers.OpenRouter.APIKey
-				sel.proxy = cfg.Providers.OpenRouter.Proxy
-				if cfg.Providers.OpenRouter.APIBase != "" {
-					sel.apiBase = cfg.Providers.OpenRouter.APIBase
-				} else {
-					sel.apiBase = "https://openrouter.ai/api/v1"
-				}
-			}
-		case "zhipu", "glm":
-			if cfg.Providers.Zhipu.APIKey != "" {
-				sel.apiKey = cfg.Providers.Zhipu.APIKey
-				sel.apiBase = cfg.Providers.Zhipu.APIBase
-				sel.proxy = cfg.Providers.Zhipu.Proxy
-				if sel.apiBase == "" {
-					sel.apiBase = "https://open.bigmodel.cn/api/paas/v4"
-				}
-			}
-		case "gemini", "google":
-			if cfg.Providers.Gemini.APIKey != "" {
-				sel.apiKey = cfg.Providers.Gemini.APIKey
-				sel.apiBase = cfg.Providers.Gemini.APIBase
-				sel.proxy = cfg.Providers.Gemini.Proxy
-				if sel.apiBase == "" {
-					sel.apiBase = "https://generativelanguage.googleapis.com/v1beta"
-				}
-			}
-		case "vllm":
-			if cfg.Providers.VLLM.APIBase != "" {
-				sel.apiKey = cfg.Providers.VLLM.APIKey
-				sel.apiBase = cfg.Providers.VLLM.APIBase
-				sel.proxy = cfg.Providers.VLLM.Proxy
-			}
-		case "shengsuanyun":
-			if cfg.Providers.ShengSuanYun.APIKey != "" {
-				sel.apiKey = cfg.Providers.ShengSuanYun.APIKey
-				sel.apiBase = cfg.Providers.ShengSuanYun.APIBase
-				sel.proxy = cfg.Providers.ShengSuanYun.Proxy
-				if sel.apiBase == "" {
-					sel.apiBase = "https://router.shengsuanyun.com/api/v1"
-				}
-			}
-		case "nvidia":
-			if cfg.Providers.Nvidia.APIKey != "" {
-				sel.apiKey = cfg.Providers.Nvidia.APIKey
-				sel.apiBase = cfg.Providers.Nvidia.APIBase
-				sel.proxy = cfg.Providers.Nvidia.Proxy
-				if sel.apiBase == "" {
-					sel.apiBase = "https://integrate.api.nvidia.com/v1"
-				}
-			}
-		case "claude-cli", "claude-code", "claudecode":
-			workspace := cfg.WorkspacePath()
-			if workspace == "" {
-				workspace = "."
-			}
-			sel.providerType = providerTypeClaudeCLI
-			sel.workspace = workspace
-			return sel, nil
-		case "codex-cli", "codex-code":
-			workspace := cfg.WorkspacePath()
-			if workspace == "" {
-				workspace = "."
-			}
-			sel.providerType = providerTypeCodexCLI
-			sel.workspace = workspace
-			return sel, nil
-		case "deepseek":
-			if cfg.Providers.DeepSeek.APIKey != "" {
-				sel.apiKey = cfg.Providers.DeepSeek.APIKey
-				sel.apiBase = cfg.Providers.DeepSeek.APIBase
-				sel.proxy = cfg.Providers.DeepSeek.Proxy
-				if sel.apiBase == "" {
-					sel.apiBase = "https://api.deepseek.com/v1"
-				}
-				if model != "deepseek-chat" && model != "deepseek-reasoner" {
-					sel.model = "deepseek-chat"
-				}
-			}
-		case "mistral":
-			if cfg.Providers.Mistral.APIKey != "" {
-				sel.apiKey = cfg.Providers.Mistral.APIKey
-				sel.apiBase = cfg.Providers.Mistral.APIBase
-				sel.proxy = cfg.Providers.Mistral.Proxy
-				if sel.apiBase == "" {
-					sel.apiBase = "https://api.mistral.ai/v1"
-				}
-			}
-		case "github_copilot", "copilot":
-			sel.providerType = providerTypeGitHubCopilot
-			if cfg.Providers.GitHubCopilot.APIBase != "" {
-				sel.apiBase = cfg.Providers.GitHubCopilot.APIBase
-			} else {
-				sel.apiBase = "localhost:4321"
-			}
-			sel.connectMode = cfg.Providers.GitHubCopilot.ConnectMode
-			return sel, nil
-		}
-	}
-
-	// Fallback: infer provider from model and configured keys.
-	if sel.apiKey == "" && sel.apiBase == "" {
-		switch {
-		case (strings.Contains(lowerModel, "kimi") || strings.Contains(lowerModel, "moonshot") || strings.HasPrefix(model, "moonshot/")) && cfg.Providers.Moonshot.APIKey != "":
-			sel.apiKey = cfg.Providers.Moonshot.APIKey
-			sel.apiBase = cfg.Providers.Moonshot.APIBase
-			sel.proxy = cfg.Providers.Moonshot.Proxy
-			if sel.apiBase == "" {
-				sel.apiBase = "https://api.moonshot.cn/v1"
-			}
-		case strings.HasPrefix(model, "openrouter/") ||
-			strings.HasPrefix(model, "anthropic/") ||
-			strings.HasPrefix(model, "openai/") ||
-			strings.HasPrefix(model, "meta-llama/") ||
-			strings.HasPrefix(model, "deepseek/") ||
-			strings.HasPrefix(model, "google/"):
-			sel.apiKey = cfg.Providers.OpenRouter.APIKey
-			sel.proxy = cfg.Providers.OpenRouter.Proxy
-			if cfg.Providers.OpenRouter.APIBase != "" {
-				sel.apiBase = cfg.Providers.OpenRouter.APIBase
-			} else {
-				sel.apiBase = "https://openrouter.ai/api/v1"
-			}
-		case (strings.Contains(lowerModel, "claude") || strings.HasPrefix(model, "anthropic/")) &&
-			(cfg.Providers.Anthropic.APIKey != "" || cfg.Providers.Anthropic.AuthMethod != ""):
-			if cfg.Providers.Anthropic.AuthMethod == "oauth" || cfg.Providers.Anthropic.AuthMethod == "token" {
-				sel.apiBase = cfg.Providers.Anthropic.APIBase
-				if sel.apiBase == "" {
-					sel.apiBase = defaultAnthropicAPIBase
-				}
-				sel.providerType = providerTypeClaudeAuth
-				return sel, nil
-			}
-			sel.apiKey = cfg.Providers.Anthropic.APIKey
-			sel.apiBase = cfg.Providers.Anthropic.APIBase
-			sel.proxy = cfg.Providers.Anthropic.Proxy
-			if sel.apiBase == "" {
-				sel.apiBase = defaultAnthropicAPIBase
-			}
-		case (strings.Contains(lowerModel, "gpt") || strings.HasPrefix(model, "openai/")) &&
-			(cfg.Providers.OpenAI.APIKey != "" || cfg.Providers.OpenAI.AuthMethod != ""):
-			sel.enableWebSearch = cfg.Providers.OpenAI.WebSearch
-			if cfg.Providers.OpenAI.AuthMethod == "codex-cli" {
-				sel.providerType = providerTypeCodexCLIToken
-				return sel, nil
-			}
-			if cfg.Providers.OpenAI.AuthMethod == "oauth" || cfg.Providers.OpenAI.AuthMethod == "token" {
-				sel.providerType = providerTypeCodexAuth
-				return sel, nil
-			}
-			sel.apiKey = cfg.Providers.OpenAI.APIKey
-			sel.apiBase = cfg.Providers.OpenAI.APIBase
-			sel.proxy = cfg.Providers.OpenAI.Proxy
-			if sel.apiBase == "" {
-				sel.apiBase = "https://api.openai.com/v1"
-			}
-		case (strings.Contains(lowerModel, "gemini") || strings.HasPrefix(model, "google/")) && cfg.Providers.Gemini.APIKey != "":
-			sel.apiKey = cfg.Providers.Gemini.APIKey
-			sel.apiBase = cfg.Providers.Gemini.APIBase
-			sel.proxy = cfg.Providers.Gemini.Proxy
-			if sel.apiBase == "" {
-				sel.apiBase = "https://generativelanguage.googleapis.com/v1beta"
-			}
-		case (strings.Contains(lowerModel, "glm") || strings.Contains(lowerModel, "zhipu") || strings.Contains(lowerModel, "zai")) && cfg.Providers.Zhipu.APIKey != "":
-			sel.apiKey = cfg.Providers.Zhipu.APIKey
-			sel.apiBase = cfg.Providers.Zhipu.APIBase
-			sel.proxy = cfg.Providers.Zhipu.Proxy
-			if sel.apiBase == "" {
-				sel.apiBase = "https://open.bigmodel.cn/api/paas/v4"
-			}
-		case (strings.Contains(lowerModel, "groq") || strings.HasPrefix(model, "groq/")) && cfg.Providers.Groq.APIKey != "":
-			sel.apiKey = cfg.Providers.Groq.APIKey
-			sel.apiBase = cfg.Providers.Groq.APIBase
-			sel.proxy = cfg.Providers.Groq.Proxy
-			if sel.apiBase == "" {
-				sel.apiBase = "https://api.groq.com/openai/v1"
-			}
-		case (strings.Contains(lowerModel, "nvidia") || strings.HasPrefix(model, "nvidia/")) && cfg.Providers.Nvidia.APIKey != "":
-			sel.apiKey = cfg.Providers.Nvidia.APIKey
-			sel.apiBase = cfg.Providers.Nvidia.APIBase
-			sel.proxy = cfg.Providers.Nvidia.Proxy
-			if sel.apiBase == "" {
-				sel.apiBase = "https://integrate.api.nvidia.com/v1"
-			}
-		case (strings.Contains(lowerModel, "ollama") || strings.HasPrefix(model, "ollama/")) && cfg.Providers.Ollama.APIKey != "":
-			sel.apiKey = cfg.Providers.Ollama.APIKey
-			sel.apiBase = cfg.Providers.Ollama.APIBase
-			sel.proxy = cfg.Providers.Ollama.Proxy
-			if sel.apiBase == "" {
-				sel.apiBase = "http://localhost:11434/v1"
-			}
-		case (strings.Contains(lowerModel, "mistral") || strings.HasPrefix(model, "mistral/")) && cfg.Providers.Mistral.APIKey != "":
-			sel.apiKey = cfg.Providers.Mistral.APIKey
-			sel.apiBase = cfg.Providers.Mistral.APIBase
-			sel.proxy = cfg.Providers.Mistral.Proxy
-			if sel.apiBase == "" {
-				sel.apiBase = "https://api.mistral.ai/v1"
-			}
-		case cfg.Providers.VLLM.APIBase != "":
-			sel.apiKey = cfg.Providers.VLLM.APIKey
-			sel.apiBase = cfg.Providers.VLLM.APIBase
-			sel.proxy = cfg.Providers.VLLM.Proxy
-		default:
-			if cfg.Providers.OpenRouter.APIKey != "" {
-				sel.apiKey = cfg.Providers.OpenRouter.APIKey
-				sel.proxy = cfg.Providers.OpenRouter.Proxy
-				if cfg.Providers.OpenRouter.APIBase != "" {
-					sel.apiBase = cfg.Providers.OpenRouter.APIBase
-				} else {
-					sel.apiBase = "https://openrouter.ai/api/v1"
-				}
-			} else {
-				return providerSelection{}, fmt.Errorf("no API key configured for model: %s", model)
-			}
-		}
-	}
-
-	if sel.providerType == providerTypeHTTPCompat {
-		if sel.apiKey == "" && !strings.HasPrefix(model, "bedrock/") {
-			return providerSelection{}, fmt.Errorf("no API key configured for provider (model: %s)", model)
-		}
-		if sel.apiBase == "" {
-			return providerSelection{}, fmt.Errorf("no API base configured for provider (model: %s)", model)
-		}
-	}
-
-	return sel, nil
-}
diff --git a/pkg/providers/factory_provider.go b/pkg/providers/factory_provider.go
index 53f7a08a0..1128fc042 100644
--- a/pkg/providers/factory_provider.go
+++ b/pkg/providers/factory_provider.go
@@ -6,10 +6,15 @@
 package providers
 
 import (
+	"context"
 	"fmt"
 	"strings"
+	"time"
 
 	"github.com/sipeed/picoclaw/pkg/config"
+	anthropicmessages "github.com/sipeed/picoclaw/pkg/providers/anthropic_messages"
+	"github.com/sipeed/picoclaw/pkg/providers/azure"
+	"github.com/sipeed/picoclaw/pkg/providers/bedrock"
 )
 
 // createClaudeAuthProvider creates a Claude provider using OAuth credentials from auth store.
@@ -53,7 +58,9 @@ func ExtractProtocol(model string) (protocol, modelID string) {
 
 // CreateProviderFromConfig creates a provider based on the ModelConfig.
 // It uses the protocol prefix in the Model field to determine which provider to create.
-// Supported protocols: openai, anthropic, antigravity, claude-cli, codex-cli, github-copilot
+// Supported protocol families include OpenAI-compatible prefixes (e.g., openai, openrouter, groq, gemini),
+// Azure OpenAI, Amazon Bedrock, Anthropic (including messages), and various CLI/compatibility shims.
+// See the switch on protocol in this function for the authoritative list.
 // Returns the provider, the model ID (without protocol prefix), and any error.
 func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, error) {
 	if cfg == nil {
@@ -77,7 +84,7 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 			return provider, modelID, nil
 		}
 		// OpenAI with API key
-		if cfg.APIKey == "" && cfg.APIBase == "" {
+		if cfg.APIKey() == "" && cfg.APIBase == "" {
 			return nil, "", fmt.Errorf("api_key or api_base is required for HTTP-based protocol %q", protocol)
 		}
 		apiBase := cfg.APIBase
@@ -85,18 +92,75 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 			apiBase = getDefaultAPIBase(protocol)
 		}
 		return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
-			cfg.APIKey,
+			cfg.APIKey(),
 			apiBase,
 			cfg.Proxy,
 			cfg.MaxTokensField,
 			cfg.RequestTimeout,
+			cfg.ExtraBody,
+		), modelID, nil
+
+	case "azure", "azure-openai":
+		// Azure OpenAI uses deployment-based URLs, api-key header auth,
+		// and always sends max_completion_tokens.
+		if cfg.APIKey() == "" {
+			return nil, "", fmt.Errorf("api_key is required for azure protocol")
+		}
+		if cfg.APIBase == "" {
+			return nil, "", fmt.Errorf(
+				"api_base is required for azure protocol (e.g., https://your-resource.openai.azure.com)",
+			)
+		}
+		return azure.NewProviderWithTimeout(
+			cfg.APIKey(),
+			cfg.APIBase,
+			cfg.Proxy,
+			cfg.RequestTimeout,
 		), modelID, nil
 
-	case "openrouter", "groq", "zhipu", "gemini", "nvidia",
+	case "bedrock":
+		// AWS Bedrock uses AWS SDK credentials (env vars, profiles, IAM roles, etc.)
+		// api_base can be:
+		//   - A full endpoint URL: https://bedrock-runtime.us-east-1.amazonaws.com
+		//   - A region name: us-east-1 (AWS SDK resolves endpoint automatically)
+		var opts []bedrock.Option
+		if cfg.APIBase != "" {
+			if !strings.Contains(cfg.APIBase, "://") {
+				// Treat as region: let AWS SDK resolve the correct endpoint
+				// (supports all AWS partitions: aws, aws-cn, aws-us-gov, etc.)
+				opts = append(opts, bedrock.WithRegion(cfg.APIBase))
+			} else {
+				// Full endpoint URL provided (for custom endpoints or testing)
+				opts = append(opts, bedrock.WithBaseEndpoint(cfg.APIBase))
+			}
+		}
+		// Use a separate timeout for AWS config loading (credential resolution can block)
+		initTimeout := 30 * time.Second
+		if cfg.RequestTimeout > 0 {
+			reqTimeout := time.Duration(cfg.RequestTimeout) * time.Second
+			// Set request timeout for API calls
+			opts = append(opts, bedrock.WithRequestTimeout(reqTimeout))
+			// Ensure init timeout is at least as large as request timeout
+			if reqTimeout > initTimeout {
+				initTimeout = reqTimeout
+			}
+		}
+		ctx, cancel := context.WithTimeout(context.Background(), initTimeout)
+		defer cancel()
+		// Note: AWS_PROFILE env var is automatically used by AWS SDK
+		provider, err := bedrock.NewProvider(ctx, opts...)
+		if err != nil {
+			return nil, "", fmt.Errorf("creating bedrock provider: %w", err)
+		}
+		return provider, modelID, nil
+
+	case "litellm", "openrouter", "groq", "zhipu", "gemini", "nvidia",
 		"ollama", "moonshot", "shengsuanyun", "deepseek", "cerebras",
-		"volcengine", "vllm", "qwen", "mistral":
+		"vivgrid", "volcengine", "vllm", "qwen", "qwen-intl", "qwen-international", "dashscope-intl",
+		"qwen-us", "dashscope-us", "mistral", "avian", "longcat", "modelscope", "novita",
+		"coding-plan", "alibaba-coding", "qwen-coding":
 		// All other OpenAI-compatible HTTP providers
-		if cfg.APIKey == "" && cfg.APIBase == "" {
+		if cfg.APIKey() == "" && cfg.APIBase == "" {
 			return nil, "", fmt.Errorf("api_key or api_base is required for HTTP-based protocol %q", protocol)
 		}
 		apiBase := cfg.APIBase
@@ -104,11 +168,37 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 			apiBase = getDefaultAPIBase(protocol)
 		}
 		return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
-			cfg.APIKey,
+			cfg.APIKey(),
 			apiBase,
 			cfg.Proxy,
 			cfg.MaxTokensField,
 			cfg.RequestTimeout,
+			cfg.ExtraBody,
+		), modelID, nil
+
+	case "minimax":
+		// Minimax requires reasoning_split: true in the request body
+		if cfg.APIKey() == "" && cfg.APIBase == "" {
+			return nil, "", fmt.Errorf("api_key or api_base is required for HTTP-based protocol %q", protocol)
+		}
+		apiBase := cfg.APIBase
+		if apiBase == "" {
+			apiBase = getDefaultAPIBase(protocol)
+		}
+		extraBody := cfg.ExtraBody
+		if extraBody == nil {
+			extraBody = make(map[string]any)
+		}
+		if _, ok := extraBody["reasoning_split"]; !ok {
+			extraBody["reasoning_split"] = true
+		}
+		return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
+			cfg.APIKey(),
+			apiBase,
+			cfg.Proxy,
+			cfg.MaxTokensField,
+			cfg.RequestTimeout,
+			extraBody,
 		), modelID, nil
 
 	case "anthropic":
@@ -125,15 +215,46 @@ func CreateProviderFromConfig(cfg *config.ModelConfig) (LLMProvider, string, err
 		if apiBase == "" {
 			apiBase = "https://api.anthropic.com/v1"
 		}
-		if cfg.APIKey == "" {
+		if cfg.APIKey() == "" {
 			return nil, "", fmt.Errorf("api_key is required for anthropic protocol (model: %s)", cfg.Model)
 		}
 		return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
-			cfg.APIKey,
+			cfg.APIKey(),
 			apiBase,
 			cfg.Proxy,
 			cfg.MaxTokensField,
 			cfg.RequestTimeout,
+			cfg.ExtraBody,
+		), modelID, nil
+
+	case "anthropic-messages":
+		// Anthropic Messages API with native format (HTTP-based, no SDK)
+		apiBase := cfg.APIBase
+		if apiBase == "" {
+			apiBase = "https://api.anthropic.com/v1"
+		}
+		if cfg.APIKey() == "" {
+			return nil, "", fmt.Errorf("api_key is required for anthropic-messages protocol (model: %s)", cfg.Model)
+		}
+		return anthropicmessages.NewProviderWithTimeout(
+			cfg.APIKey(),
+			apiBase,
+			cfg.RequestTimeout,
+		), modelID, nil
+
+	case "coding-plan-anthropic", "alibaba-coding-anthropic":
+		// Alibaba Coding Plan with Anthropic-compatible API
+		apiBase := cfg.APIBase
+		if apiBase == "" {
+			apiBase = getDefaultAPIBase(protocol)
+		}
+		if cfg.APIKey() == "" {
+			return nil, "", fmt.Errorf("api_key is required for %q protocol (model: %s)", protocol, cfg.Model)
+		}
+		return anthropicmessages.NewProviderWithTimeout(
+			cfg.APIKey(),
+			apiBase,
+			cfg.RequestTimeout,
 		), modelID, nil
 
 	case "antigravity":
@@ -180,6 +301,10 @@ func getDefaultAPIBase(protocol string) string {
 		return "https://api.openai.com/v1"
 	case "openrouter":
 		return "https://openrouter.ai/api/v1"
+	case "litellm":
+		return "http://localhost:4000/v1"
+	case "novita":
+		return "https://api.novita.ai/openai"
 	case "groq":
 		return "https://api.groq.com/openai/v1"
 	case "zhipu":
@@ -198,14 +323,32 @@ func getDefaultAPIBase(protocol string) string {
 		return "https://api.deepseek.com/v1"
 	case "cerebras":
 		return "https://api.cerebras.ai/v1"
+	case "vivgrid":
+		return "https://api.vivgrid.com/v1"
 	case "volcengine":
 		return "https://ark.cn-beijing.volces.com/api/v3"
 	case "qwen":
 		return "https://dashscope.aliyuncs.com/compatible-mode/v1"
+	case "qwen-intl", "qwen-international", "dashscope-intl":
+		return "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+	case "qwen-us", "dashscope-us":
+		return "https://dashscope-us.aliyuncs.com/compatible-mode/v1"
+	case "coding-plan", "alibaba-coding", "qwen-coding":
+		return "https://coding-intl.dashscope.aliyuncs.com/v1"
+	case "coding-plan-anthropic", "alibaba-coding-anthropic":
+		return "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic"
 	case "vllm":
 		return "http://localhost:8000/v1"
 	case "mistral":
 		return "https://api.mistral.ai/v1"
+	case "avian":
+		return "https://api.avian.io/v1"
+	case "minimax":
+		return "https://api.minimaxi.com/v1"
+	case "longcat":
+		return "https://api.longcat.chat/openai"
+	case "modelscope":
+		return "https://api-inference.modelscope.cn/v1"
 	default:
 		return ""
 	}
diff --git a/pkg/providers/factory_provider_test.go b/pkg/providers/factory_provider_test.go
index e0c0eddef..2fed18c35 100644
--- a/pkg/providers/factory_provider_test.go
+++ b/pkg/providers/factory_provider_test.go
@@ -6,6 +6,7 @@
 package providers
 
 import (
+	"encoding/json"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -64,6 +65,12 @@ func TestExtractProtocol(t *testing.T) {
 			wantProtocol: "nvidia",
 			wantModelID:  "meta/llama-3.1-8b",
 		},
+		{
+			name:         "azure with prefix",
+			model:        "azure/my-gpt5-deployment",
+			wantProtocol: "azure",
+			wantModelID:  "my-gpt5-deployment",
+		},
 	}
 
 	for _, tt := range tests {
@@ -83,9 +90,9 @@ func TestCreateProviderFromConfig_OpenAI(t *testing.T) {
 	cfg := &config.ModelConfig{
 		ModelName: "test-openai",
 		Model:     "openai/gpt-4o",
-		APIKey:    "test-key",
 		APIBase:   "https://api.example.com/v1",
 	}
+	cfg.SetAPIKey("test-key")
 
 	provider, modelID, err := CreateProviderFromConfig(cfg)
 	if err != nil {
@@ -106,12 +113,16 @@ func TestCreateProviderFromConfig_DefaultAPIBase(t *testing.T) {
 	}{
 		{"openai", "openai"},
 		{"groq", "groq"},
+		{"novita", "novita"},
 		{"openrouter", "openrouter"},
 		{"cerebras", "cerebras"},
+		{"vivgrid", "vivgrid"},
 		{"qwen", "qwen"},
 		{"vllm", "vllm"},
 		{"deepseek", "deepseek"},
 		{"ollama", "ollama"},
+		{"longcat", "longcat"},
+		{"modelscope", "modelscope"},
 	}
 
 	for _, tt := range tests {
@@ -119,8 +130,8 @@ func TestCreateProviderFromConfig_DefaultAPIBase(t *testing.T) {
 			cfg := &config.ModelConfig{
 				ModelName: "test-" + tt.protocol,
 				Model:     tt.protocol + "/test-model",
-				APIKey:    "test-key",
 			}
+			cfg.SetAPIKey("test-key")
 
 			provider, _, err := CreateProviderFromConfig(cfg)
 			if err != nil {
@@ -135,12 +146,118 @@ func TestCreateProviderFromConfig_DefaultAPIBase(t *testing.T) {
 	}
 }
 
+func TestGetDefaultAPIBase_LiteLLM(t *testing.T) {
+	if got := getDefaultAPIBase("litellm"); got != "http://localhost:4000/v1" {
+		t.Fatalf("getDefaultAPIBase(%q) = %q, want %q", "litellm", got, "http://localhost:4000/v1")
+	}
+}
+
+func TestCreateProviderFromConfig_LiteLLM(t *testing.T) {
+	cfg := &config.ModelConfig{
+		ModelName: "test-litellm",
+		Model:     "litellm/my-proxy-alias",
+		APIBase:   "http://localhost:4000/v1",
+	}
+	cfg.SetAPIKey("test-key")
+
+	provider, modelID, err := CreateProviderFromConfig(cfg)
+	if err != nil {
+		t.Fatalf("CreateProviderFromConfig() error = %v", err)
+	}
+	if provider == nil {
+		t.Fatal("CreateProviderFromConfig() returned nil provider")
+	}
+	if modelID != "my-proxy-alias" {
+		t.Errorf("modelID = %q, want %q", modelID, "my-proxy-alias")
+	}
+}
+
+func TestCreateProviderFromConfig_LongCat(t *testing.T) {
+	cfg := &config.ModelConfig{
+		ModelName: "test-longcat",
+		Model:     "longcat/LongCat-Flash-Thinking",
+		APIBase:   "https://api.longcat.chat/openai",
+	}
+	cfg.SetAPIKey("test-key")
+
+	provider, modelID, err := CreateProviderFromConfig(cfg)
+	if err != nil {
+		t.Fatalf("CreateProviderFromConfig() error = %v", err)
+	}
+	if provider == nil {
+		t.Fatal("CreateProviderFromConfig() returned nil provider")
+	}
+	if modelID != "LongCat-Flash-Thinking" {
+		t.Errorf("modelID = %q, want %q", modelID, "LongCat-Flash-Thinking")
+	}
+	if _, ok := provider.(*HTTPProvider); !ok {
+		t.Fatalf("expected *HTTPProvider, got %T", provider)
+	}
+}
+
+func TestCreateProviderFromConfig_ModelScope(t *testing.T) {
+	cfg := &config.ModelConfig{
+		ModelName: "test-modelscope",
+		Model:     "modelscope/Qwen/Qwen3-235B-A22B-Instruct-2507",
+		APIBase:   "https://api-inference.modelscope.cn/v1",
+	}
+	cfg.SetAPIKey("test-key")
+
+	provider, modelID, err := CreateProviderFromConfig(cfg)
+	if err != nil {
+		t.Fatalf("CreateProviderFromConfig() error = %v", err)
+	}
+	if provider == nil {
+		t.Fatal("CreateProviderFromConfig() returned nil provider")
+	}
+	if modelID != "Qwen/Qwen3-235B-A22B-Instruct-2507" {
+		t.Errorf("modelID = %q, want %q", modelID, "Qwen/Qwen3-235B-A22B-Instruct-2507")
+	}
+	if _, ok := provider.(*HTTPProvider); !ok {
+		t.Fatalf("expected *HTTPProvider, got %T", provider)
+	}
+}
+
+func TestGetDefaultAPIBase_ModelScope(t *testing.T) {
+	if got := getDefaultAPIBase("modelscope"); got != "https://api-inference.modelscope.cn/v1" {
+		t.Fatalf("getDefaultAPIBase(%q) = %q, want %q", "modelscope", got, "https://api-inference.modelscope.cn/v1")
+	}
+}
+
+func TestCreateProviderFromConfig_Novita(t *testing.T) {
+	cfg := &config.ModelConfig{
+		ModelName: "test-novita",
+		Model:     "novita/deepseek/deepseek-v3.2",
+	}
+	cfg.SetAPIKey("test-key")
+
+	provider, modelID, err := CreateProviderFromConfig(cfg)
+	if err != nil {
+		t.Fatalf("CreateProviderFromConfig() error = %v", err)
+	}
+	if provider == nil {
+		t.Fatal("CreateProviderFromConfig() returned nil provider")
+	}
+	if modelID != "deepseek/deepseek-v3.2" {
+		t.Errorf("modelID = %q, want %q", modelID, "deepseek/deepseek-v3.2")
+	}
+	if _, ok := provider.(*HTTPProvider); !ok {
+		t.Fatalf("expected *HTTPProvider, got %T", provider)
+	}
+}
+
+func TestGetDefaultAPIBase_Novita(t *testing.T) {
+	if got := getDefaultAPIBase("novita"); got != "https://api.novita.ai/openai" {
+		t.Fatalf("getDefaultAPIBase(%q) = %q, want %q", "novita", got, "https://api.novita.ai/openai")
+	}
+}
+
 func TestCreateProviderFromConfig_Anthropic(t *testing.T) {
 	cfg := &config.ModelConfig{
 		ModelName: "test-anthropic",
 		Model:     "anthropic/claude-sonnet-4.6",
-		APIKey:    "test-key",
 	}
+	cfg.SetAPIKey("test-key")
 
 	provider, modelID, err := CreateProviderFromConfig(cfg)
 	if err != nil {
@@ -224,8 +341,8 @@ func TestCreateProviderFromConfig_UnknownProtocol(t *testing.T) {
 	cfg := &config.ModelConfig{
 		ModelName: "test-unknown",
 		Model:     "unknown-protocol/model",
-		APIKey:    "test-key",
 	}
+	cfg.SetAPIKey("test-key")
 
 	_, _, err := CreateProviderFromConfig(cfg)
 	if err == nil {
@@ -266,6 +383,7 @@ func TestCreateProviderFromConfig_RequestTimeoutPropagation(t *testing.T) {
 		APIBase:        server.URL,
 		RequestTimeout: 1,
 	}
+	cfg.SetAPIKey("test-key")
 
 	provider, modelID, err := CreateProviderFromConfig(cfg)
 	if err != nil {
@@ -290,3 +408,370 @@ func TestCreateProviderFromConfig_RequestTimeoutPropagation(t *testing.T) {
 		t.Fatalf("Chat() error = %q, want timeout-related error", errMsg)
 	}
 }
+
+func TestCreateProviderFromConfig_Azure(t *testing.T) {
+	cfg := &config.ModelConfig{
+		ModelName: "azure-gpt5",
+		Model:     "azure/my-gpt5-deployment",
+		APIBase:   "https://my-resource.openai.azure.com",
+	}
+	cfg.SetAPIKey("test-azure-key")
+
+	provider, modelID, err := CreateProviderFromConfig(cfg)
+	if err != nil {
+		t.Fatalf("CreateProviderFromConfig() error = %v", err)
+	}
+	if provider == nil {
+		t.Fatal("CreateProviderFromConfig() returned nil provider")
+	}
+	if modelID != "my-gpt5-deployment" {
+		t.Errorf("modelID = %q, want %q", modelID, "my-gpt5-deployment")
+	}
+}
+
+func TestCreateProviderFromConfig_AzureOpenAIAlias(t *testing.T) {
+	cfg := &config.ModelConfig{
+		ModelName: "azure-gpt4",
+		Model:     "azure-openai/my-deployment",
+		APIBase:   "https://my-resource.openai.azure.com",
+	}
+	cfg.SetAPIKey("test-azure-key")
+
+	provider, modelID, err := CreateProviderFromConfig(cfg)
+	if err != nil {
+		t.Fatalf("CreateProviderFromConfig() error = %v", err)
+	}
+	if provider == nil {
+		t.Fatal("CreateProviderFromConfig() returned nil provider")
+	}
+	if modelID != "my-deployment" {
+		t.Errorf("modelID = %q, want %q", modelID, "my-deployment")
+	}
+}
+
+func TestCreateProviderFromConfig_AzureMissingAPIKey(t *testing.T) {
+	cfg := &config.ModelConfig{
+		ModelName: "azure-gpt5",
+		Model:     "azure/my-gpt5-deployment",
+		APIBase:   "https://my-resource.openai.azure.com",
+	}
+
+	_, _, err := CreateProviderFromConfig(cfg)
+	if err == nil {
+		t.Fatal("CreateProviderFromConfig() expected error for missing API key")
+	}
+}
+
+func TestCreateProviderFromConfig_AzureMissingAPIBase(t *testing.T) {
+	cfg := &config.ModelConfig{
+		ModelName: "azure-gpt5",
+		Model:     "azure/my-gpt5-deployment",
+	}
+	cfg.SetAPIKey("test-azure-key")
+
+	_, _, err := CreateProviderFromConfig(cfg)
+	if err == nil {
+		t.Fatal("CreateProviderFromConfig() expected error for missing API base")
+	}
+}
+
+func TestCreateProviderFromConfig_QwenInternationalAlias(t *testing.T) {
+	tests := []struct {
+		name     string
+		protocol string
+	}{
+		{"qwen-international", "qwen-international"},
+		{"dashscope-intl", "dashscope-intl"},
+		{"qwen-intl", "qwen-intl"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := &config.ModelConfig{
+				ModelName: "test-" + tt.protocol,
+				Model:     tt.protocol + "/qwen-max",
+			}
+			cfg.SetAPIKey("test-key")
+
+			provider, modelID, err := CreateProviderFromConfig(cfg)
+			if err != nil {
+				t.Fatalf("CreateProviderFromConfig() error = %v", err)
+			}
+			if provider == nil {
+				t.Fatal("CreateProviderFromConfig() returned nil provider")
+			}
+			if modelID != "qwen-max" {
+				t.Errorf("modelID = %q, want %q", modelID, "qwen-max")
+			}
+			if _, ok := provider.(*HTTPProvider); !ok {
+				t.Fatalf("expected *HTTPProvider, got %T", provider)
+			}
+		})
+	}
+}
+
+func TestCreateProviderFromConfig_QwenUSAlias(t *testing.T) {
+	tests := []struct {
+		name     string
+		protocol string
+	}{
+		{"qwen-us", "qwen-us"},
+		{"dashscope-us", "dashscope-us"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := &config.ModelConfig{
+				ModelName: "test-" + tt.protocol,
+				Model:     tt.protocol + "/qwen-max",
+			}
+			cfg.SetAPIKey("test-key")
+
+			provider, modelID, err := CreateProviderFromConfig(cfg)
+			if err != nil {
+				t.Fatalf("CreateProviderFromConfig() error = %v", err)
+			}
+			if provider == nil {
+				t.Fatal("CreateProviderFromConfig() returned nil provider")
+			}
+			if modelID != "qwen-max" {
+				t.Errorf("modelID = %q, want %q", modelID, "qwen-max")
+			}
+			if _, ok := provider.(*HTTPProvider); !ok {
+				t.Fatalf("expected *HTTPProvider, got %T", provider)
+			}
+		})
+	}
+}
+
+func TestCreateProviderFromConfig_CodingPlanAnthropic(t *testing.T) {
+	tests := []struct {
+		name     string
+		protocol string
+	}{
+		{"coding-plan-anthropic", "coding-plan-anthropic"},
+		{"alibaba-coding-anthropic", "alibaba-coding-anthropic"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cfg := &config.ModelConfig{
+				ModelName: "test-" + tt.protocol,
+				Model:     tt.protocol + "/claude-sonnet-4-20250514",
+			}
+			cfg.SetAPIKey("test-key")
+
+			provider, modelID, err := CreateProviderFromConfig(cfg)
+			if err != nil {
+				t.Fatalf("CreateProviderFromConfig() error = %v", err)
+			}
+			if provider == nil {
+				t.Fatal("CreateProviderFromConfig() returned nil provider")
+			}
+			if modelID != "claude-sonnet-4-20250514" {
+				t.Errorf("modelID = %q, want %q", modelID, "claude-sonnet-4-20250514")
+			}
+			// coding-plan-anthropic uses Anthropic Messages provider
+			// Verify it's the anthropic messages provider by checking interface
+			var _ LLMProvider = provider
+		})
+	}
+}
+
+func TestGetDefaultAPIBase_CodingPlanAnthropic(t *testing.T) {
+	expectedURL := "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic"
+	if got := getDefaultAPIBase("coding-plan-anthropic"); got != expectedURL {
+		t.Fatalf("getDefaultAPIBase(%q) = %q, want %q", "coding-plan-anthropic", got, expectedURL)
+	}
+	if got := getDefaultAPIBase("alibaba-coding-anthropic"); got != expectedURL {
+		t.Fatalf("getDefaultAPIBase(%q) = %q, want %q", "alibaba-coding-anthropic", got, expectedURL)
+	}
+}
+
+func TestGetDefaultAPIBase_QwenIntlAliases(t *testing.T) {
+	expectedURL := "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
+	for _, protocol := range []string{"qwen-intl", "qwen-international", "dashscope-intl"} {
+		if got := getDefaultAPIBase(protocol); got != expectedURL {
+			t.Fatalf("getDefaultAPIBase(%q) = %q, want %q", protocol, got, expectedURL)
+		}
+	}
+}
+
+func TestGetDefaultAPIBase_QwenUSAliases(t *testing.T) {
+	expectedURL := "https://dashscope-us.aliyuncs.com/compatible-mode/v1"
+	for _, protocol := range []string{"qwen-us", "dashscope-us"} {
+		if got := getDefaultAPIBase(protocol); got != expectedURL {
+			t.Fatalf("getDefaultAPIBase(%q) = %q, want %q", protocol, got, expectedURL)
+		}
+	}
+}
+
+func TestCreateProviderFromConfig_MinimaxInjectsReasoningSplit(t *testing.T) {
+	var requestBody map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"},"finish_reason":"stop"}]}`))
+	}))
+	defer server.Close()
+
+	cfg := &config.ModelConfig{
+		ModelName: "test-minimax",
+		Model:     "minimax/MiniMax-M2.5",
+		APIBase:   server.URL,
+	}
+	cfg.SetAPIKey("test-key")
+
+	provider, modelID, err := CreateProviderFromConfig(cfg)
+	if err != nil {
+		t.Fatalf("CreateProviderFromConfig() error = %v", err)
+	}
+	if provider == nil {
+		t.Fatal("CreateProviderFromConfig() returned nil provider")
+	}
+	if modelID != "MiniMax-M2.5" {
+		t.Errorf("modelID = %q, want %q", modelID, "MiniMax-M2.5")
+	}
+
+	_, err = provider.Chat(
+		t.Context(),
+		[]Message{{Role: "user", Content: "hi"}},
+		nil,
+		modelID,
+		nil,
+	)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	// Verify reasoning_split is automatically injected
+	if got, ok := requestBody["reasoning_split"]; !ok || got != true {
+		t.Fatalf("reasoning_split = %v, want true", got)
+	}
+}
+
+func TestCreateProviderFromConfig_MinimaxPreservesUserExtraBody(t *testing.T) {
+	var requestBody map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"},"finish_reason":"stop"}]}`))
+	}))
+	defer server.Close()
+
+	cfg := &config.ModelConfig{
+		ModelName: "test-minimax-custom",
+		Model:     "minimax/MiniMax-M2.5",
+		APIBase:   server.URL,
+		ExtraBody: map[string]any{"custom_field": "test"},
+	}
+	cfg.SetAPIKey("test-key")
+
+	provider, modelID, err := CreateProviderFromConfig(cfg)
+	if err != nil {
+		t.Fatalf("CreateProviderFromConfig() error = %v", err)
+	}
+
+	_, err = provider.Chat(
+		t.Context(),
+		[]Message{{Role: "user", Content: "hi"}},
+		nil,
+		modelID,
+		nil,
+	)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	// Verify reasoning_split is automatically injected
+	if got, ok := requestBody["reasoning_split"]; !ok || got != true {
+		t.Fatalf("reasoning_split = %v, want true", got)
+	}
+	// Verify user's custom field is preserved
+	if got, ok := requestBody["custom_field"]; !ok || got != "test" {
+		t.Fatalf("custom_field = %v, want test", got)
+	}
+}
+
+func TestCreateProviderFromConfig_Bedrock(t *testing.T) {
+	// Set dummy AWS env vars to make test deterministic
+	t.Setenv("AWS_ACCESS_KEY_ID", "test-key")
+	t.Setenv("AWS_SECRET_ACCESS_KEY", "test-secret")
+	t.Setenv("AWS_EC2_METADATA_DISABLED", "true")
+	// Clear profile-related env vars to avoid loading shared config
+	t.Setenv("AWS_PROFILE", "")
+	t.Setenv("AWS_DEFAULT_PROFILE", "")
+	t.Setenv("AWS_SDK_LOAD_CONFIG", "")
+	t.Setenv("AWS_SHARED_CREDENTIALS_FILE", "")
+
+	cfg := &config.ModelConfig{
+		ModelName: "bedrock-claude",
+		Model:     "bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0",
+		APIBase:   "us-west-2", // Region (also sets AWS region)
+	}
+
+	provider, modelID, err := CreateProviderFromConfig(cfg)
+	if err == nil {
+		// Provider created successfully (built with -tags bedrock)
+		if provider == nil {
+			t.Error("provider is nil on success")
+		}
+		if modelID != "us.anthropic.claude-sonnet-4-20250514-v1:0" {
+			t.Errorf("modelID = %q, want %q", modelID, "us.anthropic.claude-sonnet-4-20250514-v1:0")
+		}
+		return
+	}
+	errMsg := err.Error()
+	// When built without -tags bedrock, expect stub error
+	if strings.Contains(errMsg, "build with -tags bedrock") {
+		return // Expected stub error
+	}
+	// Unexpected error - fail the test
+	t.Errorf("unexpected error from bedrock provider: %v", err)
+}
+
+func TestCreateProviderFromConfig_BedrockWithEndpointURL(t *testing.T) {
+	// Set dummy AWS env vars to make test deterministic
+	t.Setenv("AWS_ACCESS_KEY_ID", "test-key")
+	t.Setenv("AWS_SECRET_ACCESS_KEY", "test-secret")
+	t.Setenv("AWS_REGION", "us-east-1") // Required when using endpoint URL
+	t.Setenv("AWS_EC2_METADATA_DISABLED", "true")
+	// Clear profile-related env vars to avoid loading shared config
+	t.Setenv("AWS_PROFILE", "")
+	t.Setenv("AWS_DEFAULT_PROFILE", "")
+	t.Setenv("AWS_SDK_LOAD_CONFIG", "")
+	t.Setenv("AWS_SHARED_CREDENTIALS_FILE", "")
+
+	cfg := &config.ModelConfig{
+		ModelName: "bedrock-claude",
+		Model:     "bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0",
+		APIBase:   "https://bedrock-runtime.us-east-1.amazonaws.com", // Full endpoint URL
+	}
+
+	provider, modelID, err := CreateProviderFromConfig(cfg)
+	if err == nil {
+		// Provider created successfully (built with -tags bedrock)
+		if provider == nil {
+			t.Error("provider is nil on success")
+		}
+		if modelID != "us.anthropic.claude-sonnet-4-20250514-v1:0" {
+			t.Errorf("modelID = %q, want %q", modelID, "us.anthropic.claude-sonnet-4-20250514-v1:0")
+		}
+		return
+	}
+	errMsg := err.Error()
+	// When built without -tags bedrock, expect stub error
+	if strings.Contains(errMsg, "build with -tags bedrock") {
+		return // Expected stub error
+	}
+	// Unexpected error - fail the test
+	t.Errorf("unexpected error from bedrock provider: %v", err)
+}
diff --git a/pkg/providers/factory_test.go b/pkg/providers/factory_test.go
index 5680f23b3..b99f5baf9 100644
--- a/pkg/providers/factory_test.go
+++ b/pkg/providers/factory_test.go
@@ -1,210 +1,22 @@
 package providers
 
 import (
-	"strings"
 	"testing"
 
 	"github.com/sipeed/picoclaw/pkg/auth"
 	"github.com/sipeed/picoclaw/pkg/config"
 )
 
-func TestResolveProviderSelection(t *testing.T) {
-	tests := []struct {
-		name          string
-		setup         func(*config.Config)
-		wantType      providerType
-		wantAPIBase   string
-		wantProxy     string
-		wantErrSubstr string
-	}{
-		{
-			name: "explicit claude-cli provider routes to cli provider type",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Provider = "claude-cli"
-				cfg.Agents.Defaults.Workspace = "/tmp/ws"
-			},
-			wantType: providerTypeClaudeCLI,
-		},
-		{
-			name: "explicit copilot provider routes to github copilot type",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Provider = "copilot"
-			},
-			wantType:    providerTypeGitHubCopilot,
-			wantAPIBase: "localhost:4321",
-		},
-		{
-			name: "explicit deepseek provider uses deepseek defaults",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Provider = "deepseek"
-				cfg.Agents.Defaults.Model = "deepseek/deepseek-chat"
-				cfg.Providers.DeepSeek.APIKey = "deepseek-key"
-				cfg.Providers.DeepSeek.Proxy = "http://127.0.0.1:7890"
-			},
-			wantType:    providerTypeHTTPCompat,
-			wantAPIBase: "https://api.deepseek.com/v1",
-			wantProxy:   "http://127.0.0.1:7890",
-		},
-		{
-			name: "explicit shengsuanyun provider uses defaults",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Provider = "shengsuanyun"
-				cfg.Providers.ShengSuanYun.APIKey = "ssy-key"
-				cfg.Providers.ShengSuanYun.Proxy = "http://127.0.0.1:7890"
-			},
-			wantType:    providerTypeHTTPCompat,
-			wantAPIBase: "https://router.shengsuanyun.com/api/v1",
-			wantProxy:   "http://127.0.0.1:7890",
-		},
-		{
-			name: "explicit nvidia provider uses defaults",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Provider = "nvidia"
-				cfg.Providers.Nvidia.APIKey = "nvapi-test"
-				cfg.Providers.Nvidia.Proxy = "http://127.0.0.1:7890"
-			},
-			wantType:    providerTypeHTTPCompat,
-			wantAPIBase: "https://integrate.api.nvidia.com/v1",
-			wantProxy:   "http://127.0.0.1:7890",
-		},
-		{
-			name: "openrouter model uses openrouter defaults",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Model = "openrouter/auto"
-				cfg.Providers.OpenRouter.APIKey = "sk-or-test"
-			},
-			wantType:    providerTypeHTTPCompat,
-			wantAPIBase: "https://openrouter.ai/api/v1",
-		},
-		{
-			name: "anthropic oauth routes to claude auth provider",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Model = "claude-sonnet-4.6"
-				cfg.Providers.Anthropic.AuthMethod = "oauth"
-			},
-			wantType: providerTypeClaudeAuth,
-		},
-		{
-			name: "openai oauth routes to codex auth provider",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Model = "gpt-4o"
-				cfg.Providers.OpenAI.AuthMethod = "oauth"
-			},
-			wantType: providerTypeCodexAuth,
-		},
-		{
-			name: "openai codex-cli auth routes to codex cli token provider",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Model = "gpt-4o"
-				cfg.Providers.OpenAI.AuthMethod = "codex-cli"
-			},
-			wantType: providerTypeCodexCLIToken,
-		},
-		{
-			name: "explicit codex-code provider routes to codex cli provider type",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Provider = "codex-code"
-				cfg.Agents.Defaults.Workspace = "/tmp/ws"
-			},
-			wantType: providerTypeCodexCLI,
-		},
-		{
-			name: "zhipu model uses zhipu base default",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Model = "glm-4.7"
-				cfg.Providers.Zhipu.APIKey = "zhipu-key"
-			},
-			wantType:    providerTypeHTTPCompat,
-			wantAPIBase: "https://open.bigmodel.cn/api/paas/v4",
-		},
-		{
-			name: "groq model uses groq base default",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Model = "groq/llama-3.3-70b"
-				cfg.Providers.Groq.APIKey = "gsk-key"
-			},
-			wantType:    providerTypeHTTPCompat,
-			wantAPIBase: "https://api.groq.com/openai/v1",
-		},
-		{
-			name: "ollama model uses ollama base default",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Model = "ollama/qwen2.5:14b"
-				cfg.Providers.Ollama.APIKey = "ollama-key"
-			},
-			wantType:    providerTypeHTTPCompat,
-			wantAPIBase: "http://localhost:11434/v1",
-		},
-		{
-			name: "moonshot model keeps proxy and default base",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Model = "moonshot/kimi-k2.5"
-				cfg.Providers.Moonshot.APIKey = "moonshot-key"
-				cfg.Providers.Moonshot.Proxy = "http://127.0.0.1:7890"
-			},
-			wantType:    providerTypeHTTPCompat,
-			wantAPIBase: "https://api.moonshot.cn/v1",
-			wantProxy:   "http://127.0.0.1:7890",
-		},
-		{
-			name: "missing keys returns model config error",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Model = "custom-model"
-			},
-			wantErrSubstr: "no API key configured for model",
-		},
-		{
-			name: "openrouter prefix without key returns provider key error",
-			setup: func(cfg *config.Config) {
-				cfg.Agents.Defaults.Model = "openrouter/auto"
-			},
-			wantErrSubstr: "no API key configured for provider",
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			cfg := config.DefaultConfig()
-			tt.setup(cfg)
-
-			got, err := resolveProviderSelection(cfg)
-			if tt.wantErrSubstr != "" {
-				if err == nil {
-					t.Fatalf("expected error containing %q, got nil", tt.wantErrSubstr)
-				}
-				if !strings.Contains(err.Error(), tt.wantErrSubstr) {
-					t.Fatalf("error = %q, want substring %q", err.Error(), tt.wantErrSubstr)
-				}
-				return
-			}
-
-			if err != nil {
-				t.Fatalf("resolveProviderSelection() error = %v", err)
-			}
-			if got.providerType != tt.wantType {
-				t.Fatalf("providerType = %v, want %v", got.providerType, tt.wantType)
-			}
-			if tt.wantAPIBase != "" && got.apiBase != tt.wantAPIBase {
-				t.Fatalf("apiBase = %q, want %q", got.apiBase, tt.wantAPIBase)
-			}
-			if tt.wantProxy != "" && got.proxy != tt.wantProxy {
-				t.Fatalf("proxy = %q, want %q", got.proxy, tt.wantProxy)
-			}
-		})
-	}
-}
-
 func TestCreateProviderReturnsHTTPProviderForOpenRouter(t *testing.T) {
 	cfg := config.DefaultConfig()
-	cfg.Agents.Defaults.Model = "test-openrouter"
-	cfg.ModelList = []config.ModelConfig{
-		{
-			ModelName: "test-openrouter",
-			Model:     "openrouter/auto",
-			APIKey:    "sk-or-test",
-			APIBase:   "https://openrouter.ai/api/v1",
-		},
+	cfg.Agents.Defaults.ModelName = "test-openrouter"
+	modelCfg := &config.ModelConfig{
+		ModelName: "test-openrouter",
+		Model:     "openrouter/auto",
+		APIBase:   "https://openrouter.ai/api/v1",
 	}
+	modelCfg.SetAPIKey("sk-or-test")
+	cfg.ModelList = []*config.ModelConfig{modelCfg}
 
 	provider, _, err := CreateProvider(cfg)
 	if err != nil {
@@ -218,8 +30,8 @@ func TestCreateProviderReturnsHTTPProviderForOpenRouter(t *testing.T) {
 
 func TestCreateProviderReturnsCodexCliProviderForCodexCode(t *testing.T) {
 	cfg := config.DefaultConfig()
-	cfg.Agents.Defaults.Model = "test-codex"
-	cfg.ModelList = []config.ModelConfig{
+	cfg.Agents.Defaults.ModelName = "test-codex"
+	cfg.ModelList = []*config.ModelConfig{
 		{
 			ModelName: "test-codex",
 			Model:     "codex-cli/codex-model",
@@ -239,8 +51,8 @@ func TestCreateProviderReturnsCodexCliProviderForCodexCode(t *testing.T) {
 
 func TestCreateProviderReturnsClaudeCliProviderForClaudeCli(t *testing.T) {
 	cfg := config.DefaultConfig()
-	cfg.Agents.Defaults.Model = "test-claude-cli"
-	cfg.ModelList = []config.ModelConfig{
+	cfg.Agents.Defaults.ModelName = "test-claude-cli"
+	cfg.ModelList = []*config.ModelConfig{
 		{
 			ModelName: "test-claude-cli",
 			Model:     "claude-cli/claude-sonnet",
@@ -272,8 +84,8 @@ func TestCreateProviderReturnsClaudeProviderForAnthropicOAuth(t *testing.T) {
 	}
 
 	cfg := config.DefaultConfig()
-	cfg.Agents.Defaults.Model = "test-claude-oauth"
-	cfg.ModelList = []config.ModelConfig{
+	cfg.Agents.Defaults.ModelName = "test-claude-oauth"
+	cfg.ModelList = []*config.ModelConfig{
 		{
 			ModelName:  "test-claude-oauth",
 			Model:      "anthropic/claude-sonnet-4.6",
diff --git a/pkg/providers/fallback.go b/pkg/providers/fallback.go
index 7ba563b66..549ec7837 100644
--- a/pkg/providers/fallback.go
+++ b/pkg/providers/fallback.go
@@ -117,17 +117,19 @@ func (fc *FallbackChain) Execute(
 			return nil, context.Canceled
 		}
 
-		// Check cooldown.
-		if !fc.cooldown.IsAvailable(candidate.Provider) {
-			remaining := fc.cooldown.CooldownRemaining(candidate.Provider)
+		// Check cooldown (per provider/model, not just provider).
+		// This allows multi-key failover where different keys use different model names.
+		cooldownKey := ModelKey(candidate.Provider, candidate.Model)
+		if !fc.cooldown.IsAvailable(cooldownKey) {
+			remaining := fc.cooldown.CooldownRemaining(cooldownKey)
 			result.Attempts = append(result.Attempts, FallbackAttempt{
 				Provider: candidate.Provider,
 				Model:    candidate.Model,
 				Skipped:  true,
 				Reason:   FailoverRateLimit,
 				Error: fmt.Errorf(
-					"provider %s in cooldown (%s remaining)",
-					candidate.Provider,
+					"%s in cooldown (%s remaining)",
+					cooldownKey,
 					remaining.Round(time.Second),
 				),
 			})
@@ -141,7 +143,7 @@ func (fc *FallbackChain) Execute(
 
 		if err == nil {
 			// Success.
-			fc.cooldown.MarkSuccess(candidate.Provider)
+			fc.cooldown.MarkSuccess(cooldownKey)
 			result.Response = resp
 			result.Provider = candidate.Provider
 			result.Model = candidate.Model
@@ -187,7 +189,7 @@ func (fc *FallbackChain) Execute(
 		}
 
 		// Retriable error: mark failure and continue to next candidate.
-		fc.cooldown.MarkFailure(candidate.Provider, failErr.Reason)
+		fc.cooldown.MarkFailure(cooldownKey, failErr.Reason)
 		result.Attempts = append(result.Attempts, FallbackAttempt{
 			Provider: candidate.Provider,
 			Model:    candidate.Model,
diff --git a/pkg/providers/fallback_multikey_test.go b/pkg/providers/fallback_multikey_test.go
new file mode 100644
index 000000000..9ed8fa73c
--- /dev/null
+++ b/pkg/providers/fallback_multikey_test.go
@@ -0,0 +1,384 @@
+package providers
+
+import (
+	"context"
+	"errors"
+	"testing"
+)
+
+// TestMultiKeyFailover tests the complete failover flow with multiple API keys.
+// This simulates the config expansion scenario where api_keys: ["key1", "key2", "key3"]
+// is expanded into primary + fallbacks.
+func TestMultiKeyFailover(t *testing.T) {
+	// Simulate expanded config: primary with 2 fallbacks
+	// This is what ExpandMultiKeyModels would produce for api_keys: ["key1", "key2", "key3"]
+	cfg := ModelConfig{
+		Primary:   "glm-4.7",
+		Fallbacks: []string{"glm-4.7__key_1", "glm-4.7__key_2"},
+	}
+
+	candidates := ResolveCandidates(cfg, "zhipu")
+
+	if len(candidates) != 3 {
+		t.Fatalf("expected 3 candidates, got %d: %v", len(candidates), candidates)
+	}
+
+	// Create fallback chain
+	cooldown := NewCooldownTracker()
+	chain := NewFallbackChain(cooldown)
+
+	// Mock run function: first call fails with 429, second succeeds
+	callCount := 0
+	mockRun := func(ctx context.Context, provider, model string) (*LLMResponse, error) {
+		callCount++
+		if callCount == 1 {
+			// First call: simulate rate limit
+			return nil, errors.New("http error: status 429 - rate limit exceeded")
+		}
+		// Second call: success
+		return &LLMResponse{
+			Content: "Hello from key2!",
+		}, nil
+	}
+
+	// Execute fallback chain
+	result, err := chain.Execute(context.Background(), candidates, mockRun)
+	if err != nil {
+		t.Fatalf("expected success after failover, got error: %v", err)
+	}
+
+	if result == nil {
+		t.Fatal("expected result, got nil")
+	}
+
+	if result.Response.Content != "Hello from key2!" {
+		t.Errorf("expected response from key2, got: %s", result.Response.Content)
+	}
+
+	if callCount != 2 {
+		t.Errorf("expected 2 calls (1 fail + 1 success), got %d", callCount)
+	}
+
+	// Verify first attempt was recorded
+	if len(result.Attempts) != 1 {
+		t.Errorf("expected 1 failed attempt recorded, got %d", len(result.Attempts))
+	}
+
+	if result.Attempts[0].Reason != FailoverRateLimit {
+		t.Errorf(
+			"expected first attempt reason to be rate_limit, got: %s",
+			result.Attempts[0].Reason,
+		)
+	}
+}
+
+// TestMultiKeyFailoverAllFail tests when all keys hit rate limit
+func TestMultiKeyFailoverAllFail(t *testing.T) {
+	cfg := ModelConfig{
+		Primary:   "glm-4.7",
+		Fallbacks: []string{"glm-4.7__key_1", "glm-4.7__key_2"},
+	}
+
+	candidates := ResolveCandidates(cfg, "zhipu")
+
+	cooldown := NewCooldownTracker()
+	chain := NewFallbackChain(cooldown)
+
+	// Mock run function: all calls fail with rate limit
+	callCount := 0
+	mockRun := func(ctx context.Context, provider, model string) (*LLMResponse, error) {
+		callCount++
+		return nil, errors.New("status: 429 - too many requests")
+	}
+
+	// Execute fallback chain
+	result, err := chain.Execute(context.Background(), candidates, mockRun)
+
+	if err == nil {
+		t.Fatal("expected error when all keys fail, got nil")
+	}
+
+	if result != nil {
+		t.Errorf("expected nil result on failure, got: %v", result)
+	}
+
+	if callCount != 3 {
+		t.Errorf("expected 3 calls (all fail), got %d", callCount)
+	}
+
+	// Verify error type
+	var exhausted *FallbackExhaustedError
+	if !errors.As(err, &exhausted) {
+		t.Errorf("expected FallbackExhaustedError, got: %T - %v", err, err)
+	}
+
+	if len(exhausted.Attempts) != 3 {
+		t.Errorf("expected 3 attempts in exhausted error, got %d", len(exhausted.Attempts))
+	}
+}
+
+// TestMultiKeyFailoverCooldown tests that a key in cooldown is skipped
+func TestMultiKeyFailoverCooldown(t *testing.T) {
+	cfg := ModelConfig{
+		Primary:   "glm-4.7",
+		Fallbacks: []string{"glm-4.7__key_1"},
+	}
+
+	candidates := ResolveCandidates(cfg, "zhipu")
+
+	cooldown := NewCooldownTracker()
+	chain := NewFallbackChain(cooldown)
+
+	// Put the first model in cooldown (using ModelKey now, not just provider)
+	cooldownKey := ModelKey(candidates[0].Provider, candidates[0].Model)
+	cooldown.MarkFailure(cooldownKey, FailoverRateLimit)
+
+	// Verify it's not available
+	if cooldown.IsAvailable(cooldownKey) {
+		t.Fatal("expected first model to be in cooldown")
+	}
+
+	// Mock run function: only second should be called
+	callCount := 0
+	calledProviders := []string{}
+	mockRun := func(ctx context.Context, provider, model string) (*LLMResponse, error) {
+		callCount++
+		calledProviders = append(calledProviders, provider+"/"+model)
+		return &LLMResponse{Content: "success"}, nil
+	}
+
+	result, err := chain.Execute(context.Background(), candidates, mockRun)
+	if err != nil {
+		t.Fatalf("expected success, got error: %v", err)
+	}
+
+	// First provider should have been skipped
+	if callCount != 1 {
+		t.Errorf("expected 1 call (first skipped due to cooldown), got %d", callCount)
+	}
+
+	// Should have called the second provider/model
+	if len(calledProviders) != 1 ||
+		calledProviders[0] != candidates[1].Provider+"/"+candidates[1].Model {
+		t.Errorf("expected second model to be called, got: %v", calledProviders)
+	}
+
+	// Verify first attempt was recorded as skipped
+	if len(result.Attempts) != 1 {
+		t.Fatalf("expected 1 attempt (skipped), got %d", len(result.Attempts))
+	}
+
+	if !result.Attempts[0].Skipped {
+		t.Error("expected first attempt to be marked as skipped")
+	}
+}
+
+// TestMultiKeyFailoverWithFormatError tests that format errors are non-retriable
+func TestMultiKeyFailoverWithFormatError(t *testing.T) {
+	cfg := ModelConfig{
+		Primary:   "glm-4.7",
+		Fallbacks: []string{"glm-4.7__key_1"},
+	}
+
+	candidates := ResolveCandidates(cfg, "zhipu")
+
+	cooldown := NewCooldownTracker()
+	chain := NewFallbackChain(cooldown)
+
+	// Mock run function: first call fails with format error (bad request)
+	callCount := 0
+	mockRun := func(ctx context.Context, provider, model string) (*LLMResponse, error) {
+		callCount++
+		return nil, errors.New("invalid request format: tool_use.id missing")
+	}
+
+	// Execute fallback chain
+	result, err := chain.Execute(context.Background(), candidates, mockRun)
+
+	if err == nil {
+		t.Fatal("expected error for format failure, got nil")
+	}
+
+	// Format errors should NOT trigger failover (non-retriable)
+	// So we should only have 1 call
+	if callCount != 1 {
+		t.Errorf("expected 1 call (format error is non-retriable), got %d", callCount)
+	}
+
+	// Verify the error is a FailoverError with format reason
+	var failoverErr *FailoverError
+	if !errors.As(err, &failoverErr) {
+		t.Errorf("expected FailoverError, got: %T - %v", err, err)
+	}
+
+	if failoverErr.Reason != FailoverFormat {
+		t.Errorf("expected FailoverFormat reason, got: %s", failoverErr.Reason)
+	}
+
+	_ = result // result should be nil
+}
+
+// TestMultiKeyWithModelFallback tests multi-key failover combined with model fallback.
+// This simulates the scenario: api_keys: ["k1", "k2"] + fallbacks: ["minimax"]
+// Expected failover order: glm-4.7 (k1) → glm-4.7__key_1 (k2) → minimax
+func TestMultiKeyWithModelFallback(t *testing.T) {
+	// Simulate expanded config from:
+	// { "model_name": "glm-4.7", "api_keys": ["k1", "k2"], "fallbacks": ["minimax"] }
+	// After ExpandMultiKeyModels, primaryEntry.Fallbacks = ["glm-4.7__key_1", "minimax"]
+	// Note: In production, "minimax" would be resolved via model lookup to "minimax/minimax"
+	// In this test, we use the full format to avoid needing a lookup function.
+	cfg := ModelConfig{
+		Primary:   "glm-4.7",
+		Fallbacks: []string{"glm-4.7__key_1", "minimax/minimax"},
+	}
+
+	candidates := ResolveCandidates(cfg, "zhipu")
+
+	// Should have 3 candidates: glm-4.7 (zhipu), glm-4.7__key_1 (zhipu), minimax (minimax)
+	if len(candidates) != 3 {
+		t.Fatalf("expected 3 candidates, got %d: %v", len(candidates), candidates)
+	}
+
+	// Verify candidate order
+	if candidates[0].Model != "glm-4.7" || candidates[0].Provider != "zhipu" {
+		t.Errorf(
+			"expected first candidate to be zhipu/glm-4.7, got: %s/%s",
+			candidates[0].Provider,
+			candidates[0].Model,
+		)
+	}
+	if candidates[1].Model != "glm-4.7__key_1" || candidates[1].Provider != "zhipu" {
+		t.Errorf(
+			"expected second candidate to be zhipu/glm-4.7__key_1, got: %s/%s",
+			candidates[1].Provider,
+			candidates[1].Model,
+		)
+	}
+	if candidates[2].Model != "minimax" || candidates[2].Provider != "minimax" {
+		t.Errorf(
+			"expected third candidate to be minimax/minimax, got: %s/%s",
+			candidates[2].Provider,
+			candidates[2].Model,
+		)
+	}
+
+	cooldown := NewCooldownTracker()
+	chain := NewFallbackChain(cooldown)
+
+	// Mock run function: first two fail, third succeeds (model fallback)
+	callCount := 0
+	calledModels := []string{}
+	mockRun := func(ctx context.Context, provider, model string) (*LLMResponse, error) {
+		callCount++
+		calledModels = append(calledModels, provider+"/"+model)
+
+		switch callCount {
+		case 1:
+			// k1: rate limit
+			return nil, errors.New("status: 429 - rate limit")
+		case 2:
+			// k2: also rate limit (all zhipu keys exhausted)
+			return nil, errors.New("status: 429 - rate limit")
+		case 3:
+			// minimax: success
+			return &LLMResponse{Content: "success from minimax"}, nil
+		default:
+			return nil, errors.New("unexpected call")
+		}
+	}
+
+	result, err := chain.Execute(context.Background(), candidates, mockRun)
+	if err != nil {
+		t.Fatalf("expected success after failover to model fallback, got error: %v", err)
+	}
+
+	if callCount != 3 {
+		t.Errorf("expected 3 calls (k1 fail + k2 fail + minimax success), got %d", callCount)
+	}
+
+	if result.Response.Content != "success from minimax" {
+		t.Errorf("expected response from minimax, got: %s", result.Response.Content)
+	}
+
+	// Verify call order
+	if len(calledModels) != 3 {
+		t.Fatalf("expected 3 called models, got %d", len(calledModels))
+	}
+	if calledModels[0] != "zhipu/glm-4.7" {
+		t.Errorf("expected first call to zhipu/glm-4.7, got: %s", calledModels[0])
+	}
+	if calledModels[1] != "zhipu/glm-4.7__key_1" {
+		t.Errorf("expected second call to zhipu/glm-4.7__key_1, got: %s", calledModels[1])
+	}
+	if calledModels[2] != "minimax/minimax" {
+		t.Errorf("expected third call to minimax/minimax, got: %s", calledModels[2])
+	}
+
+	// Verify 2 failed attempts recorded
+	if len(result.Attempts) != 2 {
+		t.Errorf("expected 2 failed attempts, got %d", len(result.Attempts))
+	}
+
+	// Both should be rate limit
+	for i, attempt := range result.Attempts {
+		if attempt.Reason != FailoverRateLimit {
+			t.Errorf("expected attempt %d to be rate_limit, got: %s", i, attempt.Reason)
+		}
+	}
+}
+
+// TestMultiKeyFailoverMixedErrors tests failover with different error types
+func TestMultiKeyFailoverMixedErrors(t *testing.T) {
+	cfg := ModelConfig{
+		Primary:   "glm-4.7",
+		Fallbacks: []string{"glm-4.7__key_1", "glm-4.7__key_2"},
+	}
+
+	candidates := ResolveCandidates(cfg, "zhipu")
+
+	cooldown := NewCooldownTracker()
+	chain := NewFallbackChain(cooldown)
+
+	// Mock run function: different errors for each key
+	callCount := 0
+	mockRun := func(ctx context.Context, provider, model string) (*LLMResponse, error) {
+		callCount++
+		switch callCount {
+		case 1:
+			// First: rate limit (retriable)
+			return nil, errors.New("status: 429 - rate limit")
+		case 2:
+			// Second: timeout (retriable)
+			return nil, errors.New("context deadline exceeded")
+		case 3:
+			// Third: success
+			return &LLMResponse{Content: "success from key3"}, nil
+		default:
+			return nil, errors.New("unexpected call")
+		}
+	}
+
+	result, err := chain.Execute(context.Background(), candidates, mockRun)
+	if err != nil {
+		t.Fatalf("expected success after 2 failovers, got error: %v", err)
+	}
+
+	if callCount != 3 {
+		t.Errorf("expected 3 calls, got %d", callCount)
+	}
+
+	// Verify both failed attempts were recorded
+	if len(result.Attempts) != 2 {
+		t.Errorf("expected 2 failed attempts, got %d", len(result.Attempts))
+	}
+
+	// First should be rate limit
+	if result.Attempts[0].Reason != FailoverRateLimit {
+		t.Errorf("expected first attempt to be rate_limit, got: %s", result.Attempts[0].Reason)
+	}
+
+	// Second should be timeout
+	if result.Attempts[1].Reason != FailoverTimeout {
+		t.Errorf("expected second attempt to be timeout, got: %s", result.Attempts[1].Reason)
+	}
+}
diff --git a/pkg/providers/fallback_test.go b/pkg/providers/fallback_test.go
index 1783ebcb5..1a1118e33 100644
--- a/pkg/providers/fallback_test.go
+++ b/pkg/providers/fallback_test.go
@@ -157,8 +157,8 @@ func TestFallback_CooldownSkip(t *testing.T) {
 	ct, _ := newTestTracker(now)
 	fc := NewFallbackChain(ct)
 
-	// Put openai in cooldown
-	ct.MarkFailure("openai", FailoverRateLimit)
+	// Put openai/gpt-4 in cooldown (using ModelKey now)
+	ct.MarkFailure(ModelKey("openai", "gpt-4"), FailoverRateLimit)
 
 	candidates := []FallbackCandidate{
 		makeCandidate("openai", "gpt-4"),
@@ -195,9 +195,9 @@ func TestFallback_AllInCooldown(t *testing.T) {
 	ct := NewCooldownTracker()
 	fc := NewFallbackChain(ct)
 
-	// Put all providers in cooldown
-	ct.MarkFailure("openai", FailoverRateLimit)
-	ct.MarkFailure("anthropic", FailoverBilling)
+	// Put all models in cooldown (using ModelKey now)
+	ct.MarkFailure(ModelKey("openai", "gpt-4"), FailoverRateLimit)
+	ct.MarkFailure(ModelKey("anthropic", "claude"), FailoverBilling)
 
 	candidates := []FallbackCandidate{
 		makeCandidate("openai", "gpt-4"),
@@ -273,12 +273,13 @@ func TestFallback_SuccessResetsCooldown(t *testing.T) {
 	fc := NewFallbackChain(ct)
 
 	candidates := []FallbackCandidate{makeCandidate("openai", "gpt-4")}
+	modelKey := ModelKey("openai", "gpt-4")
 
 	attempt := 0
 	run := func(ctx context.Context, provider, model string) (*LLMResponse, error) {
 		attempt++
 		if attempt == 1 {
-			ct.MarkFailure("openai", FailoverRateLimit) // simulate failure tracked elsewhere
+			ct.MarkFailure(modelKey, FailoverRateLimit) // simulate failure tracked elsewhere
 		}
 		return &LLMResponse{Content: "ok", FinishReason: "stop"}, nil
 	}
@@ -287,7 +288,7 @@ func TestFallback_SuccessResetsCooldown(t *testing.T) {
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
 	}
-	if !ct.IsAvailable("openai") {
+	if !ct.IsAvailable(modelKey) {
 		t.Error("success should reset cooldown")
 	}
 }
diff --git a/pkg/providers/http_provider.go b/pkg/providers/http_provider.go
index 5c328f418..f2ff52f1d 100644
--- a/pkg/providers/http_provider.go
+++ b/pkg/providers/http_provider.go
@@ -24,12 +24,13 @@ func NewHTTPProvider(apiKey, apiBase, proxy string) *HTTPProvider {
 }
 
 func NewHTTPProviderWithMaxTokensField(apiKey, apiBase, proxy, maxTokensField string) *HTTPProvider {
-	return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(apiKey, apiBase, proxy, maxTokensField, 0)
+	return NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(apiKey, apiBase, proxy, maxTokensField, 0, nil)
 }
 
 func NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
 	apiKey, apiBase, proxy, maxTokensField string,
 	requestTimeoutSeconds int,
+	extraBody map[string]any,
 ) *HTTPProvider {
 	return &HTTPProvider{
 		delegate: openai_compat.NewProvider(
@@ -38,6 +39,7 @@ func NewHTTPProviderWithMaxTokensFieldAndRequestTimeout(
 			proxy,
 			openai_compat.WithMaxTokensField(maxTokensField),
 			openai_compat.WithRequestTimeout(time.Duration(requestTimeoutSeconds)*time.Second),
+			openai_compat.WithExtraBody(extraBody),
 		),
 	}
 }
@@ -52,6 +54,23 @@ func (p *HTTPProvider) Chat(
 	return p.delegate.Chat(ctx, messages, tools, model, options)
 }
 
+// ChatStream implements providers.StreamingProvider by delegating to the
+// OpenAI-compatible streaming endpoint (SSE with stream: true).
+func (p *HTTPProvider) ChatStream(
+	ctx context.Context,
+	messages []Message,
+	tools []ToolDefinition,
+	model string,
+	options map[string]any,
+	onChunk func(accumulated string),
+) (*LLMResponse, error) {
+	return p.delegate.ChatStream(ctx, messages, tools, model, options, onChunk)
+}
+
 func (p *HTTPProvider) GetDefaultModel() string {
 	return ""
 }
+
+func (p *HTTPProvider) SupportsNativeSearch() bool {
+	return p.delegate.SupportsNativeSearch()
+}
diff --git a/pkg/providers/legacy_provider.go b/pkg/providers/legacy_provider.go
index 26905159f..4b0815dd4 100644
--- a/pkg/providers/legacy_provider.go
+++ b/pkg/providers/legacy_provider.go
@@ -18,23 +18,6 @@ import (
 func CreateProvider(cfg *config.Config) (LLMProvider, string, error) {
 	model := cfg.Agents.Defaults.GetModelName()
 
-	// Ensure model_list is populated from providers config if needed
-	// This handles two cases:
-	// 1. ModelList is empty - convert all providers
-	// 2. ModelList has some entries but not all providers - merge missing ones
-	if cfg.HasProvidersConfig() {
-		providerModels := config.ConvertProvidersToModelList(cfg)
-		existingModelNames := make(map[string]bool)
-		for _, m := range cfg.ModelList {
-			existingModelNames[m.ModelName] = true
-		}
-		for _, pm := range providerModels {
-			if !existingModelNames[pm.ModelName] {
-				cfg.ModelList = append(cfg.ModelList, pm)
-			}
-		}
-	}
-
 	// Must have model_list at this point
 	if len(cfg.ModelList) == 0 {
 		return nil, "", fmt.Errorf("no providers configured. Please add entries to model_list in your config")
diff --git a/pkg/providers/model_ref.go b/pkg/providers/model_ref.go
index 0d1b02d16..be9f63bc6 100644
--- a/pkg/providers/model_ref.go
+++ b/pkg/providers/model_ref.go
@@ -53,6 +53,14 @@ func NormalizeProvider(provider string) string {
 		return "zhipu"
 	case "google":
 		return "gemini"
+	case "alibaba-coding", "qwen-coding":
+		return "coding-plan"
+	case "alibaba-coding-anthropic":
+		return "coding-plan-anthropic"
+	case "qwen-international", "dashscope-intl":
+		return "qwen-intl"
+	case "dashscope-us":
+		return "qwen-us"
 	}
 
 	return p
diff --git a/pkg/providers/model_ref_test.go b/pkg/providers/model_ref_test.go
index 6dd25167f..040c511ba 100644
--- a/pkg/providers/model_ref_test.go
+++ b/pkg/providers/model_ref_test.go
@@ -73,6 +73,14 @@ func TestNormalizeProvider(t *testing.T) {
 		{"glm", "zhipu"},
 		{"google", "gemini"},
 		{"groq", "groq"},
+		// Alibaba Coding Plan aliases
+		{"alibaba-coding", "coding-plan"},
+		{"qwen-coding", "coding-plan"},
+		{"alibaba-coding-anthropic", "coding-plan-anthropic"},
+		// Qwen international aliases
+		{"qwen-international", "qwen-intl"},
+		{"dashscope-intl", "qwen-intl"},
+		{"dashscope-us", "qwen-us"},
 		{"", ""},
 	}
 
diff --git a/pkg/providers/openai_compat/provider.go b/pkg/providers/openai_compat/provider.go
index d922ed5f7..90bc683b8 100644
--- a/pkg/providers/openai_compat/provider.go
+++ b/pkg/providers/openai_compat/provider.go
@@ -1,6 +1,7 @@
 package openai_compat
 
 import (
+	"bufio"
 	"bytes"
 	"context"
 	"encoding/json"
@@ -12,6 +13,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/sipeed/picoclaw/pkg/providers/common"
 	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
 )
 
@@ -33,11 +35,12 @@ type Provider struct {
 	apiBase        string
 	maxTokensField string // Field name for max tokens (e.g., "max_completion_tokens" for o1/glm models)
 	httpClient     *http.Client
+	extraBody      map[string]any // Additional fields to inject into request body
 }
 
 type Option func(*Provider)
 
-const defaultRequestTimeout = 120 * time.Second
+const defaultRequestTimeout = common.DefaultRequestTimeout
 
 func WithMaxTokensField(maxTokensField string) Option {
 	return func(p *Provider) {
@@ -53,26 +56,17 @@ func WithRequestTimeout(timeout time.Duration) Option {
 	}
 }
 
+func WithExtraBody(extraBody map[string]any) Option {
+	return func(p *Provider) {
+		p.extraBody = extraBody
+	}
+}
+
 func NewProvider(apiKey, apiBase, proxy string, opts ...Option) *Provider {
-	client := &http.Client{
-		Timeout: defaultRequestTimeout,
-	}
-
-	if proxy != "" {
-		parsed, err := url.Parse(proxy)
-		if err == nil {
-			client.Transport = &http.Transport{
-				Proxy: http.ProxyURL(parsed),
-			}
-		} else {
-			log.Printf("openai_compat: invalid proxy URL %q: %v", proxy, err)
-		}
-	}
-
 	p := &Provider{
 		apiKey:     apiKey,
 		apiBase:    strings.TrimRight(apiBase, "/"),
-		httpClient: client,
+		httpClient: common.NewHTTPClient(proxy),
 	}
 
 	for _, opt := range opts {
@@ -101,34 +95,28 @@ func NewProviderWithMaxTokensFieldAndTimeout(
 	)
 }
 
-func (p *Provider) Chat(
-	ctx context.Context,
-	messages []Message,
-	tools []ToolDefinition,
-	model string,
-	options map[string]any,
-) (*LLMResponse, error) {
-	if p.apiBase == "" {
-		return nil, fmt.Errorf("API base not configured")
-	}
-
+// buildRequestBody constructs the common request body for Chat and ChatStream.
+func (p *Provider) buildRequestBody(
+	messages []Message, tools []ToolDefinition, model string, options map[string]any,
+) map[string]any {
 	model = normalizeModel(model, p.apiBase)
 
 	requestBody := map[string]any{
 		"model":    model,
-		"messages": stripSystemParts(messages),
+		"messages": common.SerializeMessages(messages),
 	}
 
-	if len(tools) > 0 {
-		requestBody["tools"] = tools
+	// When fallback uses a different provider (e.g. DeepSeek), that provider must not inject web_search_preview.
+	nativeSearch, _ := options["native_search"].(bool)
+	nativeSearch = nativeSearch && isNativeSearchHost(p.apiBase)
+	if len(tools) > 0 || nativeSearch {
+		requestBody["tools"] = buildToolsList(tools, nativeSearch)
 		requestBody["tool_choice"] = "auto"
 	}
 
-	if maxTokens, ok := asInt(options["max_tokens"]); ok {
-		// Use configured maxTokensField if specified, otherwise fallback to model-based detection
+	if maxTokens, ok := common.AsInt(options["max_tokens"]); ok {
 		fieldName := p.maxTokensField
 		if fieldName == "" {
-			// Fallback: detect from model name for backward compatibility
 			lowerModel := strings.ToLower(model)
 			if strings.Contains(lowerModel, "glm") || strings.Contains(lowerModel, "o1") ||
 				strings.Contains(lowerModel, "gpt-5") {
@@ -140,9 +128,8 @@ func (p *Provider) Chat(
 		requestBody[fieldName] = maxTokens
 	}
 
-	if temperature, ok := asFloat(options["temperature"]); ok {
+	if temperature, ok := common.AsFloat(options["temperature"]); ok {
 		lowerModel := strings.ToLower(model)
-		// Kimi k2 models only support temperature=1.
 		if strings.Contains(lowerModel, "kimi") && strings.Contains(lowerModel, "k2") {
 			requestBody["temperature"] = 1.0
 		} else {
@@ -152,16 +139,36 @@ func (p *Provider) Chat(
 
 	// Prompt caching: pass a stable cache key so OpenAI can bucket requests
 	// with the same key and reuse prefix KV cache across calls.
-	// The key is typically the agent ID — stable per agent, shared across requests.
-	// See: https://platform.openai.com/docs/guides/prompt-caching
 	// Prompt caching is only supported by OpenAI-native endpoints.
-	// Gemini and other providers reject unknown fields, so skip for non-OpenAI APIs.
+	// Non-OpenAI providers reject unknown fields with 422 errors.
 	if cacheKey, ok := options["prompt_cache_key"].(string); ok && cacheKey != "" {
-		if !strings.Contains(p.apiBase, "generativelanguage.googleapis.com") {
+		if supportsPromptCacheKey(p.apiBase) {
 			requestBody["prompt_cache_key"] = cacheKey
 		}
 	}
 
+	// Merge extra body fields configured per-provider/model.
+	// These are injected last so they take precedence over defaults.
+	for k, v := range p.extraBody {
+		requestBody[k] = v
+	}
+
+	return requestBody
+}
+
+func (p *Provider) Chat(
+	ctx context.Context,
+	messages []Message,
+	tools []ToolDefinition,
+	model string,
+	options map[string]any,
+) (*LLMResponse, error) {
+	if p.apiBase == "" {
+		return nil, fmt.Errorf("API base not configured")
+	}
+
+	requestBody := p.buildRequestBody(messages, tools, model, options)
+
 	jsonData, err := json.Marshal(requestBody)
 	if err != nil {
 		return nil, fmt.Errorf("failed to marshal request: %w", err)
@@ -183,134 +190,202 @@ func (p *Provider) Chat(
 	}
 	defer resp.Body.Close()
 
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read response: %w", err)
-	}
-
 	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("API request failed:\n  Status: %d\n  Body:   %s", resp.StatusCode, string(body))
+		return nil, common.HandleErrorResponse(resp, p.apiBase)
 	}
 
-	return parseResponse(body)
+	return common.ReadAndParseResponse(resp, p.apiBase)
 }
 
-func parseResponse(body []byte) (*LLMResponse, error) {
-	var apiResponse struct {
-		Choices []struct {
-			Message struct {
-				Content          string            `json:"content"`
-				ReasoningContent string            `json:"reasoning_content"`
-				Reasoning        string            `json:"reasoning"`
-				ReasoningDetails []ReasoningDetail `json:"reasoning_details"`
-				ToolCalls        []struct {
-					ID       string `json:"id"`
-					Type     string `json:"type"`
-					Function *struct {
-						Name      string `json:"name"`
-						Arguments string `json:"arguments"`
-					} `json:"function"`
-					ExtraContent *struct {
-						Google *struct {
-							ThoughtSignature string `json:"thought_signature"`
-						} `json:"google"`
-					} `json:"extra_content"`
-				} `json:"tool_calls"`
-			} `json:"message"`
-			FinishReason string `json:"finish_reason"`
-		} `json:"choices"`
-		Usage *UsageInfo `json:"usage"`
+// ChatStream implements streaming via OpenAI-compatible SSE (stream: true).
+// onChunk receives the accumulated text so far on each text delta.
+func (p *Provider) ChatStream(
+	ctx context.Context,
+	messages []Message,
+	tools []ToolDefinition,
+	model string,
+	options map[string]any,
+	onChunk func(accumulated string),
+) (*LLMResponse, error) {
+	if p.apiBase == "" {
+		return nil, fmt.Errorf("API base not configured")
 	}
 
-	if err := json.Unmarshal(body, &apiResponse); err != nil {
-		return nil, fmt.Errorf("failed to unmarshal response: %w", err)
+	requestBody := p.buildRequestBody(messages, tools, model, options)
+	requestBody["stream"] = true
+
+	jsonData, err := json.Marshal(requestBody)
+	if err != nil {
+		return nil, fmt.Errorf("failed to marshal request: %w", err)
 	}
 
-	if len(apiResponse.Choices) == 0 {
-		return &LLMResponse{
-			Content:      "",
-			FinishReason: "stop",
-		}, nil
+	req, err := http.NewRequestWithContext(ctx, "POST", p.apiBase+"/chat/completions", bytes.NewReader(jsonData))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create request: %w", err)
 	}
 
-	choice := apiResponse.Choices[0]
-	toolCalls := make([]ToolCall, 0, len(choice.Message.ToolCalls))
-	for _, tc := range choice.Message.ToolCalls {
-		arguments := make(map[string]any)
-		name := ""
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Accept", "text/event-stream")
+	if p.apiKey != "" {
+		req.Header.Set("Authorization", "Bearer "+p.apiKey)
+	}
 
-		// Extract thought_signature from Gemini/Google-specific extra content
-		thoughtSignature := ""
-		if tc.ExtraContent != nil && tc.ExtraContent.Google != nil {
-			thoughtSignature = tc.ExtraContent.Google.ThoughtSignature
+	// Use a client without Timeout for streaming — the http.Client.Timeout covers
+	// the entire request lifecycle including body reads, which would kill long streams.
+	// Context cancellation still provides the safety net.
+	streamClient := &http.Client{Transport: p.httpClient.Transport}
+	resp, err := streamClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to send request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, common.HandleErrorResponse(resp, p.apiBase)
+	}
+
+	return parseStreamResponse(ctx, resp.Body, onChunk)
+}
+
+// parseStreamResponse parses an OpenAI-compatible SSE stream.
+func parseStreamResponse(
+	ctx context.Context,
+	reader io.Reader,
+	onChunk func(accumulated string),
+) (*LLMResponse, error) {
+	var textContent strings.Builder
+	var finishReason string
+	var usage *UsageInfo
+
+	// Tool call assembly: OpenAI streams tool calls as incremental deltas
+	type toolAccum struct {
+		id       string
+		name     string
+		argsJSON strings.Builder
+	}
+	activeTools := map[int]*toolAccum{}
+
+	scanner := bufio.NewScanner(reader)
+	scanner.Buffer(make([]byte, 0, 1024*1024), 10*1024*1024) // 1MB initial, 10MB max
+	for scanner.Scan() {
+		// Check for context cancellation between chunks
+		if err := ctx.Err(); err != nil {
+			return nil, err
 		}
 
-		if tc.Function != nil {
-			name = tc.Function.Name
-			if tc.Function.Arguments != "" {
-				if err := json.Unmarshal([]byte(tc.Function.Arguments), &arguments); err != nil {
-					log.Printf("openai_compat: failed to decode tool call arguments for %q: %v", name, err)
-					arguments["raw"] = tc.Function.Arguments
+		line := scanner.Text()
+
+		if !strings.HasPrefix(line, "data: ") {
+			continue
+		}
+		data := strings.TrimPrefix(line, "data: ")
+		if data == "[DONE]" {
+			break
+		}
+
+		var chunk struct {
+			Choices []struct {
+				Delta struct {
+					Content   string `json:"content"`
+					ToolCalls []struct {
+						Index    int    `json:"index"`
+						ID       string `json:"id"`
+						Function *struct {
+							Name      string `json:"name"`
+							Arguments string `json:"arguments"`
+						} `json:"function"`
+					} `json:"tool_calls"`
+				} `json:"delta"`
+				FinishReason *string `json:"finish_reason"`
+			} `json:"choices"`
+			Usage *UsageInfo `json:"usage"`
+		}
+
+		if err := json.Unmarshal([]byte(data), &chunk); err != nil {
+			continue // skip malformed chunks
+		}
+
+		if chunk.Usage != nil {
+			usage = chunk.Usage
+		}
+
+		if len(chunk.Choices) == 0 {
+			continue
+		}
+
+		choice := chunk.Choices[0]
+
+		// Accumulate text content
+		if choice.Delta.Content != "" {
+			textContent.WriteString(choice.Delta.Content)
+			if onChunk != nil {
+				onChunk(textContent.String())
+			}
+		}
+
+		// Accumulate tool call deltas
+		for _, tc := range choice.Delta.ToolCalls {
+			acc, ok := activeTools[tc.Index]
+			if !ok {
+				acc = &toolAccum{}
+				activeTools[tc.Index] = acc
+			}
+			if tc.ID != "" {
+				acc.id = tc.ID
+			}
+			if tc.Function != nil {
+				if tc.Function.Name != "" {
+					acc.name = tc.Function.Name
+				}
+				if tc.Function.Arguments != "" {
+					acc.argsJSON.WriteString(tc.Function.Arguments)
 				}
 			}
 		}
 
-		// Build ToolCall with ExtraContent for Gemini 3 thought_signature persistence
-		toolCall := ToolCall{
-			ID:               tc.ID,
-			Name:             name,
-			Arguments:        arguments,
-			ThoughtSignature: thoughtSignature,
+		if choice.FinishReason != nil {
+			finishReason = *choice.FinishReason
 		}
+	}
 
-		if thoughtSignature != "" {
-			toolCall.ExtraContent = &ExtraContent{
-				Google: &GoogleExtra{
-					ThoughtSignature: thoughtSignature,
-				},
+	if err := scanner.Err(); err != nil {
+		return nil, fmt.Errorf("streaming read error: %w", err)
+	}
+
+	// Assemble tool calls from accumulated deltas
+	var toolCalls []ToolCall
+	for i := 0; i < len(activeTools); i++ {
+		acc, ok := activeTools[i]
+		if !ok {
+			continue
+		}
+		args := make(map[string]any)
+		raw := acc.argsJSON.String()
+		if raw != "" {
+			if err := json.Unmarshal([]byte(raw), &args); err != nil {
+				log.Printf("openai_compat stream: failed to decode tool call arguments for %q: %v", acc.name, err)
+				args["raw"] = raw
 			}
 		}
+		toolCalls = append(toolCalls, ToolCall{
+			ID:        acc.id,
+			Name:      acc.name,
+			Arguments: args,
+		})
+	}
 
-		toolCalls = append(toolCalls, toolCall)
+	if finishReason == "" {
+		finishReason = "stop"
 	}
 
 	return &LLMResponse{
-		Content:          choice.Message.Content,
-		ReasoningContent: choice.Message.ReasoningContent,
-		Reasoning:        choice.Message.Reasoning,
-		ReasoningDetails: choice.Message.ReasoningDetails,
-		ToolCalls:        toolCalls,
-		FinishReason:     choice.FinishReason,
-		Usage:            apiResponse.Usage,
+		Content:      textContent.String(),
+		ToolCalls:    toolCalls,
+		FinishReason: finishReason,
+		Usage:        usage,
 	}, nil
 }
 
-// openaiMessage is the wire-format message for OpenAI-compatible APIs.
-// It mirrors protocoltypes.Message but omits SystemParts, which is an
-// internal field that would be unknown to third-party endpoints.
-type openaiMessage struct {
-	Role       string     `json:"role"`
-	Content    string     `json:"content"`
-	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`
-	ToolCallID string     `json:"tool_call_id,omitempty"`
-}
-
-// stripSystemParts converts []Message to []openaiMessage, dropping the
-// SystemParts field so it doesn't leak into the JSON payload sent to
-// OpenAI-compatible APIs (some strict endpoints reject unknown fields).
-func stripSystemParts(messages []Message) []openaiMessage {
-	out := make([]openaiMessage, len(messages))
-	for i, m := range messages {
-		out[i] = openaiMessage{
-			Role:       m.Role,
-			Content:    m.Content,
-			ToolCalls:  m.ToolCalls,
-			ToolCallID: m.ToolCallID,
-		}
-	}
-	return out
-}
-
 func normalizeModel(model, apiBase string) string {
 	before, after, ok := strings.Cut(model, "/")
 	if !ok {
@@ -323,39 +398,50 @@ func normalizeModel(model, apiBase string) string {
 
 	prefix := strings.ToLower(before)
 	switch prefix {
-	case "moonshot", "nvidia", "groq", "ollama", "deepseek", "google", "openrouter", "zhipu", "mistral":
+	case "litellm", "moonshot", "nvidia", "groq", "ollama", "deepseek", "google",
+		"openrouter", "zhipu", "mistral", "vivgrid", "minimax", "novita":
 		return after
 	default:
 		return model
 	}
 }
 
-func asInt(v any) (int, bool) {
-	switch val := v.(type) {
-	case int:
-		return val, true
-	case int64:
-		return int(val), true
-	case float64:
-		return int(val), true
-	case float32:
-		return int(val), true
-	default:
-		return 0, false
+func buildToolsList(tools []ToolDefinition, nativeSearch bool) []any {
+	result := make([]any, 0, len(tools)+1)
+	for _, t := range tools {
+		if nativeSearch && strings.EqualFold(t.Function.Name, "web_search") {
+			continue
+		}
+		result = append(result, t)
 	}
+	if nativeSearch {
+		result = append(result, map[string]any{"type": "web_search_preview"})
+	}
+	return result
 }
 
-func asFloat(v any) (float64, bool) {
-	switch val := v.(type) {
-	case float64:
-		return val, true
-	case float32:
-		return float64(val), true
-	case int:
-		return float64(val), true
-	case int64:
-		return float64(val), true
-	default:
-		return 0, false
-	}
+func (p *Provider) SupportsNativeSearch() bool {
+	return isNativeSearchHost(p.apiBase)
+}
+
+func isNativeSearchHost(apiBase string) bool {
+	u, err := url.Parse(apiBase)
+	if err != nil {
+		return false
+	}
+	host := u.Hostname()
+	return host == "api.openai.com" || strings.HasSuffix(host, ".openai.azure.com")
+}
+
+// supportsPromptCacheKey reports whether the given API base is known to
+// support the prompt_cache_key request field. Currently only OpenAI's own
+// API and Azure OpenAI support this. All other OpenAI-compatible providers
+// (Mistral, Gemini, DeepSeek, Groq, etc.) reject unknown fields with 422 errors.
+func supportsPromptCacheKey(apiBase string) bool {
+	u, err := url.Parse(apiBase)
+	if err != nil {
+		return false
+	}
+	host := u.Hostname()
+	return host == "api.openai.com" || strings.HasSuffix(host, ".openai.azure.com")
 }
diff --git a/pkg/providers/openai_compat/provider_test.go b/pkg/providers/openai_compat/provider_test.go
index 7247fea3e..ab632ccf3 100644
--- a/pkg/providers/openai_compat/provider_test.go
+++ b/pkg/providers/openai_compat/provider_test.go
@@ -1,12 +1,19 @@
 package openai_compat
 
 import (
+	"bytes"
 	"encoding/json"
+	"fmt"
+	"io"
 	"net/http"
 	"net/http/httptest"
 	"net/url"
+	"strings"
 	"testing"
 	"time"
+
+	"github.com/sipeed/picoclaw/pkg/providers/common"
+	"github.com/sipeed/picoclaw/pkg/providers/protocoltypes"
 )
 
 func TestProviderChat_UsesMaxCompletionTokensForGLM(t *testing.T) {
@@ -102,6 +109,55 @@ func TestProviderChat_ParsesToolCalls(t *testing.T) {
 	}
 }
 
+func TestProviderChat_ParsesToolCallsWithObjectArguments(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		resp := map[string]any{
+			"choices": []map[string]any{
+				{
+					"message": map[string]any{
+						"content": "",
+						"tool_calls": []map[string]any{
+							{
+								"id":   "call_1",
+								"type": "function",
+								"function": map[string]any{
+									"name": "get_weather",
+									"arguments": map[string]any{
+										"city":   "SF",
+										"metric": true,
+									},
+								},
+							},
+						},
+					},
+					"finish_reason": "tool_calls",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	}))
+	defer server.Close()
+
+	p := NewProvider("key", server.URL, "")
+	out, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "hi"}}, nil, "gpt-4o", nil)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+	if len(out.ToolCalls) != 1 {
+		t.Fatalf("len(ToolCalls) = %d, want 1", len(out.ToolCalls))
+	}
+	if out.ToolCalls[0].Name != "get_weather" {
+		t.Fatalf("ToolCalls[0].Name = %q, want %q", out.ToolCalls[0].Name, "get_weather")
+	}
+	if out.ToolCalls[0].Arguments["city"] != "SF" {
+		t.Fatalf("ToolCalls[0].Arguments[city] = %v, want SF", out.ToolCalls[0].Arguments["city"])
+	}
+	if out.ToolCalls[0].Arguments["metric"] != true {
+		t.Fatalf("ToolCalls[0].Arguments[metric] = %v, want true", out.ToolCalls[0].Arguments["metric"])
+	}
+}
+
 func TestProviderChat_ParsesReasoningContent(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		resp := map[string]any{
@@ -146,6 +202,56 @@ func TestProviderChat_ParsesReasoningContent(t *testing.T) {
 	}
 }
 
+func TestProviderChat_PreservesReasoningContentInHistory(t *testing.T) {
+	var requestBody map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		resp := map[string]any{
+			"choices": []map[string]any{
+				{
+					"message":       map[string]any{"content": "ok"},
+					"finish_reason": "stop",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	}))
+	defer server.Close()
+
+	p := NewProvider("key", server.URL, "")
+
+	// Simulate a multi-turn conversation where the assistant's previous
+	// reply included reasoning_content (e.g. from kimi-k2.5).
+	messages := []Message{
+		{Role: "user", Content: "What is 1+1?"},
+		{Role: "assistant", Content: "2", ReasoningContent: "Let me think... 1+1=2"},
+		{Role: "user", Content: "What about 2+2?"},
+	}
+
+	_, err := p.Chat(t.Context(), messages, nil, "kimi-k2.5", nil)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	// Verify reasoning_content is preserved in the serialized request.
+	reqMessages, ok := requestBody["messages"].([]any)
+	if !ok {
+		t.Fatalf("messages is not []any: %T", requestBody["messages"])
+	}
+	assistantMsg, ok := reqMessages[1].(map[string]any)
+	if !ok {
+		t.Fatalf("assistant message is not map[string]any: %T", reqMessages[1])
+	}
+	if assistantMsg["reasoning_content"] != "Let me think... 1+1=2" {
+		t.Errorf("reasoning_content not preserved in request, got %v", assistantMsg["reasoning_content"])
+	}
+}
+
 func TestProviderChat_HTTPError(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		http.Error(w, "bad request", http.StatusBadRequest)
@@ -159,6 +265,132 @@ func TestProviderChat_HTTPError(t *testing.T) {
 	}
 }
 
+func TestProviderChat_JSONHTTPErrorDoesNotReportHTML(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		_, _ = w.Write([]byte(`{"error":"bad request"}`))
+	}))
+	defer server.Close()
+
+	p := NewProvider("key", server.URL, "")
+	_, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "hi"}}, nil, "gpt-4o", nil)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "Status: 400") {
+		t.Fatalf("expected status code in error, got %v", err)
+	}
+	if strings.Contains(err.Error(), "returned HTML instead of JSON") {
+		t.Fatalf("expected non-HTML http error, got %v", err)
+	}
+}
+
+func TestProviderChat_HTMLResponsesReturnHelpfulError(t *testing.T) {
+	tests := []struct {
+		name        string
+		contentType string
+		statusCode  int
+		body        string
+	}{
+		{
+			name:        "html success response",
+			contentType: "text/html; charset=utf-8",
+			statusCode:  http.StatusOK,
+			body:        "<!DOCTYPE html><html><body>gateway login</body></html>",
+		},
+		{
+			name:        "html error response",
+			contentType: "text/html; charset=utf-8",
+			statusCode:  http.StatusBadGateway,
+			body:        "<!DOCTYPE html><html><body>bad gateway</body></html>",
+		},
+		{
+			name:        "mislabeled html success response",
+			contentType: "application/json",
+			statusCode:  http.StatusOK,
+			body:        "   \r\n\t<!DOCTYPE html><html><body>gateway login</body></html>",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.Header().Set("Content-Type", tt.contentType)
+				w.WriteHeader(tt.statusCode)
+				_, _ = w.Write([]byte(tt.body))
+			}))
+			defer server.Close()
+
+			p := NewProvider("key", server.URL, "")
+			_, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "hi"}}, nil, "gpt-4o", nil)
+			if err == nil {
+				t.Fatal("expected error, got nil")
+			}
+			if !strings.Contains(err.Error(), fmt.Sprintf("Status: %d", tt.statusCode)) {
+				t.Fatalf("expected status code in error, got %v", err)
+			}
+			if !strings.Contains(err.Error(), "returned HTML instead of JSON") {
+				t.Fatalf("expected helpful HTML error, got %v", err)
+			}
+			if !strings.Contains(err.Error(), "check api_base or proxy configuration") {
+				t.Fatalf("expected configuration hint, got %v", err)
+			}
+		})
+	}
+}
+
+func TestProviderChat_SuccessResponseUsesStreamingDecoder(t *testing.T) {
+	content := strings.Repeat("a", 1024)
+	body := `{"choices":[{"message":{"content":"` + content + `"},"finish_reason":"stop"}]}`
+
+	p := NewProvider("key", "https://example.com/v1", "")
+	p.httpClient = &http.Client{
+		Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+			return &http.Response{
+				StatusCode: http.StatusOK,
+				Header:     http.Header{"Content-Type": []string{"application/json"}},
+				Body: &errAfterDataReadCloser{
+					data:      []byte(body),
+					chunkSize: 64,
+				},
+			}, nil
+		}),
+	}
+
+	out, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "hi"}}, nil, "gpt-4o", nil)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+	if out.Content != content {
+		t.Fatalf("Content = %q, want %q", out.Content, content)
+	}
+}
+
+func TestProviderChat_LargeHTMLResponsePreviewIsTruncated(t *testing.T) {
+	body := append([]byte("<!DOCTYPE html><html><body>"), bytes.Repeat([]byte("A"), 2048)...)
+	body = append(body, []byte("</body></html>")...)
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		w.WriteHeader(http.StatusBadGateway)
+		_, _ = w.Write(body)
+	}))
+	defer server.Close()
+
+	p := NewProvider("key", server.URL, "")
+	_, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "hi"}}, nil, "gpt-4o", nil)
+	if err == nil {
+		t.Fatal("expected error, got nil")
+	}
+	if !strings.Contains(err.Error(), "Body:   <!DOCTYPE html><html><body>") {
+		t.Fatalf("expected html preview in error, got %v", err)
+	}
+	if !strings.Contains(err.Error(), "...") {
+		t.Fatalf("expected truncated preview, got %v", err)
+	}
+}
+
 func TestProviderChat_StripsMoonshotPrefixAndNormalizesKimiTemperature(t *testing.T) {
 	var requestBody map[string]any
 
@@ -200,12 +432,38 @@ func TestProviderChat_StripsMoonshotPrefixAndNormalizesKimiTemperature(t *testin
 	}
 }
 
-func TestProviderChat_StripsGroqAndOllamaPrefixes(t *testing.T) {
+func TestProviderChat_StripsGroqOllamaDeepseekVivgridNovitaPrefixes(t *testing.T) {
+	var requestBody map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		resp := map[string]any{
+			"choices": []map[string]any{
+				{
+					"message":       map[string]any{"content": "ok"},
+					"finish_reason": "stop",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	}))
+	defer server.Close()
+
+	p := NewProvider("key", server.URL, "")
 	tests := []struct {
 		name      string
 		input     string
 		wantModel string
 	}{
+		{
+			name:      "strips litellm prefix and preserves proxy model name",
+			input:     "litellm/my-proxy-alias",
+			wantModel: "my-proxy-alias",
+		},
 		{
 			name:      "strips groq prefix and keeps nested model",
 			input:     "groq/openai/gpt-oss-120b",
@@ -221,31 +479,30 @@ func TestProviderChat_StripsGroqAndOllamaPrefixes(t *testing.T) {
 			input:     "deepseek/deepseek-chat",
 			wantModel: "deepseek-chat",
 		},
+		{
+			name:      "strips vivgrid prefix",
+			input:     "vivgrid/auto",
+			wantModel: "auto",
+		},
+		{
+			name:      "strips novita prefix deepseek model",
+			input:     "novita/deepseek/deepseek-v3.2",
+			wantModel: "deepseek/deepseek-v3.2",
+		},
+		{
+			name:      "strips novita prefix zai model",
+			input:     "novita/zai-org/glm-5",
+			wantModel: "zai-org/glm-5",
+		},
+		{
+			name:      "strips novita prefix minimax model",
+			input:     "novita/minimax/minimax-m2.5",
+			wantModel: "minimax/minimax-m2.5",
+		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			var requestBody map[string]any
-
-			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-				if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
-					http.Error(w, err.Error(), http.StatusBadRequest)
-					return
-				}
-				resp := map[string]any{
-					"choices": []map[string]any{
-						{
-							"message":       map[string]any{"content": "ok"},
-							"finish_reason": "stop",
-						},
-					},
-				}
-				w.Header().Set("Content-Type", "application/json")
-				json.NewEncoder(w).Encode(resp)
-			}))
-			defer server.Close()
-
-			p := NewProvider("key", server.URL, "")
 			_, err := p.Chat(t.Context(), []Message{{Role: "user", Content: "hi"}}, nil, tt.input, nil)
 			if err != nil {
 				t.Fatalf("Chat() error = %v", err)
@@ -325,6 +582,18 @@ func TestNormalizeModel_UsesAPIBase(t *testing.T) {
 	if got := normalizeModel("openrouter/auto", "https://openrouter.ai/api/v1"); got != "openrouter/auto" {
 		t.Fatalf("normalizeModel(openrouter) = %q, want %q", got, "openrouter/auto")
 	}
+	if got := normalizeModel("vivgrid/managed", "https://api.vivgrid.com/v1"); got != "managed" {
+		t.Fatalf("normalizeModel(vivgrid) = %q, want %q", got, "managed")
+	}
+	if got := normalizeModel("vivgrid/auto", "https://api.vivgrid.com/v1"); got != "auto" {
+		t.Fatalf("normalizeModel(vivgrid auto) = %q, want %q", got, "auto")
+	}
+	if got := normalizeModel(
+		"novita/deepseek/deepseek-v3.2",
+		"https://api.novita.ai/openai",
+	); got != "deepseek/deepseek-v3.2" {
+		t.Fatalf("normalizeModel(novita) = %q, want %q", got, "deepseek/deepseek-v3.2")
+	}
 }
 
 func TestProvider_RequestTimeoutDefault(t *testing.T) {
@@ -341,6 +610,124 @@ func TestProvider_RequestTimeoutOverride(t *testing.T) {
 	}
 }
 
+func TestProviderChat_ExtraBodyInjected(t *testing.T) {
+	var requestBody map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		resp := map[string]any{
+			"choices": []map[string]any{
+				{
+					"message":       map[string]any{"content": "ok"},
+					"finish_reason": "stop",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	}))
+	defer server.Close()
+
+	extraBody := map[string]any{"reasoning_split": true, "custom_field": "test"}
+	p := NewProvider("key", server.URL, "", WithExtraBody(extraBody))
+
+	_, err := p.Chat(
+		t.Context(),
+		[]Message{{Role: "user", Content: "hi"}},
+		nil,
+		"minimax/abab7",
+		nil,
+	)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	if got, ok := requestBody["reasoning_split"]; !ok || got != true {
+		t.Fatalf("reasoning_split = %v, want true", got)
+	}
+	if got, ok := requestBody["custom_field"]; !ok || got != "test" {
+		t.Fatalf("custom_field = %v, want test", got)
+	}
+}
+
+func TestProviderChat_ExtraBodyOverridesOptions(t *testing.T) {
+	var requestBody map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		resp := map[string]any{
+			"choices": []map[string]any{
+				{
+					"message":       map[string]any{"content": "ok"},
+					"finish_reason": "stop",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	}))
+	defer server.Close()
+
+	extraBody := map[string]any{"temperature": 0.9}
+	p := NewProvider("key", server.URL, "", WithExtraBody(extraBody))
+
+	_, err := p.Chat(
+		t.Context(),
+		[]Message{{Role: "user", Content: "hi"}},
+		nil,
+		"gpt-4o",
+		map[string]any{"temperature": 0.5},
+	)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	// ExtraBody takes precedence over options since it is merged last.
+	if got := requestBody["temperature"]; got != float64(0.9) {
+		t.Fatalf("temperature = %v, want 0.9 (from extraBody, overriding options)", got)
+	}
+}
+
+type roundTripperFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripperFunc) RoundTrip(r *http.Request) (*http.Response, error) {
+	return f(r)
+}
+
+type errAfterDataReadCloser struct {
+	data      []byte
+	chunkSize int
+	offset    int
+}
+
+func (r *errAfterDataReadCloser) Read(p []byte) (int, error) {
+	if r.offset >= len(r.data) {
+		return 0, io.ErrUnexpectedEOF
+	}
+
+	n := r.chunkSize
+	if n <= 0 || n > len(p) {
+		n = len(p)
+	}
+	remaining := len(r.data) - r.offset
+	if n > remaining {
+		n = remaining
+	}
+	copy(p, r.data[r.offset:r.offset+n])
+	r.offset += n
+	return n, nil
+}
+
+func (r *errAfterDataReadCloser) Close() error {
+	return nil
+}
+
 func TestProvider_FunctionalOptionMaxTokensField(t *testing.T) {
 	p := NewProvider("key", "https://example.com/v1", "", WithMaxTokensField("max_completion_tokens"))
 	if p.maxTokensField != "max_completion_tokens" {
@@ -361,3 +748,428 @@ func TestProvider_FunctionalOptionRequestTimeoutNonPositive(t *testing.T) {
 		t.Fatalf("http timeout = %v, want %v", p.httpClient.Timeout, defaultRequestTimeout)
 	}
 }
+
+func TestSerializeMessages_PlainText(t *testing.T) {
+	messages := []protocoltypes.Message{
+		{Role: "user", Content: "hello"},
+		{Role: "assistant", Content: "hi", ReasoningContent: "thinking..."},
+	}
+	result := common.SerializeMessages(messages)
+
+	data, err := json.Marshal(result)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var msgs []map[string]any
+	json.Unmarshal(data, &msgs)
+
+	if msgs[0]["content"] != "hello" {
+		t.Fatalf("expected plain string content, got %v", msgs[0]["content"])
+	}
+	if msgs[1]["reasoning_content"] != "thinking..." {
+		t.Fatalf("reasoning_content not preserved, got %v", msgs[1]["reasoning_content"])
+	}
+}
+
+func TestSerializeMessages_WithMedia(t *testing.T) {
+	messages := []protocoltypes.Message{
+		{Role: "user", Content: "describe this", Media: []string{"data:image/png;base64,abc123"}},
+	}
+	result := common.SerializeMessages(messages)
+
+	data, _ := json.Marshal(result)
+	var msgs []map[string]any
+	json.Unmarshal(data, &msgs)
+
+	content, ok := msgs[0]["content"].([]any)
+	if !ok {
+		t.Fatalf("expected array content for media message, got %T", msgs[0]["content"])
+	}
+	if len(content) != 2 {
+		t.Fatalf("expected 2 content parts, got %d", len(content))
+	}
+
+	textPart := content[0].(map[string]any)
+	if textPart["type"] != "text" || textPart["text"] != "describe this" {
+		t.Fatalf("text part mismatch: %v", textPart)
+	}
+
+	imgPart := content[1].(map[string]any)
+	if imgPart["type"] != "image_url" {
+		t.Fatalf("expected image_url type, got %v", imgPart["type"])
+	}
+	imgURL := imgPart["image_url"].(map[string]any)
+	if imgURL["url"] != "data:image/png;base64,abc123" {
+		t.Fatalf("image url mismatch: %v", imgURL["url"])
+	}
+}
+
+func TestSerializeMessages_MediaWithToolCallID(t *testing.T) {
+	messages := []protocoltypes.Message{
+		{Role: "tool", Content: "image result", Media: []string{"data:image/png;base64,xyz"}, ToolCallID: "call_1"},
+	}
+	result := common.SerializeMessages(messages)
+
+	data, _ := json.Marshal(result)
+	var msgs []map[string]any
+	json.Unmarshal(data, &msgs)
+
+	if msgs[0]["tool_call_id"] != "call_1" {
+		t.Fatalf("tool_call_id not preserved with media, got %v", msgs[0]["tool_call_id"])
+	}
+	// Content should be multipart array
+	if _, ok := msgs[0]["content"].([]any); !ok {
+		t.Fatalf("expected array content, got %T", msgs[0]["content"])
+	}
+}
+
+// chatWithCacheKey sets up a test server, sends a Chat request with prompt_cache_key,
+// and returns the decoded request body for assertion.
+func chatWithCacheKey(t *testing.T, apiBase string) map[string]any {
+	t.Helper()
+	var requestBody map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		resp := map[string]any{
+			"choices": []map[string]any{
+				{
+					"message":       map[string]any{"content": "ok"},
+					"finish_reason": "stop",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	}))
+	defer server.Close()
+
+	p := NewProvider("key", server.URL, "")
+	p.apiBase = apiBase
+	p.httpClient = &http.Client{
+		Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+			r.URL, _ = url.Parse(server.URL + r.URL.Path)
+			return http.DefaultTransport.RoundTrip(r)
+		}),
+	}
+
+	_, err := p.Chat(
+		t.Context(),
+		[]Message{{Role: "user", Content: "hi"}},
+		nil,
+		"test-model",
+		map[string]any{"prompt_cache_key": "agent-main"},
+	)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+	return requestBody
+}
+
+func TestProviderChat_PromptCacheKeySentToOpenAI(t *testing.T) {
+	body := chatWithCacheKey(t, "https://api.openai.com/v1")
+	if body["prompt_cache_key"] != "agent-main" {
+		t.Fatalf("prompt_cache_key = %v, want %q", body["prompt_cache_key"], "agent-main")
+	}
+}
+
+func TestProviderChat_PromptCacheKeyOmittedForNonOpenAI(t *testing.T) {
+	tests := []struct {
+		name    string
+		apiBase string
+	}{
+		{"mistral", "https://api.mistral.ai/v1"},
+		{"gemini", "https://generativelanguage.googleapis.com/v1beta"},
+		{"deepseek", "https://api.deepseek.com/v1"},
+		{"groq", "https://api.groq.com/openai/v1"},
+		{"minimax", "https://api.minimaxi.com/v1"},
+		{"ollama_local", "http://localhost:11434/v1"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			body := chatWithCacheKey(t, tt.apiBase)
+			if _, exists := body["prompt_cache_key"]; exists {
+				t.Fatalf("prompt_cache_key should NOT be sent to %s, but was included in request", tt.name)
+			}
+		})
+	}
+}
+
+func TestSupportsPromptCacheKey(t *testing.T) {
+	tests := []struct {
+		apiBase string
+		want    bool
+	}{
+		{"https://api.openai.com/v1", true},
+		{"https://api.openai.com/v1/", true},
+		{"https://myresource.openai.azure.com/openai/deployments/gpt-4", true},
+		{"https://eastus.openai.azure.com/v1", true},
+		{"https://api.mistral.ai/v1", false},
+		{"https://generativelanguage.googleapis.com/v1beta", false},
+		{"https://api.deepseek.com/v1", false},
+		{"https://api.groq.com/openai/v1", false},
+		{"http://localhost:11434/v1", false},
+		{"https://openrouter.ai/api/v1", false},
+		// Edge cases: proxy URLs with openai.com in path should NOT match
+		{"https://my-proxy.com/api.openai.com/v1", false},
+		{"https://proxy.example.com/openai.azure.com/v1", false},
+		// Malformed or empty
+		{"", false},
+		{"not-a-url", false},
+	}
+	for _, tt := range tests {
+		if got := supportsPromptCacheKey(tt.apiBase); got != tt.want {
+			t.Errorf("supportsPromptCacheKey(%q) = %v, want %v", tt.apiBase, got, tt.want)
+		}
+	}
+}
+
+func TestBuildToolsList_NativeSearchAddsWebSearchPreview(t *testing.T) {
+	tools := []ToolDefinition{
+		{Type: "function", Function: ToolFunctionDefinition{Name: "read_file", Description: "read"}},
+	}
+	result := buildToolsList(tools, true)
+	if len(result) != 2 {
+		t.Fatalf("len(result) = %d, want 2", len(result))
+	}
+	wsEntry, ok := result[1].(map[string]any)
+	if !ok {
+		t.Fatalf("web search entry is %T, want map[string]any", result[1])
+	}
+	if wsEntry["type"] != "web_search_preview" {
+		t.Fatalf("type = %v, want web_search_preview", wsEntry["type"])
+	}
+}
+
+func TestBuildToolsList_NativeSearchFiltersClientWebSearch(t *testing.T) {
+	tools := []ToolDefinition{
+		{Type: "function", Function: ToolFunctionDefinition{Name: "web_search", Description: "search"}},
+		{Type: "function", Function: ToolFunctionDefinition{Name: "read_file", Description: "read"}},
+	}
+	result := buildToolsList(tools, true)
+	for _, entry := range result {
+		if td, ok := entry.(ToolDefinition); ok && strings.EqualFold(td.Function.Name, "web_search") {
+			t.Fatal("client-side web_search should be filtered out when native search is enabled")
+		}
+	}
+	if len(result) != 2 { // read_file + web_search_preview
+		t.Fatalf("len(result) = %d, want 2 (read_file + web_search_preview)", len(result))
+	}
+}
+
+func TestBuildToolsList_NoNativeSearchPassesThrough(t *testing.T) {
+	tools := []ToolDefinition{
+		{Type: "function", Function: ToolFunctionDefinition{Name: "web_search", Description: "search"}},
+		{Type: "function", Function: ToolFunctionDefinition{Name: "read_file", Description: "read"}},
+	}
+	result := buildToolsList(tools, false)
+	if len(result) != 2 {
+		t.Fatalf("len(result) = %d, want 2", len(result))
+	}
+}
+
+func TestIsNativeSearchHost(t *testing.T) {
+	tests := []struct {
+		apiBase string
+		want    bool
+	}{
+		{"https://api.openai.com/v1", true},
+		{"https://myresource.openai.azure.com/openai/deployments/gpt-4", true},
+		{"https://api.mistral.ai/v1", false},
+		{"https://api.deepseek.com/v1", false},
+		{"https://api.groq.com/openai/v1", false},
+		{"http://localhost:11434/v1", false},
+		{"", false},
+	}
+	for _, tt := range tests {
+		if got := isNativeSearchHost(tt.apiBase); got != tt.want {
+			t.Errorf("isNativeSearchHost(%q) = %v, want %v", tt.apiBase, got, tt.want)
+		}
+	}
+}
+
+func TestSupportsNativeSearch_OpenAI(t *testing.T) {
+	p := NewProvider("key", "https://api.openai.com/v1", "")
+	if !p.SupportsNativeSearch() {
+		t.Fatal("OpenAI provider should support native search")
+	}
+}
+
+func TestSupportsNativeSearch_NonOpenAI(t *testing.T) {
+	p := NewProvider("key", "https://api.deepseek.com/v1", "")
+	if p.SupportsNativeSearch() {
+		t.Fatal("DeepSeek provider should not support native search")
+	}
+}
+
+func TestProviderChat_NativeSearchToolInjected(t *testing.T) {
+	var requestBody map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		resp := map[string]any{
+			"choices": []map[string]any{
+				{
+					"message":       map[string]any{"content": "ok"},
+					"finish_reason": "stop",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	}))
+	defer server.Close()
+
+	p := NewProvider("key", server.URL, "")
+	p.apiBase = "https://api.openai.com/v1"
+	p.httpClient = &http.Client{
+		Transport: roundTripperFunc(func(r *http.Request) (*http.Response, error) {
+			r.URL, _ = url.Parse(server.URL + r.URL.Path)
+			return http.DefaultTransport.RoundTrip(r)
+		}),
+	}
+	tools := []ToolDefinition{
+		{Type: "function", Function: ToolFunctionDefinition{Name: "read_file", Description: "read"}},
+	}
+	_, err := p.Chat(
+		t.Context(),
+		[]Message{{Role: "user", Content: "hi"}},
+		tools,
+		"gpt-5.4",
+		map[string]any{"native_search": true},
+	)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	toolsRaw, ok := requestBody["tools"].([]any)
+	if !ok {
+		t.Fatalf("tools is %T, want []any", requestBody["tools"])
+	}
+	if len(toolsRaw) != 2 {
+		t.Fatalf("len(tools) = %d, want 2 (read_file + web_search_preview)", len(toolsRaw))
+	}
+
+	lastTool, ok := toolsRaw[1].(map[string]any)
+	if !ok {
+		t.Fatalf("last tool is %T, want map[string]any", toolsRaw[1])
+	}
+	if lastTool["type"] != "web_search_preview" {
+		t.Fatalf("last tool type = %v, want web_search_preview", lastTool["type"])
+	}
+}
+
+func TestProviderChat_NativeSearchNotInjectedWithoutOption(t *testing.T) {
+	var requestBody map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		resp := map[string]any{
+			"choices": []map[string]any{
+				{
+					"message":       map[string]any{"content": "ok"},
+					"finish_reason": "stop",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	}))
+	defer server.Close()
+
+	p := NewProvider("key", server.URL, "")
+	tools := []ToolDefinition{
+		{Type: "function", Function: ToolFunctionDefinition{Name: "web_search", Description: "search"}},
+	}
+	_, err := p.Chat(
+		t.Context(),
+		[]Message{{Role: "user", Content: "hi"}},
+		tools,
+		"gpt-5.4",
+		map[string]any{},
+	)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	toolsRaw, ok := requestBody["tools"].([]any)
+	if !ok {
+		t.Fatalf("tools is %T, want []any", requestBody["tools"])
+	}
+	if len(toolsRaw) != 1 {
+		t.Fatalf("len(tools) = %d, want 1 (web_search only)", len(toolsRaw))
+	}
+}
+
+// TestProviderChat_NativeSearchIgnoredOnNonOpenAI verifies that when native_search
+// is true in options but the provider's apiBase is not OpenAI (e.g. fallback to DeepSeek),
+// we do not inject web_search_preview to avoid API errors.
+func TestProviderChat_NativeSearchIgnoredOnNonOpenAI(t *testing.T) {
+	var requestBody map[string]any
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		resp := map[string]any{
+			"choices": []map[string]any{
+				{
+					"message":       map[string]any{"content": "ok"},
+					"finish_reason": "stop",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	}))
+	defer server.Close()
+
+	// Use server.URL so host is not api.openai.com — simulates DeepSeek/other provider
+	p := NewProvider("key", server.URL, "")
+	_, err := p.Chat(
+		t.Context(),
+		[]Message{{Role: "user", Content: "hi"}},
+		nil,
+		"deepseek-chat",
+		map[string]any{"native_search": true},
+	)
+	if err != nil {
+		t.Fatalf("Chat() error = %v", err)
+	}
+
+	// Should not have tools at all (no tools passed, and we must not add web_search_preview)
+	if toolsRaw, ok := requestBody["tools"]; ok {
+		t.Fatalf("tools should be omitted for non-OpenAI when only native_search was requested, got %v", toolsRaw)
+	}
+}
+
+func TestSerializeMessages_StripsSystemParts(t *testing.T) {
+	messages := []protocoltypes.Message{
+		{
+			Role:    "system",
+			Content: "you are helpful",
+			SystemParts: []protocoltypes.ContentBlock{
+				{Type: "text", Text: "you are helpful"},
+			},
+		},
+	}
+	result := common.SerializeMessages(messages)
+
+	data, _ := json.Marshal(result)
+	raw := string(data)
+	if strings.Contains(raw, "system_parts") {
+		t.Fatal("system_parts should not appear in serialized output")
+	}
+}
diff --git a/pkg/providers/protocoltypes/types.go b/pkg/providers/protocoltypes/types.go
index 99f13334e..194c1aa6f 100644
--- a/pkg/providers/protocoltypes/types.go
+++ b/pkg/providers/protocoltypes/types.go
@@ -65,6 +65,7 @@ type ContentBlock struct {
 type Message struct {
 	Role             string         `json:"role"`
 	Content          string         `json:"content"`
+	Media            []string       `json:"media,omitempty"`
 	ReasoningContent string         `json:"reasoning_content,omitempty"`
 	SystemParts      []ContentBlock `json:"system_parts,omitempty"` // structured system blocks for cache-aware adapters
 	ToolCalls        []ToolCall     `json:"tool_calls,omitempty"`
diff --git a/pkg/providers/toolcall_utils.go b/pkg/providers/toolcall_utils.go
index 49218b1b1..a33e1eb5c 100644
--- a/pkg/providers/toolcall_utils.go
+++ b/pkg/providers/toolcall_utils.go
@@ -5,7 +5,43 @@
 
 package providers
 
-import "encoding/json"
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+)
+
+// buildCLIToolsPrompt creates the tool definitions section for a CLI provider system prompt.
+func buildCLIToolsPrompt(tools []ToolDefinition) string {
+	var sb strings.Builder
+
+	sb.WriteString("## Available Tools\n\n")
+	sb.WriteString("When you need to use a tool, respond with ONLY a JSON object:\n\n")
+	sb.WriteString("```json\n")
+	sb.WriteString(
+		`{"tool_calls":[{"id":"call_xxx","type":"function","function":{"name":"tool_name","arguments":"{...}"}}]}`,
+	)
+	sb.WriteString("\n```\n\n")
+	sb.WriteString("CRITICAL: The 'arguments' field MUST be a JSON-encoded STRING.\n\n")
+	sb.WriteString("### Tool Definitions:\n\n")
+
+	for _, tool := range tools {
+		if tool.Type != "function" {
+			continue
+		}
+		sb.WriteString(fmt.Sprintf("#### %s\n", tool.Function.Name))
+		if tool.Function.Description != "" {
+			sb.WriteString(fmt.Sprintf("Description: %s\n", tool.Function.Description))
+		}
+		if len(tool.Function.Parameters) > 0 {
+			paramsJSON, _ := json.Marshal(tool.Function.Parameters)
+			sb.WriteString(fmt.Sprintf("Parameters:\n```json\n%s\n```\n", string(paramsJSON)))
+		}
+		sb.WriteString("\n")
+	}
+
+	return sb.String()
+}
 
 // NormalizeToolCall normalizes a ToolCall to ensure all fields are properly populated.
 // It handles cases where Name/Arguments might be in different locations (top-level vs Function)
diff --git a/pkg/providers/types.go b/pkg/providers/types.go
index f0c168bc6..9a4d126a7 100644
--- a/pkg/providers/types.go
+++ b/pkg/providers/types.go
@@ -37,6 +37,36 @@ type StatefulProvider interface {
 	Close()
 }
 
+// StreamingProvider is an optional interface for providers that support token streaming.
+// onChunk receives the accumulated text so far (not individual deltas).
+// The returned LLMResponse is the same complete response for compatibility with tool-call handling.
+type StreamingProvider interface {
+	ChatStream(
+		ctx context.Context,
+		messages []Message,
+		tools []ToolDefinition,
+		model string,
+		options map[string]any,
+		onChunk func(accumulated string),
+	) (*LLMResponse, error)
+}
+
+// ThinkingCapable is an optional interface for providers that support
+// extended thinking (e.g. Anthropic). Used by the agent loop to warn
+// when thinking_level is configured but the active provider cannot use it.
+type ThinkingCapable interface {
+	SupportsThinking() bool
+}
+
+// NativeSearchCapable is an optional interface for providers that support
+// built-in web search during LLM inference (e.g. OpenAI web_search_preview,
+// xAI Grok search). When the active provider implements this interface and
+// returns true, the agent loop can hide the client-side web_search tool to
+// avoid duplicate search surfaces and use the provider's native search instead.
+type NativeSearchCapable interface {
+	SupportsNativeSearch() bool
+}
+
 // FailoverReason classifies why an LLM request failed for fallback decisions.
 type FailoverReason string
 
diff --git a/pkg/routing/classifier.go b/pkg/routing/classifier.go
new file mode 100644
index 000000000..8cddaf069
--- /dev/null
+++ b/pkg/routing/classifier.go
@@ -0,0 +1,80 @@
+package routing
+
+// Classifier evaluates a feature set and returns a complexity score in [0, 1].
+// A higher score indicates a more complex task that benefits from a heavy model.
+// The score is compared against the configured threshold: score >= threshold selects
+// the primary (heavy) model; score < threshold selects the light model.
+//
+// Classifier is an interface so that future implementations (ML-based, embedding-based,
+// or any other approach) can be swapped in without changing routing infrastructure.
+type Classifier interface {
+	Score(f Features) float64
+}
+
+// RuleClassifier is the v1 implementation.
+// It uses a weighted sum of structural signals with no external dependencies,
+// no API calls, and sub-microsecond latency. The raw sum is capped at 1.0 so
+// that the returned score always falls within the [0, 1] contract.
+//
+// Individual weights (multiple signals can fire simultaneously):
+//
+//	token > 200 (≈600 chars): 0.35  — very long prompts are almost always complex
+//	token 50-200:             0.15  — medium length; may or may not be complex
+//	code block present:       0.40  — coding tasks need the heavy model
+//	tool calls > 3 (recent):  0.25  — dense tool usage signals an agentic workflow
+//	tool calls 1-3 (recent):  0.10  — some tool activity
+//	conversation depth > 10:  0.10  — long sessions carry implicit complexity
+//	attachments present:      1.00  — hard gate; multi-modal always needs heavy model
+//
+// Default threshold is 0.35, so:
+//   - Pure greetings / trivial Q&A:                 0.00 → light  ✓
+//   - Medium prose message (50–200 tokens):          0.15 → light  ✓
+//   - Message with code block:                       0.40 → heavy  ✓
+//   - Long message (>200 tokens):                    0.35 → heavy  ✓
+//   - Active tool session + medium message:          0.25 → light  (acceptable)
+//   - Any message with an image/audio attachment:    1.00 → heavy  ✓
+type RuleClassifier struct{}
+
+// Score computes the complexity score for the given feature set.
+// The returned value is in [0, 1]. Attachments short-circuit to 1.0.
+func (c *RuleClassifier) Score(f Features) float64 {
+	// Hard gate: multi-modal inputs always require the heavy model.
+	if f.HasAttachments {
+		return 1.0
+	}
+
+	var score float64
+
+	// Token estimate — primary verbosity signal
+	switch {
+	case f.TokenEstimate > 200:
+		score += 0.35
+	case f.TokenEstimate > 50:
+		score += 0.15
+	}
+
+	// Fenced code blocks — strongest indicator of a coding/technical task
+	if f.CodeBlockCount > 0 {
+		score += 0.40
+	}
+
+	// Recent tool call density — indicates an ongoing agentic workflow
+	switch {
+	case f.RecentToolCalls > 3:
+		score += 0.25
+	case f.RecentToolCalls > 0:
+		score += 0.10
+	}
+
+	// Conversation depth — accumulated context implies compound task
+	if f.ConversationDepth > 10 {
+		score += 0.10
+	}
+
+	// Cap at 1.0 to honor the [0, 1] contract even when multiple signals fire
+	// simultaneously (e.g., long message + code block + tool chain = 1.10 raw).
+	if score > 1.0 {
+		score = 1.0
+	}
+	return score
+}
diff --git a/pkg/routing/features.go b/pkg/routing/features.go
new file mode 100644
index 000000000..c371e21aa
--- /dev/null
+++ b/pkg/routing/features.go
@@ -0,0 +1,127 @@
+package routing
+
+import (
+	"strings"
+	"unicode/utf8"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// lookbackWindow is the number of recent history entries scanned for tool calls.
+// Six entries covers roughly one full tool-use round-trip (user → assistant+tool_call → tool_result → assistant).
+const lookbackWindow = 6
+
+// Features holds the structural signals extracted from a message and its session context.
+// Every dimension is language-agnostic by construction — no keyword or pattern matching
+// against natural-language content. This ensures consistent routing for all locales.
+type Features struct {
+	// TokenEstimate is a proxy for token count.
+	// CJK runes count as 1 token each; non-CJK runes as 0.25 tokens each.
+	// This avoids API calls while giving accurate estimates for all scripts.
+	TokenEstimate int
+
+	// CodeBlockCount is the number of fenced code blocks (``` pairs) in the message.
+	// Coding tasks almost always require the heavy model.
+	CodeBlockCount int
+
+	// RecentToolCalls is the count of tool_call messages in the last lookbackWindow
+	// history entries. A high density indicates an active agentic workflow.
+	RecentToolCalls int
+
+	// ConversationDepth is the total number of messages in the session history.
+	// Deep sessions tend to carry implicit complexity built up over many turns.
+	ConversationDepth int
+
+	// HasAttachments is true when the message appears to contain media (images,
+	// audio, video). Multi-modal inputs require vision-capable heavy models.
+	HasAttachments bool
+}
+
+// ExtractFeatures computes the structural feature vector for a message.
+// It is a pure function with no side effects and zero allocations beyond
+// the returned struct.
+func ExtractFeatures(msg string, history []providers.Message) Features {
+	return Features{
+		TokenEstimate:     estimateTokens(msg),
+		CodeBlockCount:    countCodeBlocks(msg),
+		RecentToolCalls:   countRecentToolCalls(history),
+		ConversationDepth: len(history),
+		HasAttachments:    hasAttachments(msg),
+	}
+}
+
+// estimateTokens returns a token count proxy that handles both CJK and Latin text.
+// CJK runes (U+2E80–U+9FFF, U+F900–U+FAFF, U+AC00–U+D7AF) map to roughly one
+// token each, while non-CJK runes average ~0.25 tokens/rune (≈4 chars per token
+// for English). Splitting the count this way avoids the 3x underestimation that a
+// flat rune_count/3 would produce for Chinese, Japanese, and Korean text.
+func estimateTokens(msg string) int {
+	total := utf8.RuneCountInString(msg)
+	if total == 0 {
+		return 0
+	}
+	cjk := 0
+	for _, r := range msg {
+		if r >= 0x2E80 && r <= 0x9FFF || r >= 0xF900 && r <= 0xFAFF || r >= 0xAC00 && r <= 0xD7AF {
+			cjk++
+		}
+	}
+	return cjk + (total-cjk)/4
+}
+
+// countCodeBlocks counts the number of complete fenced code blocks.
+// Each ``` delimiter increments a counter; pairs of delimiters form one block.
+// An unclosed opening fence (odd count) is treated as zero complete blocks
+// since it may just be an inline code span or a typo.
+func countCodeBlocks(msg string) int {
+	n := strings.Count(msg, "```")
+	return n / 2
+}
+
+// countRecentToolCalls counts messages with tool calls in the last lookbackWindow
+// entries of history. It examines the ToolCalls field rather than parsing
+// the content string, so it is robust to any message format.
+func countRecentToolCalls(history []providers.Message) int {
+	start := len(history) - lookbackWindow
+	if start < 0 {
+		start = 0
+	}
+
+	count := 0
+	for _, msg := range history[start:] {
+		if len(msg.ToolCalls) > 0 {
+			count += len(msg.ToolCalls)
+		}
+	}
+	return count
+}
+
+// hasAttachments returns true when the message content contains embedded media.
+// It checks for base64 data URIs (data:image/, data:audio/, data:video/) and
+// common image/audio URL extensions. This is intentionally conservative —
+// false negatives (missing an attachment) just mean the routing falls back to
+// the primary model anyway.
+func hasAttachments(msg string) bool {
+	lower := strings.ToLower(msg)
+
+	// Base64 data URIs embedded directly in the message
+	if strings.Contains(lower, "data:image/") ||
+		strings.Contains(lower, "data:audio/") ||
+		strings.Contains(lower, "data:video/") {
+		return true
+	}
+
+	// Common image/audio extensions in URLs or file references
+	mediaExts := []string{
+		".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp",
+		".mp3", ".wav", ".ogg", ".m4a", ".flac",
+		".mp4", ".avi", ".mov", ".webm",
+	}
+	for _, ext := range mediaExts {
+		if strings.Contains(lower, ext) {
+			return true
+		}
+	}
+
+	return false
+}
diff --git a/pkg/routing/route_test.go b/pkg/routing/route_test.go
index 8255db5f9..fdfc899f9 100644
--- a/pkg/routing/route_test.go
+++ b/pkg/routing/route_test.go
@@ -11,7 +11,7 @@ func testConfig(agents []config.AgentConfig, bindings []config.AgentBinding) *co
 		Agents: config.AgentsConfig{
 			Defaults: config.AgentDefaults{
 				Workspace: "/tmp/picoclaw-test",
-				Model:     "gpt-4",
+				ModelName: "gpt-4",
 			},
 			List: agents,
 		},
diff --git a/pkg/routing/router.go b/pkg/routing/router.go
new file mode 100644
index 000000000..b1fa347e9
--- /dev/null
+++ b/pkg/routing/router.go
@@ -0,0 +1,82 @@
+package routing
+
+import (
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// defaultThreshold is used when the config threshold is zero or negative.
+// At 0.35 a message needs at least one strong signal (code block, long text,
+// or an attachment) before the heavy model is chosen.
+const defaultThreshold = 0.35
+
+// RouterConfig holds the validated model routing settings.
+// It mirrors config.RoutingConfig but lives in pkg/routing to keep the
+// dependency graph simple: pkg/agent resolves config → routing, not the reverse.
+type RouterConfig struct {
+	// LightModel is the model_name (from model_list) used for simple tasks.
+	LightModel string
+
+	// Threshold is the complexity score cutoff in [0, 1].
+	// score >= Threshold → primary (heavy) model.
+	// score <  Threshold → light model.
+	Threshold float64
+}
+
+// Router selects the appropriate model tier for each incoming message.
+// It is safe for concurrent use from multiple goroutines.
+type Router struct {
+	cfg        RouterConfig
+	classifier Classifier
+}
+
+// New creates a Router with the given config and the default RuleClassifier.
+// If cfg.Threshold is zero or negative, defaultThreshold (0.35) is used.
+func New(cfg RouterConfig) *Router {
+	if cfg.Threshold <= 0 {
+		cfg.Threshold = defaultThreshold
+	}
+	return &Router{
+		cfg:        cfg,
+		classifier: &RuleClassifier{},
+	}
+}
+
+// newWithClassifier creates a Router with a custom Classifier.
+// Intended for unit tests that need to inject a deterministic scorer.
+func newWithClassifier(cfg RouterConfig, c Classifier) *Router {
+	if cfg.Threshold <= 0 {
+		cfg.Threshold = defaultThreshold
+	}
+	return &Router{cfg: cfg, classifier: c}
+}
+
+// SelectModel returns the model to use for this conversation turn along with
+// the computed complexity score (for logging and debugging).
+//
+//   - If score < cfg.Threshold: returns (cfg.LightModel, true, score)
+//   - Otherwise:               returns (primaryModel, false, score)
+//
+// The caller is responsible for resolving the returned model name into
+// provider candidates (see AgentInstance.LightCandidates).
+func (r *Router) SelectModel(
+	msg string,
+	history []providers.Message,
+	primaryModel string,
+) (model string, usedLight bool, score float64) {
+	features := ExtractFeatures(msg, history)
+	score = r.classifier.Score(features)
+	if score < r.cfg.Threshold {
+		return r.cfg.LightModel, true, score
+	}
+	return primaryModel, false, score
+}
+
+// LightModel returns the configured light model name.
+func (r *Router) LightModel() string {
+	return r.cfg.LightModel
+}
+
+// Threshold returns the complexity threshold in use.
+func (r *Router) Threshold() float64 {
+	return r.cfg.Threshold
+}
diff --git a/pkg/routing/router_test.go b/pkg/routing/router_test.go
new file mode 100644
index 000000000..2824d10ab
--- /dev/null
+++ b/pkg/routing/router_test.go
@@ -0,0 +1,414 @@
+package routing
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// ── ExtractFeatures ──────────────────────────────────────────────────────────
+
+func TestExtractFeatures_EmptyMessage(t *testing.T) {
+	f := ExtractFeatures("", nil)
+	if f.TokenEstimate != 0 {
+		t.Errorf("TokenEstimate: got %d, want 0", f.TokenEstimate)
+	}
+	if f.CodeBlockCount != 0 {
+		t.Errorf("CodeBlockCount: got %d, want 0", f.CodeBlockCount)
+	}
+	if f.RecentToolCalls != 0 {
+		t.Errorf("RecentToolCalls: got %d, want 0", f.RecentToolCalls)
+	}
+	if f.ConversationDepth != 0 {
+		t.Errorf("ConversationDepth: got %d, want 0", f.ConversationDepth)
+	}
+	if f.HasAttachments {
+		t.Error("HasAttachments: got true, want false")
+	}
+}
+
+func TestExtractFeatures_TokenEstimate(t *testing.T) {
+	// 30 ASCII runes: 0 CJK + 30/4 = 7 tokens
+	msg := strings.Repeat("a", 30)
+	f := ExtractFeatures(msg, nil)
+	if f.TokenEstimate != 7 {
+		t.Errorf("TokenEstimate: got %d, want 7", f.TokenEstimate)
+	}
+}
+
+func TestExtractFeatures_TokenEstimate_CJK(t *testing.T) {
+	// 9 CJK runes → 9 tokens (each CJK rune ≈ 1 token).
+	// Using a rune slice literal avoids CJK string literals in source.
+	msg := string([]rune{
+		0x4F60, 0x597D, 0x4E16, 0x754C,
+		0x4F60, 0x597D, 0x4E16, 0x754C,
+		0x4F60,
+	})
+	f := ExtractFeatures(msg, nil)
+	if f.TokenEstimate != 9 {
+		t.Errorf("CJK TokenEstimate: got %d, want 9", f.TokenEstimate)
+	}
+}
+
+func TestExtractFeatures_TokenEstimate_Mixed(t *testing.T) {
+	// Mixed: 4 CJK runes + 8 ASCII runes → 4 + 8/4 = 6 tokens.
+	msg := string([]rune{0x4F60, 0x597D, 0x4E16, 0x754C}) + "hello ok"
+	f := ExtractFeatures(msg, nil)
+	if f.TokenEstimate != 6 {
+		t.Errorf("Mixed TokenEstimate: got %d, want 6", f.TokenEstimate)
+	}
+}
+
+func TestExtractFeatures_CodeBlocks(t *testing.T) {
+	cases := []struct {
+		msg  string
+		want int
+	}{
+		{"no code here", 0},
+		{"```go\nfmt.Println()\n```", 1},
+		{"```python\npass\n```\n```js\nconsole.log()\n```", 2},
+		{"```unclosed", 0}, // odd number of fences = 0 complete blocks
+	}
+	for _, tc := range cases {
+		f := ExtractFeatures(tc.msg, nil)
+		if f.CodeBlockCount != tc.want {
+			t.Errorf("msg=%q: CodeBlockCount got %d, want %d", tc.msg, f.CodeBlockCount, tc.want)
+		}
+	}
+}
+
+func TestExtractFeatures_RecentToolCalls(t *testing.T) {
+	// History longer than lookbackWindow — only last lookbackWindow entries count.
+	history := make([]providers.Message, 10)
+	// Put 2 tool calls at positions 8 and 9 (within the last 6)
+	history[8] = providers.Message{Role: "assistant", ToolCalls: []providers.ToolCall{{Name: "exec"}}}
+	history[9] = providers.Message{
+		Role:      "assistant",
+		ToolCalls: []providers.ToolCall{{Name: "read_file"}, {Name: "write_file"}},
+	}
+	// Position 3 is outside the lookback window and must NOT be counted
+	history[3] = providers.Message{Role: "assistant", ToolCalls: []providers.ToolCall{{Name: "old_tool"}}}
+
+	f := ExtractFeatures("test", history)
+	// 1 (position 8) + 2 (position 9) = 3
+	if f.RecentToolCalls != 3 {
+		t.Errorf("RecentToolCalls: got %d, want 3", f.RecentToolCalls)
+	}
+}
+
+func TestExtractFeatures_ConversationDepth(t *testing.T) {
+	history := make([]providers.Message, 7)
+	f := ExtractFeatures("msg", history)
+	if f.ConversationDepth != 7 {
+		t.Errorf("ConversationDepth: got %d, want 7", f.ConversationDepth)
+	}
+}
+
+func TestExtractFeatures_HasAttachments_DataURI(t *testing.T) {
+	cases := []struct {
+		msg  string
+		want bool
+	}{
+		{"plain text", false},
+		{"here is an image: data:image/png;base64,abc123", true},
+		{"audio: data:audio/mp3;base64,xyz", true},
+		{"video: data:video/mp4;base64,xyz", true},
+	}
+	for _, tc := range cases {
+		f := ExtractFeatures(tc.msg, nil)
+		if f.HasAttachments != tc.want {
+			t.Errorf("msg=%q: HasAttachments got %v, want %v", tc.msg, f.HasAttachments, tc.want)
+		}
+	}
+}
+
+func TestExtractFeatures_HasAttachments_Extension(t *testing.T) {
+	cases := []struct {
+		msg  string
+		want bool
+	}{
+		{"check out photo.jpg", true},
+		{"see screenshot.png", true},
+		{"listen to audio.mp3", true},
+		{"watch clip.mp4", true},
+		{"just a .go file", false},
+		{"document.pdf", false}, // pdf is not in the media list
+	}
+	for _, tc := range cases {
+		f := ExtractFeatures(tc.msg, nil)
+		if f.HasAttachments != tc.want {
+			t.Errorf("msg=%q: HasAttachments got %v, want %v", tc.msg, f.HasAttachments, tc.want)
+		}
+	}
+}
+
+// ── RuleClassifier ───────────────────────────────────────────────────────────
+
+func TestRuleClassifier_ZeroFeatures(t *testing.T) {
+	c := &RuleClassifier{}
+	score := c.Score(Features{})
+	if score != 0.0 {
+		t.Errorf("zero features: got %f, want 0.0", score)
+	}
+}
+
+func TestRuleClassifier_AttachmentsHardGate(t *testing.T) {
+	c := &RuleClassifier{}
+	score := c.Score(Features{HasAttachments: true})
+	if score != 1.0 {
+		t.Errorf("attachments: got %f, want 1.0", score)
+	}
+}
+
+func TestRuleClassifier_CodeBlockAlone(t *testing.T) {
+	c := &RuleClassifier{}
+	// Code block alone = 0.40, above default threshold 0.35
+	score := c.Score(Features{CodeBlockCount: 1})
+	if score < 0.35 {
+		t.Errorf("code block: score %f is below default threshold 0.35", score)
+	}
+}
+
+func TestRuleClassifier_LongMessage(t *testing.T) {
+	c := &RuleClassifier{}
+	// >200 tokens = 0.35, exactly at default threshold → heavy
+	score := c.Score(Features{TokenEstimate: 250})
+	if score < 0.35 {
+		t.Errorf("long message: score %f is below default threshold 0.35", score)
+	}
+}
+
+func TestRuleClassifier_MediumMessage(t *testing.T) {
+	c := &RuleClassifier{}
+	// 50-200 tokens = 0.15, below threshold → light
+	score := c.Score(Features{TokenEstimate: 100})
+	if score >= 0.35 {
+		t.Errorf("medium message: score %f should be below default threshold 0.35", score)
+	}
+}
+
+func TestRuleClassifier_ShortMessage(t *testing.T) {
+	c := &RuleClassifier{}
+	// <50 tokens, no other signals = 0.0 → light
+	score := c.Score(Features{TokenEstimate: 10})
+	if score != 0.0 {
+		t.Errorf("short message: got %f, want 0.0", score)
+	}
+}
+
+func TestRuleClassifier_ToolCallDensity(t *testing.T) {
+	c := &RuleClassifier{}
+
+	scoreNone := c.Score(Features{RecentToolCalls: 0})
+	scoreLow := c.Score(Features{RecentToolCalls: 2})
+	scoreHigh := c.Score(Features{RecentToolCalls: 5})
+
+	if scoreNone != 0.0 {
+		t.Errorf("no tools: got %f, want 0.0", scoreNone)
+	}
+	if scoreLow <= scoreNone {
+		t.Errorf("low tools should score higher than none: %f vs %f", scoreLow, scoreNone)
+	}
+	if scoreHigh <= scoreLow {
+		t.Errorf("high tools should score higher than low: %f vs %f", scoreHigh, scoreLow)
+	}
+}
+
+func TestRuleClassifier_DeepConversation(t *testing.T) {
+	c := &RuleClassifier{}
+	shallow := c.Score(Features{ConversationDepth: 5})
+	deep := c.Score(Features{ConversationDepth: 15})
+	if deep <= shallow {
+		t.Errorf("deep conversation should score higher: %f vs %f", deep, shallow)
+	}
+}
+
+func TestRuleClassifier_ScoreDoesNotExceedOne(t *testing.T) {
+	c := &RuleClassifier{}
+	// Max all signals simultaneously
+	f := Features{
+		TokenEstimate:     500,
+		CodeBlockCount:    3,
+		RecentToolCalls:   10,
+		ConversationDepth: 20,
+	}
+	score := c.Score(f)
+	if score > 1.0 {
+		t.Errorf("score %f exceeds 1.0", score)
+	}
+}
+
+// ── Router ───────────────────────────────────────────────────────────────────
+
+func TestRouter_DefaultThreshold(t *testing.T) {
+	r := New(RouterConfig{LightModel: "gemini-flash"})
+	if r.Threshold() != defaultThreshold {
+		t.Errorf("default threshold: got %f, want %f", r.Threshold(), defaultThreshold)
+	}
+}
+
+func TestRouter_NegativeThresholdFallsBackToDefault(t *testing.T) {
+	r := New(RouterConfig{LightModel: "gemini-flash", Threshold: -0.1})
+	if r.Threshold() != defaultThreshold {
+		t.Errorf("negative threshold: got %f, want %f", r.Threshold(), defaultThreshold)
+	}
+}
+
+func TestRouter_SelectModel_SimpleMessageUsesLight(t *testing.T) {
+	r := New(RouterConfig{LightModel: "gemini-flash", Threshold: 0.35})
+	msg := "hi"
+	model, usedLight, _ := r.SelectModel(msg, nil, "claude-sonnet-4-6")
+	if !usedLight {
+		t.Error("simple message: expected light model to be selected")
+	}
+	if model != "gemini-flash" {
+		t.Errorf("simple message: model got %q, want %q", model, "gemini-flash")
+	}
+}
+
+func TestRouter_SelectModel_CodeBlockUsesPrimary(t *testing.T) {
+	r := New(RouterConfig{LightModel: "gemini-flash", Threshold: 0.35})
+	msg := "```go\nfmt.Println(\"hello\")\n```"
+	model, usedLight, _ := r.SelectModel(msg, nil, "claude-sonnet-4-6")
+	if usedLight {
+		t.Error("code block: expected primary model to be selected")
+	}
+	if model != "claude-sonnet-4-6" {
+		t.Errorf("code block: model got %q, want %q", model, "claude-sonnet-4-6")
+	}
+}
+
+func TestRouter_SelectModel_AttachmentUsesPrimary(t *testing.T) {
+	r := New(RouterConfig{LightModel: "gemini-flash", Threshold: 0.35})
+	msg := "can you analyze this? data:image/png;base64,abc123"
+	model, usedLight, _ := r.SelectModel(msg, nil, "claude-sonnet-4-6")
+	if usedLight {
+		t.Error("attachment: expected primary model to be selected")
+	}
+	if model != "claude-sonnet-4-6" {
+		t.Errorf("attachment: model got %q, want %q", model, "claude-sonnet-4-6")
+	}
+}
+
+func TestRouter_SelectModel_LongMessageUsesPrimary(t *testing.T) {
+	r := New(RouterConfig{LightModel: "gemini-flash", Threshold: 0.35})
+	// >200 token estimate: 210 * 3 = 630 chars
+	msg := strings.Repeat("word ", 210)
+	model, usedLight, _ := r.SelectModel(msg, nil, "claude-sonnet-4-6")
+	if usedLight {
+		t.Error("long message: expected primary model to be selected")
+	}
+	if model != "claude-sonnet-4-6" {
+		t.Errorf("long message: model got %q, want %q", model, "claude-sonnet-4-6")
+	}
+}
+
+func TestRouter_SelectModel_DeepToolChainUsesLight(t *testing.T) {
+	// Tool calls alone (0.25) don't cross the 0.35 threshold — acceptable behavior.
+	// Routing is conservative: only promote to heavy when the signal is unambiguous.
+	r := New(RouterConfig{LightModel: "gemini-flash", Threshold: 0.35})
+	history := []providers.Message{
+		{Role: "assistant", ToolCalls: []providers.ToolCall{{Name: "read_file"}, {Name: "write_file"}}},
+		{Role: "assistant", ToolCalls: []providers.ToolCall{{Name: "exec"}, {Name: "search"}}},
+	}
+	msg := "ok"
+	_, usedLight, _ := r.SelectModel(msg, history, "claude-sonnet-4-6")
+	if !usedLight {
+		t.Error("short message + moderate tool calls: expected light model (score 0.20 < 0.35)")
+	}
+}
+
+func TestRouter_SelectModel_ToolChainPlusMediumUsesHeavy(t *testing.T) {
+	// Tool calls (0.25) + medium message (0.15) = 0.40 >= 0.35 → heavy
+	r := New(RouterConfig{LightModel: "gemini-flash", Threshold: 0.35})
+	history := []providers.Message{
+		{Role: "assistant", ToolCalls: []providers.ToolCall{
+			{Name: "a"}, {Name: "b"}, {Name: "c"}, {Name: "d"},
+		}},
+	}
+	// ~55 tokens * 3 = 165 chars
+	msg := strings.Repeat("word ", 55)
+	_, usedLight, _ := r.SelectModel(msg, history, "claude-sonnet-4-6")
+	if usedLight {
+		t.Error("tool chain + medium message: expected primary model (score >= 0.35)")
+	}
+}
+
+func TestRouter_SelectModel_CustomThreshold(t *testing.T) {
+	// Very low threshold: even a short message triggers heavy model
+	r := New(RouterConfig{LightModel: "gemini-flash", Threshold: 0.05})
+	msg := strings.Repeat("word ", 55) // medium message → 0.15 >= 0.05
+	_, usedLight, _ := r.SelectModel(msg, nil, "claude-sonnet-4-6")
+	if usedLight {
+		t.Error("low threshold: medium message should use primary model")
+	}
+}
+
+func TestRouter_SelectModel_HighThreshold(t *testing.T) {
+	// Very high threshold: even code blocks route to light
+	r := New(RouterConfig{LightModel: "gemini-flash", Threshold: 0.99})
+	msg := "```go\nfmt.Println()\n```"
+	_, usedLight, _ := r.SelectModel(msg, nil, "claude-sonnet-4-6")
+	if !usedLight {
+		t.Error("very high threshold: code block (0.40) should route to light model")
+	}
+}
+
+func TestRouter_LightModel(t *testing.T) {
+	r := New(RouterConfig{LightModel: "my-fast-model", Threshold: 0.35})
+	if r.LightModel() != "my-fast-model" {
+		t.Errorf("LightModel: got %q, want %q", r.LightModel(), "my-fast-model")
+	}
+}
+
+// ── newWithClassifier (internal testing hook) ─────────────────────────────────
+
+type fixedScoreClassifier struct{ score float64 }
+
+func (f *fixedScoreClassifier) Score(_ Features) float64 { return f.score }
+
+func TestRouter_CustomClassifier_LowScore_SelectsLight(t *testing.T) {
+	r := newWithClassifier(
+		RouterConfig{LightModel: "light", Threshold: 0.5},
+		&fixedScoreClassifier{score: 0.2},
+	)
+	_, usedLight, _ := r.SelectModel("anything", nil, "heavy")
+	if !usedLight {
+		t.Error("low score with custom classifier: expected light model")
+	}
+}
+
+func TestRouter_CustomClassifier_HighScore_SelectsPrimary(t *testing.T) {
+	r := newWithClassifier(
+		RouterConfig{LightModel: "light", Threshold: 0.5},
+		&fixedScoreClassifier{score: 0.8},
+	)
+	_, usedLight, _ := r.SelectModel("anything", nil, "heavy")
+	if usedLight {
+		t.Error("high score with custom classifier: expected primary model")
+	}
+}
+
+func TestRouter_CustomClassifier_ExactThreshold_SelectsPrimary(t *testing.T) {
+	// score == threshold → primary (uses >= comparison)
+	r := newWithClassifier(
+		RouterConfig{LightModel: "light", Threshold: 0.5},
+		&fixedScoreClassifier{score: 0.5},
+	)
+	_, usedLight, _ := r.SelectModel("anything", nil, "heavy")
+	if usedLight {
+		t.Error("score == threshold: expected primary model (>= threshold → primary)")
+	}
+}
+
+func TestRouter_SelectModel_ReturnsScore(t *testing.T) {
+	r := newWithClassifier(
+		RouterConfig{LightModel: "light", Threshold: 0.5},
+		&fixedScoreClassifier{score: 0.42},
+	)
+	_, _, score := r.SelectModel("anything", nil, "heavy")
+	if score != 0.42 {
+		t.Errorf("score: got %f, want 0.42", score)
+	}
+}
diff --git a/pkg/session/jsonl_backend.go b/pkg/session/jsonl_backend.go
new file mode 100644
index 000000000..7f470de15
--- /dev/null
+++ b/pkg/session/jsonl_backend.go
@@ -0,0 +1,81 @@
+package session
+
+import (
+	"context"
+	"log"
+
+	"github.com/sipeed/picoclaw/pkg/memory"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// JSONLBackend adapts a memory.Store into the SessionStore interface.
+// Write errors are logged rather than returned, matching the fire-and-forget
+// contract of SessionManager that the agent loop relies on.
+type JSONLBackend struct {
+	store memory.Store
+}
+
+// NewJSONLBackend wraps a memory.Store for use as a SessionStore.
+func NewJSONLBackend(store memory.Store) *JSONLBackend {
+	return &JSONLBackend{store: store}
+}
+
+func (b *JSONLBackend) AddMessage(sessionKey, role, content string) {
+	if err := b.store.AddMessage(context.Background(), sessionKey, role, content); err != nil {
+		log.Printf("session: add message: %v", err)
+	}
+}
+
+func (b *JSONLBackend) AddFullMessage(sessionKey string, msg providers.Message) {
+	if err := b.store.AddFullMessage(context.Background(), sessionKey, msg); err != nil {
+		log.Printf("session: add full message: %v", err)
+	}
+}
+
+func (b *JSONLBackend) GetHistory(key string) []providers.Message {
+	msgs, err := b.store.GetHistory(context.Background(), key)
+	if err != nil {
+		log.Printf("session: get history: %v", err)
+		return []providers.Message{}
+	}
+	return msgs
+}
+
+func (b *JSONLBackend) GetSummary(key string) string {
+	summary, err := b.store.GetSummary(context.Background(), key)
+	if err != nil {
+		log.Printf("session: get summary: %v", err)
+		return ""
+	}
+	return summary
+}
+
+func (b *JSONLBackend) SetSummary(key, summary string) {
+	if err := b.store.SetSummary(context.Background(), key, summary); err != nil {
+		log.Printf("session: set summary: %v", err)
+	}
+}
+
+func (b *JSONLBackend) SetHistory(key string, history []providers.Message) {
+	if err := b.store.SetHistory(context.Background(), key, history); err != nil {
+		log.Printf("session: set history: %v", err)
+	}
+}
+
+func (b *JSONLBackend) TruncateHistory(key string, keepLast int) {
+	if err := b.store.TruncateHistory(context.Background(), key, keepLast); err != nil {
+		log.Printf("session: truncate history: %v", err)
+	}
+}
+
+// Save persists session state. Since the JSONL store fsyncs every write
+// immediately, the data is already durable. Save runs compaction to reclaim
+// space from logically truncated messages (no-op when there are none).
+func (b *JSONLBackend) Save(key string) error {
+	return b.store.Compact(context.Background(), key)
+}
+
+// Close releases resources held by the underlying store.
+func (b *JSONLBackend) Close() error {
+	return b.store.Close()
+}
diff --git a/pkg/session/jsonl_backend_test.go b/pkg/session/jsonl_backend_test.go
new file mode 100644
index 000000000..40fa019cb
--- /dev/null
+++ b/pkg/session/jsonl_backend_test.go
@@ -0,0 +1,179 @@
+package session_test
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/memory"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/session"
+)
+
+// Compile-time interface satisfaction checks.
+var (
+	_ session.SessionStore = (*session.SessionManager)(nil)
+	_ session.SessionStore = (*session.JSONLBackend)(nil)
+)
+
+func newBackend(t *testing.T) *session.JSONLBackend {
+	t.Helper()
+	store, err := memory.NewJSONLStore(t.TempDir())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { store.Close() })
+	return session.NewJSONLBackend(store)
+}
+
+func TestJSONLBackend_AddAndGetHistory(t *testing.T) {
+	b := newBackend(t)
+
+	b.AddMessage("s1", "user", "hello")
+	b.AddMessage("s1", "assistant", "hi")
+
+	history := b.GetHistory("s1")
+	if len(history) != 2 {
+		t.Fatalf("got %d messages, want 2", len(history))
+	}
+	if history[0].Role != "user" || history[0].Content != "hello" {
+		t.Errorf("msg[0] = %+v", history[0])
+	}
+	if history[1].Role != "assistant" || history[1].Content != "hi" {
+		t.Errorf("msg[1] = %+v", history[1])
+	}
+}
+
+func TestJSONLBackend_AddFullMessage(t *testing.T) {
+	b := newBackend(t)
+
+	msg := providers.Message{
+		Role:    "assistant",
+		Content: "done",
+		ToolCalls: []providers.ToolCall{
+			{ID: "tc1", Function: &providers.FunctionCall{Name: "read_file", Arguments: `{"path":"x"}`}},
+		},
+	}
+	b.AddFullMessage("s1", msg)
+
+	history := b.GetHistory("s1")
+	if len(history) != 1 {
+		t.Fatalf("got %d, want 1", len(history))
+	}
+	if len(history[0].ToolCalls) != 1 || history[0].ToolCalls[0].ID != "tc1" {
+		t.Errorf("tool calls = %+v", history[0].ToolCalls)
+	}
+}
+
+func TestJSONLBackend_Summary(t *testing.T) {
+	b := newBackend(t)
+
+	if got := b.GetSummary("s1"); got != "" {
+		t.Errorf("got %q, want empty", got)
+	}
+
+	b.SetSummary("s1", "test summary")
+	if got := b.GetSummary("s1"); got != "test summary" {
+		t.Errorf("got %q, want %q", got, "test summary")
+	}
+}
+
+func TestJSONLBackend_TruncateAndSave(t *testing.T) {
+	b := newBackend(t)
+
+	for i := 0; i < 10; i++ {
+		b.AddMessage("s1", "user", fmt.Sprintf("msg %d", i))
+	}
+	b.TruncateHistory("s1", 3)
+
+	history := b.GetHistory("s1")
+	if len(history) != 3 {
+		t.Fatalf("got %d, want 3", len(history))
+	}
+	if history[0].Content != "msg 7" {
+		t.Errorf("got %q, want %q", history[0].Content, "msg 7")
+	}
+
+	// Save triggers compaction.
+	if err := b.Save("s1"); err != nil {
+		t.Fatal(err)
+	}
+
+	// Messages still accessible after compaction.
+	history = b.GetHistory("s1")
+	if len(history) != 3 {
+		t.Fatalf("after save: got %d, want 3", len(history))
+	}
+}
+
+func TestJSONLBackend_SetHistory(t *testing.T) {
+	b := newBackend(t)
+	b.AddMessage("s1", "user", "old")
+
+	b.SetHistory("s1", []providers.Message{
+		{Role: "user", Content: "new1"},
+		{Role: "assistant", Content: "new2"},
+	})
+
+	history := b.GetHistory("s1")
+	if len(history) != 2 {
+		t.Fatalf("got %d, want 2", len(history))
+	}
+	if history[0].Content != "new1" {
+		t.Errorf("got %q, want %q", history[0].Content, "new1")
+	}
+}
+
+func TestJSONLBackend_EmptySession(t *testing.T) {
+	b := newBackend(t)
+
+	history := b.GetHistory("nonexistent")
+	if history == nil {
+		t.Fatal("got nil, want empty slice")
+	}
+	if len(history) != 0 {
+		t.Errorf("got %d, want 0", len(history))
+	}
+}
+
+func TestJSONLBackend_SessionIsolation(t *testing.T) {
+	b := newBackend(t)
+	b.AddMessage("s1", "user", "session1")
+	b.AddMessage("s2", "user", "session2")
+
+	h1 := b.GetHistory("s1")
+	h2 := b.GetHistory("s2")
+
+	if len(h1) != 1 || h1[0].Content != "session1" {
+		t.Errorf("s1: %+v", h1)
+	}
+	if len(h2) != 1 || h2[0].Content != "session2" {
+		t.Errorf("s2: %+v", h2)
+	}
+}
+
+func TestJSONLBackend_SummarizeFlow(t *testing.T) {
+	// Simulates the real summarization flow in the agent loop:
+	// SetSummary → TruncateHistory → Save
+	b := newBackend(t)
+
+	for i := 0; i < 20; i++ {
+		b.AddMessage("s1", "user", fmt.Sprintf("msg %d", i))
+	}
+
+	b.SetSummary("s1", "conversation about testing")
+	b.TruncateHistory("s1", 4)
+	if err := b.Save("s1"); err != nil {
+		t.Fatal(err)
+	}
+
+	if got := b.GetSummary("s1"); got != "conversation about testing" {
+		t.Errorf("summary = %q", got)
+	}
+	history := b.GetHistory("s1")
+	if len(history) != 4 {
+		t.Fatalf("got %d messages, want 4", len(history))
+	}
+	if history[0].Content != "msg 16" {
+		t.Errorf("first message = %q, want %q", history[0].Content, "msg 16")
+	}
+}
diff --git a/pkg/session/manager.go b/pkg/session/manager.go
index 08f0b0ad2..ef720b7c5 100644
--- a/pkg/session/manager.go
+++ b/pkg/session/manager.go
@@ -32,7 +32,7 @@ func NewSessionManager(storage string) *SessionManager {
 	}
 
 	if storage != "" {
-		os.MkdirAll(storage, 0o755)
+		os.MkdirAll(storage, 0o700)
 		sm.loadSessions()
 	}
 
@@ -146,12 +146,15 @@ func (sm *SessionManager) TruncateHistory(key string, keepLast int) {
 }
 
 // sanitizeFilename converts a session key into a cross-platform safe filename.
-// Session keys use "channel:chatID" (e.g. "telegram:123456") but ':' is the
-// volume separator on Windows, so filepath.Base would misinterpret the key.
-// We replace it with '_'. The original key is preserved inside the JSON file,
-// so loadSessions still maps back to the right in-memory key.
+// Replaces ':' with '_' (session key separator) and '/' and '\' with '_' so
+// composite IDs (e.g. Telegram forum "chatID/threadID") do not create
+// subdirectories or break on Windows. The original key is preserved inside
+// the JSON file, so loadSessions still maps back to the right in-memory key.
 func sanitizeFilename(key string) string {
-	return strings.ReplaceAll(key, ":", "_")
+	s := strings.ReplaceAll(key, ":", "_")
+	s = strings.ReplaceAll(s, "/", "_")
+	s = strings.ReplaceAll(s, "\\", "_")
+	return s
 }
 
 func (sm *SessionManager) Save(key string) error {
@@ -162,10 +165,9 @@ func (sm *SessionManager) Save(key string) error {
 	filename := sanitizeFilename(key)
 
 	// filepath.IsLocal rejects empty names, "..", absolute paths, and
-	// OS-reserved device names (NUL, COM1 … on Windows).
-	// The extra checks reject "." and any directory separators so that
-	// the session file is always written directly inside sm.storage.
-	if filename == "." || !filepath.IsLocal(filename) || strings.ContainsAny(filename, `/\`) {
+	// OS-reserved device names (NUL, COM1 … on Windows). sanitizeFilename
+	// already replaced '/' and '\' with '_', so no subdirs are created.
+	if filename == "." || !filepath.IsLocal(filename) {
 		return os.ErrInvalid
 	}
 
@@ -214,7 +216,7 @@ func (sm *SessionManager) Save(key string) error {
 		_ = tmpFile.Close()
 		return err
 	}
-	if err := tmpFile.Chmod(0o644); err != nil {
+	if err := tmpFile.Chmod(0o600); err != nil {
 		_ = tmpFile.Close()
 		return err
 	}
@@ -265,6 +267,12 @@ func (sm *SessionManager) loadSessions() error {
 	return nil
 }
 
+// Close is a no-op for the in-memory SessionManager; it satisfies the
+// SessionStore interface so callers can release resources uniformly.
+func (sm *SessionManager) Close() error {
+	return nil
+}
+
 // SetHistory updates the messages of a session.
 func (sm *SessionManager) SetHistory(key string, history []providers.Message) {
 	sm.mu.Lock()
diff --git a/pkg/session/manager_test.go b/pkg/session/manager_test.go
index 5ef5f4349..bc5615966 100644
--- a/pkg/session/manager_test.go
+++ b/pkg/session/manager_test.go
@@ -17,6 +17,7 @@ func TestSanitizeFilename(t *testing.T) {
 		{"slack:C01234", "slack_C01234"},
 		{"no-colons-here", "no-colons-here"},
 		{"multiple:colons:here", "multiple_colons_here"},
+		{"agent:main:telegram:group:-1003822706455/12", "agent_main_telegram_group_-1003822706455_12"},
 	}
 
 	for _, tt := range tests {
@@ -64,11 +65,21 @@ func TestSave_RejectsPathTraversal(t *testing.T) {
 	tmpDir := t.TempDir()
 	sm := NewSessionManager(tmpDir)
 
-	badKeys := []string{"", ".", "..", "foo/bar", "foo\\bar"}
+	// Invalid names that must still be rejected.
+	badKeys := []string{"", ".", ".."}
 	for _, key := range badKeys {
 		sm.GetOrCreate(key)
 		if err := sm.Save(key); err == nil {
 			t.Errorf("Save(%q) should have failed but didn't", key)
 		}
 	}
+
+	// Keys containing path separators are sanitized (no subdirs created).
+	sm.GetOrCreate("foo/bar")
+	if err := sm.Save("foo/bar"); err != nil {
+		t.Fatalf("Save(\"foo/bar\") after sanitize should succeed: %v", err)
+	}
+	if _, err := os.Stat(filepath.Join(tmpDir, "foo_bar.json")); os.IsNotExist(err) {
+		t.Errorf("expected foo_bar.json in storage (sanitized from foo/bar)")
+	}
 }
diff --git a/pkg/session/session_store.go b/pkg/session/session_store.go
new file mode 100644
index 000000000..1d1a2f967
--- /dev/null
+++ b/pkg/session/session_store.go
@@ -0,0 +1,32 @@
+package session
+
+import "github.com/sipeed/picoclaw/pkg/providers"
+
+// SessionStore defines the persistence operations used by the agent loop.
+// Both SessionManager (legacy JSON backend) and JSONLBackend satisfy this
+// interface, allowing the storage layer to be swapped without touching the
+// agent loop code.
+//
+// Write methods (Add*, Set*, Truncate*) are fire-and-forget: they do not
+// return errors. Implementations should log failures internally. This
+// matches the original SessionManager contract that the agent loop relies on.
+type SessionStore interface {
+	// AddMessage appends a simple role/content message to the session.
+	AddMessage(sessionKey, role, content string)
+	// AddFullMessage appends a complete message including tool calls.
+	AddFullMessage(sessionKey string, msg providers.Message)
+	// GetHistory returns the full message history for the session.
+	GetHistory(key string) []providers.Message
+	// GetSummary returns the conversation summary, or "" if none.
+	GetSummary(key string) string
+	// SetSummary replaces the conversation summary.
+	SetSummary(key, summary string)
+	// SetHistory replaces the full message history.
+	SetHistory(key string, history []providers.Message)
+	// TruncateHistory keeps only the last keepLast messages.
+	TruncateHistory(key string, keepLast int)
+	// Save persists any pending state to durable storage.
+	Save(key string) error
+	// Close releases resources held by the store.
+	Close() error
+}
diff --git a/pkg/skills/clawhub_registry.go b/pkg/skills/clawhub_registry.go
index f78197bbe..bd4bed8fb 100644
--- a/pkg/skills/clawhub_registry.go
+++ b/pkg/skills/clawhub_registry.go
@@ -259,15 +259,7 @@ func (c *ClawHubRegistry) DownloadAndInstall(
 	}
 	u.RawQuery = q.Encode()
 
-	req, err := http.NewRequestWithContext(ctx, "GET", u.String(), nil)
-	if err != nil {
-		return nil, fmt.Errorf("failed to create request: %w", err)
-	}
-	if c.authToken != "" {
-		req.Header.Set("Authorization", "Bearer "+c.authToken)
-	}
-
-	tmpPath, err := utils.DownloadToFile(ctx, c.client, req, int64(c.maxZipSize))
+	tmpPath, err := c.downloadToTempFileWithRetry(ctx, u.String())
 	if err != nil {
 		return nil, fmt.Errorf("download failed: %w", err)
 	}
@@ -284,17 +276,12 @@ func (c *ClawHubRegistry) DownloadAndInstall(
 // --- HTTP helper ---
 
 func (c *ClawHubRegistry) doGet(ctx context.Context, urlStr string) ([]byte, error) {
-	req, err := http.NewRequestWithContext(ctx, "GET", urlStr, nil)
+	req, err := c.newGetRequest(ctx, urlStr, "application/json")
 	if err != nil {
 		return nil, err
 	}
 
-	req.Header.Set("Accept", "application/json")
-	if c.authToken != "" {
-		req.Header.Set("Authorization", "Bearer "+c.authToken)
-	}
-
-	resp, err := c.client.Do(req)
+	resp, err := utils.DoRequestWithRetry(c.client, req)
 	if err != nil {
 		return nil, err
 	}
@@ -312,3 +299,64 @@ func (c *ClawHubRegistry) doGet(ctx context.Context, urlStr string) ([]byte, err
 
 	return body, nil
 }
+
+func (c *ClawHubRegistry) newGetRequest(ctx context.Context, urlStr, accept string) (*http.Request, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, urlStr, nil)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Accept", accept)
+	if c.authToken != "" {
+		req.Header.Set("Authorization", "Bearer "+c.authToken)
+	}
+	return req, nil
+}
+
+func (c *ClawHubRegistry) downloadToTempFileWithRetry(ctx context.Context, urlStr string) (string, error) {
+	req, err := c.newGetRequest(ctx, urlStr, "application/zip")
+	if err != nil {
+		return "", err
+	}
+
+	resp, err := utils.DoRequestWithRetry(c.client, req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		errBody := make([]byte, 512)
+		n, _ := io.ReadFull(resp.Body, errBody)
+		return "", fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(errBody[:n]))
+	}
+
+	tmpFile, err := os.CreateTemp("", "picoclaw-dl-*")
+	if err != nil {
+		return "", fmt.Errorf("failed to create temp file: %w", err)
+	}
+	tmpPath := tmpFile.Name()
+
+	cleanup := func() {
+		_ = tmpFile.Close()
+		_ = os.Remove(tmpPath)
+	}
+
+	src := io.LimitReader(resp.Body, int64(c.maxZipSize)+1)
+	written, err := io.Copy(tmpFile, src)
+	if err != nil {
+		cleanup()
+		return "", fmt.Errorf("download write failed: %w", err)
+	}
+
+	if written > int64(c.maxZipSize) {
+		cleanup()
+		return "", fmt.Errorf("download too large: %d bytes (max %d)", written, c.maxZipSize)
+	}
+
+	if err := tmpFile.Close(); err != nil {
+		_ = os.Remove(tmpPath)
+		return "", fmt.Errorf("failed to close temp file: %w", err)
+	}
+
+	return tmpPath, nil
+}
diff --git a/pkg/skills/clawhub_registry_test.go b/pkg/skills/clawhub_registry_test.go
index 65ee638da..055da22dc 100644
--- a/pkg/skills/clawhub_registry_test.go
+++ b/pkg/skills/clawhub_registry_test.go
@@ -54,6 +54,39 @@ func TestClawHubRegistrySearch(t *testing.T) {
 	assert.Equal(t, "clawhub", results[0].RegistryName)
 }
 
+func TestClawHubRegistrySearchRetries429(t *testing.T) {
+	attempts := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		attempts++
+		if attempts == 1 {
+			w.Header().Set("Retry-After", "0")
+			w.WriteHeader(http.StatusTooManyRequests)
+			w.Write([]byte("rate limited"))
+			return
+		}
+
+		slug := "github"
+		name := "GitHub Integration"
+		summary := "Interact with GitHub repos"
+		version := "1.0.0"
+
+		json.NewEncoder(w).Encode(clawhubSearchResponse{
+			Results: []clawhubSearchResult{
+				{Score: 0.95, Slug: &slug, DisplayName: &name, Summary: &summary, Version: &version},
+			},
+		})
+	}))
+	defer srv.Close()
+
+	reg := newTestRegistry(srv.URL, "")
+	results, err := reg.Search(context.Background(), "github", 5)
+
+	require.NoError(t, err)
+	require.Len(t, results, 1)
+	assert.Equal(t, 2, attempts)
+	assert.Equal(t, "github", results[0].Slug)
+}
+
 func TestClawHubRegistryGetSkillMeta(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		assert.Equal(t, "/api/v1/skills/github", r.URL.Path)
@@ -137,6 +170,54 @@ func TestClawHubRegistryDownloadAndInstall(t *testing.T) {
 	assert.Contains(t, string(readmeContent), "# Test Skill")
 }
 
+func TestClawHubRegistryDownloadAndInstallRetries429(t *testing.T) {
+	zipBuf := createTestZip(t, map[string]string{
+		"SKILL.md": "---\nname: retry-skill\ndescription: A test\n---\nHello skill",
+	})
+
+	downloadAttempts := 0
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/api/v1/skills/retry-skill":
+			json.NewEncoder(w).Encode(clawhubSkillResponse{
+				Slug:          "retry-skill",
+				DisplayName:   "Retry Skill",
+				Summary:       "A retry test skill",
+				LatestVersion: &clawhubVersionInfo{Version: "1.0.0"},
+			})
+		case "/api/v1/download":
+			downloadAttempts++
+			if downloadAttempts == 1 {
+				w.Header().Set("Retry-After", "0")
+				w.WriteHeader(http.StatusTooManyRequests)
+				w.Write([]byte("rate limited"))
+				return
+			}
+			assert.Equal(t, "retry-skill", r.URL.Query().Get("slug"))
+			w.Header().Set("Content-Type", "application/zip")
+			w.Write(zipBuf)
+		default:
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	defer srv.Close()
+
+	tmpDir := t.TempDir()
+	targetDir := filepath.Join(tmpDir, "retry-skill")
+
+	reg := newTestRegistry(srv.URL, "")
+	result, err := reg.DownloadAndInstall(context.Background(), "retry-skill", "", targetDir)
+
+	require.NoError(t, err)
+	require.NotNil(t, result)
+	assert.Equal(t, "1.0.0", result.Version)
+	assert.Equal(t, 2, downloadAttempts)
+
+	skillContent, err := os.ReadFile(filepath.Join(targetDir, "SKILL.md"))
+	require.NoError(t, err)
+	assert.Contains(t, string(skillContent), "Hello skill")
+}
+
 func TestClawHubRegistryAuthToken(t *testing.T) {
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		authHeader := r.Header.Get("Authorization")
diff --git a/pkg/skills/installer.go b/pkg/skills/installer.go
index c9f19f25d..f6cdee3a6 100644
--- a/pkg/skills/installer.go
+++ b/pkg/skills/installer.go
@@ -2,80 +2,289 @@ package skills
 
 import (
 	"context"
+	"encoding/json"
 	"fmt"
-	"io"
 	"net/http"
+	"net/url"
 	"os"
+	"path"
 	"path/filepath"
+	"strings"
 	"time"
 
-	"github.com/sipeed/picoclaw/pkg/fileutil"
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
-type SkillInstaller struct {
-	workspace string
+// GitHubContent represents a file or directory in GitHub API response
+type GitHubContent struct {
+	Name        string `json:"name"`
+	Path        string `json:"path"`
+	Type        string `json:"type"` // "file" or "dir"
+	DownloadURL string `json:"download_url"`
+	URL         string `json:"url"` // API URL for subdirectories
 }
 
-func NewSkillInstaller(workspace string) *SkillInstaller {
-	return &SkillInstaller{
-		workspace: workspace,
+// GitHubRef represents a parsed GitHub reference
+type GitHubRef struct {
+	Owner    string // Repository owner
+	RepoName string // Repository name
+	Ref      string // Git reference (branch, tag, or commit)
+	SubPath  string // Path within the repository
+}
+
+type SkillInstaller struct {
+	workspace   string
+	client      *http.Client
+	githubToken string
+	proxy       string
+}
+
+// NewSkillInstaller creates a new skill installer.
+// proxy is an optional HTTP/HTTPS/SOCKS5 proxy URL for downloading skills.
+func NewSkillInstaller(workspace, githubToken, proxy string) (*SkillInstaller, error) {
+	client, err := utils.CreateHTTPClient(proxy, 15*time.Second)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create HTTP client: %w", err)
 	}
+
+	return &SkillInstaller{
+		workspace:   workspace,
+		client:      client,
+		githubToken: githubToken,
+		proxy:       proxy,
+	}, nil
+}
+
+// parseGitHubRef parses a GitHub reference.
+// Supports: "owner/repo", "owner/repo/path", or full URL like "https://github.com/owner/repo/tree/ref/path"
+func parseGitHubRef(repo string) (GitHubRef, error) {
+	repo = strings.TrimSpace(repo)
+
+	// Handle full URL
+	if strings.HasPrefix(repo, "http://") || strings.HasPrefix(repo, "https://") {
+		u, err := url.Parse(repo)
+		if err != nil {
+			return GitHubRef{}, fmt.Errorf("invalid URL: %w", err)
+		}
+		parts := strings.Split(strings.Trim(u.Path, "/"), "/")
+		if len(parts) < 2 {
+			return GitHubRef{}, fmt.Errorf("invalid GitHub URL")
+		}
+		ref := GitHubRef{
+			Owner:    parts[0],
+			RepoName: parts[1],
+			Ref:      "main",
+		}
+		// Look for /tree/ or /blob/ in the path
+		for i := 2; i < len(parts); i++ {
+			if parts[i] == "tree" || parts[i] == "blob" {
+				if i+1 < len(parts) {
+					ref.Ref = parts[i+1]
+					ref.SubPath = strings.Join(parts[i+2:], "/")
+				}
+				break
+			}
+		}
+		return ref, nil
+	}
+
+	// Handle shorthand format
+	parts := strings.Split(strings.Trim(repo, "/"), "/")
+	if len(parts) < 2 {
+		return GitHubRef{}, fmt.Errorf("invalid format %q: expected 'owner/repo'", repo)
+	}
+	ref := GitHubRef{
+		Owner:    parts[0],
+		RepoName: parts[1],
+		Ref:      "main",
+	}
+	if len(parts) > 2 {
+		ref.SubPath = strings.Join(parts[2:], "/")
+	}
+	return ref, nil
 }
 
 func (si *SkillInstaller) InstallFromGitHub(ctx context.Context, repo string) error {
-	skillDir := filepath.Join(si.workspace, "skills", filepath.Base(repo))
-
-	if _, err := os.Stat(skillDir); err == nil {
-		return fmt.Errorf("skill '%s' already exists", filepath.Base(repo))
+	ref, err := parseGitHubRef(repo)
+	if err != nil {
+		return err
 	}
 
-	url := fmt.Sprintf("https://raw.githubusercontent.com/%s/main/SKILL.md", repo)
+	skillName := ref.RepoName
+	if ref.SubPath != "" {
+		skillName = filepath.Base(ref.SubPath)
+	}
+	skillDirectory := filepath.Join(si.workspace, "skills", skillName)
+
+	if _, err := os.Stat(skillDirectory); err == nil {
+		return fmt.Errorf("skill '%s' already exists", skillName)
+	}
+
+	// Build GitHub API URL
+	apiPath := path.Join(ref.Owner, ref.RepoName, "contents")
+	if ref.SubPath != "" {
+		apiPath = path.Join(apiPath, ref.SubPath)
+	}
+	apiURL := fmt.Sprintf("https://api.github.com/repos/%s?ref=%s", apiPath, ref.Ref)
+
+	if err := si.getGithubDirAllFiles(ctx, apiURL, skillDirectory, true); err != nil {
+		// Fallback to raw download
+		return si.downloadRaw(ctx, ref.Owner, ref.RepoName, ref.Ref, ref.SubPath, skillDirectory)
+	}
+
+	if _, err := os.Stat(filepath.Join(skillDirectory, "SKILL.md")); err != nil {
+		return fmt.Errorf("SKILL.md not found in repository")
+	}
+	return nil
+}
+
+// downloadDir recursively downloads a directory from GitHub API
+// isRoot: true if this is the skill root directory (only download SKILL.md at root)
+func (si *SkillInstaller) getGithubDirAllFiles(ctx context.Context, apiURL, localDir string, isRoot bool) error {
+	req, err := http.NewRequestWithContext(ctx, "GET", apiURL, nil)
+	if err != nil {
+		return err
+	}
+	if si.githubToken != "" {
+		req.Header.Set("Authorization", "Bearer "+si.githubToken)
+	}
+
+	resp, err := utils.DoRequestWithRetry(si.client, req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != 200 {
+		return fmt.Errorf("HTTP %d", resp.StatusCode)
+	}
+
+	var items []GitHubContent
+	if err := json.NewDecoder(resp.Body).Decode(&items); err != nil {
+		return err
+	}
+
+	for _, item := range items {
+		localPath := filepath.Join(localDir, item.Name)
+
+		switch item.Type {
+		case "file":
+			if !shouldDownload(item.Name, isRoot) {
+				continue
+			}
+			if err := si.downloadFile(ctx, item.DownloadURL, localPath); err != nil {
+				return fmt.Errorf("download %s: %w", item.Name, err)
+			}
+		case "dir":
+			if !isSkillDirectory(item.Name) {
+				continue
+			}
+			if err := si.getGithubDirAllFiles(ctx, item.URL, localPath, false); err != nil {
+				return err
+			}
+		}
+	}
+	return nil
+}
+
+// downloadRaw is a fallback that downloads just SKILL.md from raw.githubusercontent.com
+func (si *SkillInstaller) downloadRaw(ctx context.Context, owner, repo, ref, subPath, localDir string) error {
+	urlPath := path.Join(owner, repo, ref)
+	if subPath != "" {
+		urlPath = path.Join(urlPath, subPath)
+	}
+	url := fmt.Sprintf("https://raw.githubusercontent.com/%s/SKILL.md", urlPath)
 
-	client := &http.Client{Timeout: 15 * time.Second}
 	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
 	if err != nil {
 		return fmt.Errorf("failed to create request: %w", err)
 	}
 
-	resp, err := utils.DoRequestWithRetry(client, req)
+	// Use chunked download to temporary file.
+	tmpPath, err := utils.DownloadToFile(ctx, si.client, req, 0)
 	if err != nil {
 		return fmt.Errorf("failed to fetch skill: %w", err)
 	}
-	defer resp.Body.Close()
+	defer os.Remove(tmpPath)
 
-	if resp.StatusCode != 200 {
-		return fmt.Errorf("failed to fetch skill: HTTP %d", resp.StatusCode)
-	}
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return fmt.Errorf("failed to read response: %w", err)
-	}
-
-	if err := os.MkdirAll(skillDir, 0o755); err != nil {
+	if err := os.MkdirAll(localDir, 0o755); err != nil {
 		return fmt.Errorf("failed to create skill directory: %w", err)
 	}
 
-	skillPath := filepath.Join(skillDir, "SKILL.md")
+	localPath := filepath.Join(localDir, "SKILL.md")
 
-	// Use unified atomic write utility with explicit sync for flash storage reliability.
-	if err := fileutil.WriteFileAtomic(skillPath, body, 0o600); err != nil {
+	// Atomic move from temp to final location.
+	if err := os.Rename(tmpPath, localPath); err != nil {
 		return fmt.Errorf("failed to write skill file: %w", err)
 	}
 
-	return nil
+	return os.Chmod(localPath, 0o600)
+}
+
+func (si *SkillInstaller) downloadFile(ctx context.Context, url, localPath string) error {
+	req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+	if err != nil {
+		return err
+	}
+
+	// Use chunked download to temporary file, then move atomically to target.
+	tmpPath, err := utils.DownloadToFile(ctx, si.client, req, 0)
+	if err != nil {
+		return err
+	}
+	defer os.Remove(tmpPath)
+
+	if err := os.MkdirAll(filepath.Dir(localPath), 0o755); err != nil {
+		return err
+	}
+
+	// Atomic move from temp to final location.
+	if err := os.Rename(tmpPath, localPath); err != nil {
+		return fmt.Errorf("failed to move downloaded file: %w", err)
+	}
+
+	return os.Chmod(localPath, 0o600)
+}
+
+// shouldDownload determines if a file should be downloaded
+// root: true if we're at the skill root directory
+func shouldDownload(name string, root bool) bool {
+	if root {
+		return name == "SKILL.md"
+	}
+	return true
+}
+
+// isSkillDir checks if a directory is a standard skill resource directory
+func isSkillDirectory(name string) bool {
+	switch name {
+	case "scripts", "references", "assets", "templates", "docs":
+		return true
+	}
+	return false
 }
 
 func (si *SkillInstaller) Uninstall(skillName string) error {
-	skillDir := filepath.Join(si.workspace, "skills", skillName)
+	parts := strings.Split(skillName, "/")
+	var finalSkillName string
+	for i := len(parts) - 1; i >= 0; i-- {
+		if parts[i] != "" {
+			finalSkillName = parts[i]
+			break
+		}
+	}
+	if finalSkillName == "" {
+		finalSkillName = skillName
+	}
+
+	skillDir := filepath.Join(si.workspace, "skills", finalSkillName)
 
 	if _, err := os.Stat(skillDir); os.IsNotExist(err) {
-		return fmt.Errorf("skill '%s' not found", skillName)
+		return fmt.Errorf("skill '%s' not found (processed as '%s')", skillName, finalSkillName)
 	}
 
 	if err := os.RemoveAll(skillDir); err != nil {
-		return fmt.Errorf("failed to remove skill: %w", err)
+		return fmt.Errorf("failed to remove skill '%s': %w", finalSkillName, err)
 	}
 
 	return nil
diff --git a/pkg/skills/installer_test.go b/pkg/skills/installer_test.go
new file mode 100644
index 000000000..759cfc489
--- /dev/null
+++ b/pkg/skills/installer_test.go
@@ -0,0 +1,665 @@
+package skills
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestParseGitHubRef(t *testing.T) {
+	tests := []struct {
+		name           string
+		repo           string
+		wantOwner      string
+		wantRepoName   string
+		wantRef        string
+		wantSubPath    string
+		wantErr        bool
+		wantErrContain string
+	}{
+		{
+			name:         "simple owner/repo",
+			repo:         "sipeed/picoclaw",
+			wantOwner:    "sipeed",
+			wantRepoName: "picoclaw",
+			wantRef:      "main",
+			wantSubPath:  "",
+		},
+		{
+			name:         "owner/repo with subpath",
+			repo:         "sipeed/picoclaw/skills/test",
+			wantOwner:    "sipeed",
+			wantRepoName: "picoclaw",
+			wantRef:      "main",
+			wantSubPath:  "skills/test",
+		},
+		{
+			name:         "full URL with tree",
+			repo:         "https://github.com/sipeed/picoclaw/tree/dev/skills/test",
+			wantOwner:    "sipeed",
+			wantRepoName: "picoclaw",
+			wantRef:      "dev",
+			wantSubPath:  "skills/test",
+		},
+		{
+			name:         "full URL with blob",
+			repo:         "https://github.com/sipeed/picoclaw/blob/main/README.md",
+			wantOwner:    "sipeed",
+			wantRepoName: "picoclaw",
+			wantRef:      "main",
+			wantSubPath:  "README.md",
+		},
+		{
+			name:         "full URL without ref",
+			repo:         "https://github.com/sipeed/picoclaw",
+			wantOwner:    "sipeed",
+			wantRepoName: "picoclaw",
+			wantRef:      "main",
+			wantSubPath:  "",
+		},
+		{
+			name:           "invalid format - single part",
+			repo:           "sipeed",
+			wantErr:        true,
+			wantErrContain: "expected 'owner/repo'",
+		},
+		{
+			name:           "invalid URL",
+			repo:           "http://[invalid",
+			wantErr:        true,
+			wantErrContain: "invalid URL",
+		},
+		{
+			name:           "invalid GitHub URL - only one path part",
+			repo:           "https://github.com/sipeed",
+			wantErr:        true,
+			wantErrContain: "invalid GitHub URL",
+		},
+		{
+			name:         "with whitespace",
+			repo:         "  sipeed/picoclaw  ",
+			wantOwner:    "sipeed",
+			wantRepoName: "picoclaw",
+			wantRef:      "main",
+			wantSubPath:  "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ref, err := parseGitHubRef(tt.repo)
+
+			if tt.wantErr {
+				if err == nil {
+					t.Errorf("parseGitHubRef() error = nil, wantErr = true")
+					return
+				}
+				if tt.wantErrContain != "" && !strings.Contains(err.Error(), tt.wantErrContain) {
+					t.Errorf("parseGitHubRef() error = %v, want error containing %v", err, tt.wantErrContain)
+				}
+				return
+			}
+
+			if err != nil {
+				t.Errorf("parseGitHubRef() unexpected error = %v", err)
+				return
+			}
+
+			if ref.Owner != tt.wantOwner {
+				t.Errorf("parseGitHubRef() owner = %v, want %v", ref.Owner, tt.wantOwner)
+			}
+			if ref.RepoName != tt.wantRepoName {
+				t.Errorf("parseGitHubRef() repoName = %v, want %v", ref.RepoName, tt.wantRepoName)
+			}
+			if ref.Ref != tt.wantRef {
+				t.Errorf("parseGitHubRef() ref = %v, want %v", ref.Ref, tt.wantRef)
+			}
+			if ref.SubPath != tt.wantSubPath {
+				t.Errorf("parseGitHubRef() subPath = %v, want %v", ref.SubPath, tt.wantSubPath)
+			}
+		})
+	}
+}
+
+func TestShouldDownload(t *testing.T) {
+	tests := []struct {
+		name string
+		file string
+		root bool
+		want bool
+	}{
+		{"SKILL.md at root", "SKILL.md", true, true},
+		{"other file at root", "README.md", true, false},
+		{"script at root", "script.py", true, false},
+		{"SKILL.md not at root", "SKILL.md", false, true},
+		{"any file not at root", "any.txt", false, true},
+		{"script not at root", "script.py", false, true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := shouldDownload(tt.file, tt.root)
+			if got != tt.want {
+				t.Errorf("shouldDownload(%q, %v) = %v, want %v", tt.file, tt.root, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestIsSkillDirectory(t *testing.T) {
+	tests := []struct {
+		name string
+		dir  string
+		want bool
+	}{
+		{"scripts dir", "scripts", true},
+		{"references dir", "references", true},
+		{"assets dir", "assets", true},
+		{"templates dir", "templates", true},
+		{"docs dir", "docs", true},
+		{"other dir", "other", false},
+		{"src dir", "src", false},
+		{"empty string", "", false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isSkillDirectory(tt.dir)
+			if got != tt.want {
+				t.Errorf("isSkillDirectory(%q) = %v, want %v", tt.dir, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestNewSkillInstaller(t *testing.T) {
+	tmpDir := t.TempDir()
+	installer, err := NewSkillInstaller(tmpDir, "test-token", "")
+	if err != nil {
+		t.Fatalf("NewSkillInstaller() error = %v", err)
+	}
+
+	if installer == nil {
+		t.Fatal("NewSkillInstaller() returned nil")
+	}
+
+	if installer.workspace != tmpDir {
+		t.Errorf("workspace = %v, want %v", installer.workspace, tmpDir)
+	}
+
+	if installer.githubToken != "test-token" {
+		t.Errorf("githubToken = %v, want 'test-token'", installer.githubToken)
+	}
+
+	if installer.proxy != "" {
+		t.Errorf("proxy = %v, want empty", installer.proxy)
+	}
+
+	if installer.client == nil {
+		t.Error("client is nil")
+	} else if installer.client.Timeout != 15*time.Second {
+		t.Errorf("client.Timeout = %v, want 15s", installer.client.Timeout)
+	}
+}
+
+func TestNewSkillInstaller_WithProxy(t *testing.T) {
+	tmpDir := t.TempDir()
+	installer, err := NewSkillInstaller(tmpDir, "test-token", "http://127.0.0.1:7890")
+	if err != nil {
+		t.Fatalf("NewSkillInstaller() error = %v", err)
+	}
+
+	if installer.proxy != "http://127.0.0.1:7890" {
+		t.Errorf("proxy = %v, want 'http://127.0.0.1:7890'", installer.proxy)
+	}
+
+	if installer.client == nil {
+		t.Fatal("client is nil")
+	}
+
+	// Verify the transport has proxy configured
+	transport, ok := installer.client.Transport.(*http.Transport)
+	if !ok {
+		t.Fatal("client.Transport is not *http.Transport")
+	}
+
+	if transport.Proxy == nil {
+		t.Error("transport.Proxy is nil, expected non-nil")
+	}
+}
+
+func TestNewSkillInstaller_InvalidProxy(t *testing.T) {
+	tmpDir := t.TempDir()
+	installer, err := NewSkillInstaller(tmpDir, "test-token", "://invalid-proxy")
+	if err == nil {
+		t.Error("NewSkillInstaller() expected error for invalid proxy, got nil")
+	}
+	if installer != nil {
+		t.Error("expected nil installer on error")
+	}
+}
+
+func TestSkillInstaller_DownloadFile(t *testing.T) {
+	// Create a test server that serves files
+	content := "test file content for skill download"
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			t.Errorf("expected GET, got %s", r.Method)
+		}
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(content))
+	}))
+	defer server.Close()
+
+	tmpDir := t.TempDir()
+	installer, err := NewSkillInstaller(tmpDir, "", "")
+	if err != nil {
+		t.Fatalf("NewSkillInstaller() error = %v", err)
+	}
+
+	t.Run("successful download", func(t *testing.T) {
+		localPath := filepath.Join(tmpDir, "test-skill", "SKILL.md")
+		err := installer.downloadFile(context.Background(), server.URL, localPath)
+		if err != nil {
+			t.Errorf("downloadFile() error = %v", err)
+			return
+		}
+
+		// Verify file was downloaded
+		data, err := os.ReadFile(localPath)
+		if err != nil {
+			t.Errorf("failed to read downloaded file: %v", err)
+			return
+		}
+
+		if string(data) != content {
+			t.Errorf("downloaded content = %q, want %q", string(data), content)
+		}
+
+		// Check file permissions
+		info, err := os.Stat(localPath)
+		if err != nil {
+			t.Errorf("failed to stat file: %v", err)
+			return
+		}
+
+		if info.Mode().Perm() != 0o600 {
+			t.Errorf("file permissions = %o, want %o", info.Mode().Perm(), 0o600)
+		}
+	})
+
+	t.Run("http error", func(t *testing.T) {
+		errorServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusNotFound)
+			w.Write([]byte("not found"))
+		}))
+		defer errorServer.Close()
+
+		localPath := filepath.Join(tmpDir, "error-test", "SKILL.md")
+		err := installer.downloadFile(context.Background(), errorServer.URL, localPath)
+		if err == nil {
+			t.Error("downloadFile() expected error for 404, got nil")
+		}
+	})
+}
+
+func TestSkillInstaller_DownloadRaw(t *testing.T) {
+	content := "raw skill content"
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte(content))
+	}))
+	defer server.Close()
+
+	tmpDir := t.TempDir()
+	installer, err := NewSkillInstaller(tmpDir, "", "")
+	if err != nil {
+		t.Fatalf("NewSkillInstaller() error = %v", err)
+	}
+
+	// Replace the client with one that points to our test server
+	// We need to modify the URL in the function, so we'll test indirectly
+
+	localDir := filepath.Join(tmpDir, "raw-test")
+	ctx := context.Background()
+
+	// Create a simple test by calling downloadFile directly since downloadRaw
+	// constructs its own URL
+	testFile := filepath.Join(localDir, "SKILL.md")
+	err = installer.downloadFile(ctx, server.URL, testFile)
+	if err != nil {
+		t.Errorf("downloadFile() error = %v", err)
+	}
+
+	// Verify file content
+	data, err := os.ReadFile(testFile)
+	if err != nil {
+		t.Errorf("failed to read file: %v", err)
+		return
+	}
+
+	if string(data) != content {
+		t.Errorf("content = %q, want %q", string(data), content)
+	}
+}
+
+func TestSkillInstaller_Uninstall(t *testing.T) {
+	tmpDir := t.TempDir()
+	skillsDir := filepath.Join(tmpDir, "skills")
+	os.MkdirAll(skillsDir, 0o755)
+
+	installer, err := NewSkillInstaller(tmpDir, "", "")
+	if err != nil {
+		t.Fatalf("NewSkillInstaller() error = %v", err)
+	}
+
+	t.Run("uninstall existing skill", func(t *testing.T) {
+		skillName := "test-skill"
+		skillDir := filepath.Join(skillsDir, skillName)
+
+		// Create skill directory with a file
+		os.MkdirAll(skillDir, 0o755)
+		os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte("test"), 0o644)
+
+		if err := installer.Uninstall(skillName); err != nil {
+			t.Errorf("Uninstall() error = %v", err)
+		}
+
+		// Verify directory was removed
+		if _, err := os.Stat(skillDir); !os.IsNotExist(err) {
+			t.Error("skill directory still exists after uninstall")
+		}
+	})
+
+	t.Run("uninstall non-existent skill", func(t *testing.T) {
+		if err := installer.Uninstall("non-existent-skill"); err == nil {
+			t.Error("Uninstall() expected error for non-existent skill, got nil")
+		} else if !strings.Contains(err.Error(), "not found") {
+			t.Errorf("error message = %q, want 'not found'", err.Error())
+		}
+	})
+
+	t.Run("uninstall with path separator", func(t *testing.T) {
+		skillName := "owner/repo/skill-name"
+		skillDir := filepath.Join(skillsDir, "skill-name")
+
+		// Create skill directory
+		os.MkdirAll(skillDir, 0o755)
+		os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte("test"), 0o644)
+
+		if err := installer.Uninstall(skillName); err != nil {
+			t.Errorf("Uninstall() error = %v", err)
+		}
+
+		if _, err := os.Stat(skillDir); !os.IsNotExist(err) {
+			t.Error("skill directory still exists after uninstall")
+		}
+	})
+
+	t.Run("uninstall with trailing slash", func(t *testing.T) {
+		skillName := "skill-name/"
+		skillDir := filepath.Join(skillsDir, "skill-name")
+
+		// Create skill directory
+		os.MkdirAll(skillDir, 0o755)
+		os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte("test"), 0o644)
+
+		if err := installer.Uninstall(skillName); err != nil {
+			t.Errorf("Uninstall() error = %v", err)
+		}
+
+		if _, err := os.Stat(skillDir); !os.IsNotExist(err) {
+			t.Error("skill directory still exists after uninstall")
+		}
+	})
+}
+
+func TestSkillInstaller_InstallFromGitHub_SkillAlreadyExists(t *testing.T) {
+	tmpDir := t.TempDir()
+	skillsDir := filepath.Join(tmpDir, "skills")
+	os.MkdirAll(skillsDir, 0o755)
+
+	installer, err := NewSkillInstaller(tmpDir, "", "")
+	if err != nil {
+		t.Fatalf("NewSkillInstaller() error = %v", err)
+	}
+
+	// Create an existing skill directory
+	existingSkill := filepath.Join(skillsDir, "picoclaw")
+	os.MkdirAll(existingSkill, 0o755)
+	os.WriteFile(filepath.Join(existingSkill, "SKILL.md"), []byte("existing"), 0o644)
+
+	// Try to install the same skill - should fail
+	err = installer.InstallFromGitHub(context.Background(), "sipeed/picoclaw")
+	if err == nil {
+		t.Error("InstallFromGitHub() expected error for existing skill, got nil")
+	}
+	if !strings.Contains(err.Error(), "already exists") {
+		t.Errorf("error message = %q, want 'already exists'", err.Error())
+	}
+}
+
+func TestGitHubContent_Struct(t *testing.T) {
+	// Test that GitHubContent struct can be properly unmarshaled
+	jsonData := `{
+		"name": "test.md",
+		"path": "skills/test.md",
+		"type": "file",
+		"download_url": "https://example.com/download",
+		"url": "https://api.github.com/contents/skills/test.md"
+	}`
+
+	var content GitHubContent
+	err := json.Unmarshal([]byte(jsonData), &content)
+	if err != nil {
+		t.Errorf("failed to unmarshal GitHubContent: %v", err)
+	}
+
+	if content.Name != "test.md" {
+		t.Errorf("Name = %q, want 'test.md'", content.Name)
+	}
+	if content.Type != "file" {
+		t.Errorf("Type = %q, want 'file'", content.Type)
+	}
+	if content.DownloadURL != "https://example.com/download" {
+		t.Errorf("DownloadURL = %q, want 'https://example.com/download'", content.DownloadURL)
+	}
+}
+
+func TestSkillInstaller_GetGithubDirAllFiles(t *testing.T) {
+	tmpDir := t.TempDir()
+	installer, err := NewSkillInstaller(tmpDir, "", "")
+	if err != nil {
+		t.Fatalf("NewSkillInstaller() error = %v", err)
+	}
+
+	// Create a test server that mimics GitHub API
+	fileContent := "skill file content"
+	var serverURL string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Check for authorization header
+		authHeader := r.Header.Get("Authorization")
+		if authHeader != "" && !strings.HasPrefix(authHeader, "Bearer ") {
+			t.Errorf("expected Bearer token, got: %s", authHeader)
+		}
+
+		// Return different responses based on path
+		if strings.Contains(r.URL.Path, "/contents") {
+			// API response for directory listing
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+
+			items := []map[string]any{
+				{
+					"name":         "SKILL.md",
+					"path":         "SKILL.md",
+					"type":         "file",
+					"download_url": serverURL + "/download/SKILL.md",
+				},
+				{
+					"name": "scripts",
+					"path": "scripts",
+					"type": "dir",
+					"url":  serverURL + "/api/scripts",
+				},
+			}
+			json.NewEncoder(w).Encode(items)
+		} else if strings.Contains(r.URL.Path, "/api/scripts") {
+			// API response for scripts subdirectory
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+
+			items := []map[string]any{
+				{
+					"name":         "test.py",
+					"path":         "scripts/test.py",
+					"type":         "file",
+					"download_url": serverURL + "/download/test.py",
+				},
+			}
+			json.NewEncoder(w).Encode(items)
+		} else if strings.Contains(r.URL.Path, "/download/") {
+			// Raw file download
+			w.WriteHeader(http.StatusOK)
+			w.Write([]byte(fileContent))
+		} else {
+			w.WriteHeader(http.StatusNotFound)
+		}
+	}))
+	serverURL = server.URL
+	defer server.Close()
+
+	localDir := filepath.Join(tmpDir, "test-skill")
+
+	t.Run("download from GitHub API", func(t *testing.T) {
+		err := installer.getGithubDirAllFiles(context.Background(), server.URL+"/contents", localDir, true)
+		if err != nil {
+			t.Errorf("getGithubDirAllFiles() error = %v", err)
+			return
+		}
+
+		// Verify SKILL.md was downloaded
+		skillMd := filepath.Join(localDir, "SKILL.md")
+		data, err := os.ReadFile(skillMd)
+		if err != nil {
+			t.Errorf("failed to read SKILL.md: %v", err)
+			return
+		}
+		if string(data) != fileContent {
+			t.Errorf("SKILL.md content = %q, want %q", string(data), fileContent)
+		}
+
+		// Verify scripts directory and file
+		scriptFile := filepath.Join(localDir, "scripts", "test.py")
+		data, err = os.ReadFile(scriptFile)
+		if err != nil {
+			t.Errorf("failed to read test.py: %v", err)
+			return
+		}
+		if string(data) != fileContent {
+			t.Errorf("test.py content = %q, want %q", string(data), fileContent)
+		}
+	})
+
+	t.Run("http error response", func(t *testing.T) {
+		errorServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			w.WriteHeader(http.StatusForbidden)
+		}))
+		defer errorServer.Close()
+
+		err := installer.getGithubDirAllFiles(
+			context.Background(),
+			errorServer.URL,
+			filepath.Join(tmpDir, "error-test"),
+			true,
+		)
+		if err == nil {
+			t.Error("getGithubDirAllFiles() expected error for 403, got nil")
+		}
+	})
+}
+
+func TestSkillInstaller_InstallFromGitHub_WithToken(t *testing.T) {
+	tmpDir := t.TempDir()
+	skillsDir := filepath.Join(tmpDir, "skills")
+	os.MkdirAll(skillsDir, 0o755)
+
+	var serverURL string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Capture the authorization header
+		authHeader := r.Header.Get("Authorization")
+		if authHeader != "" {
+			tokenReceived := strings.TrimPrefix(authHeader, "Bearer ")
+			t.Fatalf("github token is %s", tokenReceived)
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+
+		items := []map[string]any{
+			{
+				"name":         "SKILL.md",
+				"path":         "SKILL.md",
+				"type":         "file",
+				"download_url": serverURL + "/download/SKILL.md",
+			},
+		}
+		json.NewEncoder(w).Encode(items)
+	}))
+	serverURL = server.URL
+	defer server.Close()
+
+	installer, err := NewSkillInstaller(tmpDir, "test-github-token", "")
+	if err != nil {
+		t.Fatalf("NewSkillInstaller() error = %v", err)
+	}
+
+	// We need to test the token is passed - the actual install will fail
+	// because we're not fully mocking the download, but we can verify
+	// the token is sent in the request
+
+	// Use a simple context with timeout
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	// The install will fail because download URL isn't properly set up,
+	// but the token should be sent in the API request
+	_ = installer.InstallFromGitHub(ctx, "owner/repo")
+
+	// Note: We can't easily intercept the download request since it's a different URL,
+	// but the fact that the API request was made verifies the token flow
+	// In a real scenario, the token would be sent to both API and raw downloads
+}
+
+func TestSkillInstaller_ContextCancellation(t *testing.T) {
+	tmpDir := t.TempDir()
+	installer, err := NewSkillInstaller(tmpDir, "", "")
+	if err != nil {
+		t.Fatalf("NewSkillInstaller() error = %v", err)
+	}
+
+	// Create a slow server
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		time.Sleep(100 * time.Millisecond)
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("response"))
+	}))
+	defer server.Close()
+
+	// Create a canceled context
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel() // Cancel immediately
+
+	localPath := filepath.Join(tmpDir, "cancel-test", "file.txt")
+	err = installer.downloadFile(ctx, server.URL, localPath)
+
+	if err == nil {
+		t.Error("downloadFile() expected error for canceled context, got nil")
+	}
+}
diff --git a/pkg/skills/loader.go b/pkg/skills/loader.go
index fcbcf934b..f5985a662 100644
--- a/pkg/skills/loader.go
+++ b/pkg/skills/loader.go
@@ -10,14 +10,15 @@ import (
 	"regexp"
 	"strings"
 
+	"github.com/gomarkdown/markdown"
+	"github.com/gomarkdown/markdown/ast"
+	"github.com/gomarkdown/markdown/parser"
+	"gopkg.in/yaml.v3"
+
 	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
-var (
-	namePattern        = regexp.MustCompile(`^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$`)
-	reFrontmatter      = regexp.MustCompile(`(?s)^---(?:\r\n|\n|\r)(.*?)(?:\r\n|\n|\r)---`)
-	reStripFrontmatter = regexp.MustCompile(`(?s)^---(?:\r\n|\n|\r)(.*?)(?:\r\n|\n|\r)---(?:\r\n|\n|\r)*`)
-)
+var namePattern = regexp.MustCompile(`^[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*$`)
 
 const (
 	MaxNameLength        = 64
@@ -64,6 +65,29 @@ type SkillsLoader struct {
 	builtinSkills   string // builtin skills
 }
 
+// SkillRoots returns all unique skill root directories used by this loader.
+// The order follows resolution priority: workspace > global > builtin.
+func (sl *SkillsLoader) SkillRoots() []string {
+	roots := []string{sl.workspaceSkills, sl.globalSkills, sl.builtinSkills}
+	seen := make(map[string]struct{}, len(roots))
+	out := make([]string, 0, len(roots))
+
+	for _, root := range roots {
+		trimmed := strings.TrimSpace(root)
+		if trimmed == "" {
+			continue
+		}
+		clean := filepath.Clean(trimmed)
+		if _, ok := seen[clean]; ok {
+			continue
+		}
+		seen[clean] = struct{}{}
+		out = append(out, clean)
+	}
+
+	return out
+}
+
 func NewSkillsLoader(workspace string, globalSkills string, builtinSkills string) *SkillsLoader {
 	return &SkillsLoader{
 		workspace:       workspace,
@@ -203,11 +227,20 @@ func (sl *SkillsLoader) getSkillMetadata(skillPath string) *SkillMetadata {
 		return nil
 	}
 
-	frontmatter := sl.extractFrontmatter(string(content))
+	frontmatter, bodyContent := splitFrontmatter(string(content))
+	dirName := filepath.Base(filepath.Dir(skillPath))
+	title, bodyDescription := extractMarkdownMetadata(bodyContent)
+
+	metadata := &SkillMetadata{
+		Name:        dirName,
+		Description: bodyDescription,
+	}
+	if title != "" && namePattern.MatchString(title) && len(title) <= MaxNameLength {
+		metadata.Name = title
+	}
+
 	if frontmatter == "" {
-		return &SkillMetadata{
-			Name: filepath.Base(filepath.Dir(skillPath)),
-		}
+		return metadata
 	}
 
 	// Try JSON first (for backward compatibility)
@@ -216,60 +249,133 @@ func (sl *SkillsLoader) getSkillMetadata(skillPath string) *SkillMetadata {
 		Description string `json:"description"`
 	}
 	if err := json.Unmarshal([]byte(frontmatter), &jsonMeta); err == nil {
-		return &SkillMetadata{
-			Name:        jsonMeta.Name,
-			Description: jsonMeta.Description,
+		if jsonMeta.Name != "" {
+			metadata.Name = jsonMeta.Name
 		}
+		if jsonMeta.Description != "" {
+			metadata.Description = jsonMeta.Description
+		}
+		return metadata
 	}
 
 	// Fall back to simple YAML parsing
 	yamlMeta := sl.parseSimpleYAML(frontmatter)
-	return &SkillMetadata{
-		Name:        yamlMeta["name"],
-		Description: yamlMeta["description"],
+	if name := yamlMeta["name"]; name != "" {
+		metadata.Name = name
 	}
+	if description := yamlMeta["description"]; description != "" {
+		metadata.Description = description
+	}
+	return metadata
 }
 
-// parseSimpleYAML parses simple key: value YAML format
-// Example: name: github\n description: "..."
-// Normalizes line endings to handle \n (Unix), \r\n (Windows), and \r (classic Mac)
+func extractMarkdownMetadata(content string) (title, description string) {
+	p := parser.NewWithExtensions(parser.CommonExtensions)
+	doc := markdown.Parse([]byte(content), p)
+	if doc == nil {
+		return "", ""
+	}
+
+	ast.WalkFunc(doc, func(node ast.Node, entering bool) ast.WalkStatus {
+		if !entering {
+			return ast.GoToNext
+		}
+
+		switch n := node.(type) {
+		case *ast.Heading:
+			if title == "" && n.Level == 1 {
+				title = nodeText(n)
+				if title != "" && description != "" {
+					return ast.Terminate
+				}
+			}
+		case *ast.Paragraph:
+			if description == "" {
+				description = nodeText(n)
+				if title != "" && description != "" {
+					return ast.Terminate
+				}
+			}
+		}
+		return ast.GoToNext
+	})
+
+	return title, description
+}
+
+func nodeText(n ast.Node) string {
+	var b strings.Builder
+	ast.WalkFunc(n, func(node ast.Node, entering bool) ast.WalkStatus {
+		if !entering {
+			return ast.GoToNext
+		}
+
+		switch t := node.(type) {
+		case *ast.Text:
+			b.Write(t.Literal)
+		case *ast.Code:
+			b.Write(t.Literal)
+		case *ast.Softbreak, *ast.Hardbreak, *ast.NonBlockingSpace:
+			b.WriteByte(' ')
+		}
+		return ast.GoToNext
+	})
+	return strings.Join(strings.Fields(b.String()), " ")
+}
+
+// parseSimpleYAML parses YAML frontmatter and extracts known metadata fields.
 func (sl *SkillsLoader) parseSimpleYAML(content string) map[string]string {
 	result := make(map[string]string)
 
-	// Normalize line endings: convert \r\n and \r to \n
-	normalized := strings.ReplaceAll(content, "\r\n", "\n")
-	normalized = strings.ReplaceAll(normalized, "\r", "\n")
-
-	for line := range strings.SplitSeq(normalized, "\n") {
-		line = strings.TrimSpace(line)
-		if line == "" || strings.HasPrefix(line, "#") {
-			continue
-		}
-
-		parts := strings.SplitN(line, ":", 2)
-		if len(parts) == 2 {
-			key := strings.TrimSpace(parts[0])
-			value := strings.TrimSpace(parts[1])
-			// Remove quotes if present
-			value = strings.Trim(value, "\"'")
-			result[key] = value
-		}
+	var meta struct {
+		Name        string `yaml:"name"`
+		Description string `yaml:"description"`
+	}
+	if err := yaml.Unmarshal([]byte(content), &meta); err != nil {
+		return result
+	}
+	if meta.Name != "" {
+		result["name"] = meta.Name
+	}
+	if meta.Description != "" {
+		result["description"] = meta.Description
 	}
 
 	return result
 }
 
 func (sl *SkillsLoader) extractFrontmatter(content string) string {
-	// Support \n (Unix), \r\n (Windows), and \r (classic Mac) line endings for frontmatter blocks
-	match := reFrontmatter.FindStringSubmatch(content)
-	if len(match) > 1 {
-		return match[1]
-	}
-	return ""
+	frontmatter, _ := splitFrontmatter(content)
+	return frontmatter
 }
 
 func (sl *SkillsLoader) stripFrontmatter(content string) string {
-	return reStripFrontmatter.ReplaceAllString(content, "")
+	_, body := splitFrontmatter(content)
+	return body
+}
+
+func splitFrontmatter(content string) (frontmatter, body string) {
+	normalized := string(parser.NormalizeNewlines([]byte(content)))
+	lines := strings.Split(normalized, "\n")
+	if len(lines) == 0 || lines[0] != "---" {
+		return "", content
+	}
+
+	end := -1
+	for i := 1; i < len(lines); i++ {
+		if lines[i] == "---" {
+			end = i
+			break
+		}
+	}
+	if end == -1 {
+		return "", content
+	}
+
+	frontmatter = strings.Join(lines[1:end], "\n")
+	body = strings.Join(lines[end+1:], "\n")
+	body = strings.TrimLeft(body, "\n")
+	return frontmatter, body
 }
 
 func escapeXML(s string) string {
diff --git a/pkg/skills/loader_test.go b/pkg/skills/loader_test.go
index 9428bea62..645d8b7ac 100644
--- a/pkg/skills/loader_test.go
+++ b/pkg/skills/loader_test.go
@@ -326,3 +326,94 @@ func TestStripFrontmatter(t *testing.T) {
 		})
 	}
 }
+
+func TestSkillRootsTrimsWhitespaceAndDedups(t *testing.T) {
+	tmp := t.TempDir()
+	workspace := filepath.Join(tmp, "workspace")
+	global := filepath.Join(tmp, "global")
+	builtin := filepath.Join(tmp, "builtin")
+
+	sl := NewSkillsLoader(workspace, "  "+global+"  ", "\t"+builtin+"\n")
+	roots := sl.SkillRoots()
+
+	assert.Equal(t, []string{
+		filepath.Join(workspace, "skills"),
+		global,
+		builtin,
+	}, roots)
+}
+
+func TestGetSkillMetadata_UsesMarkdownParagraphWhenNoFrontmatter(t *testing.T) {
+	tmp := t.TempDir()
+	skillDir := filepath.Join(tmp, "workspace", "skills", "plain-skill")
+	require.NoError(t, os.MkdirAll(skillDir, 0o755))
+
+	content := "# Plain Skill\n\nThis is parsed from markdown paragraph.\n"
+	require.NoError(t, os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte(content), 0o644))
+
+	sl := &SkillsLoader{}
+	meta := sl.getSkillMetadata(filepath.Join(skillDir, "SKILL.md"))
+	require.NotNil(t, meta)
+	assert.Equal(t, "plain-skill", meta.Name)
+	assert.Equal(t, "This is parsed from markdown paragraph.", meta.Description)
+}
+
+func TestGetSkillMetadata_FrontmatterOverridesMarkdown(t *testing.T) {
+	tmp := t.TempDir()
+	skillDir := filepath.Join(tmp, "workspace", "skills", "plain-skill")
+	require.NoError(t, os.MkdirAll(skillDir, 0o755))
+
+	content := "---\nname: frontmatter-skill\ndescription: frontmatter description\n---\n\n# Plain Skill\n\nBody description.\n"
+	require.NoError(t, os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte(content), 0o644))
+
+	sl := &SkillsLoader{}
+	meta := sl.getSkillMetadata(filepath.Join(skillDir, "SKILL.md"))
+	require.NotNil(t, meta)
+	assert.Equal(t, "frontmatter-skill", meta.Name)
+	assert.Equal(t, "frontmatter description", meta.Description)
+}
+
+func TestGetSkillMetadata_YAMLMultilineDescription(t *testing.T) {
+	tmp := t.TempDir()
+	skillDir := filepath.Join(tmp, "workspace", "skills", "plain-skill")
+	require.NoError(t, os.MkdirAll(skillDir, 0o755))
+
+	content := "---\nname: frontmatter-skill\ndescription: |\n  line 1: with colon\n  line 2\n---\n\n# Plain Skill\n\nBody description.\n"
+	require.NoError(t, os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte(content), 0o644))
+
+	sl := &SkillsLoader{}
+	meta := sl.getSkillMetadata(filepath.Join(skillDir, "SKILL.md"))
+	require.NotNil(t, meta)
+	assert.Equal(t, "frontmatter-skill", meta.Name)
+	assert.Equal(t, "line 1: with colon\nline 2", meta.Description)
+}
+
+func TestGetSkillMetadata_InvalidHeadingNameFallsBackToDirName(t *testing.T) {
+	tmp := t.TempDir()
+	skillDir := filepath.Join(tmp, "workspace", "skills", "valid-name")
+	require.NoError(t, os.MkdirAll(skillDir, 0o755))
+
+	content := "# Invalid Heading Name\n\nBody description.\n"
+	require.NoError(t, os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte(content), 0o644))
+
+	sl := &SkillsLoader{}
+	meta := sl.getSkillMetadata(filepath.Join(skillDir, "SKILL.md"))
+	require.NotNil(t, meta)
+	assert.Equal(t, "valid-name", meta.Name)
+	assert.Equal(t, "Body description.", meta.Description)
+}
+
+func TestGetSkillMetadata_IgnoresHTMLCommentBlocks(t *testing.T) {
+	tmp := t.TempDir()
+	skillDir := filepath.Join(tmp, "workspace", "skills", "biomed-skill")
+	require.NoError(t, os.MkdirAll(skillDir, 0o755))
+
+	content := "<!--\n# COPYRIGHT NOTICE\n# This file is part of the \"Universal Biomedical Skills\" project.\n# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>\n# All Rights Reserved.\n#\n# This code is proprietary and confidential.\n# Unauthorized copying of this file, via any medium is strictly prohibited.\n#\n# Provenance: Authenticated by MD BABU MIA\n\n-->\n\n# Biomed Skill\n\nSummarize biomedical papers.\n"
+	require.NoError(t, os.WriteFile(filepath.Join(skillDir, "SKILL.md"), []byte(content), 0o644))
+
+	sl := &SkillsLoader{}
+	meta := sl.getSkillMetadata(filepath.Join(skillDir, "SKILL.md"))
+	require.NotNil(t, meta)
+	assert.Equal(t, "biomed-skill", meta.Name)
+	assert.Equal(t, "Summarize biomedical papers.", meta.Description)
+}
diff --git a/pkg/state/state.go b/pkg/state/state.go
index 57f371f12..5da7bbde1 100644
--- a/pkg/state/state.go
+++ b/pkg/state/state.go
@@ -40,8 +40,8 @@ func NewManager(workspace string) *Manager {
 	oldStateFile := filepath.Join(workspace, "state.json")
 
 	// Create state directory if it doesn't exist
-	if err := os.MkdirAll(stateDir, 0o755); err != nil {
-		log.Fatalf("[FATAL] state: failed to create state directory: %v", err)
+	if err := os.MkdirAll(stateDir, 0o700); err != nil {
+		log.Printf("[WARN] state: failed to create state directory %s: %v", stateDir, err)
 	}
 
 	sm := &Manager{
diff --git a/pkg/state/state_test.go b/pkg/state/state_test.go
index e5e116ef6..3924e5533 100644
--- a/pkg/state/state_test.go
+++ b/pkg/state/state_test.go
@@ -2,7 +2,6 @@ package state
 
 import (
 	"encoding/json"
-	"errors"
 	"fmt"
 	"os"
 	"os/exec"
@@ -217,10 +216,7 @@ func TestNewManager_EmptyWorkspace(t *testing.T) {
 	}
 }
 
-func TestNewManager_MkdirFailureCrashes(t *testing.T) {
-	// Since log.Fatalf calls os.Exit(1), we cannot test it normally
-	// Otherwise, the test suite would stop altogether.
-	// We use the standard pattern of Go: rerun this test in a subprocess.
+func TestNewManager_MkdirFailureDoesNotCrash(t *testing.T) {
 	if os.Getenv("BE_CRASHER") == "1" {
 		tmpDir := os.Getenv("CRASH_DIR")
 
@@ -240,15 +236,11 @@ func TestNewManager_MkdirFailureCrashes(t *testing.T) {
 	}
 	defer os.RemoveAll(tmpDir)
 
-	cmd := exec.Command(os.Args[0], "-test.run=TestNewManager_MkdirFailureCrashes")
+	cmd := exec.Command(os.Args[0], "-test.run=TestNewManager_MkdirFailureDoesNotCrash")
 	cmd.Env = append(os.Environ(), "BE_CRASHER=1", "CRASH_DIR="+tmpDir)
 
 	err = cmd.Run()
-
-	var e *exec.ExitError
-	if errors.As(err, &e) && !e.Success() {
-		return
+	if err != nil {
+		t.Fatalf("NewManager should not crash when state dir creation fails, got: %v", err)
 	}
-
-	t.Fatalf("The process ended without error, a crash was expected via os.Exit(1). Err: %v", err)
 }
diff --git a/pkg/tools/base.go b/pkg/tools/base.go
index 770d8cb04..ec743e164 100644
--- a/pkg/tools/base.go
+++ b/pkg/tools/base.go
@@ -10,11 +10,38 @@ type Tool interface {
 	Execute(ctx context.Context, args map[string]any) *ToolResult
 }
 
-// ContextualTool is an optional interface that tools can implement
-// to receive the current message context (channel, chatID)
-type ContextualTool interface {
-	Tool
-	SetContext(channel, chatID string)
+// --- Request-scoped tool context (channel / chatID) ---
+//
+// Carried via context.Value so that concurrent tool calls each receive
+// their own immutable copy — no mutable state on singleton tool instances.
+//
+// Keys are unexported pointer-typed vars — guaranteed collision-free,
+// and only accessible through the helper functions below.
+
+type toolCtxKey struct{ name string }
+
+var (
+	ctxKeyChannel = &toolCtxKey{"channel"}
+	ctxKeyChatID  = &toolCtxKey{"chatID"}
+)
+
+// WithToolContext returns a child context carrying channel and chatID.
+func WithToolContext(ctx context.Context, channel, chatID string) context.Context {
+	ctx = context.WithValue(ctx, ctxKeyChannel, channel)
+	ctx = context.WithValue(ctx, ctxKeyChatID, chatID)
+	return ctx
+}
+
+// ToolChannel extracts the channel from ctx, or "" if unset.
+func ToolChannel(ctx context.Context) string {
+	v, _ := ctx.Value(ctxKeyChannel).(string)
+	return v
+}
+
+// ToolChatID extracts the chatID from ctx, or "" if unset.
+func ToolChatID(ctx context.Context) string {
+	v, _ := ctx.Value(ctxKeyChatID).(string)
+	return v
 }
 
 // AsyncCallback is a function type that async tools use to notify completion.
@@ -22,51 +49,36 @@ type ContextualTool interface {
 //
 // The ctx parameter allows the callback to be canceled if the agent is shutting down.
 // The result parameter contains the tool's execution result.
-//
-// Example usage in an async tool:
-//
-//	func (t *MyAsyncTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult {
-//	    // Start async work in background
-//	    go func() {
-//	        result := doAsyncWork()
-//	        if t.callback != nil {
-//	            t.callback(ctx, result)
-//	        }
-//	    }()
-//	    return AsyncResult("Async task started")
-//	}
 type AsyncCallback func(ctx context.Context, result *ToolResult)
 
-// AsyncTool is an optional interface that tools can implement to support
+// AsyncExecutor is an optional interface that tools can implement to support
 // asynchronous execution with completion callbacks.
 //
-// Async tools return immediately with an AsyncResult, then notify completion
-// via the callback set by SetCallback.
+// Unlike the old AsyncTool pattern (SetCallback + Execute), AsyncExecutor
+// receives the callback as a parameter of ExecuteAsync. This eliminates the
+// data race where concurrent calls could overwrite each other's callbacks
+// on a shared tool instance.
 //
 // This is useful for:
-// - Long-running operations that shouldn't block the agent loop
-// - Subagent spawns that complete independently
-// - Background tasks that need to report results later
+//   - Long-running operations that shouldn't block the agent loop
+//   - Subagent spawns that complete independently
+//   - Background tasks that need to report results later
 //
 // Example:
 //
-//	type SpawnTool struct {
-//	    callback AsyncCallback
-//	}
-//
-//	func (t *SpawnTool) SetCallback(cb AsyncCallback) {
-//	    t.callback = cb
-//	}
-//
-//	func (t *SpawnTool) Execute(ctx context.Context, args map[string]interface{}) *ToolResult {
-//	    go t.runSubagent(ctx, args)
+//	func (t *SpawnTool) ExecuteAsync(ctx context.Context, args map[string]any, cb AsyncCallback) *ToolResult {
+//	    go func() {
+//	        result := t.runSubagent(ctx, args)
+//	        if cb != nil { cb(ctx, result) }
+//	    }()
 //	    return AsyncResult("Subagent spawned, will report back")
 //	}
-type AsyncTool interface {
+type AsyncExecutor interface {
 	Tool
-	// SetCallback registers a callback function to be invoked when the async operation completes.
-	// The callback will be called from a goroutine and should handle thread-safety if needed.
-	SetCallback(cb AsyncCallback)
+	// ExecuteAsync runs the tool asynchronously. The callback cb will be
+	// invoked (possibly from another goroutine) when the async operation
+	// completes. cb is guaranteed to be non-nil by the caller (registry).
+	ExecuteAsync(ctx context.Context, args map[string]any, cb AsyncCallback) *ToolResult
 }
 
 func ToolToSchema(tool Tool) map[string]any {
diff --git a/pkg/tools/cron.go b/pkg/tools/cron.go
index 6888d1326..154ec75f0 100644
--- a/pkg/tools/cron.go
+++ b/pkg/tools/cron.go
@@ -4,11 +4,11 @@ import (
 	"context"
 	"fmt"
 	"strings"
-	"sync"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/constants"
 	"github.com/sipeed/picoclaw/pkg/cron"
 	"github.com/sipeed/picoclaw/pkg/utils"
 )
@@ -20,13 +20,12 @@ type JobExecutor interface {
 
 // CronTool provides scheduling capabilities for the agent
 type CronTool struct {
-	cronService *cron.CronService
-	executor    JobExecutor
-	msgBus      *bus.MessageBus
-	execTool    *ExecTool
-	channel     string
-	chatID      string
-	mu          sync.RWMutex
+	cronService  *cron.CronService
+	executor     JobExecutor
+	msgBus       *bus.MessageBus
+	execTool     *ExecTool
+	allowCommand bool
+	execEnabled  bool
 }
 
 // NewCronTool creates a new CronTool
@@ -35,17 +34,32 @@ func NewCronTool(
 	cronService *cron.CronService, executor JobExecutor, msgBus *bus.MessageBus, workspace string, restrict bool,
 	execTimeout time.Duration, config *config.Config,
 ) (*CronTool, error) {
-	execTool, err := NewExecToolWithConfig(workspace, restrict, config)
-	if err != nil {
-		return nil, fmt.Errorf("unable to configure exec tool: %w", err)
+	allowCommand := true
+	execEnabled := true
+	if config != nil {
+		allowCommand = config.Tools.Cron.AllowCommand
+		execEnabled = config.Tools.Exec.Enabled
 	}
 
-	execTool.SetTimeout(execTimeout)
+	var execTool *ExecTool
+	if execEnabled {
+		var err error
+		execTool, err = NewExecToolWithConfig(workspace, restrict, config)
+		if err != nil {
+			return nil, fmt.Errorf("unable to configure exec tool: %w", err)
+		}
+	}
+
+	if execTool != nil {
+		execTool.SetTimeout(execTimeout)
+	}
 	return &CronTool{
-		cronService: cronService,
-		executor:    executor,
-		msgBus:      msgBus,
-		execTool:    execTool,
+		cronService:  cronService,
+		executor:     executor,
+		msgBus:       msgBus,
+		execTool:     execTool,
+		allowCommand: allowCommand,
+		execEnabled:  execEnabled,
 	}, nil
 }
 
@@ -77,6 +91,10 @@ func (t *CronTool) Parameters() map[string]any {
 				"type":        "string",
 				"description": "Optional: Shell command to execute directly (e.g., 'df -h'). If set, the agent will run this command and report output instead of just showing the message. 'deliver' will be forced to false for commands.",
 			},
+			"command_confirm": map[string]any{
+				"type":        "boolean",
+				"description": "Optional explicit confirmation flag for scheduling a shell command. Command execution must also be enabled via tools.cron.allow_command.",
+			},
 			"at_seconds": map[string]any{
 				"type":        "integer",
 				"description": "One-time reminder: seconds from now when to trigger (e.g., 600 for 10 minutes later). Use this for one-time reminders like 'remind me in 10 minutes'.",
@@ -95,21 +113,13 @@ func (t *CronTool) Parameters() map[string]any {
 			},
 			"deliver": map[string]any{
 				"type":        "boolean",
-				"description": "If true, send message directly to channel. If false, let agent process message (for complex tasks). Default: true",
+				"description": "If true, send message directly to channel. If false, let agent process message (for complex tasks). Default: false",
 			},
 		},
 		"required": []string{"action"},
 	}
 }
 
-// SetContext sets the current session context for job creation
-func (t *CronTool) SetContext(channel, chatID string) {
-	t.mu.Lock()
-	defer t.mu.Unlock()
-	t.channel = channel
-	t.chatID = chatID
-}
-
 // Execute runs the tool with the given arguments
 func (t *CronTool) Execute(ctx context.Context, args map[string]any) *ToolResult {
 	action, ok := args["action"].(string)
@@ -119,7 +129,7 @@ func (t *CronTool) Execute(ctx context.Context, args map[string]any) *ToolResult
 
 	switch action {
 	case "add":
-		return t.addJob(args)
+		return t.addJob(ctx, args)
 	case "list":
 		return t.listJobs()
 	case "remove":
@@ -133,11 +143,9 @@ func (t *CronTool) Execute(ctx context.Context, args map[string]any) *ToolResult
 	}
 }
 
-func (t *CronTool) addJob(args map[string]any) *ToolResult {
-	t.mu.RLock()
-	channel := t.channel
-	chatID := t.chatID
-	t.mu.RUnlock()
+func (t *CronTool) addJob(ctx context.Context, args map[string]any) *ToolResult {
+	channel := ToolChannel(ctx)
+	chatID := ToolChatID(ctx)
 
 	if channel == "" || chatID == "" {
 		return ErrorResult("no session context (channel/chat_id not set). Use this tool in an active conversation.")
@@ -155,6 +163,12 @@ func (t *CronTool) addJob(args map[string]any) *ToolResult {
 	everySeconds, hasEvery := args["every_seconds"].(float64)
 	cronExpr, hasCron := args["cron_expr"].(string)
 
+	// Fix: type assertions return true for zero values, need additional validity checks
+	// This prevents LLMs that fill unused optional parameters with defaults (0) from triggering wrong type
+	hasAt = hasAt && atSeconds > 0
+	hasEvery = hasEvery && everySeconds > 0
+	hasCron = hasCron && cronExpr != ""
+
 	// Priority: at_seconds > every_seconds > cron_expr
 	if hasAt {
 		atMS := time.Now().UnixMilli() + int64(atSeconds)*1000
@@ -177,18 +191,27 @@ func (t *CronTool) addJob(args map[string]any) *ToolResult {
 		return ErrorResult("one of at_seconds, every_seconds, or cron_expr is required")
 	}
 
-	// Read deliver parameter, default to true
-	deliver := true
+	// Read deliver parameter, default to false so scheduled tasks execute through the agent
+	deliver := false
 	if d, ok := args["deliver"].(bool); ok {
 		deliver = d
 	}
 
+	// GHSA-pv8c-p6jf-3fpp: command scheduling requires internal channel. When
+	// allow_command is disabled, explicit confirmation is required as an override.
+	// Non-command reminders remain open to all channels.
 	command, _ := args["command"].(string)
+	commandConfirm, _ := args["command_confirm"].(bool)
 	if command != "" {
-		// Commands must be processed by agent/exec tool, so deliver must be false (or handled specifically)
-		// Actually, let's keep deliver=false to let the system know it's not a simple chat message
-		// But for our new logic in ExecuteJob, we can handle it regardless of deliver flag if Payload.Command is set.
-		// However, logically, it's not "delivered" to chat directly as is.
+		if !t.execEnabled {
+			return ErrorResult("command execution is disabled")
+		}
+		if !constants.IsInternalChannel(channel) {
+			return ErrorResult("scheduling command execution is restricted to internal channels")
+		}
+		if !t.allowCommand && !commandConfirm {
+			return ErrorResult("command_confirm=true is required when allow_command is disabled")
+		}
 		deliver = false
 	}
 
@@ -288,8 +311,22 @@ func (t *CronTool) ExecuteJob(ctx context.Context, job *cron.CronJob) string {
 
 	// Execute command if present
 	if job.Payload.Command != "" {
+		if !t.execEnabled || t.execTool == nil {
+			output := "Error executing scheduled command: command execution is disabled"
+			pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
+			defer pubCancel()
+			t.msgBus.PublishOutbound(pubCtx, bus.OutboundMessage{
+				Channel: channel,
+				ChatID:  chatID,
+				Content: output,
+			})
+			return "ok"
+		}
+
 		args := map[string]any{
-			"command": job.Payload.Command,
+			"command":   job.Payload.Command,
+			"__channel": channel,
+			"__chat_id": chatID,
 		}
 
 		result := t.execTool.Execute(ctx, args)
diff --git a/pkg/tools/cron_test.go b/pkg/tools/cron_test.go
new file mode 100644
index 000000000..cd7d39860
--- /dev/null
+++ b/pkg/tools/cron_test.go
@@ -0,0 +1,239 @@
+package tools
+
+import (
+	"context"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/bus"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/cron"
+)
+
+func newTestCronToolWithConfig(t *testing.T, cfg *config.Config) *CronTool {
+	t.Helper()
+	storePath := filepath.Join(t.TempDir(), "cron.json")
+	cronService := cron.NewCronService(storePath, nil)
+	msgBus := bus.NewMessageBus()
+	tool, err := NewCronTool(cronService, nil, msgBus, t.TempDir(), true, 0, cfg)
+	if err != nil {
+		t.Fatalf("NewCronTool() error: %v", err)
+	}
+	return tool
+}
+
+func newTestCronTool(t *testing.T) *CronTool {
+	t.Helper()
+	return newTestCronToolWithConfig(t, config.DefaultConfig())
+}
+
+// TestCronTool_CommandBlockedFromRemoteChannel verifies command scheduling is restricted to internal channels
+func TestCronTool_CommandBlockedFromRemoteChannel(t *testing.T) {
+	tool := newTestCronTool(t)
+	ctx := WithToolContext(context.Background(), "telegram", "chat-1")
+	result := tool.Execute(ctx, map[string]any{
+		"action":          "add",
+		"message":         "check disk",
+		"command":         "df -h",
+		"command_confirm": true,
+		"at_seconds":      float64(60),
+	})
+
+	if !result.IsError {
+		t.Fatal("expected command scheduling to be blocked from remote channel")
+	}
+	if !strings.Contains(result.ForLLM, "restricted to internal channels") {
+		t.Errorf("expected 'restricted to internal channels', got: %s", result.ForLLM)
+	}
+}
+
+func TestCronTool_CommandDoesNotRequireConfirmByDefault(t *testing.T) {
+	tool := newTestCronTool(t)
+	ctx := WithToolContext(context.Background(), "cli", "direct")
+	result := tool.Execute(ctx, map[string]any{
+		"action":     "add",
+		"message":    "check disk",
+		"command":    "df -h",
+		"at_seconds": float64(60),
+	})
+
+	if result.IsError {
+		t.Fatalf("expected command scheduling without confirm to succeed by default, got: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "Cron job added") {
+		t.Errorf("expected 'Cron job added', got: %s", result.ForLLM)
+	}
+}
+
+func TestCronTool_CommandRequiresConfirmWhenAllowCommandDisabled(t *testing.T) {
+	cfg := config.DefaultConfig()
+	cfg.Tools.Cron.AllowCommand = false
+
+	tool := newTestCronToolWithConfig(t, cfg)
+	ctx := WithToolContext(context.Background(), "cli", "direct")
+	result := tool.Execute(ctx, map[string]any{
+		"action":     "add",
+		"message":    "check disk",
+		"command":    "df -h",
+		"at_seconds": float64(60),
+	})
+
+	if !result.IsError {
+		t.Fatal("expected command scheduling to require confirm when allow_command is disabled")
+	}
+	if !strings.Contains(result.ForLLM, "command_confirm=true") {
+		t.Errorf("expected command_confirm requirement message, got: %s", result.ForLLM)
+	}
+}
+
+func TestCronTool_CommandAllowedWithConfirmWhenAllowCommandDisabled(t *testing.T) {
+	cfg := config.DefaultConfig()
+	cfg.Tools.Cron.AllowCommand = false
+
+	tool := newTestCronToolWithConfig(t, cfg)
+	ctx := WithToolContext(context.Background(), "cli", "direct")
+	result := tool.Execute(ctx, map[string]any{
+		"action":          "add",
+		"message":         "check disk",
+		"command":         "df -h",
+		"command_confirm": true,
+		"at_seconds":      float64(60),
+	})
+
+	if result.IsError {
+		t.Fatalf(
+			"expected command scheduling with confirm to succeed when allow_command is disabled, got: %s",
+			result.ForLLM,
+		)
+	}
+	if !strings.Contains(result.ForLLM, "Cron job added") {
+		t.Errorf("expected 'Cron job added', got: %s", result.ForLLM)
+	}
+}
+
+func TestCronTool_CommandBlockedWhenExecDisabled(t *testing.T) {
+	cfg := config.DefaultConfig()
+	cfg.Tools.Exec.Enabled = false
+
+	tool := newTestCronToolWithConfig(t, cfg)
+	ctx := WithToolContext(context.Background(), "cli", "direct")
+	result := tool.Execute(ctx, map[string]any{
+		"action":          "add",
+		"message":         "check disk",
+		"command":         "df -h",
+		"command_confirm": true,
+		"at_seconds":      float64(60),
+	})
+
+	if !result.IsError {
+		t.Fatal("expected command scheduling to be blocked when exec is disabled")
+	}
+	if !strings.Contains(result.ForLLM, "command execution is disabled") {
+		t.Errorf("expected exec disabled message, got: %s", result.ForLLM)
+	}
+}
+
+// TestCronTool_CommandAllowedFromInternalChannel verifies command scheduling works from internal channels
+func TestCronTool_CommandAllowedFromInternalChannel(t *testing.T) {
+	tool := newTestCronTool(t)
+	ctx := WithToolContext(context.Background(), "cli", "direct")
+	result := tool.Execute(ctx, map[string]any{
+		"action":          "add",
+		"message":         "check disk",
+		"command":         "df -h",
+		"command_confirm": true,
+		"at_seconds":      float64(60),
+	})
+
+	if result.IsError {
+		t.Fatalf("expected command scheduling to succeed from internal channel, got: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "Cron job added") {
+		t.Errorf("expected 'Cron job added', got: %s", result.ForLLM)
+	}
+}
+
+// TestCronTool_AddJobRequiresSessionContext verifies fail-closed when channel/chatID missing
+func TestCronTool_AddJobRequiresSessionContext(t *testing.T) {
+	tool := newTestCronTool(t)
+	result := tool.Execute(context.Background(), map[string]any{
+		"action":     "add",
+		"message":    "reminder",
+		"at_seconds": float64(60),
+	})
+
+	if !result.IsError {
+		t.Fatal("expected error when session context is missing")
+	}
+	if !strings.Contains(result.ForLLM, "no session context") {
+		t.Errorf("expected 'no session context' message, got: %s", result.ForLLM)
+	}
+}
+
+// TestCronTool_NonCommandJobAllowedFromRemoteChannel verifies regular reminders work from any channel
+func TestCronTool_NonCommandJobAllowedFromRemoteChannel(t *testing.T) {
+	tool := newTestCronTool(t)
+	ctx := WithToolContext(context.Background(), "telegram", "chat-1")
+	result := tool.Execute(ctx, map[string]any{
+		"action":     "add",
+		"message":    "time to stretch",
+		"at_seconds": float64(600),
+	})
+
+	if result.IsError {
+		t.Fatalf("expected non-command reminder to succeed from remote channel, got: %s", result.ForLLM)
+	}
+}
+
+func TestCronTool_NonCommandJobDefaultsDeliverToFalse(t *testing.T) {
+	tool := newTestCronTool(t)
+	ctx := WithToolContext(context.Background(), "telegram", "chat-1")
+	result := tool.Execute(ctx, map[string]any{
+		"action":     "add",
+		"message":    "send me a poem",
+		"at_seconds": float64(600),
+	})
+
+	if result.IsError {
+		t.Fatalf("expected non-command reminder to succeed, got: %s", result.ForLLM)
+	}
+
+	jobs := tool.cronService.ListJobs(false)
+	if len(jobs) != 1 {
+		t.Fatalf("expected 1 job, got %d", len(jobs))
+	}
+	if jobs[0].Payload.Deliver {
+		t.Fatal("expected deliver=false by default for non-command jobs")
+	}
+}
+
+func TestCronTool_ExecuteJobPublishesErrorWhenExecDisabled(t *testing.T) {
+	cfg := config.DefaultConfig()
+	cfg.Tools.Exec.Enabled = false
+
+	tool := newTestCronToolWithConfig(t, cfg)
+	job := &cron.CronJob{}
+	job.Payload.Channel = "cli"
+	job.Payload.To = "direct"
+	job.Payload.Command = "df -h"
+
+	if got := tool.ExecuteJob(context.Background(), job); got != "ok" {
+		t.Fatalf("ExecuteJob() = %q, want ok", got)
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+
+	var msg bus.OutboundMessage
+	select {
+	case msg = <-tool.msgBus.OutboundChan():
+		// got message
+	case <-ctx.Done():
+		t.Fatal("timeout waiting for outbound message")
+	}
+	if !strings.Contains(msg.Content, "command execution is disabled") {
+		t.Fatalf("expected exec disabled message, got: %s", msg.Content)
+	}
+}
diff --git a/pkg/tools/filesystem.go b/pkg/tools/filesystem.go
index cd8da3195..39d45013d 100644
--- a/pkg/tools/filesystem.go
+++ b/pkg/tools/filesystem.go
@@ -2,19 +2,25 @@ package tools
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"io"
 	"io/fs"
+	"math"
 	"os"
 	"path/filepath"
 	"regexp"
+	"strconv"
 	"strings"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/fileutil"
+	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
-// validatePath ensures the given path is within the workspace if restrict is true.
-func validatePath(path, workspace string, restrict bool) (string, error) {
+const MaxReadFileSize = 64 * 1024 // 64KB limit to avoid context overflow
+
+func validatePathWithAllowPaths(path, workspace string, restrict bool, patterns []*regexp.Regexp) (string, error) {
 	if workspace == "" {
 		return path, fmt.Errorf("workspace is not defined")
 	}
@@ -35,6 +41,10 @@ func validatePath(path, workspace string, restrict bool) (string, error) {
 	}
 
 	if restrict {
+		if isAllowedPath(absPath, patterns) {
+			return absPath, nil
+		}
+
 		if !isWithinWorkspace(absPath, absWorkspace) {
 			return "", fmt.Errorf("access denied: path is outside the workspace")
 		}
@@ -66,6 +76,137 @@ func validatePath(path, workspace string, restrict bool) (string, error) {
 	return absPath, nil
 }
 
+func isAllowedPath(path string, patterns []*regexp.Regexp) bool {
+	if len(patterns) == 0 {
+		return false
+	}
+
+	cleaned := filepath.Clean(path)
+	if !filepath.IsAbs(cleaned) {
+		return false
+	}
+	if !matchesAllowedPath(cleaned, patterns) {
+		return false
+	}
+
+	resolved, err := resolvePathAgainstExistingAncestor(cleaned)
+	if err != nil {
+		return false
+	}
+
+	return matchesAllowedPath(resolved, patterns)
+}
+
+func matchesAllowedPath(path string, patterns []*regexp.Regexp) bool {
+	cleaned := filepath.Clean(path)
+	for _, pattern := range patterns {
+		if pattern.MatchString(cleaned) {
+			return true
+		}
+		if root, ok := extractAllowedPathRoot(pattern); ok && isWithinAllowedRoot(cleaned, root) {
+			return true
+		}
+	}
+	return false
+}
+
+func extractAllowedPathRoot(pattern *regexp.Regexp) (string, bool) {
+	raw := pattern.String()
+	if !strings.HasPrefix(raw, "^") {
+		return "", false
+	}
+
+	literal := strings.TrimPrefix(raw, "^")
+
+	// Recognize the common "directory prefix" form: ^<literal>(?:/|$)
+	literal = strings.TrimSuffix(literal, "(?:/|$)")
+	literal = strings.TrimSuffix(literal, `(?:\\|$)`)
+
+	// Reject patterns that still contain regex operators after removing the
+	// optional anchored-directory suffix. That keeps arbitrary regex behavior
+	// unchanged and only enables normalized prefix matching for literal paths.
+	if containsUnescapedRegexMeta(literal) {
+		return "", false
+	}
+
+	unescaped, ok := unescapeRegexLiteral(literal)
+	if !ok || unescaped == "" {
+		return "", false
+	}
+
+	return filepath.Clean(unescaped), filepath.IsAbs(unescaped)
+}
+
+func appendUniquePath(paths []string, path string) []string {
+	for _, existing := range paths {
+		if existing == path {
+			return paths
+		}
+	}
+	return append(paths, path)
+}
+
+func containsUnescapedRegexMeta(s string) bool {
+	escaped := false
+	for _, r := range s {
+		if escaped {
+			escaped = false
+			continue
+		}
+		if r == '\\' {
+			escaped = true
+			continue
+		}
+		switch r {
+		case '.', '+', '*', '?', '(', ')', '[', ']', '{', '}', '|':
+			return true
+		}
+	}
+	return escaped
+}
+
+func unescapeRegexLiteral(s string) (string, bool) {
+	var b strings.Builder
+	b.Grow(len(s))
+
+	escaped := false
+	for _, r := range s {
+		if escaped {
+			b.WriteRune(r)
+			escaped = false
+			continue
+		}
+		if r == '\\' {
+			escaped = true
+			continue
+		}
+		b.WriteRune(r)
+	}
+
+	if escaped {
+		return "", false
+	}
+
+	return b.String(), true
+}
+
+func isWithinAllowedRoot(path, root string) bool {
+	candidate := filepath.Clean(path)
+	allowedVariants := []string{filepath.Clean(root)}
+
+	if resolvedRoot, err := resolvePathAgainstExistingAncestor(root); err == nil {
+		allowedVariants = appendUniquePath(allowedVariants, filepath.Clean(resolvedRoot))
+	}
+
+	for _, allowedRoot := range allowedVariants {
+		if isWithinWorkspace(candidate, allowedRoot) {
+			return true
+		}
+	}
+
+	return false
+}
+
 func resolveExistingAncestor(path string) (string, error) {
 	for current := filepath.Clean(path); ; current = filepath.Dir(current) {
 		if resolved, err := filepath.EvalSymlinks(current); err == nil {
@@ -79,21 +220,59 @@ func resolveExistingAncestor(path string) (string, error) {
 	}
 }
 
+func resolvePathAgainstExistingAncestor(path string) (string, error) {
+	cleaned := filepath.Clean(path)
+	for current := cleaned; ; current = filepath.Dir(current) {
+		resolved, err := filepath.EvalSymlinks(current)
+		if err == nil {
+			suffix, relErr := filepath.Rel(current, cleaned)
+			if relErr != nil {
+				return "", relErr
+			}
+			if suffix == "." {
+				return filepath.Clean(resolved), nil
+			}
+			return filepath.Clean(filepath.Join(resolved, suffix)), nil
+		}
+		if !os.IsNotExist(err) {
+			return "", err
+		}
+		if filepath.Dir(current) == current {
+			return "", os.ErrNotExist
+		}
+	}
+}
+
 func isWithinWorkspace(candidate, workspace string) bool {
 	rel, err := filepath.Rel(filepath.Clean(workspace), filepath.Clean(candidate))
-	return err == nil && filepath.IsLocal(rel)
+	return err == nil && (rel == "." || filepath.IsLocal(rel))
 }
 
 type ReadFileTool struct {
-	fs fileSystem
+	fs      fileSystem
+	maxSize int64
 }
 
-func NewReadFileTool(workspace string, restrict bool, allowPaths ...[]*regexp.Regexp) *ReadFileTool {
+func NewReadFileTool(
+	workspace string,
+	restrict bool,
+	maxReadFileSize int,
+	allowPaths ...[]*regexp.Regexp,
+) *ReadFileTool {
 	var patterns []*regexp.Regexp
 	if len(allowPaths) > 0 {
 		patterns = allowPaths[0]
 	}
-	return &ReadFileTool{fs: buildFs(workspace, restrict, patterns)}
+
+	maxSize := int64(maxReadFileSize)
+	if maxSize <= 0 {
+		maxSize = MaxReadFileSize
+	}
+
+	return &ReadFileTool{
+		fs:      buildFs(workspace, restrict, patterns),
+		maxSize: maxSize,
+	}
 }
 
 func (t *ReadFileTool) Name() string {
@@ -101,7 +280,7 @@ func (t *ReadFileTool) Name() string {
 }
 
 func (t *ReadFileTool) Description() string {
-	return "Read the contents of a file"
+	return "Read the contents of a file. Supports pagination via `offset` and `length`."
 }
 
 func (t *ReadFileTool) Parameters() map[string]any {
@@ -110,7 +289,17 @@ func (t *ReadFileTool) Parameters() map[string]any {
 		"properties": map[string]any{
 			"path": map[string]any{
 				"type":        "string",
-				"description": "Path to the file to read",
+				"description": "Path to the file to read.",
+			},
+			"offset": map[string]any{
+				"type":        "integer",
+				"description": "Byte offset to start reading from.",
+				"default":     0,
+			},
+			"length": map[string]any{
+				"type":        "integer",
+				"description": "Maximum number of bytes to read.",
+				"default":     t.maxSize,
 			},
 		},
 		"required": []string{"path"},
@@ -123,11 +312,171 @@ func (t *ReadFileTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 		return ErrorResult("path is required")
 	}
 
-	content, err := t.fs.ReadFile(path)
+	// offset (optional, default 0)
+	offset, err := getInt64Arg(args, "offset", 0)
 	if err != nil {
 		return ErrorResult(err.Error())
 	}
-	return NewToolResult(string(content))
+	if offset < 0 {
+		return ErrorResult("offset must be >= 0")
+	}
+
+	// length (optional, capped at MaxReadFileSize)
+	length, err := getInt64Arg(args, "length", t.maxSize)
+	if err != nil {
+		return ErrorResult(err.Error())
+	}
+	if length <= 0 {
+		return ErrorResult("length must be > 0")
+	}
+	if length > t.maxSize {
+		length = t.maxSize
+	}
+
+	file, err := t.fs.Open(path)
+	if err != nil {
+		return ErrorResult(err.Error())
+	}
+	defer file.Close()
+
+	// measure total size
+	totalSize := int64(-1) // -1 means unknown
+	if info, statErr := file.Stat(); statErr == nil {
+		totalSize = info.Size()
+	}
+
+	// sniff the first 512 bytes to detect binary content before loading
+	// it into the LLM context. Seeking back to 0 afterwards restores state.
+	sniff := make([]byte, 512)
+	sniffN, _ := file.Read(sniff)
+
+	// Reset read position to beginning before applying the caller's offset.
+	if seeker, ok := file.(io.Seeker); ok {
+		_, err = seeker.Seek(0, io.SeekStart)
+		if err != nil {
+			return ErrorResult(fmt.Sprintf("failed to reset file position after sniff: %v", err))
+		}
+	} else {
+		// Non-seekable: we consumed sniffN bytes above; account for them when
+		// discarding to reach the requested offset below.
+		// If offset < sniffN the data we already read covers it, which we
+		// cannot replay on a non-seekable stream — return a clear error.
+		if offset < int64(sniffN) && offset > 0 {
+			return ErrorResult(
+				"non-seekable file: cannot seek to an offset within the first 512 bytes after binary detection",
+			)
+		}
+	}
+
+	// Seek to the requested offset.
+	if seeker, ok := file.(io.Seeker); ok {
+		_, err = seeker.Seek(offset, io.SeekStart)
+		if err != nil {
+			return ErrorResult(fmt.Sprintf("failed to seek to offset %d: %v", offset, err))
+		}
+	} else if offset > 0 {
+		// Fallback for non-seekable streams: discard leading bytes.
+		// sniffN bytes were already consumed above, so subtract them.
+		remaining := offset - int64(sniffN)
+		if remaining > 0 {
+			_, err = io.CopyN(io.Discard, file, remaining)
+			if err != nil {
+				return ErrorResult(fmt.Sprintf("failed to advance to offset %d: %v", offset, err))
+			}
+		}
+	}
+
+	// read length+1 bytes to reliably detect whether more content exists
+	// without relying on totalSize (which may be -1 for non-seekable streams).
+	// This avoids the false-positive TRUNCATED message on the last page.
+	probe := make([]byte, length+1)
+	n, err := io.ReadFull(file, probe)
+	// FIX: io.ReadFull returns io.ErrUnexpectedEOF for partial reads (0 < n < len),
+	// and io.EOF only when n == 0. Both are normal terminal conditions — only
+	// other errors are genuine failures.
+	if err != nil && err != io.EOF && !errors.Is(err, io.ErrUnexpectedEOF) {
+		return ErrorResult(fmt.Sprintf("failed to read file content: %v", err))
+	}
+
+	// hasMore is true only when we actually got the extra probe byte.
+	hasMore := int64(n) > length
+	data := probe[:min(int64(n), length)]
+
+	if len(data) == 0 {
+		return NewToolResult("[END OF FILE - no content at this offset]")
+	}
+
+	// Build metadata header.
+	// use filepath.Base(path) instead of the raw path to avoid leaking
+	// internal filesystem structure into the LLM context.
+	readEnd := offset + int64(len(data))
+	// use ASCII hyphen-minus instead of en-dash (U+2013) to keep the
+	// header parseable by downstream tools and log processors.
+	readRange := fmt.Sprintf("bytes %d-%d", offset, readEnd-1)
+
+	displayPath := filepath.Base(path)
+	var header string
+	if totalSize >= 0 {
+		header = fmt.Sprintf(
+			"[file: %s | total: %d bytes | read: %s]",
+			displayPath, totalSize, readRange,
+		)
+	} else {
+		header = fmt.Sprintf(
+			"[file: %s | read: %s | total size unknown]",
+			displayPath, readRange,
+		)
+	}
+
+	if hasMore {
+		header += fmt.Sprintf(
+			"\n[TRUNCATED - file has more content. Call read_file again with offset=%d to continue.]",
+			readEnd,
+		)
+	} else {
+		header += "\n[END OF FILE - no further content.]"
+	}
+
+	logger.DebugCF("tool", "ReadFileTool execution completed successfully",
+		map[string]any{
+			"path":       path,
+			"bytes_read": len(data),
+			"has_more":   hasMore,
+		})
+
+	return NewToolResult(header + "\n\n" + string(data))
+}
+
+// getInt64Arg extracts an integer argument from the args map, returning the
+// provided default if the key is absent.
+func getInt64Arg(args map[string]any, key string, defaultVal int64) (int64, error) {
+	raw, exists := args[key]
+	if !exists {
+		return defaultVal, nil
+	}
+
+	switch v := raw.(type) {
+	case float64:
+		if v != math.Trunc(v) {
+			return 0, fmt.Errorf("%s must be an integer, got float %v", key, v)
+		}
+		if v > math.MaxInt64 || v < math.MinInt64 {
+			return 0, fmt.Errorf("%s value %v overflows int64", key, v)
+		}
+		return int64(v), nil
+	case int:
+		return int64(v), nil
+	case int64:
+		return v, nil
+	case string:
+		parsed, err := strconv.ParseInt(v, 10, 64)
+		if err != nil {
+			return 0, fmt.Errorf("invalid integer format for %s parameter: %w", key, err)
+		}
+		return parsed, nil
+	default:
+		return 0, fmt.Errorf("unsupported type %T for %s parameter", raw, key)
+	}
 }
 
 type WriteFileTool struct {
@@ -147,7 +496,7 @@ func (t *WriteFileTool) Name() string {
 }
 
 func (t *WriteFileTool) Description() string {
-	return "Write content to a file"
+	return "Write content to a file. If the file already exists, you must set overwrite=true to replace it."
 }
 
 func (t *WriteFileTool) Parameters() map[string]any {
@@ -162,6 +511,11 @@ func (t *WriteFileTool) Parameters() map[string]any {
 				"type":        "string",
 				"description": "Content to write to the file",
 			},
+			"overwrite": map[string]any{
+				"type":        "boolean",
+				"description": "Must be set to true to overwrite an existing file.",
+				"default":     false,
+			},
 		},
 		"required": []string{"path", "content"},
 	}
@@ -178,6 +532,14 @@ func (t *WriteFileTool) Execute(ctx context.Context, args map[string]any) *ToolR
 		return ErrorResult("content is required")
 	}
 
+	overwrite, _ := args["overwrite"].(bool)
+
+	if !overwrite {
+		if _, err := t.fs.Open(path); err == nil {
+			return ErrorResult(fmt.Sprintf("file: %s already exists. Set overwrite=true to replace.", path))
+		}
+	}
+
 	if err := t.fs.WriteFile(path, []byte(content)); err != nil {
 		return ErrorResult(err.Error())
 	}
@@ -249,6 +611,7 @@ type fileSystem interface {
 	ReadFile(path string) ([]byte, error)
 	WriteFile(path string, data []byte) error
 	ReadDir(path string) ([]os.DirEntry, error)
+	Open(path string) (fs.File, error)
 }
 
 // hostFs is an unrestricted fileReadWriter that operates directly on the host filesystem.
@@ -278,6 +641,20 @@ func (h *hostFs) WriteFile(path string, data []byte) error {
 	return fileutil.WriteFileAtomic(path, data, 0o600)
 }
 
+func (h *hostFs) Open(path string) (fs.File, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, fmt.Errorf("failed to open file: file not found: %w", err)
+		}
+		if os.IsPermission(err) {
+			return nil, fmt.Errorf("failed to open file: access denied: %w", err)
+		}
+		return nil, fmt.Errorf("failed to open file: %w", err)
+	}
+	return f, nil
+}
+
 // sandboxFs is a sandboxed fileSystem that operates within a strictly defined workspace using os.Root.
 type sandboxFs struct {
 	workspace string
@@ -389,6 +766,26 @@ func (r *sandboxFs) ReadDir(path string) ([]os.DirEntry, error) {
 	return entries, err
 }
 
+func (r *sandboxFs) Open(path string) (fs.File, error) {
+	var f fs.File
+	err := r.execute(path, func(root *os.Root, relPath string) error {
+		file, err := root.Open(relPath)
+		if err != nil {
+			if os.IsNotExist(err) {
+				return fmt.Errorf("failed to open file: file not found: %w", err)
+			}
+			if os.IsPermission(err) || strings.Contains(err.Error(), "escapes from parent") ||
+				strings.Contains(err.Error(), "permission denied") {
+				return fmt.Errorf("failed to open file: access denied: %w", err)
+			}
+			return fmt.Errorf("failed to open file: %w", err)
+		}
+		f = file
+		return nil
+	})
+	return f, err
+}
+
 // whitelistFs wraps a sandboxFs and allows access to specific paths outside
 // the workspace when they match any of the provided patterns.
 type whitelistFs struct {
@@ -398,12 +795,7 @@ type whitelistFs struct {
 }
 
 func (w *whitelistFs) matches(path string) bool {
-	for _, p := range w.patterns {
-		if p.MatchString(path) {
-			return true
-		}
-	}
-	return false
+	return isAllowedPath(path, w.patterns)
 }
 
 func (w *whitelistFs) ReadFile(path string) ([]byte, error) {
@@ -427,6 +819,13 @@ func (w *whitelistFs) ReadDir(path string) ([]os.DirEntry, error) {
 	return w.sandbox.ReadDir(path)
 }
 
+func (w *whitelistFs) Open(path string) (fs.File, error) {
+	if w.matches(path) {
+		return w.host.Open(path)
+	}
+	return w.sandbox.Open(path)
+}
+
 // buildFs returns the appropriate fileSystem implementation based on restriction
 // settings and optional path whitelist patterns.
 func buildFs(workspace string, restrict bool, patterns []*regexp.Regexp) fileSystem {
diff --git a/pkg/tools/filesystem_test.go b/pkg/tools/filesystem_test.go
index 666004cd4..0b4dd310b 100644
--- a/pkg/tools/filesystem_test.go
+++ b/pkg/tools/filesystem_test.go
@@ -18,7 +18,7 @@ func TestFilesystemTool_ReadFile_Success(t *testing.T) {
 	testFile := filepath.Join(tmpDir, "test.txt")
 	os.WriteFile(testFile, []byte("test content"), 0o644)
 
-	tool := NewReadFileTool("", false)
+	tool := NewReadFileTool("", false, MaxReadFileSize)
 	ctx := context.Background()
 	args := map[string]any{
 		"path": testFile,
@@ -45,7 +45,7 @@ func TestFilesystemTool_ReadFile_Success(t *testing.T) {
 
 // TestFilesystemTool_ReadFile_NotFound verifies error handling for missing file
 func TestFilesystemTool_ReadFile_NotFound(t *testing.T) {
-	tool := NewReadFileTool("", false)
+	tool := NewReadFileTool("", false, MaxReadFileSize)
 	ctx := context.Background()
 	args := map[string]any{
 		"path": "/nonexistent_file_12345.txt",
@@ -59,7 +59,7 @@ func TestFilesystemTool_ReadFile_NotFound(t *testing.T) {
 	}
 
 	// Should contain error message
-	if !strings.Contains(result.ForLLM, "failed to read") && !strings.Contains(result.ForUser, "failed to read") {
+	if !strings.Contains(result.ForLLM, "failed to open file") && !strings.Contains(result.ForUser, "failed to read") {
 		t.Errorf("Expected error message, got ForLLM: %s, ForUser: %s", result.ForLLM, result.ForUser)
 	}
 }
@@ -189,6 +189,121 @@ func TestFilesystemTool_WriteFile_MissingContent(t *testing.T) {
 	}
 }
 
+// TestFilesystemTool_WriteFile_OverwriteDefaultBlocked verifies that writing to an
+// existing file without overwrite=true returns an error.
+func TestFilesystemTool_WriteFile_OverwriteDefaultBlocked(t *testing.T) {
+	tmpDir := t.TempDir()
+	testFile := filepath.Join(tmpDir, "existing.txt")
+	os.WriteFile(testFile, []byte("original"), 0o644)
+
+	tool := NewWriteFileTool("", false)
+	result := tool.Execute(context.Background(), map[string]any{
+		"path":    testFile,
+		"content": "new content",
+	})
+
+	assert.True(t, result.IsError, "expected error when overwriting without overwrite=true")
+	assert.Contains(t, result.ForLLM, "already exists")
+	assert.Contains(t, result.ForLLM, "overwrite=true")
+
+	// Original content must be untouched
+	data, err := os.ReadFile(testFile)
+	assert.NoError(t, err)
+	assert.Equal(t, "original", string(data))
+}
+
+// TestFilesystemTool_WriteFile_OverwriteExplicitAllowed verifies that setting
+// overwrite=true replaces the existing file.
+func TestFilesystemTool_WriteFile_OverwriteExplicitAllowed(t *testing.T) {
+	tmpDir := t.TempDir()
+	testFile := filepath.Join(tmpDir, "existing.txt")
+	os.WriteFile(testFile, []byte("original"), 0o644)
+
+	tool := NewWriteFileTool("", false)
+	result := tool.Execute(context.Background(), map[string]any{
+		"path":      testFile,
+		"content":   "replaced",
+		"overwrite": true,
+	})
+
+	assert.False(t, result.IsError, "expected success with overwrite=true, got: %s", result.ForLLM)
+
+	data, err := os.ReadFile(testFile)
+	assert.NoError(t, err)
+	assert.Equal(t, "replaced", string(data))
+}
+
+// TestFilesystemTool_WriteFile_NewFileNoOverwriteFlag verifies that a new (non-existing)
+// file can be written without setting overwrite=true.
+func TestFilesystemTool_WriteFile_NewFileNoOverwriteFlag(t *testing.T) {
+	tmpDir := t.TempDir()
+	testFile := filepath.Join(tmpDir, "newfile.txt")
+
+	tool := NewWriteFileTool("", false)
+	result := tool.Execute(context.Background(), map[string]any{
+		"path":    testFile,
+		"content": "brand new",
+	})
+
+	assert.False(t, result.IsError, "expected success for new file, got: %s", result.ForLLM)
+
+	data, err := os.ReadFile(testFile)
+	assert.NoError(t, err)
+	assert.Equal(t, "brand new", string(data))
+}
+
+// TestFilesystemTool_WriteFile_OverwriteFalseExplicitBlocked verifies that
+// explicitly passing overwrite=false also blocks overwriting.
+func TestFilesystemTool_WriteFile_OverwriteFalseExplicitBlocked(t *testing.T) {
+	tmpDir := t.TempDir()
+	testFile := filepath.Join(tmpDir, "existing.txt")
+	os.WriteFile(testFile, []byte("original"), 0o644)
+
+	tool := NewWriteFileTool("", false)
+	result := tool.Execute(context.Background(), map[string]any{
+		"path":      testFile,
+		"content":   "new content",
+		"overwrite": false,
+	})
+
+	assert.True(t, result.IsError, "expected error when overwrite=false")
+	assert.Contains(t, result.ForLLM, "already exists")
+
+	data, err := os.ReadFile(testFile)
+	assert.NoError(t, err)
+	assert.Equal(t, "original", string(data))
+}
+
+// TestFilesystemTool_WriteFile_OverwriteSandboxed verifies the overwrite guard
+// works correctly in restricted (sandbox) mode.
+func TestFilesystemTool_WriteFile_OverwriteSandboxed(t *testing.T) {
+	workspace := t.TempDir()
+	testFile := "file.txt"
+	os.WriteFile(filepath.Join(workspace, testFile), []byte("original"), 0o644)
+
+	tool := NewWriteFileTool(workspace, true)
+
+	// Without overwrite=true → blocked
+	result := tool.Execute(context.Background(), map[string]any{
+		"path":    testFile,
+		"content": "new content",
+	})
+	assert.True(t, result.IsError, "expected error in sandbox mode without overwrite=true")
+	assert.Contains(t, result.ForLLM, "already exists")
+
+	// With overwrite=true → allowed
+	result = tool.Execute(context.Background(), map[string]any{
+		"path":      testFile,
+		"content":   "replaced in sandbox",
+		"overwrite": true,
+	})
+	assert.False(t, result.IsError, "expected success in sandbox mode with overwrite=true, got: %s", result.ForLLM)
+
+	data, err := os.ReadFile(filepath.Join(workspace, testFile))
+	assert.NoError(t, err)
+	assert.Equal(t, "replaced in sandbox", string(data))
+}
+
 // TestFilesystemTool_ListDir_Success verifies successful directory listing
 func TestFilesystemTool_ListDir_Success(t *testing.T) {
 	tmpDir := t.TempDir()
@@ -271,7 +386,7 @@ func TestFilesystemTool_ReadFile_RejectsSymlinkEscape(t *testing.T) {
 		t.Skipf("symlink not supported in this environment: %v", err)
 	}
 
-	tool := NewReadFileTool(workspace, true)
+	tool := NewReadFileTool(workspace, true, MaxReadFileSize)
 	result := tool.Execute(context.Background(), map[string]any{
 		"path": link,
 	})
@@ -289,7 +404,7 @@ func TestFilesystemTool_ReadFile_RejectsSymlinkEscape(t *testing.T) {
 }
 
 func TestFilesystemTool_EmptyWorkspace_AccessDenied(t *testing.T) {
-	tool := NewReadFileTool("", true) // restrict=true but workspace=""
+	tool := NewReadFileTool("", true, MaxReadFileSize) // restrict=true but workspace=""
 
 	// Try to read a sensitive file (simulated by a temp file outside workspace)
 	tmpDir := t.TempDir()
@@ -499,7 +614,7 @@ func TestWhitelistFs_AllowsMatchingPaths(t *testing.T) {
 	// Pattern allows access to the outsideDir.
 	patterns := []*regexp.Regexp{regexp.MustCompile(`^` + regexp.QuoteMeta(outsideDir))}
 
-	tool := NewReadFileTool(workspace, true, patterns)
+	tool := NewReadFileTool(workspace, true, MaxReadFileSize, patterns)
 
 	// Read from whitelisted path should succeed.
 	result := tool.Execute(context.Background(), map[string]any{"path": outsideFile})
@@ -520,3 +635,211 @@ func TestWhitelistFs_AllowsMatchingPaths(t *testing.T) {
 		t.Errorf("expected non-whitelisted path to be blocked, got: %s", result.ForLLM)
 	}
 }
+
+func TestWhitelistFs_BlocksSymlinkEscapeInAllowedDir(t *testing.T) {
+	workspace := t.TempDir()
+	allowedDir := t.TempDir()
+	secretDir := t.TempDir()
+	secretFile := filepath.Join(secretDir, "secret.txt")
+	if err := os.WriteFile(secretFile, []byte("top secret"), 0o644); err != nil {
+		t.Fatalf("WriteFile(secretFile) error = %v", err)
+	}
+
+	linkPath := filepath.Join(allowedDir, "link_out")
+	if err := os.Symlink(secretDir, linkPath); err != nil {
+		t.Skipf("symlink not supported in this environment: %v", err)
+	}
+
+	patterns := []*regexp.Regexp{regexp.MustCompile(`^` + regexp.QuoteMeta(allowedDir))}
+	tool := NewReadFileTool(workspace, true, MaxReadFileSize, patterns)
+
+	result := tool.Execute(context.Background(), map[string]any{"path": filepath.Join(linkPath, "secret.txt")})
+	if !result.IsError {
+		t.Fatalf("expected symlink escape from allowed dir to be blocked, got: %s", result.ForLLM)
+	}
+}
+
+func TestWhitelistFs_WriteAllowsNewFileUnderAllowedDir(t *testing.T) {
+	workspace := t.TempDir()
+	rootDir := t.TempDir()
+	allowedDir := filepath.Join(rootDir, "allowed")
+	targetFile := filepath.Join(allowedDir, "nested", "file.txt")
+
+	patterns := []*regexp.Regexp{regexp.MustCompile(`^` + regexp.QuoteMeta(allowedDir))}
+	tool := NewWriteFileTool(workspace, true, patterns)
+
+	result := tool.Execute(context.Background(), map[string]any{
+		"path":    targetFile,
+		"content": "outside write",
+	})
+	if result.IsError {
+		t.Fatalf("expected whitelisted write to succeed, got: %s", result.ForLLM)
+	}
+
+	data, err := os.ReadFile(targetFile)
+	if err != nil {
+		t.Fatalf("ReadFile(targetFile) error = %v", err)
+	}
+	if string(data) != "outside write" {
+		t.Fatalf("target file content = %q, want %q", string(data), "outside write")
+	}
+}
+
+func TestWhitelistFs_AllowsResolvedAllowedRootAlias(t *testing.T) {
+	workspace := t.TempDir()
+	realDir := t.TempDir()
+	linkParent := t.TempDir()
+	allowedAlias := filepath.Join(linkParent, "allowed-link")
+
+	if err := os.Symlink(realDir, allowedAlias); err != nil {
+		t.Skipf("symlink not supported in this environment: %v", err)
+	}
+
+	targetFile := filepath.Join(allowedAlias, "nested", "alias.txt")
+	if err := os.MkdirAll(filepath.Dir(targetFile), 0o755); err != nil {
+		t.Fatalf("MkdirAll(targetFile dir) error = %v", err)
+	}
+	if err := os.WriteFile(targetFile, []byte("through alias"), 0o644); err != nil {
+		t.Fatalf("WriteFile(targetFile) error = %v", err)
+	}
+
+	patterns := []*regexp.Regexp{
+		regexp.MustCompile(
+			"^" + regexp.QuoteMeta(filepath.Clean(allowedAlias)) +
+				"(?:" + regexp.QuoteMeta(string(os.PathSeparator)) + "|$)",
+		),
+	}
+	tool := NewReadFileTool(workspace, true, MaxReadFileSize, patterns)
+
+	result := tool.Execute(context.Background(), map[string]any{"path": targetFile})
+	if result.IsError {
+		t.Fatalf("expected symlink-backed allowed root to be readable, got: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "through alias") {
+		t.Fatalf("expected file content, got: %s", result.ForLLM)
+	}
+}
+
+// TestReadFileTool_ChunkedReading verifies the pagination logic of the tool
+// by reading a file in multiple chunks using 'offset' and 'length'.
+func TestReadFileTool_ChunkedReading(t *testing.T) {
+	tmpDir := t.TempDir()
+	testFile := filepath.Join(tmpDir, "pagination_test.txt")
+
+	// Create a test file with exactly 26 bytes of content
+	fullContent := "abcdefghijklmnopqrstuvwxyz"
+	err := os.WriteFile(testFile, []byte(fullContent), 0o644)
+	if err != nil {
+		t.Fatalf("Failed to write test file: %v", err)
+	}
+
+	tool := NewReadFileTool(tmpDir, false, MaxReadFileSize)
+	ctx := context.Background()
+
+	// --- Step 1: Read the first chunk (10 bytes) ---
+	args1 := map[string]any{
+		"path":   testFile,
+		"offset": 0,
+		"length": 10,
+	}
+	result1 := tool.Execute(ctx, args1)
+
+	if result1.IsError {
+		t.Fatalf("Chunk 1 failed: %s", result1.ForLLM)
+	}
+
+	// Expect the first 10 characters
+	if !strings.Contains(result1.ForLLM, "abcdefghij") {
+		t.Errorf("Chunk 1 should contain 'abcdefghij', got: %s", result1.ForLLM)
+	}
+	// Expect the header to indicate the file is truncated
+	if !strings.Contains(result1.ForLLM, "[TRUNCATED") {
+		t.Errorf("Chunk 1 header should indicate truncation, got: %s", result1.ForLLM)
+	}
+	// Expect the header to suggest the next offset (10)
+	if !strings.Contains(result1.ForLLM, "offset=10") {
+		t.Errorf("Chunk 1 header should suggest next offset=10, got: %s", result1.ForLLM)
+	}
+
+	// Step 2: Read the second chunk (10 bytes) ---
+	args2 := map[string]any{
+		"path":   testFile,
+		"offset": 10,
+		"length": 10,
+	}
+	result2 := tool.Execute(ctx, args2)
+
+	if result2.IsError {
+		t.Fatalf("Chunk 2 failed: %s", result2.ForLLM)
+	}
+
+	// Expect the next 10 characters
+	if !strings.Contains(result2.ForLLM, "klmnopqrst") {
+		t.Errorf("Chunk 2 should contain 'klmnopqrst', got: %s", result2.ForLLM)
+	}
+	// Expect the header to suggest the next offset (20)
+	if !strings.Contains(result2.ForLLM, "offset=20") {
+		t.Errorf("Chunk 2 header should suggest next offset=20, got: %s", result2.ForLLM)
+	}
+
+	// Step 3: Read the final chunk (remaining 6 bytes) ---
+	// We ask for 10 bytes, but only 6 are left in the file
+	args3 := map[string]any{
+		"path":   testFile,
+		"offset": 20,
+		"length": 10,
+	}
+	result3 := tool.Execute(ctx, args3)
+
+	if result3.IsError {
+		t.Fatalf("Chunk 3 failed: %s", result3.ForLLM)
+	}
+
+	// Expect the last 6 characters
+	if !strings.Contains(result3.ForLLM, "uvwxyz") {
+		t.Errorf("Chunk 3 should contain 'uvwxyz', got: %s", result3.ForLLM)
+	}
+	// Expect the header to indicate the end of the file
+	if !strings.Contains(result3.ForLLM, "[END OF FILE") {
+		t.Errorf("Chunk 3 header should indicate end of file, got: %s", result3.ForLLM)
+	}
+
+	// Ensure no TRUNCATED message is present in the final chunk
+	if strings.Contains(result3.ForLLM, "[TRUNCATED") {
+		t.Errorf("Chunk 3 header should NOT indicate truncation, got: %s", result3.ForLLM)
+	}
+}
+
+// TestReadFileTool_OffsetBeyondEOF checks the behavior when requesting
+// An offset that exceeds the total file size.
+func TestReadFileTool_OffsetBeyondEOF(t *testing.T) {
+	tmpDir := t.TempDir()
+	testFile := filepath.Join(tmpDir, "short.txt")
+
+	// create a file of only 5 bytes
+	err := os.WriteFile(testFile, []byte("12345"), 0o644)
+	if err != nil {
+		t.Fatalf("Failed to write test file: %v", err)
+	}
+
+	tool := NewReadFileTool(tmpDir, false, MaxReadFileSize)
+	ctx := context.Background()
+
+	args := map[string]any{
+		"path":   testFile,
+		"offset": int64(100), // Offset beyond the end of the file
+	}
+
+	result := tool.Execute(ctx, args)
+
+	// It should not be classified as a tool execution error
+	if result.IsError {
+		t.Errorf("A mistake was not expected, obtained IsError=true: %s", result.ForLLM)
+	}
+
+	// Must return EXACTLY the string provided in the code
+	expectedMsg := "[END OF FILE - no content at this offset]"
+	if result.ForLLM != expectedMsg {
+		t.Errorf("The message %q was expected, obtained: %q", expectedMsg, result.ForLLM)
+	}
+}
diff --git a/pkg/tools/mcp_tool.go b/pkg/tools/mcp_tool.go
new file mode 100644
index 000000000..5bffb4e89
--- /dev/null
+++ b/pkg/tools/mcp_tool.go
@@ -0,0 +1,504 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"hash/fnv"
+	"os"
+	"strings"
+	"time"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+// MCPManager defines the interface for MCP manager operations
+// This allows for easier testing with mock implementations
+type MCPManager interface {
+	CallTool(
+		ctx context.Context,
+		serverName, toolName string,
+		arguments map[string]any,
+	) (*mcp.CallToolResult, error)
+}
+
+// MCPTool wraps an MCP tool to implement the Tool interface
+type MCPTool struct {
+	manager    MCPManager
+	serverName string
+	tool       *mcp.Tool
+	mediaStore media.MediaStore
+}
+
+// NewMCPTool creates a new MCP tool wrapper
+func NewMCPTool(manager MCPManager, serverName string, tool *mcp.Tool) *MCPTool {
+	return &MCPTool{
+		manager:    manager,
+		serverName: serverName,
+		tool:       tool,
+	}
+}
+
+func (t *MCPTool) SetMediaStore(store media.MediaStore) {
+	t.mediaStore = store
+}
+
+// sanitizeIdentifierComponent normalizes a string so it can be safely used
+// as part of a tool/function identifier for downstream providers.
+// It:
+//   - lowercases the string
+//   - replaces any character not in [a-z0-9_-] with '_'
+//   - collapses multiple consecutive '_' into a single '_'
+//   - trims leading/trailing '_'
+//   - falls back to "unnamed" if the result is empty
+//   - truncates overly long components to a reasonable length
+func sanitizeIdentifierComponent(s string) string {
+	const maxLen = 64
+
+	s = strings.ToLower(s)
+	var b strings.Builder
+	b.Grow(len(s))
+
+	prevUnderscore := false
+	for _, r := range s {
+		isAllowed := (r >= 'a' && r <= 'z') ||
+			(r >= '0' && r <= '9') ||
+			r == '_' || r == '-'
+
+		if !isAllowed {
+			// Normalize any disallowed character to '_'
+			if !prevUnderscore {
+				b.WriteRune('_')
+				prevUnderscore = true
+			}
+			continue
+		}
+
+		if r == '_' {
+			if prevUnderscore {
+				continue
+			}
+			prevUnderscore = true
+		} else {
+			prevUnderscore = false
+		}
+
+		b.WriteRune(r)
+	}
+
+	result := strings.Trim(b.String(), "_")
+	if result == "" {
+		result = "unnamed"
+	}
+
+	if len(result) > maxLen {
+		result = result[:maxLen]
+	}
+
+	return result
+}
+
+// Name returns the tool name, prefixed with the server name.
+// The total length is capped at 64 characters (OpenAI-compatible API limit).
+// A short hash of the original (unsanitized) server and tool names is appended
+// whenever sanitization is lossy or the name is truncated, ensuring that two
+// names which differ only in disallowed characters remain distinct after sanitization.
+func (t *MCPTool) Name() string {
+	// Prefix with server name to avoid conflicts, and sanitize components
+	sanitizedServer := sanitizeIdentifierComponent(t.serverName)
+	sanitizedTool := sanitizeIdentifierComponent(t.tool.Name)
+	full := fmt.Sprintf("mcp_%s_%s", sanitizedServer, sanitizedTool)
+
+	// Check if sanitization was lossless (only lowercasing, no char replacement/truncation)
+	lossless := strings.ToLower(t.serverName) == sanitizedServer &&
+		strings.ToLower(t.tool.Name) == sanitizedTool
+
+	const maxTotal = 64
+	if lossless && len(full) <= maxTotal {
+		return full
+	}
+
+	// Sanitization was lossy or name too long: append hash of the ORIGINAL names
+	// (not the sanitized names) so different originals always yield different hashes.
+	h := fnv.New32a()
+	_, _ = h.Write([]byte(t.serverName + "\x00" + t.tool.Name))
+	suffix := fmt.Sprintf("%08x", h.Sum32()) // 8 chars
+
+	base := full
+	if len(base) > maxTotal-9 {
+		base = strings.TrimRight(full[:maxTotal-9], "_")
+	}
+	return base + "_" + suffix
+}
+
+// Description returns the tool description
+func (t *MCPTool) Description() string {
+	desc := t.tool.Description
+	if desc == "" {
+		desc = fmt.Sprintf("MCP tool from %s server", t.serverName)
+	}
+	// Add server info to description
+	return fmt.Sprintf("[MCP:%s] %s", t.serverName, desc)
+}
+
+// Parameters returns the tool parameters schema
+func (t *MCPTool) Parameters() map[string]any {
+	// The InputSchema is already a JSON Schema object
+	schema := t.tool.InputSchema
+
+	// Handle nil schema
+	if schema == nil {
+		return map[string]any{
+			"type":       "object",
+			"properties": map[string]any{},
+			"required":   []string{},
+		}
+	}
+
+	// Try direct conversion first (fast path)
+	if schemaMap, ok := schema.(map[string]any); ok {
+		return schemaMap
+	}
+
+	// Handle json.RawMessage and []byte - unmarshal directly
+	var jsonData []byte
+	if rawMsg, ok := schema.(json.RawMessage); ok {
+		jsonData = rawMsg
+	} else if bytes, ok := schema.([]byte); ok {
+		jsonData = bytes
+	}
+
+	if jsonData != nil {
+		var result map[string]any
+		if err := json.Unmarshal(jsonData, &result); err == nil {
+			return result
+		}
+		// Fallback on error
+		return map[string]any{
+			"type":       "object",
+			"properties": map[string]any{},
+			"required":   []string{},
+		}
+	}
+
+	// For other types (structs, etc.), convert via JSON marshal/unmarshal
+	var err error
+	jsonData, err = json.Marshal(schema)
+	if err != nil {
+		// Fallback to empty schema if marshaling fails
+		return map[string]any{
+			"type":       "object",
+			"properties": map[string]any{},
+			"required":   []string{},
+		}
+	}
+
+	var result map[string]any
+	if err := json.Unmarshal(jsonData, &result); err != nil {
+		// Fallback to empty schema if unmarshaling fails
+		return map[string]any{
+			"type":       "object",
+			"properties": map[string]any{},
+			"required":   []string{},
+		}
+	}
+
+	return result
+}
+
+// Execute executes the MCP tool
+func (t *MCPTool) Execute(ctx context.Context, args map[string]any) *ToolResult {
+	result, err := t.manager.CallTool(ctx, t.serverName, t.tool.Name, args)
+	if err != nil {
+		return ErrorResult(fmt.Sprintf("MCP tool execution failed: %v", err)).WithError(err)
+	}
+
+	if result == nil {
+		nilErr := fmt.Errorf("MCP tool returned nil result without error")
+		return ErrorResult("MCP tool execution failed: nil result").WithError(nilErr)
+	}
+
+	// Handle error result from server
+	if result.IsError {
+		errMsg := extractContentText(result.Content)
+		return ErrorResult(fmt.Sprintf("MCP tool returned error: %s", errMsg)).
+			WithError(fmt.Errorf("MCP tool error: %s", errMsg))
+	}
+
+	return t.normalizeResultContent(ctx, result.Content)
+}
+
+// extractContentText extracts text from MCP content array
+func extractContentText(content []mcp.Content) string {
+	var parts []string
+	for _, c := range content {
+		switch v := c.(type) {
+		case *mcp.TextContent:
+			parts = append(parts, sanitizeToolLLMContent(v.Text))
+		case *mcp.ImageContent:
+			parts = append(parts, fmt.Sprintf("[Image: %s]", normalizedMIMEType(v.MIMEType)))
+		case *mcp.AudioContent:
+			parts = append(parts, fmt.Sprintf("[Audio: %s]", normalizedMIMEType(v.MIMEType)))
+		case *mcp.ResourceLink:
+			parts = append(parts, summarizeResourceLink(v))
+		case *mcp.EmbeddedResource:
+			parts = append(parts, summarizeEmbeddedResource(v))
+		default:
+			// For other content types, use string representation
+			parts = append(parts, fmt.Sprintf("[Content: %T]", v))
+		}
+	}
+	return sanitizeToolLLMContent(strings.Join(parts, "\n"))
+}
+
+func (t *MCPTool) normalizeResultContent(ctx context.Context, content []mcp.Content) *ToolResult {
+	llmParts := make([]string, 0, len(content))
+	mediaRefs := make([]string, 0, len(content))
+
+	for _, c := range content {
+		switch v := c.(type) {
+		case *mcp.TextContent:
+			text := strings.TrimSpace(sanitizeToolLLMContent(v.Text))
+			if text != "" {
+				llmParts = append(llmParts, text)
+			}
+		case *mcp.ImageContent:
+			ref, note := t.storeBinaryContent(
+				ctx,
+				"image",
+				normalizedMIMEType(v.MIMEType),
+				v.Data,
+				v.Annotations,
+			)
+			if ref != "" {
+				mediaRefs = append(mediaRefs, ref)
+			}
+			if note != "" {
+				llmParts = append(llmParts, note)
+			}
+		case *mcp.AudioContent:
+			ref, note := t.storeBinaryContent(
+				ctx,
+				"audio",
+				normalizedMIMEType(v.MIMEType),
+				v.Data,
+				v.Annotations,
+			)
+			if ref != "" {
+				mediaRefs = append(mediaRefs, ref)
+			}
+			if note != "" {
+				llmParts = append(llmParts, note)
+			}
+		case *mcp.ResourceLink:
+			llmParts = append(llmParts, summarizeResourceLink(v))
+		case *mcp.EmbeddedResource:
+			ref, note := t.storeEmbeddedResource(ctx, v)
+			if ref != "" {
+				mediaRefs = append(mediaRefs, ref)
+			}
+			if note != "" {
+				llmParts = append(llmParts, note)
+			}
+		default:
+			llmParts = append(llmParts, fmt.Sprintf("[MCP returned unsupported content type %T]", v))
+		}
+	}
+
+	result := &ToolResult{
+		ForLLM: strings.Join(compactStrings(llmParts), "\n"),
+		Media:  mediaRefs,
+	}
+	return result
+}
+
+func (t *MCPTool) storeEmbeddedResource(ctx context.Context, content *mcp.EmbeddedResource) (string, string) {
+	if content == nil || content.Resource == nil {
+		return "", "[MCP returned an embedded resource without data.]"
+	}
+
+	resource := content.Resource
+	if len(resource.Blob) > 0 {
+		return t.storeBinaryContent(
+			ctx,
+			"resource",
+			normalizedMIMEType(resource.MIMEType),
+			resource.Blob,
+			content.Annotations,
+		)
+	}
+
+	if strings.TrimSpace(resource.Text) != "" {
+		return "", sanitizeToolLLMContent(resource.Text)
+	}
+
+	return "", summarizeEmbeddedResource(content)
+}
+
+func (t *MCPTool) storeBinaryContent(
+	ctx context.Context,
+	kind string,
+	mimeType string,
+	data []byte,
+	annotations *mcp.Annotations,
+) (string, string) {
+	if len(data) == 0 {
+		return "", fmt.Sprintf("[MCP returned %s content (%s) but it was empty.]", kind, mimeType)
+	}
+	if !annotationsAllowUser(annotations) {
+		return "", fmt.Sprintf(
+			"[MCP returned %s content (%s) for non-user audience; omitted from model context.]",
+			kind,
+			mimeType,
+		)
+	}
+	if t.mediaStore == nil {
+		return "", fmt.Sprintf(
+			"[MCP returned %s content (%s); omitted from model context because media delivery is unavailable.]",
+			kind,
+			mimeType,
+		)
+	}
+
+	channel := ToolChannel(ctx)
+	chatID := ToolChatID(ctx)
+	if channel == "" || chatID == "" {
+		return "", fmt.Sprintf(
+			"[MCP returned %s content (%s); omitted from model context because no target chat was available.]",
+			kind,
+			mimeType,
+		)
+	}
+
+	dir := media.TempDir()
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return "", fmt.Sprintf("[MCP returned %s content (%s) but it could not be stored.]", kind, mimeType)
+	}
+
+	ext := extensionForMIMEType(mimeType)
+	tmpFile, err := os.CreateTemp(dir, "mcp-*"+ext)
+	if err != nil {
+		return "", fmt.Sprintf("[MCP returned %s content (%s) but it could not be stored.]", kind, mimeType)
+	}
+	tmpPath := tmpFile.Name()
+	if _, err = tmpFile.Write(data); err != nil {
+		_ = tmpFile.Close()
+		_ = os.Remove(tmpPath)
+		return "", fmt.Sprintf("[MCP returned %s content (%s) but it could not be stored.]", kind, mimeType)
+	}
+	if err = tmpFile.Close(); err != nil {
+		_ = os.Remove(tmpPath)
+		return "", fmt.Sprintf("[MCP returned %s content (%s) but it could not be stored.]", kind, mimeType)
+	}
+
+	scope := fmt.Sprintf(
+		"tool:mcp:%s:%s:%s:%d",
+		sanitizeIdentifierComponent(t.serverName),
+		channel,
+		chatID,
+		time.Now().UnixNano(),
+	)
+	filename := fmt.Sprintf(
+		"%s_%s%s",
+		sanitizeIdentifierComponent(t.serverName),
+		sanitizeIdentifierComponent(t.tool.Name),
+		ext,
+	)
+
+	ref, err := t.mediaStore.Store(tmpPath, media.MediaMeta{
+		Filename:    filename,
+		ContentType: mimeType,
+		Source: fmt.Sprintf(
+			"tool:mcp:%s:%s",
+			sanitizeIdentifierComponent(t.serverName),
+			sanitizeIdentifierComponent(t.tool.Name),
+		),
+	}, scope)
+	if err != nil {
+		_ = os.Remove(tmpPath)
+		return "", fmt.Sprintf(
+			"[MCP returned %s content (%s) but it could not be registered as media.]",
+			kind,
+			mimeType,
+		)
+	}
+
+	return ref, fmt.Sprintf(
+		"[MCP returned %s content (%s); omitted from model context and stored as a local media artifact.]",
+		kind,
+		mimeType,
+	)
+}
+
+func summarizeResourceLink(content *mcp.ResourceLink) string {
+	if content == nil {
+		return "[MCP returned an empty resource link.]"
+	}
+
+	parts := []string{"[MCP returned resource link"}
+	if content.Name != "" {
+		parts = append(parts, fmt.Sprintf("name=%q", content.Name))
+	}
+	if content.URI != "" {
+		parts = append(parts, fmt.Sprintf("uri=%q", content.URI))
+	}
+	if content.MIMEType != "" {
+		parts = append(parts, fmt.Sprintf("mime=%q", content.MIMEType))
+	}
+	if content.Description != "" {
+		desc := strings.TrimSpace(content.Description)
+		if len(desc) > 200 {
+			desc = desc[:200] + "..."
+		}
+		parts = append(parts, fmt.Sprintf("description=%q", desc))
+	}
+	return strings.Join(parts, ", ") + "]"
+}
+
+func summarizeEmbeddedResource(content *mcp.EmbeddedResource) string {
+	if content == nil || content.Resource == nil {
+		return "[MCP returned an embedded resource.]"
+	}
+
+	resource := content.Resource
+	if resource.URI != "" {
+		return fmt.Sprintf(
+			"[MCP returned embedded resource %q (%s).]",
+			resource.URI,
+			normalizedMIMEType(resource.MIMEType),
+		)
+	}
+	return fmt.Sprintf("[MCP returned embedded resource (%s).]", normalizedMIMEType(resource.MIMEType))
+}
+
+func annotationsAllowUser(annotations *mcp.Annotations) bool {
+	if annotations == nil || len(annotations.Audience) == 0 {
+		return true
+	}
+	for _, audience := range annotations.Audience {
+		if strings.EqualFold(string(audience), "user") {
+			return true
+		}
+	}
+	return false
+}
+
+func normalizedMIMEType(mimeType string) string {
+	if strings.TrimSpace(mimeType) == "" {
+		return "application/octet-stream"
+	}
+	return mimeType
+}
+
+func compactStrings(parts []string) []string {
+	compact := make([]string, 0, len(parts))
+	for _, part := range parts {
+		if strings.TrimSpace(part) == "" {
+			continue
+		}
+		compact = append(compact, part)
+	}
+	return compact
+}
diff --git a/pkg/tools/mcp_tool_test.go b/pkg/tools/mcp_tool_test.go
new file mode 100644
index 000000000..8bbac3bc7
--- /dev/null
+++ b/pkg/tools/mcp_tool_test.go
@@ -0,0 +1,636 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+// MockMCPManager is a mock implementation of MCPManager interface for testing
+type MockMCPManager struct {
+	callToolFunc func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error)
+}
+
+func (m *MockMCPManager) CallTool(
+	ctx context.Context,
+	serverName, toolName string,
+	arguments map[string]any,
+) (*mcp.CallToolResult, error) {
+	if m.callToolFunc != nil {
+		return m.callToolFunc(ctx, serverName, toolName, arguments)
+	}
+	return &mcp.CallToolResult{
+		Content: []mcp.Content{
+			&mcp.TextContent{Text: "mock result"},
+		},
+		IsError: false,
+	}, nil
+}
+
+// TestNewMCPTool verifies MCP tool creation
+func TestNewMCPTool(t *testing.T) {
+	manager := &MockMCPManager{}
+	tool := &mcp.Tool{
+		Name:        "test_tool",
+		Description: "A test tool",
+		InputSchema: map[string]any{
+			"type": "object",
+			"properties": map[string]any{
+				"input": map[string]any{
+					"type":        "string",
+					"description": "Test input",
+				},
+			},
+		},
+	}
+
+	mcpTool := NewMCPTool(manager, "test_server", tool)
+
+	if mcpTool == nil {
+		t.Fatal("NewMCPTool should not return nil")
+	}
+	// Verify tool properties we can access
+	if mcpTool.Name() != "mcp_test_server_test_tool" {
+		t.Errorf("Expected tool name with prefix, got '%s'", mcpTool.Name())
+	}
+}
+
+// TestMCPTool_Name verifies tool name with server prefix
+func TestMCPTool_Name(t *testing.T) {
+	tests := []struct {
+		name       string
+		serverName string
+		toolName   string
+		expected   string
+	}{
+		{
+			name:       "simple name",
+			serverName: "github",
+			toolName:   "create_issue",
+			expected:   "mcp_github_create_issue",
+		},
+		{
+			name:       "filesystem server",
+			serverName: "filesystem",
+			toolName:   "read_file",
+			expected:   "mcp_filesystem_read_file",
+		},
+		{
+			name:       "remote server",
+			serverName: "remote-api",
+			toolName:   "fetch_data",
+			expected:   "mcp_remote-api_fetch_data",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			manager := &MockMCPManager{}
+			tool := &mcp.Tool{Name: tt.toolName}
+			mcpTool := NewMCPTool(manager, tt.serverName, tool)
+
+			result := mcpTool.Name()
+			if result != tt.expected {
+				t.Errorf("Expected name '%s', got '%s'", tt.expected, result)
+			}
+		})
+	}
+}
+
+// TestMCPTool_Description verifies tool description generation
+func TestMCPTool_Description(t *testing.T) {
+	tests := []struct {
+		name            string
+		serverName      string
+		toolDescription string
+		expectContains  []string
+	}{
+		{
+			name:            "with description",
+			serverName:      "github",
+			toolDescription: "Create a GitHub issue",
+			expectContains:  []string{"[MCP:github]", "Create a GitHub issue"},
+		},
+		{
+			name:            "empty description",
+			serverName:      "filesystem",
+			toolDescription: "",
+			expectContains:  []string{"[MCP:filesystem]", "MCP tool from filesystem server"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			manager := &MockMCPManager{}
+			tool := &mcp.Tool{
+				Name:        "test_tool",
+				Description: tt.toolDescription,
+			}
+			mcpTool := NewMCPTool(manager, tt.serverName, tool)
+
+			result := mcpTool.Description()
+
+			for _, expected := range tt.expectContains {
+				if !strings.Contains(result, expected) {
+					t.Errorf("Description should contain '%s', got: %s", expected, result)
+				}
+			}
+		})
+	}
+}
+
+// TestMCPTool_Parameters verifies parameter schema conversion
+func TestMCPTool_Parameters(t *testing.T) {
+	tests := []struct {
+		name           string
+		inputSchema    any
+		expectType     string
+		checkProperty  string
+		expectProperty bool
+	}{
+		{
+			name: "map schema",
+			inputSchema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"query": map[string]any{
+						"type":        "string",
+						"description": "Search query",
+					},
+				},
+				"required": []string{"query"},
+			},
+			expectType:     "object",
+			checkProperty:  "query",
+			expectProperty: true,
+		},
+		{
+			name:           "nil schema",
+			inputSchema:    nil,
+			expectType:     "object",
+			expectProperty: false,
+		},
+		{
+			name: "json.RawMessage schema",
+			inputSchema: []byte(`{
+				"type": "object",
+				"properties": {
+					"repo": {
+						"type": "string",
+						"description": "Repository name"
+					},
+					"stars": {
+						"type": "integer",
+						"description": "Minimum stars"
+					}
+				},
+				"required": ["repo"]
+			}`),
+			expectType:     "object",
+			checkProperty:  "repo",
+			expectProperty: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			manager := &MockMCPManager{}
+			tool := &mcp.Tool{
+				Name:        "test_tool",
+				InputSchema: tt.inputSchema,
+			}
+			mcpTool := NewMCPTool(manager, "test_server", tool)
+
+			params := mcpTool.Parameters()
+
+			if params == nil {
+				t.Fatal("Parameters should not be nil")
+			}
+
+			if params["type"] != tt.expectType {
+				t.Errorf("Expected type '%s', got '%v'", tt.expectType, params["type"])
+			}
+
+			// Check if property exists when expected
+			if tt.checkProperty != "" {
+				properties, ok := params["properties"].(map[string]any)
+				if !ok && tt.expectProperty {
+					t.Errorf("Expected properties to be a map")
+					return
+				}
+				if ok {
+					_, hasProperty := properties[tt.checkProperty]
+					if hasProperty != tt.expectProperty {
+						t.Errorf("Expected property '%s' existence: %v, got: %v",
+							tt.checkProperty, tt.expectProperty, hasProperty)
+					}
+				}
+			}
+		})
+	}
+}
+
+// TestMCPTool_Execute_Success tests successful tool execution
+func TestMCPTool_Execute_Success(t *testing.T) {
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			// Verify correct parameters passed
+			if serverName != "github" {
+				t.Errorf("Expected serverName 'github', got '%s'", serverName)
+			}
+			if toolName != "search_repos" {
+				t.Errorf("Expected toolName 'search_repos', got '%s'", toolName)
+			}
+
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					&mcp.TextContent{Text: "Found 3 repositories"},
+				},
+				IsError: false,
+			}, nil
+		},
+	}
+
+	tool := &mcp.Tool{
+		Name:        "search_repos",
+		Description: "Search GitHub repositories",
+	}
+	mcpTool := NewMCPTool(manager, "github", tool)
+
+	ctx := context.Background()
+	args := map[string]any{
+		"query": "golang mcp",
+	}
+
+	result := mcpTool.Execute(ctx, args)
+
+	if result == nil {
+		t.Fatal("Result should not be nil")
+	}
+	if result.IsError {
+		t.Errorf("Expected no error, got error: %s", result.ForLLM)
+	}
+	if result.ForLLM != "Found 3 repositories" {
+		t.Errorf("Expected 'Found 3 repositories', got '%s'", result.ForLLM)
+	}
+}
+
+// TestMCPTool_Execute_ManagerError tests execution when manager returns error
+func TestMCPTool_Execute_ManagerError(t *testing.T) {
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			return nil, fmt.Errorf("connection failed")
+		},
+	}
+
+	tool := &mcp.Tool{Name: "test_tool"}
+	mcpTool := NewMCPTool(manager, "test_server", tool)
+
+	ctx := context.Background()
+	result := mcpTool.Execute(ctx, map[string]any{})
+
+	if result == nil {
+		t.Fatal("Result should not be nil")
+	}
+	if !result.IsError {
+		t.Error("Expected IsError to be true")
+	}
+	if !strings.Contains(result.ForLLM, "MCP tool execution failed") {
+		t.Errorf("Error message should mention execution failure, got: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "connection failed") {
+		t.Errorf("Error message should include original error, got: %s", result.ForLLM)
+	}
+}
+
+// TestMCPTool_Execute_ServerError tests execution when server returns error
+func TestMCPTool_Execute_ServerError(t *testing.T) {
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					&mcp.TextContent{Text: "Invalid API key"},
+				},
+				IsError: true,
+			}, nil
+		},
+	}
+
+	tool := &mcp.Tool{Name: "test_tool"}
+	mcpTool := NewMCPTool(manager, "test_server", tool)
+
+	ctx := context.Background()
+	result := mcpTool.Execute(ctx, map[string]any{})
+
+	if result == nil {
+		t.Fatal("Result should not be nil")
+	}
+	if !result.IsError {
+		t.Error("Expected IsError to be true")
+	}
+	if !strings.Contains(result.ForLLM, "MCP tool returned error") {
+		t.Errorf("Error message should mention server error, got: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "Invalid API key") {
+		t.Errorf("Error message should include server message, got: %s", result.ForLLM)
+	}
+}
+
+// TestMCPTool_Execute_MultipleContent tests execution with multiple content items
+func TestMCPTool_Execute_MultipleContent(t *testing.T) {
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					&mcp.TextContent{Text: "First line"},
+					&mcp.TextContent{Text: "Second line"},
+					&mcp.TextContent{Text: "Third line"},
+				},
+				IsError: false,
+			}, nil
+		},
+	}
+
+	tool := &mcp.Tool{Name: "multi_output"}
+	mcpTool := NewMCPTool(manager, "test_server", tool)
+
+	ctx := context.Background()
+	result := mcpTool.Execute(ctx, map[string]any{})
+
+	if result.IsError {
+		t.Errorf("Expected no error, got: %s", result.ForLLM)
+	}
+
+	expected := "First line\nSecond line\nThird line"
+	if result.ForLLM != expected {
+		t.Errorf("Expected '%s', got '%s'", expected, result.ForLLM)
+	}
+}
+
+// TestExtractContentText_TextContent tests text content extraction
+func TestExtractContentText_TextContent(t *testing.T) {
+	content := []mcp.Content{
+		&mcp.TextContent{Text: "Hello World"},
+		&mcp.TextContent{Text: "Second message"},
+	}
+
+	result := extractContentText(content)
+	expected := "Hello World\nSecond message"
+
+	if result != expected {
+		t.Errorf("Expected '%s', got '%s'", expected, result)
+	}
+}
+
+// TestExtractContentText_ImageContent tests image content extraction
+func TestExtractContentText_ImageContent(t *testing.T) {
+	content := []mcp.Content{
+		&mcp.ImageContent{
+			Data:     []byte("base64data"),
+			MIMEType: "image/png",
+		},
+	}
+
+	result := extractContentText(content)
+
+	if !strings.Contains(result, "[Image:") {
+		t.Errorf("Expected image indicator, got: %s", result)
+	}
+	if !strings.Contains(result, "image/png") {
+		t.Errorf("Expected MIME type in output, got: %s", result)
+	}
+}
+
+// TestExtractContentText_MixedContent tests mixed content types
+func TestExtractContentText_MixedContent(t *testing.T) {
+	content := []mcp.Content{
+		&mcp.TextContent{Text: "Description"},
+		&mcp.ImageContent{
+			Data:     []byte("data"),
+			MIMEType: "image/jpeg",
+		},
+		&mcp.TextContent{Text: "More text"},
+	}
+
+	result := extractContentText(content)
+
+	if !strings.Contains(result, "Description") {
+		t.Errorf("Should contain text content, got: %s", result)
+	}
+	if !strings.Contains(result, "[Image:") {
+		t.Errorf("Should contain image indicator, got: %s", result)
+	}
+	if !strings.Contains(result, "More text") {
+		t.Errorf("Should contain second text, got: %s", result)
+	}
+}
+
+// TestExtractContentText_EmptyContent tests empty content array
+func TestExtractContentText_EmptyContent(t *testing.T) {
+	content := []mcp.Content{}
+
+	result := extractContentText(content)
+
+	if result != "" {
+		t.Errorf("Expected empty string for empty content, got: %s", result)
+	}
+}
+
+// TestMCPTool_InterfaceCompliance verifies MCPTool implements Tool interface
+func TestMCPTool_InterfaceCompliance(t *testing.T) {
+	manager := &MockMCPManager{}
+	tool := &mcp.Tool{Name: "test"}
+	mcpTool := NewMCPTool(manager, "test_server", tool)
+
+	// Verify it implements Tool interface
+	var _ Tool = mcpTool
+}
+
+// TestMCPTool_Parameters_MapSchema tests schema that's already a map
+func TestMCPTool_Parameters_MapSchema(t *testing.T) {
+	manager := &MockMCPManager{}
+	schema := map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"name": map[string]any{
+				"type":        "string",
+				"description": "The name parameter",
+			},
+		},
+		"required": []string{"name"},
+	}
+
+	tool := &mcp.Tool{
+		Name:        "test_tool",
+		InputSchema: schema,
+	}
+	mcpTool := NewMCPTool(manager, "test_server", tool)
+
+	params := mcpTool.Parameters()
+
+	// Should return the schema as-is when it's already a map
+	if params["type"] != "object" {
+		t.Errorf("Expected type 'object', got '%v'", params["type"])
+	}
+
+	props, ok := params["properties"].(map[string]any)
+	if !ok {
+		t.Error("Properties should be a map")
+	}
+
+	nameParam, ok := props["name"].(map[string]any)
+	if !ok {
+		t.Error("Name parameter should exist")
+	}
+
+	if nameParam["type"] != "string" {
+		t.Errorf("Name type should be 'string', got '%v'", nameParam["type"])
+	}
+}
+
+func TestMCPTool_Execute_ImageContentStoredAsMedia(t *testing.T) {
+	store := media.NewFileMediaStore()
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					&mcp.ImageContent{
+						Data:     []byte("fake-image-bytes"),
+						MIMEType: "image/png",
+					},
+				},
+			}, nil
+		},
+	}
+
+	mcpTool := NewMCPTool(manager, "screenshoto", &mcp.Tool{Name: "take_screenshot"})
+	mcpTool.SetMediaStore(store)
+
+	result := mcpTool.Execute(WithToolContext(context.Background(), "telegram", "chat-42"), nil)
+
+	if result.IsError {
+		t.Fatalf("expected success, got %q", result.ForLLM)
+	}
+	if len(result.Media) != 1 {
+		t.Fatalf("expected 1 media ref, got %d", len(result.Media))
+	}
+	if result.ResponseHandled {
+		t.Fatal("expected MCP image artifact not to mark response as handled")
+	}
+	if !strings.Contains(result.ForLLM, "stored as a local media artifact") {
+		t.Fatalf("expected local media artifact note, got %q", result.ForLLM)
+	}
+
+	path, meta, err := store.ResolveWithMeta(result.Media[0])
+	if err != nil {
+		t.Fatalf("expected stored media ref to resolve: %v", err)
+	}
+	if meta.ContentType != "image/png" {
+		t.Fatalf("expected image/png content type, got %q", meta.ContentType)
+	}
+	if filepath.Ext(path) != ".png" {
+		t.Fatalf("expected png temp file, got %q", path)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("expected stored media file to be readable: %v", err)
+	}
+	if string(data) != "fake-image-bytes" {
+		t.Fatalf("expected stored media bytes to match input, got %q", string(data))
+	}
+}
+
+func TestMCPTool_Execute_EmbeddedResourceBlobStoredAsMedia(t *testing.T) {
+	store := media.NewFileMediaStore()
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					&mcp.EmbeddedResource{
+						Resource: &mcp.ResourceContents{
+							URI:      "file:///tmp/report.png",
+							MIMEType: "image/png",
+							Blob:     []byte("blob-bytes"),
+						},
+					},
+				},
+			}, nil
+		},
+	}
+
+	mcpTool := NewMCPTool(manager, "grafana", &mcp.Tool{Name: "get_dashboard_image"})
+	mcpTool.SetMediaStore(store)
+
+	result := mcpTool.Execute(WithToolContext(context.Background(), "telegram", "chat-42"), nil)
+
+	if len(result.Media) != 1 {
+		t.Fatalf("expected embedded resource blob to be stored as media, got %d refs", len(result.Media))
+	}
+	path, _, err := store.ResolveWithMeta(result.Media[0])
+	if err != nil {
+		t.Fatalf("expected stored media ref to resolve: %v", err)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("expected stored media file to be readable: %v", err)
+	}
+	if string(data) != "blob-bytes" {
+		t.Fatalf("expected stored blob bytes to match input, got %q", string(data))
+	}
+}
+
+func TestMCPTool_Execute_RespectsUserAudienceForBinaryContent(t *testing.T) {
+	store := media.NewFileMediaStore()
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					&mcp.ImageContent{
+						Data:        []byte("assistant-only"),
+						MIMEType:    "image/png",
+						Annotations: &mcp.Annotations{Audience: []mcp.Role{"assistant"}},
+					},
+				},
+			}, nil
+		},
+	}
+
+	mcpTool := NewMCPTool(manager, "screenshoto", &mcp.Tool{Name: "take_screenshot"})
+	mcpTool.SetMediaStore(store)
+
+	result := mcpTool.Execute(WithToolContext(context.Background(), "telegram", "chat-42"), nil)
+
+	if len(result.Media) != 0 {
+		t.Fatalf("expected no media ref for non-user audience, got %d", len(result.Media))
+	}
+	if !strings.Contains(result.ForLLM, "non-user audience") {
+		t.Fatalf("expected audience note, got %q", result.ForLLM)
+	}
+}
+
+func TestMCPTool_Execute_LargeBase64TextIsOmittedFromContext(t *testing.T) {
+	manager := &MockMCPManager{
+		callToolFunc: func(ctx context.Context, serverName, toolName string, arguments map[string]any) (*mcp.CallToolResult, error) {
+			return &mcp.CallToolResult{
+				Content: []mcp.Content{
+					&mcp.TextContent{Text: strings.Repeat("QUJD", 400)},
+				},
+			}, nil
+		},
+	}
+
+	mcpTool := NewMCPTool(manager, "test_server", &mcp.Tool{Name: "dump_payload"})
+
+	result := mcpTool.Execute(context.Background(), nil)
+
+	if result.ForLLM != largeBase64OmittedMessage {
+		t.Fatalf("expected sanitized large base64 note, got %q", result.ForLLM)
+	}
+}
diff --git a/pkg/tools/message.go b/pkg/tools/message.go
index 15ef4ff73..438ceeddd 100644
--- a/pkg/tools/message.go
+++ b/pkg/tools/message.go
@@ -3,15 +3,14 @@ package tools
 import (
 	"context"
 	"fmt"
+	"sync/atomic"
 )
 
 type SendCallback func(channel, chatID, content string) error
 
 type MessageTool struct {
-	sendCallback   SendCallback
-	defaultChannel string
-	defaultChatID  string
-	sentInRound    bool // Tracks whether a message was sent in the current processing round
+	sendCallback SendCallback
+	sentInRound  atomic.Bool // Tracks whether a message was sent in the current processing round
 }
 
 func NewMessageTool() *MessageTool {
@@ -47,15 +46,15 @@ func (t *MessageTool) Parameters() map[string]any {
 	}
 }
 
-func (t *MessageTool) SetContext(channel, chatID string) {
-	t.defaultChannel = channel
-	t.defaultChatID = chatID
-	t.sentInRound = false // Reset send tracking for new processing round
+// ResetSentInRound resets the per-round send tracker.
+// Called by the agent loop at the start of each inbound message processing round.
+func (t *MessageTool) ResetSentInRound() {
+	t.sentInRound.Store(false)
 }
 
 // HasSentInRound returns true if the message tool sent a message during the current round.
 func (t *MessageTool) HasSentInRound() bool {
-	return t.sentInRound
+	return t.sentInRound.Load()
 }
 
 func (t *MessageTool) SetSendCallback(callback SendCallback) {
@@ -72,10 +71,10 @@ func (t *MessageTool) Execute(ctx context.Context, args map[string]any) *ToolRes
 	chatID, _ := args["chat_id"].(string)
 
 	if channel == "" {
-		channel = t.defaultChannel
+		channel = ToolChannel(ctx)
 	}
 	if chatID == "" {
-		chatID = t.defaultChatID
+		chatID = ToolChatID(ctx)
 	}
 
 	if channel == "" || chatID == "" {
@@ -94,7 +93,7 @@ func (t *MessageTool) Execute(ctx context.Context, args map[string]any) *ToolRes
 		}
 	}
 
-	t.sentInRound = true
+	t.sentInRound.Store(true)
 	// Silent: user already received the message directly
 	return &ToolResult{
 		ForLLM: fmt.Sprintf("Message sent to %s:%s", channel, chatID),
diff --git a/pkg/tools/message_test.go b/pkg/tools/message_test.go
index 717c1117b..05630972e 100644
--- a/pkg/tools/message_test.go
+++ b/pkg/tools/message_test.go
@@ -8,7 +8,6 @@ import (
 
 func TestMessageTool_Execute_Success(t *testing.T) {
 	tool := NewMessageTool()
-	tool.SetContext("test-channel", "test-chat-id")
 
 	var sentChannel, sentChatID, sentContent string
 	tool.SetSendCallback(func(channel, chatID, content string) error {
@@ -18,7 +17,7 @@ func TestMessageTool_Execute_Success(t *testing.T) {
 		return nil
 	})
 
-	ctx := context.Background()
+	ctx := WithToolContext(context.Background(), "test-channel", "test-chat-id")
 	args := map[string]any{
 		"content": "Hello, world!",
 	}
@@ -60,7 +59,6 @@ func TestMessageTool_Execute_Success(t *testing.T) {
 
 func TestMessageTool_Execute_WithCustomChannel(t *testing.T) {
 	tool := NewMessageTool()
-	tool.SetContext("default-channel", "default-chat-id")
 
 	var sentChannel, sentChatID string
 	tool.SetSendCallback(func(channel, chatID, content string) error {
@@ -69,7 +67,7 @@ func TestMessageTool_Execute_WithCustomChannel(t *testing.T) {
 		return nil
 	})
 
-	ctx := context.Background()
+	ctx := WithToolContext(context.Background(), "default-channel", "default-chat-id")
 	args := map[string]any{
 		"content": "Test message",
 		"channel": "custom-channel",
@@ -96,14 +94,13 @@ func TestMessageTool_Execute_WithCustomChannel(t *testing.T) {
 
 func TestMessageTool_Execute_SendFailure(t *testing.T) {
 	tool := NewMessageTool()
-	tool.SetContext("test-channel", "test-chat-id")
 
 	sendErr := errors.New("network error")
 	tool.SetSendCallback(func(channel, chatID, content string) error {
 		return sendErr
 	})
 
-	ctx := context.Background()
+	ctx := WithToolContext(context.Background(), "test-channel", "test-chat-id")
 	args := map[string]any{
 		"content": "Test message",
 	}
@@ -133,9 +130,8 @@ func TestMessageTool_Execute_SendFailure(t *testing.T) {
 
 func TestMessageTool_Execute_MissingContent(t *testing.T) {
 	tool := NewMessageTool()
-	tool.SetContext("test-channel", "test-chat-id")
 
-	ctx := context.Background()
+	ctx := WithToolContext(context.Background(), "test-channel", "test-chat-id")
 	args := map[string]any{} // content missing
 
 	result := tool.Execute(ctx, args)
@@ -151,7 +147,7 @@ func TestMessageTool_Execute_MissingContent(t *testing.T) {
 
 func TestMessageTool_Execute_NoTargetChannel(t *testing.T) {
 	tool := NewMessageTool()
-	// No SetContext called, so defaultChannel and defaultChatID are empty
+	// No WithToolContext — channel/chatID are empty
 
 	tool.SetSendCallback(func(channel, chatID, content string) error {
 		return nil
@@ -175,10 +171,9 @@ func TestMessageTool_Execute_NoTargetChannel(t *testing.T) {
 
 func TestMessageTool_Execute_NotConfigured(t *testing.T) {
 	tool := NewMessageTool()
-	tool.SetContext("test-channel", "test-chat-id")
 	// No SetSendCallback called
 
-	ctx := context.Background()
+	ctx := WithToolContext(context.Background(), "test-channel", "test-chat-id")
 	args := map[string]any{
 		"content": "Test message",
 	}
diff --git a/pkg/tools/normalization.go b/pkg/tools/normalization.go
new file mode 100644
index 000000000..3a76c5d92
--- /dev/null
+++ b/pkg/tools/normalization.go
@@ -0,0 +1,292 @@
+package tools
+
+import (
+	"encoding/base64"
+	"fmt"
+	"mime"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"time"
+	"unicode"
+
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+const (
+	largeBase64OmittedMessage = "[Tool returned a large base64-like payload; omitted from model context.]"
+	inlineMediaOmittedMessage = "[Tool returned inline media content; omitted from model context.]"
+	inlineMediaStoredMessage  = "[Tool returned inline media content (%s); omitted from model context and registered as a media attachment.]"
+)
+
+var (
+	inlineMarkdownDataURLRe = regexp.MustCompile(`!\[[^\]]*\]\((data:[^)]+)\)`)
+	inlineRawDataURLRe      = regexp.MustCompile(`data:[^;\s]+;base64,[A-Za-z0-9+/=\r\n]+`)
+)
+
+func normalizeToolResult(
+	result *ToolResult,
+	toolName string,
+	store media.MediaStore,
+	channel string,
+	chatID string,
+) *ToolResult {
+	if result == nil {
+		return nil
+	}
+
+	notes := make([]string, 0, 2)
+	seen := make(map[string]struct{})
+
+	if store != nil && channel != "" && chatID != "" {
+		var refs []string
+		var extractedNotes []string
+
+		result.ForLLM, refs, extractedNotes = extractInlineMediaRefs(
+			result.ForLLM,
+			toolName,
+			store,
+			channel,
+			chatID,
+			seen,
+		)
+		result.Media = append(result.Media, refs...)
+		notes = append(notes, extractedNotes...)
+
+		result.ForUser, refs, extractedNotes = extractInlineMediaRefs(
+			result.ForUser,
+			toolName,
+			store,
+			channel,
+			chatID,
+			seen,
+		)
+		result.Media = append(result.Media, refs...)
+		notes = append(notes, extractedNotes...)
+	}
+
+	result.ForLLM = sanitizeToolLLMContent(result.ForLLM)
+
+	if len(result.Media) > 0 && len(notes) > 0 {
+		if strings.TrimSpace(result.ForLLM) == "" {
+			result.ForLLM = strings.Join(notes, "\n")
+		} else {
+			result.ForLLM = strings.TrimSpace(result.ForLLM) + "\n" + strings.Join(notes, "\n")
+		}
+	}
+	if len(result.Media) > 0 && strings.TrimSpace(result.ForLLM) == "" {
+		result.ForLLM = "[Tool returned media content; omitted from model context and registered as a media attachment.]"
+	}
+
+	return result
+}
+
+func sanitizeToolLLMContent(text string) string {
+	trimmed := strings.TrimSpace(text)
+	if trimmed == "" {
+		return text
+	}
+	if inlineMarkdownDataURLRe.MatchString(trimmed) || inlineRawDataURLRe.MatchString(trimmed) {
+		cleaned := inlineMarkdownDataURLRe.ReplaceAllString(trimmed, "")
+		cleaned = inlineRawDataURLRe.ReplaceAllString(cleaned, "")
+		cleaned = strings.TrimSpace(cleaned)
+		if cleaned == "" {
+			return inlineMediaOmittedMessage
+		}
+		return cleaned + "\n" + inlineMediaOmittedMessage
+	}
+	if looksLikeLargeBase64Payload(trimmed) {
+		return largeBase64OmittedMessage
+	}
+	return text
+}
+
+func looksLikeLargeBase64Payload(text string) bool {
+	trimmed := strings.TrimSpace(text)
+	if len(trimmed) < 1024 {
+		return false
+	}
+
+	nonSpace := 0
+	base64Like := 0
+	spaceCount := 0
+
+	for _, r := range trimmed {
+		if unicode.IsSpace(r) {
+			spaceCount++
+			continue
+		}
+		nonSpace++
+		if (r >= 'A' && r <= 'Z') ||
+			(r >= 'a' && r <= 'z') ||
+			(r >= '0' && r <= '9') ||
+			r == '+' || r == '/' || r == '=' {
+			base64Like++
+		}
+	}
+
+	if nonSpace == 0 {
+		return false
+	}
+
+	ratio := float64(base64Like) / float64(nonSpace)
+	return ratio >= 0.97 && spaceCount <= len(trimmed)/128
+}
+
+func extractInlineMediaRefs(
+	text string,
+	toolName string,
+	store media.MediaStore,
+	channel string,
+	chatID string,
+	seen map[string]struct{},
+) (cleaned string, refs []string, notes []string) {
+	cleaned = text
+
+	matches := inlineMarkdownDataURLRe.FindAllStringSubmatch(cleaned, -1)
+	for _, match := range matches {
+		if len(match) < 2 {
+			continue
+		}
+		dataURL := match[1]
+		ref, note := storeInlineDataURL(toolName, store, channel, chatID, dataURL, seen)
+		if ref != "" {
+			refs = append(refs, ref)
+		}
+		if note != "" {
+			notes = append(notes, note)
+		}
+		cleaned = strings.ReplaceAll(cleaned, match[0], "")
+	}
+
+	rawMatches := inlineRawDataURLRe.FindAllString(cleaned, -1)
+	for _, dataURL := range rawMatches {
+		ref, note := storeInlineDataURL(toolName, store, channel, chatID, dataURL, seen)
+		if ref != "" {
+			refs = append(refs, ref)
+		}
+		if note != "" {
+			notes = append(notes, note)
+		}
+		cleaned = strings.ReplaceAll(cleaned, dataURL, "")
+	}
+
+	return strings.TrimSpace(cleaned), refs, notes
+}
+
+func storeInlineDataURL(
+	toolName string,
+	store media.MediaStore,
+	channel string,
+	chatID string,
+	dataURL string,
+	seen map[string]struct{},
+) (ref string, note string) {
+	dataURL = strings.TrimSpace(dataURL)
+	if _, ok := seen[dataURL]; ok {
+		return "", ""
+	}
+	seen[dataURL] = struct{}{}
+
+	if !strings.HasPrefix(strings.ToLower(dataURL), "data:") {
+		return "", ""
+	}
+
+	comma := strings.IndexByte(dataURL, ',')
+	if comma <= 5 {
+		return "", "[Tool returned inline media content that could not be parsed.]"
+	}
+
+	metaPart := dataURL[:comma]
+	payload := dataURL[comma+1:]
+	if !strings.Contains(strings.ToLower(metaPart), ";base64") {
+		return "", "[Tool returned inline media content that was not base64-encoded.]"
+	}
+
+	mimeType := strings.TrimSpace(strings.TrimPrefix(metaPart, "data:"))
+	if semi := strings.IndexByte(mimeType, ';'); semi >= 0 {
+		mimeType = mimeType[:semi]
+	}
+	if mimeType == "" {
+		mimeType = "application/octet-stream"
+	}
+
+	payload = strings.NewReplacer("\n", "", "\r", "", "\t", "", " ", "").Replace(payload)
+	decoded, err := base64.StdEncoding.DecodeString(payload)
+	if err != nil {
+		return "", fmt.Sprintf("[Tool returned inline media content (%s) that could not be decoded.]", mimeType)
+	}
+
+	dir := media.TempDir()
+	if err = os.MkdirAll(dir, 0o700); err != nil {
+		return "", fmt.Sprintf("[Tool returned inline media content (%s) but it could not be stored.]", mimeType)
+	}
+
+	ext := extensionForMIMEType(mimeType)
+	tmpFile, err := os.CreateTemp(dir, "tool-inline-*"+ext)
+	if err != nil {
+		return "", fmt.Sprintf("[Tool returned inline media content (%s) but it could not be stored.]", mimeType)
+	}
+	tmpPath := tmpFile.Name()
+	if _, err = tmpFile.Write(decoded); err != nil {
+		tmpFile.Close()
+		_ = os.Remove(tmpPath)
+		return "", fmt.Sprintf("[Tool returned inline media content (%s) but it could not be stored.]", mimeType)
+	}
+	if err = tmpFile.Close(); err != nil {
+		_ = os.Remove(tmpPath)
+		return "", fmt.Sprintf("[Tool returned inline media content (%s) but it could not be stored.]", mimeType)
+	}
+
+	filename := sanitizeIdentifierComponent(toolName) + ext
+	scope := fmt.Sprintf(
+		"tool:inline:%s:%s:%s:%d",
+		sanitizeIdentifierComponent(toolName),
+		channel,
+		chatID,
+		time.Now().UnixNano(),
+	)
+
+	ref, err = store.Store(tmpPath, media.MediaMeta{
+		Filename:    filename,
+		ContentType: mimeType,
+		Source:      fmt.Sprintf("tool:inline:%s", sanitizeIdentifierComponent(toolName)),
+	}, scope)
+	if err != nil {
+		_ = os.Remove(tmpPath)
+		return "", fmt.Sprintf("[Tool returned inline media content (%s) but it could not be registered.]", mimeType)
+	}
+
+	return ref, fmt.Sprintf(inlineMediaStoredMessage, mimeType)
+}
+
+func extensionForMIMEType(mimeType string) string {
+	if mimeType == "" {
+		return ".bin"
+	}
+	if exts, err := mime.ExtensionsByType(mimeType); err == nil && len(exts) > 0 {
+		return exts[0]
+	}
+
+	switch strings.ToLower(mimeType) {
+	case "image/jpeg":
+		return ".jpg"
+	case "image/png":
+		return ".png"
+	case "image/gif":
+		return ".gif"
+	case "image/webp":
+		return ".webp"
+	case "audio/wav", "audio/x-wav":
+		return ".wav"
+	case "audio/mpeg":
+		return ".mp3"
+	case "audio/ogg":
+		return ".ogg"
+	case "video/mp4":
+		return ".mp4"
+	default:
+		return filepath.Ext(mimeType)
+	}
+}
diff --git a/pkg/tools/registry.go b/pkg/tools/registry.go
index d37a093a8..56af8d695 100644
--- a/pkg/tools/registry.go
+++ b/pkg/tools/registry.go
@@ -5,34 +5,175 @@ import (
 	"fmt"
 	"sort"
 	"sync"
+	"sync/atomic"
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
+type ToolEntry struct {
+	Tool   Tool
+	IsCore bool
+	TTL    int
+}
+
 type ToolRegistry struct {
-	tools map[string]Tool
-	mu    sync.RWMutex
+	tools      map[string]*ToolEntry
+	mu         sync.RWMutex
+	version    atomic.Uint64 // incremented on Register/RegisterHidden for cache invalidation
+	mediaStore media.MediaStore
+}
+
+type mediaStoreAware interface {
+	SetMediaStore(store media.MediaStore)
 }
 
 func NewToolRegistry() *ToolRegistry {
 	return &ToolRegistry{
-		tools: make(map[string]Tool),
+		tools: make(map[string]*ToolEntry),
 	}
 }
 
 func (r *ToolRegistry) Register(tool Tool) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
-	r.tools[tool.Name()] = tool
+	name := tool.Name()
+	if _, exists := r.tools[name]; exists {
+		logger.WarnCF("tools", "Tool registration overwrites existing tool",
+			map[string]any{"name": name})
+	}
+	r.tools[name] = &ToolEntry{
+		Tool:   tool,
+		IsCore: true,
+		TTL:    0, // Core tools do not use TTL
+	}
+	if aware, ok := tool.(mediaStoreAware); ok && r.mediaStore != nil {
+		aware.SetMediaStore(r.mediaStore)
+	}
+	r.version.Add(1)
+	logger.DebugCF("tools", "Registered core tool", map[string]any{"name": name})
+}
+
+// RegisterHidden saves hidden tools (visible only via TTL)
+func (r *ToolRegistry) RegisterHidden(tool Tool) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	name := tool.Name()
+	if _, exists := r.tools[name]; exists {
+		logger.WarnCF("tools", "Hidden tool registration overwrites existing tool",
+			map[string]any{"name": name})
+	}
+	r.tools[name] = &ToolEntry{
+		Tool:   tool,
+		IsCore: false,
+		TTL:    0,
+	}
+	if aware, ok := tool.(mediaStoreAware); ok && r.mediaStore != nil {
+		aware.SetMediaStore(r.mediaStore)
+	}
+	r.version.Add(1)
+	logger.DebugCF("tools", "Registered hidden tool", map[string]any{"name": name})
+}
+
+// SetMediaStore injects a MediaStore into all registered tools that can
+// consume it, and remembers it for future registrations.
+func (r *ToolRegistry) SetMediaStore(store media.MediaStore) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+
+	r.mediaStore = store
+	for _, entry := range r.tools {
+		if aware, ok := entry.Tool.(mediaStoreAware); ok {
+			aware.SetMediaStore(store)
+		}
+	}
+}
+
+// PromoteTools atomically sets the TTL for multiple non-core tools.
+// This prevents a concurrent TickTTL from decrementing between promotions.
+func (r *ToolRegistry) PromoteTools(names []string, ttl int) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	promoted := 0
+	for _, name := range names {
+		if entry, exists := r.tools[name]; exists {
+			if !entry.IsCore {
+				entry.TTL = ttl
+				promoted++
+			}
+		}
+	}
+	logger.DebugCF(
+		"tools",
+		"PromoteTools completed",
+		map[string]any{"requested": len(names), "promoted": promoted, "ttl": ttl},
+	)
+}
+
+// TickTTL decreases TTL only for non-core tools
+func (r *ToolRegistry) TickTTL() {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	for _, entry := range r.tools {
+		if !entry.IsCore && entry.TTL > 0 {
+			entry.TTL--
+		}
+	}
+}
+
+// Version returns the current registry version (atomically).
+func (r *ToolRegistry) Version() uint64 {
+	return r.version.Load()
+}
+
+// HiddenToolSnapshot holds a consistent snapshot of hidden tools and the
+// registry version at which it was taken. Used by BM25SearchTool cache.
+type HiddenToolSnapshot struct {
+	Docs    []HiddenToolDoc
+	Version uint64
+}
+
+// HiddenToolDoc is a lightweight representation of a hidden tool for search indexing.
+type HiddenToolDoc struct {
+	Name        string
+	Description string
+}
+
+// SnapshotHiddenTools returns all non-core tools and the current registry
+// version under a single read-lock, guaranteeing consistency between the
+// two values.
+func (r *ToolRegistry) SnapshotHiddenTools() HiddenToolSnapshot {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	docs := make([]HiddenToolDoc, 0, len(r.tools))
+	for name, entry := range r.tools {
+		if !entry.IsCore {
+			docs = append(docs, HiddenToolDoc{
+				Name:        name,
+				Description: entry.Tool.Description(),
+			})
+		}
+	}
+	return HiddenToolSnapshot{
+		Docs:    docs,
+		Version: r.version.Load(),
+	}
 }
 
 func (r *ToolRegistry) Get(name string) (Tool, bool) {
 	r.mu.RLock()
 	defer r.mu.RUnlock()
-	tool, ok := r.tools[name]
-	return tool, ok
+	entry, ok := r.tools[name]
+	if !ok {
+		return nil, false
+	}
+	// Hidden tools with expired TTL are not callable.
+	if !entry.IsCore && entry.TTL <= 0 {
+		return nil, false
+	}
+	return entry.Tool, true
 }
 
 func (r *ToolRegistry) Execute(ctx context.Context, name string, args map[string]any) *ToolResult {
@@ -40,8 +181,9 @@ func (r *ToolRegistry) Execute(ctx context.Context, name string, args map[string
 }
 
 // ExecuteWithContext executes a tool with channel/chatID context and optional async callback.
-// If the tool implements AsyncTool and a non-nil callback is provided,
-// the callback will be set on the tool before execution.
+// If the tool implements AsyncExecutor and a non-nil callback is provided,
+// ExecuteAsync is called instead of Execute — the callback is a parameter,
+// never stored as mutable state on the tool.
 func (r *ToolRegistry) ExecuteWithContext(
 	ctx context.Context,
 	name string,
@@ -64,22 +206,66 @@ func (r *ToolRegistry) ExecuteWithContext(
 		return ErrorResult(fmt.Sprintf("tool %q not found", name)).WithError(fmt.Errorf("tool not found"))
 	}
 
-	// If tool implements ContextualTool, set context
-	if contextualTool, ok := tool.(ContextualTool); ok && channel != "" && chatID != "" {
-		contextualTool.SetContext(channel, chatID)
+	// Validate arguments against the tool's declared schema.
+	if err := validateToolArgs(tool.Parameters(), args); err != nil {
+		logger.WarnCF("tool", "Tool argument validation failed",
+			map[string]any{"tool": name, "error": err.Error()})
+		return ErrorResult(fmt.Sprintf("invalid arguments for tool %q: %s", name, err)).
+			WithError(fmt.Errorf("argument validation failed: %w", err))
 	}
 
-	// If tool implements AsyncTool and callback is provided, set callback
-	if asyncTool, ok := tool.(AsyncTool); ok && asyncCallback != nil {
-		asyncTool.SetCallback(asyncCallback)
-		logger.DebugCF("tool", "Async callback injected",
-			map[string]any{
-				"tool": name,
-			})
-	}
+	// Inject channel/chatID into ctx so tools read them via ToolChannel(ctx)/ToolChatID(ctx).
+	// Always inject — tools validate what they require.
+	ctx = WithToolContext(ctx, channel, chatID)
 
+	// If tool implements AsyncExecutor and callback is provided, use ExecuteAsync.
+	// The callback is a call parameter, not mutable state on the tool instance.
+	var result *ToolResult
 	start := time.Now()
-	result := tool.Execute(ctx, args)
+
+	// Use recover to catch any panics during tool execution
+	// This prevents tool crashes from killing the entire agent
+	func() {
+		defer func() {
+			if re := recover(); re != nil {
+				errMsg := fmt.Sprintf("Tool '%s' crashed with panic: %v", name, re)
+				logger.ErrorCF("tool", "Tool execution panic recovered",
+					map[string]any{
+						"tool":  name,
+						"panic": fmt.Sprintf("%v", re),
+					})
+				result = &ToolResult{
+					ForLLM:  errMsg,
+					ForUser: errMsg,
+					IsError: true,
+					Err:     fmt.Errorf("panic: %v", re),
+				}
+			}
+		}()
+
+		if asyncExec, ok := tool.(AsyncExecutor); ok && asyncCallback != nil {
+			logger.DebugCF("tool", "Executing async tool via ExecuteAsync",
+				map[string]any{
+					"tool": name,
+				})
+			result = asyncExec.ExecuteAsync(ctx, args, asyncCallback)
+		} else {
+			result = tool.Execute(ctx, args)
+		}
+	}()
+
+	// Handle nil result (should not happen, but defensive)
+	if result == nil {
+		result = &ToolResult{
+			ForLLM:  fmt.Sprintf("Tool '%s' returned nil result unexpectedly", name),
+			ForUser: fmt.Sprintf("Tool '%s' returned nil result unexpectedly", name),
+			IsError: true,
+			Err:     fmt.Errorf("nil result from tool"),
+		}
+	}
+
+	result = normalizeToolResult(result, name, r.mediaStore, channel, chatID)
+
 	duration := time.Since(start)
 
 	// Log based on result type
@@ -101,7 +287,7 @@ func (r *ToolRegistry) ExecuteWithContext(
 			map[string]any{
 				"tool":          name,
 				"duration_ms":   duration.Milliseconds(),
-				"result_length": len(result.ForLLM),
+				"result_length": len(result.ContentForLLM()),
 			})
 	}
 
@@ -128,7 +314,13 @@ func (r *ToolRegistry) GetDefinitions() []map[string]any {
 	sorted := r.sortedToolNames()
 	definitions := make([]map[string]any, 0, len(sorted))
 	for _, name := range sorted {
-		definitions = append(definitions, ToolToSchema(r.tools[name]))
+		entry := r.tools[name]
+
+		if !entry.IsCore && entry.TTL <= 0 {
+			continue
+		}
+
+		definitions = append(definitions, ToolToSchema(r.tools[name].Tool))
 	}
 	return definitions
 }
@@ -142,8 +334,13 @@ func (r *ToolRegistry) ToProviderDefs() []providers.ToolDefinition {
 	sorted := r.sortedToolNames()
 	definitions := make([]providers.ToolDefinition, 0, len(sorted))
 	for _, name := range sorted {
-		tool := r.tools[name]
-		schema := ToolToSchema(tool)
+		entry := r.tools[name]
+
+		if !entry.IsCore && entry.TTL <= 0 {
+			continue
+		}
+
+		schema := ToolToSchema(entry.Tool)
 
 		// Safely extract nested values with type checks
 		fn, ok := schema["function"].(map[string]any)
@@ -175,6 +372,29 @@ func (r *ToolRegistry) List() []string {
 	return r.sortedToolNames()
 }
 
+// Clone creates an independent copy of the registry containing the same tool
+// entries (shallow copy of each ToolEntry). This is used to give subagents a
+// snapshot of the parent agent's tools without sharing the same registry —
+// tools registered on the parent after cloning (e.g. spawn, spawn_status)
+// will NOT be visible to the clone, preventing recursive subagent spawning.
+// The version counter is reset to 0 in the clone as it's a new independent registry.
+func (r *ToolRegistry) Clone() *ToolRegistry {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	clone := &ToolRegistry{
+		tools:      make(map[string]*ToolEntry, len(r.tools)),
+		mediaStore: r.mediaStore,
+	}
+	for name, entry := range r.tools {
+		clone.tools[name] = &ToolEntry{
+			Tool:   entry.Tool,
+			IsCore: entry.IsCore,
+			TTL:    entry.TTL,
+		}
+	}
+	return clone
+}
+
 // Count returns the number of registered tools.
 func (r *ToolRegistry) Count() int {
 	r.mu.RLock()
@@ -191,8 +411,32 @@ func (r *ToolRegistry) GetSummaries() []string {
 	sorted := r.sortedToolNames()
 	summaries := make([]string, 0, len(sorted))
 	for _, name := range sorted {
-		tool := r.tools[name]
-		summaries = append(summaries, fmt.Sprintf("- `%s` - %s", tool.Name(), tool.Description()))
+		entry := r.tools[name]
+
+		if !entry.IsCore && entry.TTL <= 0 {
+			continue
+		}
+
+		summaries = append(summaries, fmt.Sprintf("- `%s` - %s", entry.Tool.Name(), entry.Tool.Description()))
 	}
 	return summaries
 }
+
+// GetAll returns all registered tools (both core and non-core with TTL > 0).
+// Used by SubTurn to inherit parent's tool set.
+func (r *ToolRegistry) GetAll() []Tool {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
+	sorted := r.sortedToolNames()
+	tools := make([]Tool, 0, len(sorted))
+	for _, name := range sorted {
+		entry := r.tools[name]
+
+		// Include core tools and non-core tools with active TTL
+		if entry.IsCore || entry.TTL > 0 {
+			tools = append(tools, entry.Tool)
+		}
+	}
+	return tools
+}
diff --git a/pkg/tools/registry_test.go b/pkg/tools/registry_test.go
index 8fe88ca78..db52749f6 100644
--- a/pkg/tools/registry_test.go
+++ b/pkg/tools/registry_test.go
@@ -2,10 +2,14 @@ package tools
 
 import (
 	"context"
+	"errors"
+	"os"
+	"path/filepath"
 	"strings"
 	"sync"
 	"testing"
 
+	"github.com/sipeed/picoclaw/pkg/media"
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
@@ -25,24 +29,33 @@ func (m *mockRegistryTool) Execute(_ context.Context, _ map[string]any) *ToolRes
 	return m.result
 }
 
-type mockCtxTool struct {
+type mockContextAwareTool struct {
 	mockRegistryTool
-	channel string
-	chatID  string
+	lastCtx context.Context
 }
 
-func (m *mockCtxTool) SetContext(channel, chatID string) {
-	m.channel = channel
-	m.chatID = chatID
+func (m *mockContextAwareTool) Execute(ctx context.Context, _ map[string]any) *ToolResult {
+	m.lastCtx = ctx
+	return m.result
 }
 
 type mockAsyncRegistryTool struct {
 	mockRegistryTool
-	cb AsyncCallback
+	lastCB AsyncCallback
 }
 
-func (m *mockAsyncRegistryTool) SetCallback(cb AsyncCallback) {
-	m.cb = cb
+func (m *mockAsyncRegistryTool) ExecuteAsync(_ context.Context, args map[string]any, cb AsyncCallback) *ToolResult {
+	m.lastCB = cb
+	return m.result
+}
+
+type mockMediaStoreAwareTool struct {
+	mockRegistryTool
+	store media.MediaStore
+}
+
+func (m *mockMediaStoreAwareTool) SetMediaStore(store media.MediaStore) {
+	m.store = store
 }
 
 // --- helpers ---
@@ -136,34 +149,44 @@ func TestToolRegistry_Execute_NotFound(t *testing.T) {
 	}
 }
 
-func TestToolRegistry_ExecuteWithContext_ContextualTool(t *testing.T) {
+func TestToolRegistry_ExecuteWithContext_InjectsToolContext(t *testing.T) {
 	r := NewToolRegistry()
-	ct := &mockCtxTool{
+	ct := &mockContextAwareTool{
 		mockRegistryTool: *newMockTool("ctx_tool", "needs context"),
 	}
 	r.Register(ct)
 
 	r.ExecuteWithContext(context.Background(), "ctx_tool", nil, "telegram", "chat-42", nil)
 
-	if ct.channel != "telegram" {
-		t.Errorf("expected channel 'telegram', got %q", ct.channel)
+	if ct.lastCtx == nil {
+		t.Fatal("expected Execute to be called")
 	}
-	if ct.chatID != "chat-42" {
-		t.Errorf("expected chatID 'chat-42', got %q", ct.chatID)
+	if got := ToolChannel(ct.lastCtx); got != "telegram" {
+		t.Errorf("expected channel 'telegram', got %q", got)
+	}
+	if got := ToolChatID(ct.lastCtx); got != "chat-42" {
+		t.Errorf("expected chatID 'chat-42', got %q", got)
 	}
 }
 
-func TestToolRegistry_ExecuteWithContext_SkipsEmptyContext(t *testing.T) {
+func TestToolRegistry_ExecuteWithContext_EmptyContext(t *testing.T) {
 	r := NewToolRegistry()
-	ct := &mockCtxTool{
+	ct := &mockContextAwareTool{
 		mockRegistryTool: *newMockTool("ctx_tool", "needs context"),
 	}
 	r.Register(ct)
 
 	r.ExecuteWithContext(context.Background(), "ctx_tool", nil, "", "", nil)
 
-	if ct.channel != "" || ct.chatID != "" {
-		t.Error("SetContext should not be called with empty channel/chatID")
+	if ct.lastCtx == nil {
+		t.Fatal("expected Execute to be called")
+	}
+	// Empty values are still injected; tools decide what to do with them.
+	if got := ToolChannel(ct.lastCtx); got != "" {
+		t.Errorf("expected empty channel, got %q", got)
+	}
+	if got := ToolChatID(ct.lastCtx); got != "" {
+		t.Errorf("expected empty chatID, got %q", got)
 	}
 }
 
@@ -179,14 +202,14 @@ func TestToolRegistry_ExecuteWithContext_AsyncCallback(t *testing.T) {
 	cb := func(_ context.Context, _ *ToolResult) { called = true }
 
 	result := r.ExecuteWithContext(context.Background(), "async_tool", nil, "", "", cb)
-	if at.cb == nil {
-		t.Error("expected SetCallback to have been called")
+	if at.lastCB == nil {
+		t.Error("expected ExecuteAsync to have received a callback")
 	}
 	if !result.Async {
 		t.Error("expected async result")
 	}
 
-	at.cb(context.Background(), SilentResult("done"))
+	at.lastCB(context.Background(), SilentResult("done"))
 	if !called {
 		t.Error("expected callback to be invoked")
 	}
@@ -325,6 +348,96 @@ func TestToolToSchema(t *testing.T) {
 	}
 }
 
+func TestToolRegistry_Clone(t *testing.T) {
+	r := NewToolRegistry()
+	r.Register(newMockTool("read_file", "reads files"))
+	r.Register(newMockTool("exec", "runs commands"))
+	r.Register(newMockTool("web_search", "searches the web"))
+
+	clone := r.Clone()
+
+	// Clone should have the same tools
+	if clone.Count() != 3 {
+		t.Errorf("expected clone to have 3 tools, got %d", clone.Count())
+	}
+	for _, name := range []string{"read_file", "exec", "web_search"} {
+		if _, ok := clone.Get(name); !ok {
+			t.Errorf("expected clone to have tool %q", name)
+		}
+	}
+
+	// Registering on parent should NOT affect clone
+	r.Register(newMockTool("spawn", "spawns subagent"))
+	if r.Count() != 4 {
+		t.Errorf("expected parent to have 4 tools, got %d", r.Count())
+	}
+	if clone.Count() != 3 {
+		t.Errorf("expected clone to still have 3 tools after parent mutation, got %d", clone.Count())
+	}
+	if _, ok := clone.Get("spawn"); ok {
+		t.Error("expected clone NOT to have 'spawn' tool registered on parent after cloning")
+	}
+
+	// Registering on clone should NOT affect parent
+	clone.Register(newMockTool("custom", "custom tool"))
+	if clone.Count() != 4 {
+		t.Errorf("expected clone to have 4 tools, got %d", clone.Count())
+	}
+	if _, ok := r.Get("custom"); ok {
+		t.Error("expected parent NOT to have 'custom' tool registered on clone")
+	}
+}
+
+func TestToolRegistry_Clone_Empty(t *testing.T) {
+	r := NewToolRegistry()
+	clone := r.Clone()
+	if clone.Count() != 0 {
+		t.Errorf("expected empty clone, got count %d", clone.Count())
+	}
+}
+
+func TestToolRegistry_Clone_PreservesHiddenToolState(t *testing.T) {
+	r := NewToolRegistry()
+	r.RegisterHidden(newMockTool("mcp_tool", "dynamic MCP tool"))
+
+	clone := r.Clone()
+
+	// Hidden tools with TTL=0 should not be gettable (same behavior as parent)
+	if _, ok := clone.Get("mcp_tool"); ok {
+		t.Error("expected hidden tool with TTL=0 to be invisible in clone")
+	}
+
+	// But the entry should exist (count includes hidden tools)
+	if clone.Count() != 1 {
+		t.Errorf("expected clone count 1 (hidden entry exists), got %d", clone.Count())
+	}
+}
+
+func TestToolRegistry_Clone_PreservesTTLValue(t *testing.T) {
+	r := NewToolRegistry()
+	r.RegisterHidden(newMockTool("ttl_tool", "tool with TTL"))
+
+	// Manually set a non-zero TTL on the entry
+	r.mu.RLock()
+	if entry, ok := r.tools["ttl_tool"]; ok {
+		entry.TTL = 5
+	}
+	r.mu.RUnlock()
+
+	clone := r.Clone()
+
+	// Verify TTL value is preserved in the clone
+	clone.mu.RLock()
+	defer clone.mu.RUnlock()
+	entry, ok := clone.tools["ttl_tool"]
+	if !ok {
+		t.Fatal("expected ttl_tool to exist in clone")
+	}
+	if entry.TTL != 5 {
+		t.Errorf("expected TTL=5 in clone, got %d", entry.TTL)
+	}
+}
+
 func TestToolRegistry_ConcurrentAccess(t *testing.T) {
 	r := NewToolRegistry()
 	var wg sync.WaitGroup
@@ -348,3 +461,274 @@ func TestToolRegistry_ConcurrentAccess(t *testing.T) {
 		t.Error("expected tools to be registered after concurrent access")
 	}
 }
+
+// --- Panic and abnormal exit tests ---
+
+// mockPanicTool is a tool that panics during execution
+type mockPanicTool struct {
+	name       string
+	panicValue any
+}
+
+func (m *mockPanicTool) Name() string               { return m.name }
+func (m *mockPanicTool) Description() string        { return "a tool that panics" }
+func (m *mockPanicTool) Parameters() map[string]any { return map[string]any{"type": "object"} }
+func (m *mockPanicTool) Execute(_ context.Context, _ map[string]any) *ToolResult {
+	panic(m.panicValue)
+}
+
+// mockNilResultTool is a tool that returns nil
+type mockNilResultTool struct {
+	name string
+}
+
+func (m *mockNilResultTool) Name() string               { return m.name }
+func (m *mockNilResultTool) Description() string        { return "a tool that returns nil" }
+func (m *mockNilResultTool) Parameters() map[string]any { return map[string]any{"type": "object"} }
+func (m *mockNilResultTool) Execute(_ context.Context, _ map[string]any) *ToolResult {
+	return nil
+}
+
+func TestToolRegistry_Execute_PanicRecovery(t *testing.T) {
+	r := NewToolRegistry()
+	r.Register(&mockPanicTool{
+		name:       "panic_tool",
+		panicValue: "something went terribly wrong",
+	})
+
+	// Should not panic, should return error result
+	result := r.Execute(context.Background(), "panic_tool", nil)
+
+	if result == nil {
+		t.Fatal("expected non-nil result after panic recovery")
+	}
+	if !result.IsError {
+		t.Error("expected IsError=true after panic")
+	}
+	if !strings.Contains(result.ForLLM, "panic") {
+		t.Errorf("expected 'panic' in error message, got %q", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "panic_tool") {
+		t.Errorf("expected tool name in error message, got %q", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "something went terribly wrong") {
+		t.Errorf("expected panic value in error message, got %q", result.ForLLM)
+	}
+	if result.Err == nil {
+		t.Error("expected Err to be set")
+	}
+}
+
+func TestToolRegistry_Execute_PanicRecovery_ErrorType(t *testing.T) {
+	r := NewToolRegistry()
+
+	// Test with error type panic
+	r.Register(&mockPanicTool{
+		name:       "error_panic_tool",
+		panicValue: errors.New("custom error panic"),
+	})
+
+	result := r.Execute(context.Background(), "error_panic_tool", nil)
+
+	if !result.IsError {
+		t.Error("expected IsError=true")
+	}
+	if !strings.Contains(result.ForLLM, "custom error panic") {
+		t.Errorf("expected error message in ForLLM, got %q", result.ForLLM)
+	}
+}
+
+func TestToolRegistry_Execute_PanicRecovery_IntType(t *testing.T) {
+	r := NewToolRegistry()
+
+	// Test with int type panic
+	r.Register(&mockPanicTool{
+		name:       "int_panic_tool",
+		panicValue: 42,
+	})
+
+	result := r.Execute(context.Background(), "int_panic_tool", nil)
+
+	if !result.IsError {
+		t.Error("expected IsError=true")
+	}
+	if !strings.Contains(result.ForLLM, "42") {
+		t.Errorf("expected panic value '42' in ForLLM, got %q", result.ForLLM)
+	}
+}
+
+func TestToolRegistry_Execute_NilResultHandling(t *testing.T) {
+	r := NewToolRegistry()
+	r.Register(&mockNilResultTool{name: "nil_tool"})
+
+	result := r.Execute(context.Background(), "nil_tool", nil)
+
+	if result == nil {
+		t.Fatal("expected non-nil result when tool returns nil")
+	}
+	if !result.IsError {
+		t.Error("expected IsError=true for nil result")
+	}
+	if !strings.Contains(result.ForLLM, "nil_tool") {
+		t.Errorf("expected tool name in error message, got %q", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "nil result") {
+		t.Errorf("expected 'nil result' in error message, got %q", result.ForLLM)
+	}
+	if result.Err == nil {
+		t.Error("expected Err to be set")
+	}
+}
+
+func TestToolRegistry_ExecuteWithContext_PanicRecovery(t *testing.T) {
+	r := NewToolRegistry()
+	r.Register(&mockPanicTool{
+		name:       "ctx_panic_tool",
+		panicValue: "context panic test",
+	})
+
+	// Should not panic even with context
+	result := r.ExecuteWithContext(
+		context.Background(),
+		"ctx_panic_tool",
+		map[string]any{"key": "value"},
+		"telegram",
+		"chat-123",
+		nil,
+	)
+
+	if result == nil {
+		t.Fatal("expected non-nil result")
+	}
+	if !result.IsError {
+		t.Error("expected IsError=true")
+	}
+	if !strings.Contains(result.ForLLM, "context panic test") {
+		t.Errorf("expected panic message, got %q", result.ForLLM)
+	}
+}
+
+func TestToolRegistry_Execute_PanicDoesNotAffectOtherTools(t *testing.T) {
+	r := NewToolRegistry()
+	r.Register(&mockPanicTool{name: "bad_tool", panicValue: "boom"})
+	r.Register(&mockRegistryTool{
+		name:   "good_tool",
+		desc:   "works fine",
+		params: map[string]any{},
+		result: SilentResult("success"),
+	})
+
+	// First, trigger the panic
+	result1 := r.Execute(context.Background(), "bad_tool", nil)
+	if !result1.IsError {
+		t.Error("expected error from panic tool")
+	}
+
+	// Then, verify the good tool still works
+	result2 := r.Execute(context.Background(), "good_tool", nil)
+	if result2.IsError {
+		t.Errorf("expected success from good tool, got error: %s", result2.ForLLM)
+	}
+	if result2.ForLLM != "success" {
+		t.Errorf("expected 'success', got %q", result2.ForLLM)
+	}
+}
+
+func TestToolRegistry_SetMediaStore_PropagatesToExistingAndNewTools(t *testing.T) {
+	r := NewToolRegistry()
+	store := media.NewFileMediaStore()
+
+	existing := &mockMediaStoreAwareTool{
+		mockRegistryTool: *newMockTool("existing", "existing tool"),
+	}
+	r.Register(existing)
+
+	r.SetMediaStore(store)
+	if existing.store != store {
+		t.Fatal("expected existing tool to receive media store")
+	}
+
+	later := &mockMediaStoreAwareTool{
+		mockRegistryTool: *newMockTool("later", "later tool"),
+	}
+	r.Register(later)
+
+	if later.store != store {
+		t.Fatal("expected newly registered tool to inherit media store")
+	}
+}
+
+func TestToolRegistry_ExecuteWithContext_SanitizesLargeBase64Payload(t *testing.T) {
+	r := NewToolRegistry()
+	payload := strings.Repeat("QUJD", 400)
+	r.Register(&mockRegistryTool{
+		name:   "base64_tool",
+		desc:   "returns huge base64",
+		params: map[string]any{},
+		result: SilentResult(payload),
+	})
+
+	result := r.ExecuteWithContext(context.Background(), "base64_tool", nil, "telegram", "chat-1", nil)
+
+	if result.ForLLM != largeBase64OmittedMessage {
+		t.Fatalf("expected sanitized payload, got %q", result.ForLLM)
+	}
+}
+
+func TestToolRegistry_ExecuteWithContext_ExtractsInlineMediaDataURL(t *testing.T) {
+	r := NewToolRegistry()
+	store := media.NewFileMediaStore()
+	r.SetMediaStore(store)
+
+	payload := "![screenshot](data:image/png;base64,aGVsbG8=)"
+	r.Register(&mockRegistryTool{
+		name:   "inline_media_tool",
+		desc:   "returns inline data url",
+		params: map[string]any{},
+		result: SilentResult(payload),
+	})
+
+	result := r.ExecuteWithContext(context.Background(), "inline_media_tool", nil, "telegram", "chat-42", nil)
+
+	if len(result.Media) != 1 {
+		t.Fatalf("expected 1 media ref, got %d", len(result.Media))
+	}
+	if strings.Contains(result.ForLLM, "data:image/png;base64") {
+		t.Fatalf("expected inline data URL to be stripped from ForLLM, got %q", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "registered as a media attachment") {
+		t.Fatalf("expected delivery note in ForLLM, got %q", result.ForLLM)
+	}
+
+	path, err := store.Resolve(result.Media[0])
+	if err != nil {
+		t.Fatalf("expected stored media ref to resolve: %v", err)
+	}
+	if _, err := os.Stat(path); err != nil {
+		t.Fatalf("expected stored media file to exist: %v", err)
+	}
+	if filepath.Ext(path) != ".png" {
+		t.Fatalf("expected stored inline media to use png extension, got %q", path)
+	}
+}
+
+func TestToolRegistry_ExecuteWithContext_SanitizesInlineMediaWithoutStore(t *testing.T) {
+	r := NewToolRegistry()
+
+	payload := "before ![img](data:image/png;base64,aGVsbG8=) after"
+	r.Register(&mockRegistryTool{
+		name:   "inline_media_no_store",
+		desc:   "returns inline data url without store",
+		params: map[string]any{},
+		result: SilentResult(payload),
+	})
+
+	result := r.ExecuteWithContext(context.Background(), "inline_media_no_store", nil, "telegram", "chat-42", nil)
+
+	if strings.Contains(result.ForLLM, "data:image/png;base64") {
+		t.Fatalf("expected inline data URL to be removed from ForLLM, got %q", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, inlineMediaOmittedMessage) {
+		t.Fatalf("expected inline media omission note, got %q", result.ForLLM)
+	}
+}
diff --git a/pkg/tools/result.go b/pkg/tools/result.go
index cab833284..c81213125 100644
--- a/pkg/tools/result.go
+++ b/pkg/tools/result.go
@@ -1,6 +1,16 @@
 package tools
 
-import "encoding/json"
+import (
+	"encoding/json"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+const (
+	handledToolLLMNote   = "The requested output has already been delivered to the user in the current chat. Do not call send_file or any other delivery tool again. If you reply, provide only a brief confirmation."
+	artifactPathsLLMNote = "Use `send_file` with one of these paths to send it to the user, or use file/exec tools to save it inside the workspace if requested."
+)
 
 // ToolResult represents the structured return value from tool execution.
 // It provides clear semantics for different types of results and supports
@@ -34,6 +44,53 @@ type ToolResult struct {
 	// Media contains media store refs produced by this tool.
 	// When non-empty, the agent will publish these as OutboundMediaMessage.
 	Media []string `json:"media,omitempty"`
+
+	// Messages holds the ephemeral session history after execution.
+	// Only populated by SubTurn executions; used by evaluator_optimizer
+	// to carry stateful worker context across evaluation iterations.
+	Messages []providers.Message `json:"-"`
+
+	// ArtifactTags exposes local artifact paths back to the LLM in a structured
+	// form, e.g. "[file:/tmp/example.png]". This is used when a tool produced a
+	// reusable local artifact but did not deliver it to the user yet.
+	ArtifactTags []string `json:"artifact_tags,omitempty"`
+
+	// ResponseHandled indicates that this tool execution already satisfied the
+	// user's request at the channel/output level, so the agent loop can stop
+	// without a follow-up assistant response.
+	ResponseHandled bool `json:"response_handled,omitempty"`
+}
+
+// ContentForLLM returns the normalized textual content to append to the
+// conversation after a tool call. Errors fall back to Err when ForLLM is empty.
+func (tr *ToolResult) ContentForLLM() string {
+	if tr == nil {
+		return ""
+	}
+	content := tr.ForLLM
+	if content == "" && tr.Err != nil {
+		content = tr.Err.Error()
+	}
+	if tr.ResponseHandled {
+		if content == "" {
+			return handledToolLLMNote
+		}
+		if !strings.Contains(content, handledToolLLMNote) {
+			content += "\n" + handledToolLLMNote
+		}
+	}
+	if len(tr.ArtifactTags) > 0 {
+		artifactNote := "Local artifact paths: " + strings.Join(tr.ArtifactTags, " ") + "\n" + artifactPathsLLMNote
+		if content == "" {
+			content = artifactNote
+		} else if !strings.Contains(content, artifactNote) {
+			content += "\n" + artifactNote
+		}
+	}
+	if content != "" {
+		return content
+	}
+	return ""
 }
 
 // NewToolResult creates a basic ToolResult with content for the LLM.
@@ -158,3 +215,9 @@ func (tr *ToolResult) WithError(err error) *ToolResult {
 	tr.Err = err
 	return tr
 }
+
+// WithResponseHandled marks the tool result as already delivered to the user.
+func (tr *ToolResult) WithResponseHandled() *ToolResult {
+	tr.ResponseHandled = true
+	return tr
+}
diff --git a/pkg/tools/result_test.go b/pkg/tools/result_test.go
index a234e33f3..5f08cb4fa 100644
--- a/pkg/tools/result_test.go
+++ b/pkg/tools/result_test.go
@@ -3,6 +3,7 @@ package tools
 import (
 	"encoding/json"
 	"errors"
+	"strings"
 	"testing"
 )
 
@@ -227,3 +228,41 @@ func TestToolResultJSONStructure(t *testing.T) {
 		t.Errorf("Expected silent false, got %v", parsed["silent"])
 	}
 }
+
+func TestToolResultContentForLLM_AppendsHandledDeliveryNote(t *testing.T) {
+	result := MediaResult("Screenshot attached.", []string{"media://example"}).WithResponseHandled()
+
+	content := result.ContentForLLM()
+	if !strings.Contains(content, "Screenshot attached.") {
+		t.Fatalf("expected original content in ContentForLLM, got %q", content)
+	}
+	if !strings.Contains(content, handledToolLLMNote) {
+		t.Fatalf("expected handled delivery note in ContentForLLM, got %q", content)
+	}
+}
+
+func TestToolResultContentForLLM_UsesHandledDeliveryNoteWhenEmpty(t *testing.T) {
+	result := (&ToolResult{}).WithResponseHandled()
+
+	if got := result.ContentForLLM(); got != handledToolLLMNote {
+		t.Fatalf("ContentForLLM() = %q, want %q", got, handledToolLLMNote)
+	}
+}
+
+func TestToolResultContentForLLM_AppendsArtifactPaths(t *testing.T) {
+	result := &ToolResult{
+		ForLLM:       "Artifact created.",
+		ArtifactTags: []string{"[file:/tmp/example.png]"},
+	}
+
+	content := result.ContentForLLM()
+	if !strings.Contains(content, "Artifact created.") {
+		t.Fatalf("expected original content in ContentForLLM, got %q", content)
+	}
+	if !strings.Contains(content, "Local artifact paths: [file:/tmp/example.png]") {
+		t.Fatalf("expected artifact path note in ContentForLLM, got %q", content)
+	}
+	if !strings.Contains(content, artifactPathsLLMNote) {
+		t.Fatalf("expected artifact guidance note in ContentForLLM, got %q", content)
+	}
+}
diff --git a/pkg/tools/search_tool.go b/pkg/tools/search_tool.go
new file mode 100644
index 000000000..f41c80d90
--- /dev/null
+++ b/pkg/tools/search_tool.go
@@ -0,0 +1,304 @@
+package tools
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strings"
+	"sync"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+const (
+	MaxRegexPatternLength = 200
+)
+
+type RegexSearchTool struct {
+	registry         *ToolRegistry
+	ttl              int
+	maxSearchResults int
+}
+
+func NewRegexSearchTool(r *ToolRegistry, ttl int, maxSearchResults int) *RegexSearchTool {
+	return &RegexSearchTool{registry: r, ttl: ttl, maxSearchResults: maxSearchResults}
+}
+
+func (t *RegexSearchTool) Name() string {
+	return "tool_search_tool_regex"
+}
+
+func (t *RegexSearchTool) Description() string {
+	return "Search available hidden tools on-demand using a regex pattern. Returns JSON schemas of discovered tools."
+}
+
+func (t *RegexSearchTool) Parameters() map[string]any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"pattern": map[string]any{
+				"type":        "string",
+				"description": "Regex pattern to match tool name or description",
+			},
+		},
+		"required": []string{"pattern"},
+	}
+}
+
+func (t *RegexSearchTool) Execute(ctx context.Context, args map[string]any) *ToolResult {
+	pattern, ok := args["pattern"].(string)
+	if !ok || strings.TrimSpace(pattern) == "" {
+		// An empty string regex (?i) will match every hidden tool,
+		// dumping massive payloads into the context and burning tokens.
+		return ErrorResult("Missing or invalid 'pattern' argument. Must be a non-empty string.")
+	}
+
+	if len(pattern) > MaxRegexPatternLength {
+		logger.WarnCF("discovery", "Regex pattern rejected (too long)", map[string]any{"len": len(pattern)})
+		return ErrorResult(fmt.Sprintf("Pattern too long: max %d characters allowed", MaxRegexPatternLength))
+	}
+
+	logger.DebugCF("discovery", "Regex search", map[string]any{"pattern": pattern})
+
+	res, err := t.registry.SearchRegex(pattern, t.maxSearchResults)
+	if err != nil {
+		logger.WarnCF("discovery", "Invalid regex pattern", map[string]any{"pattern": pattern, "error": err.Error()})
+		return ErrorResult(fmt.Sprintf("Invalid regex pattern syntax: %v. Please fix your regex and try again.", err))
+	}
+
+	logger.InfoCF("discovery", "Regex search completed", map[string]any{"pattern": pattern, "results": len(res)})
+	return formatDiscoveryResponse(t.registry, res, t.ttl)
+}
+
+type BM25SearchTool struct {
+	registry         *ToolRegistry
+	ttl              int
+	maxSearchResults int
+
+	// Cache: rebuilt only when the registry version changes.
+	cacheMu      sync.Mutex
+	cachedEngine *bm25CachedEngine
+	cacheVersion uint64
+}
+
+func NewBM25SearchTool(r *ToolRegistry, ttl int, maxSearchResults int) *BM25SearchTool {
+	return &BM25SearchTool{registry: r, ttl: ttl, maxSearchResults: maxSearchResults}
+}
+
+func (t *BM25SearchTool) Name() string {
+	return "tool_search_tool_bm25"
+}
+
+func (t *BM25SearchTool) Description() string {
+	return "Search available hidden tools on-demand using natural language query describing the action you need to perform. Returns JSON schemas of discovered tools."
+}
+
+func (t *BM25SearchTool) Parameters() map[string]any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"query": map[string]any{
+				"type":        "string",
+				"description": "Search query",
+			},
+		},
+		"required": []string{"query"},
+	}
+}
+
+func (t *BM25SearchTool) Execute(ctx context.Context, args map[string]any) *ToolResult {
+	query, ok := args["query"].(string)
+	if !ok || strings.TrimSpace(query) == "" {
+		// An empty string query will match every hidden tool,
+		// dumping massive payloads into the context and burning tokens.
+		return ErrorResult("Missing or invalid 'query' argument. Must be a non-empty string.")
+	}
+
+	logger.DebugCF("discovery", "BM25 search", map[string]any{"query": query})
+
+	cached := t.getOrBuildEngine()
+	if cached == nil {
+		logger.DebugCF("discovery", "BM25 search: no hidden tools available", nil)
+		return SilentResult("No tools found matching the query.")
+	}
+
+	ranked := cached.engine.Search(query, t.maxSearchResults)
+	if len(ranked) == 0 {
+		logger.DebugCF("discovery", "BM25 search: no matches", map[string]any{"query": query})
+		return SilentResult("No tools found matching the query.")
+	}
+
+	results := make([]ToolSearchResult, len(ranked))
+	for i, r := range ranked {
+		results[i] = ToolSearchResult{
+			Name:        r.Document.Name,
+			Description: r.Document.Description,
+		}
+	}
+
+	logger.InfoCF("discovery", "BM25 search completed", map[string]any{"query": query, "results": len(results)})
+	return formatDiscoveryResponse(t.registry, results, t.ttl)
+}
+
+// ToolSearchResult represents the result returned to the LLM.
+// Parameters are omitted from the JSON response to save context tokens;
+// the LLM will see full schemas via ToProviderDefs after promotion.
+type ToolSearchResult struct {
+	Name        string `json:"name"`
+	Description string `json:"description"`
+}
+
+func (r *ToolRegistry) SearchRegex(pattern string, maxSearchResults int) ([]ToolSearchResult, error) {
+	if maxSearchResults <= 0 {
+		return nil, nil
+	}
+
+	regex, err := regexp.Compile("(?i)" + pattern)
+	if err != nil {
+		return nil, fmt.Errorf("failed to compile regex pattern %q: %w", pattern, err)
+	}
+
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+
+	var results []ToolSearchResult
+
+	// Iterate in sorted order for deterministic results across calls.
+	for _, name := range r.sortedToolNames() {
+		entry := r.tools[name]
+		// Search only among the hidden tools (Core tools are already visible)
+		if !entry.IsCore {
+			// Directly call interface methods! No reflection/unmarshalling needed.
+			desc := entry.Tool.Description()
+
+			if regex.MatchString(name) || regex.MatchString(desc) {
+				results = append(results, ToolSearchResult{
+					Name:        name,
+					Description: desc,
+				})
+				if len(results) >= maxSearchResults {
+					break // Stop searching once we hit the max! Saves CPU.
+				}
+			}
+		}
+	}
+
+	return results, nil
+}
+
+func formatDiscoveryResponse(registry *ToolRegistry, results []ToolSearchResult, ttl int) *ToolResult {
+	if len(results) == 0 {
+		return SilentResult("No tools found matching the query.")
+	}
+
+	names := make([]string, len(results))
+	for i, r := range results {
+		names[i] = r.Name
+	}
+	registry.PromoteTools(names, ttl)
+	logger.InfoCF("discovery", "Promoted tools", map[string]any{"tools": names, "ttl": ttl})
+
+	b, err := json.Marshal(results)
+	if err != nil {
+		return ErrorResult("Failed to format search results: " + err.Error())
+	}
+
+	msg := fmt.Sprintf(
+		"Found %d tools:\n%s\n\nSUCCESS: These tools have been temporarily UNLOCKED as native tools! In your next response, you can call them directly just like any normal tool",
+		len(results),
+		string(b),
+	)
+
+	return SilentResult(msg)
+}
+
+// Lightweight internal type used as corpus document for BM25.
+type searchDoc struct {
+	Name        string
+	Description string
+}
+
+// bm25CachedEngine wraps a BM25Engine with its corpus snapshot.
+type bm25CachedEngine struct {
+	engine *utils.BM25Engine[searchDoc]
+}
+
+// snapshotToSearchDocs converts a HiddenToolSnapshot to BM25 searchDoc slice.
+func snapshotToSearchDocs(snap HiddenToolSnapshot) []searchDoc {
+	docs := make([]searchDoc, len(snap.Docs))
+	for i, d := range snap.Docs {
+		docs[i] = searchDoc{Name: d.Name, Description: d.Description}
+	}
+	return docs
+}
+
+// buildBM25Engine creates a BM25Engine from a slice of searchDocs.
+func buildBM25Engine(docs []searchDoc) *utils.BM25Engine[searchDoc] {
+	return utils.NewBM25Engine(
+		docs,
+		func(doc searchDoc) string {
+			return doc.Name + " " + doc.Description
+		},
+	)
+}
+
+// getOrBuildEngine returns a cached BM25 engine, rebuilding it only when
+// the registry version has changed (new tools registered).
+func (t *BM25SearchTool) getOrBuildEngine() *bm25CachedEngine {
+	// Fast path: optimistic check without locking.
+	if t.cachedEngine != nil && t.cacheVersion == t.registry.Version() {
+		return t.cachedEngine
+	}
+
+	t.cacheMu.Lock()
+	defer t.cacheMu.Unlock()
+
+	// Snapshot + version are read under a single registry RLock,
+	// guaranteeing consistency (no TOCTOU).
+	snap := t.registry.SnapshotHiddenTools()
+
+	// Re-check: another goroutine may have rebuilt while we waited for cacheMu.
+	if t.cachedEngine != nil && t.cacheVersion == snap.Version {
+		return t.cachedEngine
+	}
+
+	docs := snapshotToSearchDocs(snap)
+	if len(docs) == 0 {
+		t.cachedEngine = nil
+		t.cacheVersion = snap.Version
+		return nil
+	}
+
+	cached := &bm25CachedEngine{engine: buildBM25Engine(docs)}
+	t.cachedEngine = cached
+	t.cacheVersion = snap.Version
+	logger.DebugCF("discovery", "BM25 engine rebuilt", map[string]any{"docs": len(docs), "version": snap.Version})
+	return cached
+}
+
+// SearchBM25 ranks hidden tools against query using BM25 via utils.BM25Engine.
+// This non-cached variant rebuilds the engine on every call. Used by tests
+// and any code that doesn't hold a BM25SearchTool instance.
+func (r *ToolRegistry) SearchBM25(query string, maxSearchResults int) []ToolSearchResult {
+	snap := r.SnapshotHiddenTools()
+	docs := snapshotToSearchDocs(snap)
+	if len(docs) == 0 {
+		return nil
+	}
+
+	ranked := buildBM25Engine(docs).Search(query, maxSearchResults)
+	if len(ranked) == 0 {
+		return nil
+	}
+
+	out := make([]ToolSearchResult, len(ranked))
+	for i, r := range ranked {
+		out[i] = ToolSearchResult{
+			Name:        r.Document.Name,
+			Description: r.Document.Description,
+		}
+	}
+	return out
+}
diff --git a/pkg/tools/search_tools_test.go b/pkg/tools/search_tools_test.go
new file mode 100644
index 000000000..3aae941cb
--- /dev/null
+++ b/pkg/tools/search_tools_test.go
@@ -0,0 +1,339 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+)
+
+// Dummy tool to fill the registry in our tests.
+type mockSearchableTool struct {
+	name string
+	desc string
+}
+
+func (m *mockSearchableTool) Name() string        { return m.name }
+func (m *mockSearchableTool) Description() string { return m.desc }
+func (m *mockSearchableTool) Parameters() map[string]any {
+	return map[string]any{"type": "object"}
+}
+
+func (m *mockSearchableTool) Execute(ctx context.Context, args map[string]any) *ToolResult {
+	return SilentResult("mock executed: " + m.name)
+}
+
+// Helper to initialize a populated ToolRegistry
+func setupPopulatedRegistry() *ToolRegistry {
+	reg := NewToolRegistry()
+
+	// A core tool (NOT to be found by searches)
+	reg.Register(&mockSearchableTool{
+		name: "core_search",
+		desc: "I am a visible core tool for searching files",
+	})
+
+	// Hidden tools (must be found by searches)
+	reg.RegisterHidden(&mockSearchableTool{
+		name: "mcp_read_file",
+		desc: "Read the contents of a system file",
+	})
+	reg.RegisterHidden(&mockSearchableTool{
+		name: "mcp_list_dir",
+		desc: "List directories and files in the system",
+	})
+	reg.RegisterHidden(&mockSearchableTool{
+		name: "mcp_fetch_net",
+		desc: "Fetch data from a network database",
+	})
+
+	return reg
+}
+
+func TestRegexSearchTool_Execute(t *testing.T) {
+	reg := setupPopulatedRegistry()
+	tool := NewRegexSearchTool(reg, 5, 10)
+	ctx := context.Background()
+
+	t.Run("Empty Pattern Error", func(t *testing.T) {
+		res := tool.Execute(ctx, map[string]any{})
+		if !res.IsError || !strings.Contains(res.ForLLM, "Missing or invalid 'pattern'") {
+			t.Errorf("Expected missing pattern error, got: %v", res.ForLLM)
+		}
+	})
+
+	t.Run("Invalid Regex Syntax", func(t *testing.T) {
+		res := tool.Execute(ctx, map[string]any{"pattern": "[unclosed"})
+		if !res.IsError || !strings.Contains(res.ForLLM, "Invalid regex pattern syntax") {
+			t.Errorf("Expected regex syntax error, got: %v", res.ForLLM)
+		}
+	})
+
+	t.Run("No Match Found", func(t *testing.T) {
+		res := tool.Execute(ctx, map[string]any{"pattern": "alien"})
+		if res.IsError || !strings.Contains(res.ForLLM, "No tools found matching") {
+			t.Errorf("Expected 'no tools found' message, got: %v", res.ForLLM)
+		}
+	})
+
+	t.Run("Successful Match & Promotion", func(t *testing.T) {
+		res := tool.Execute(ctx, map[string]any{"pattern": "system"})
+
+		if res.IsError {
+			t.Fatalf("Unexpected error: %v", res.ForLLM)
+		}
+		if !strings.Contains(res.ForLLM, "SUCCESS: These tools have been temporarily UNLOCKED") {
+			t.Errorf("Expected success string, got: %v", res.ForLLM)
+		}
+		if !strings.Contains(res.ForLLM, "mcp_read_file") {
+			t.Errorf("Expected 'mcp_read_file' in results")
+		}
+
+		// Verify that the TTL has been updated for the tools found
+		reg.mu.RLock()
+		defer reg.mu.RUnlock()
+		if reg.tools["mcp_read_file"].TTL != 5 {
+			t.Errorf("Expected TTL of 'mcp_read_file' to be promoted to 5, got %d", reg.tools["mcp_read_file"].TTL)
+		}
+		if reg.tools["mcp_fetch_net"].TTL != 0 {
+			t.Errorf("Expected 'mcp_fetch_net' to NOT be promoted (TTL=0)")
+		}
+	})
+}
+
+func TestBM25SearchTool_Execute(t *testing.T) {
+	reg := setupPopulatedRegistry()
+	tool := NewBM25SearchTool(reg, 3, 10)
+	ctx := context.Background()
+
+	t.Run("Empty Query Error", func(t *testing.T) {
+		res := tool.Execute(ctx, map[string]any{"query": "   "})
+		if !res.IsError || !strings.Contains(res.ForLLM, "Missing or invalid 'query'") {
+			t.Errorf("Expected missing query error, got: %v", res.ForLLM)
+		}
+	})
+
+	t.Run("No Match Found", func(t *testing.T) {
+		res := tool.Execute(ctx, map[string]any{"query": "aliens spaceships"})
+		if res.IsError || !strings.Contains(res.ForLLM, "No tools found matching") {
+			t.Errorf("Expected 'no tools found', got: %v", res.ForLLM)
+		}
+	})
+
+	t.Run("Successful Match & Promotion", func(t *testing.T) {
+		res := tool.Execute(ctx, map[string]any{"query": "read files"})
+
+		if res.IsError {
+			t.Fatalf("Unexpected error: %v", res.ForLLM)
+		}
+		if !strings.Contains(res.ForLLM, "mcp_read_file") {
+			t.Errorf("Expected 'mcp_read_file' in BM25 results")
+		}
+
+		reg.mu.RLock()
+		defer reg.mu.RUnlock()
+		if reg.tools["mcp_read_file"].TTL != 3 {
+			t.Errorf("Expected TTL of 'mcp_read_file' to be promoted to 3")
+		}
+	})
+}
+
+func TestRegexSearchTool_PatternTooLong(t *testing.T) {
+	reg := setupPopulatedRegistry()
+	tool := NewRegexSearchTool(reg, 5, 10)
+	ctx := context.Background()
+
+	longPattern := strings.Repeat("a", MaxRegexPatternLength+1)
+	res := tool.Execute(ctx, map[string]any{"pattern": longPattern})
+	if !res.IsError || !strings.Contains(res.ForLLM, "Pattern too long") {
+		t.Errorf("Expected pattern too long error, got: %v", res.ForLLM)
+	}
+}
+
+func TestSearchRegex_ZeroMaxResults(t *testing.T) {
+	reg := setupPopulatedRegistry()
+
+	res, err := reg.SearchRegex("mcp", 0)
+	if err != nil {
+		t.Fatalf("SearchRegex failed: %v", err)
+	}
+	if len(res) != 0 {
+		t.Errorf("Expected 0 results with maxSearchResults=0, got %d", len(res))
+	}
+}
+
+func TestSearchBM25_ZeroMaxResults(t *testing.T) {
+	reg := setupPopulatedRegistry()
+
+	res := reg.SearchBM25("read file", 0)
+	if len(res) != 0 {
+		t.Errorf("Expected 0 results with maxSearchResults=0, got %d", len(res))
+	}
+}
+
+func TestSearchRegex_DeterministicOrder(t *testing.T) {
+	reg := NewToolRegistry()
+	for i := 0; i < 20; i++ {
+		reg.RegisterHidden(&mockSearchableTool{
+			name: fmt.Sprintf("tool_%02d", i),
+			desc: "searchable tool",
+		})
+	}
+
+	// Run the same search multiple times and verify order is stable
+	var firstRun []string
+	for attempt := 0; attempt < 10; attempt++ {
+		res, err := reg.SearchRegex("searchable", 20)
+		if err != nil {
+			t.Fatalf("SearchRegex failed: %v", err)
+		}
+
+		names := make([]string, len(res))
+		for i, r := range res {
+			names[i] = r.Name
+		}
+
+		if attempt == 0 {
+			firstRun = names
+		} else {
+			for i, name := range names {
+				if name != firstRun[i] {
+					t.Fatalf("Non-deterministic order at attempt %d, index %d: got %q, want %q",
+						attempt, i, name, firstRun[i])
+				}
+			}
+		}
+	}
+}
+
+func TestToolRegistry_SearchLimitsAndCoreFiltering(t *testing.T) {
+	reg := NewToolRegistry()
+
+	// Add 1 Core and 10 Hidden, all containing the word "match"
+	reg.Register(&mockSearchableTool{"core_match", "I am core with match"})
+	for i := 0; i < 10; i++ {
+		reg.RegisterHidden(&mockSearchableTool{
+			name: fmt.Sprintf("hidden_match_%d", i),
+			desc: "this has a match",
+		})
+	}
+
+	t.Run("Regex limits and core filtering", func(t *testing.T) {
+		// Search with Regex and a limit of maxSearchResults = 4
+		res, err := reg.SearchRegex("match", 4)
+		if err != nil {
+			t.Fatalf("SearchRegex failed: %v", err)
+		}
+
+		if len(res) != 4 {
+			t.Errorf("Expected exactly 4 results due to limit, got %d", len(res))
+		}
+
+		for _, r := range res {
+			if r.Name == "core_match" {
+				t.Errorf("SearchRegex returned a Core tool, which should be excluded")
+			}
+		}
+	})
+
+	t.Run("BM25 limits and core filtering", func(t *testing.T) {
+		// Search with BM25 and a limit of maxSearchResults = 3
+		res := reg.SearchBM25("match", 3)
+
+		if len(res) != 3 {
+			t.Errorf("Expected exactly 3 results due to limit, got %d", len(res))
+		}
+
+		for _, r := range res {
+			if r.Name == "core_match" {
+				t.Errorf("SearchBM25 returned a Core tool, which should be excluded")
+			}
+		}
+	})
+}
+
+func TestGet_HiddenToolTTLLifecycle(t *testing.T) {
+	reg := NewToolRegistry()
+	reg.RegisterHidden(&mockSearchableTool{name: "hidden_tool", desc: "test"})
+
+	// TTL=0 at registration → not gettable
+	_, ok := reg.Get("hidden_tool")
+	if ok {
+		t.Error("Expected hidden tool with TTL=0 to NOT be gettable")
+	}
+
+	// Promote → gettable
+	reg.PromoteTools([]string{"hidden_tool"}, 3)
+	_, ok = reg.Get("hidden_tool")
+	if !ok {
+		t.Error("Expected promoted hidden tool to be gettable")
+	}
+
+	// Tick down to 0 → not gettable again
+	reg.TickTTL() // 3→2
+	reg.TickTTL() // 2→1
+	reg.TickTTL() // 1→0
+	_, ok = reg.Get("hidden_tool")
+	if ok {
+		t.Error("Expected hidden tool with TTL ticked to 0 to NOT be gettable")
+	}
+
+	// Core tools remain always gettable
+	reg.Register(&mockSearchableTool{name: "core_tool", desc: "core"})
+	_, ok = reg.Get("core_tool")
+	if !ok {
+		t.Error("Expected core tool to always be gettable")
+	}
+}
+
+func TestBM25CacheInvalidation(t *testing.T) {
+	reg := NewToolRegistry()
+	reg.RegisterHidden(&mockSearchableTool{name: "tool_alpha", desc: "alpha functionality"})
+
+	tool := NewBM25SearchTool(reg, 5, 10)
+	ctx := context.Background()
+
+	// First search should find tool_alpha
+	res := tool.Execute(ctx, map[string]any{"query": "alpha"})
+	if !strings.Contains(res.ForLLM, "tool_alpha") {
+		t.Fatalf("Expected 'tool_alpha' in first search, got: %v", res.ForLLM)
+	}
+
+	// Register a new hidden tool
+	reg.RegisterHidden(&mockSearchableTool{name: "tool_beta", desc: "beta functionality"})
+
+	// Cache should be invalidated; new tool should be findable
+	res = tool.Execute(ctx, map[string]any{"query": "beta"})
+	if !strings.Contains(res.ForLLM, "tool_beta") {
+		t.Errorf("Expected 'tool_beta' after cache invalidation, got: %v", res.ForLLM)
+	}
+}
+
+func TestPromoteTools_ConcurrentWithTickTTL(t *testing.T) {
+	reg := NewToolRegistry()
+	for i := 0; i < 20; i++ {
+		reg.RegisterHidden(&mockSearchableTool{
+			name: fmt.Sprintf("concurrent_tool_%d", i),
+			desc: "concurrent test tool",
+		})
+	}
+
+	names := make([]string, 20)
+	for i := 0; i < 20; i++ {
+		names[i] = fmt.Sprintf("concurrent_tool_%d", i)
+	}
+
+	// Hammer PromoteTools and TickTTL concurrently to detect races
+	done := make(chan struct{})
+	go func() {
+		for i := 0; i < 1000; i++ {
+			reg.PromoteTools(names, 5)
+		}
+		close(done)
+	}()
+
+	for i := 0; i < 1000; i++ {
+		reg.TickTTL()
+	}
+	<-done
+}
diff --git a/pkg/tools/send_file.go b/pkg/tools/send_file.go
new file mode 100644
index 000000000..44198381e
--- /dev/null
+++ b/pkg/tools/send_file.go
@@ -0,0 +1,164 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"mime"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/h2non/filetype"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+// SendFileTool allows the LLM to send a local file (image, document, etc.)
+// to the user on the current chat channel via the MediaStore pipeline.
+type SendFileTool struct {
+	workspace   string
+	restrict    bool
+	maxFileSize int
+	mediaStore  media.MediaStore
+	allowPaths  []*regexp.Regexp
+
+	defaultChannel string
+	defaultChatID  string
+}
+
+func NewSendFileTool(
+	workspace string,
+	restrict bool,
+	maxFileSize int,
+	store media.MediaStore,
+	allowPaths ...[]*regexp.Regexp,
+) *SendFileTool {
+	if maxFileSize <= 0 {
+		maxFileSize = config.DefaultMaxMediaSize
+	}
+	var patterns []*regexp.Regexp
+	if len(allowPaths) > 0 {
+		patterns = allowPaths[0]
+	}
+	return &SendFileTool{
+		workspace:   workspace,
+		restrict:    restrict,
+		maxFileSize: maxFileSize,
+		mediaStore:  store,
+		allowPaths:  patterns,
+	}
+}
+
+func (t *SendFileTool) Name() string { return "send_file" }
+func (t *SendFileTool) Description() string {
+	return "Send a local file (image, document, etc.) to the user on the current chat channel."
+}
+
+func (t *SendFileTool) Parameters() map[string]any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"path": map[string]any{
+				"type":        "string",
+				"description": "Path to the local file. Relative paths are resolved from workspace.",
+			},
+			"filename": map[string]any{
+				"type":        "string",
+				"description": "Optional display filename. Defaults to the basename of path.",
+			},
+		},
+		"required": []string{"path"},
+	}
+}
+
+func (t *SendFileTool) SetContext(channel, chatID string) {
+	t.defaultChannel = channel
+	t.defaultChatID = chatID
+}
+
+func (t *SendFileTool) SetMediaStore(store media.MediaStore) {
+	t.mediaStore = store
+}
+
+func (t *SendFileTool) Execute(ctx context.Context, args map[string]any) *ToolResult {
+	path, _ := args["path"].(string)
+	if strings.TrimSpace(path) == "" {
+		return ErrorResult("path is required")
+	}
+
+	// Prefer context-injected channel/chatID (set by ExecuteWithContext), fall back to SetContext values.
+	channel := ToolChannel(ctx)
+	if channel == "" {
+		channel = t.defaultChannel
+	}
+	chatID := ToolChatID(ctx)
+	if chatID == "" {
+		chatID = t.defaultChatID
+	}
+	if channel == "" || chatID == "" {
+		return ErrorResult("no target channel/chat available")
+	}
+
+	if t.mediaStore == nil {
+		return ErrorResult("media store not configured")
+	}
+
+	resolved, err := validatePathWithAllowPaths(path, t.workspace, t.restrict, t.allowPaths)
+	if err != nil {
+		return ErrorResult(fmt.Sprintf("invalid path: %v", err))
+	}
+
+	info, err := os.Stat(resolved)
+	if err != nil {
+		return ErrorResult(fmt.Sprintf("file not found: %v", err))
+	}
+	if info.IsDir() {
+		return ErrorResult("path is a directory, expected a file")
+	}
+	if info.Size() > int64(t.maxFileSize) {
+		return ErrorResult(fmt.Sprintf(
+			"file too large: %d bytes (max %d bytes)",
+			info.Size(), t.maxFileSize,
+		))
+	}
+
+	filename, _ := args["filename"].(string)
+	if filename == "" {
+		filename = filepath.Base(resolved)
+	}
+
+	mediaType := detectMediaType(resolved)
+	scope := fmt.Sprintf("tool:send_file:%s:%s", channel, chatID)
+
+	ref, err := t.mediaStore.Store(resolved, media.MediaMeta{
+		Filename:      filename,
+		ContentType:   mediaType,
+		Source:        "tool:send_file",
+		CleanupPolicy: media.CleanupPolicyForgetOnly,
+	}, scope)
+	if err != nil {
+		return ErrorResult(fmt.Sprintf("failed to register media: %v", err))
+	}
+
+	return MediaResult(fmt.Sprintf("File %q sent to user", filename), []string{ref}).WithResponseHandled()
+}
+
+// detectMediaType determines the MIME type of a file.
+// Uses magic-bytes detection (h2non/filetype) first, then falls back to
+// extension-based lookup via mime.TypeByExtension.
+func detectMediaType(path string) string {
+	kind, err := filetype.MatchFile(path)
+	if err == nil && kind != filetype.Unknown {
+		return kind.MIME.Value
+	}
+
+	if ext := filepath.Ext(path); ext != "" {
+		if t := mime.TypeByExtension(ext); t != "" {
+			return t
+		}
+	}
+
+	return "application/octet-stream"
+}
diff --git a/pkg/tools/send_file_test.go b/pkg/tools/send_file_test.go
new file mode 100644
index 000000000..f36baf7d0
--- /dev/null
+++ b/pkg/tools/send_file_test.go
@@ -0,0 +1,226 @@
+package tools
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/media"
+)
+
+func TestSendFileTool_MissingPath(t *testing.T) {
+	store := media.NewFileMediaStore()
+	tool := NewSendFileTool("/tmp", false, 0, store)
+	tool.SetContext("feishu", "chat123")
+
+	result := tool.Execute(context.Background(), map[string]any{})
+	if !result.IsError {
+		t.Fatal("expected error for missing path")
+	}
+}
+
+func TestSendFileTool_NoContext(t *testing.T) {
+	store := media.NewFileMediaStore()
+	tool := NewSendFileTool("/tmp", false, 0, store)
+	// no SetContext call
+
+	result := tool.Execute(context.Background(), map[string]any{"path": "/tmp/test.txt"})
+	if !result.IsError {
+		t.Fatal("expected error when no channel context")
+	}
+}
+
+func TestSendFileTool_NoMediaStore(t *testing.T) {
+	tool := NewSendFileTool("/tmp", false, 0, nil)
+	tool.SetContext("feishu", "chat123")
+
+	result := tool.Execute(context.Background(), map[string]any{"path": "/tmp/test.txt"})
+	if !result.IsError {
+		t.Fatal("expected error when no media store")
+	}
+}
+
+func TestSendFileTool_Directory(t *testing.T) {
+	store := media.NewFileMediaStore()
+	tool := NewSendFileTool("/tmp", false, 0, store)
+	tool.SetContext("feishu", "chat123")
+
+	result := tool.Execute(context.Background(), map[string]any{"path": "/tmp"})
+	if !result.IsError {
+		t.Fatal("expected error for directory path")
+	}
+}
+
+func TestSendFileTool_FileTooLarge(t *testing.T) {
+	dir := t.TempDir()
+	testFile := filepath.Join(dir, "big.bin")
+	// Create a file larger than the limit
+	if err := os.WriteFile(testFile, make([]byte, 1024), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	store := media.NewFileMediaStore()
+	tool := NewSendFileTool(dir, false, 512, store) // 512 byte limit
+	tool.SetContext("feishu", "chat123")
+
+	result := tool.Execute(context.Background(), map[string]any{"path": testFile})
+	if !result.IsError {
+		t.Fatal("expected error for oversized file")
+	}
+	if !strings.Contains(result.ForLLM, "too large") {
+		t.Errorf("expected 'too large' in error, got %q", result.ForLLM)
+	}
+}
+
+func TestSendFileTool_DefaultMaxSize(t *testing.T) {
+	tool := NewSendFileTool("/tmp", false, 0, nil)
+	if tool.maxFileSize != config.DefaultMaxMediaSize {
+		t.Errorf("expected default max size %d, got %d", config.DefaultMaxMediaSize, tool.maxFileSize)
+	}
+}
+
+func TestSendFileTool_Success(t *testing.T) {
+	dir := t.TempDir()
+	testFile := filepath.Join(dir, "photo.png")
+	if err := os.WriteFile(testFile, []byte("fake png"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	store := media.NewFileMediaStore()
+	tool := NewSendFileTool(dir, false, 0, store)
+	tool.SetContext("feishu", "chat123")
+
+	result := tool.Execute(context.Background(), map[string]any{"path": testFile})
+	if result.IsError {
+		t.Fatalf("unexpected error: %s", result.ForLLM)
+	}
+	if len(result.Media) != 1 {
+		t.Fatalf("expected 1 media ref, got %d", len(result.Media))
+	}
+	if result.Media[0][:8] != "media://" {
+		t.Errorf("expected media:// ref, got %q", result.Media[0])
+	}
+	if !result.ResponseHandled {
+		t.Fatal("expected send_file success to mark response handled")
+	}
+
+	_, meta, err := store.ResolveWithMeta(result.Media[0])
+	if err != nil {
+		t.Fatalf("ResolveWithMeta failed: %v", err)
+	}
+	if meta.CleanupPolicy != media.CleanupPolicyForgetOnly {
+		t.Errorf("CleanupPolicy = %q, want %q", meta.CleanupPolicy, media.CleanupPolicyForgetOnly)
+	}
+}
+
+func TestSendFileTool_CustomFilename(t *testing.T) {
+	dir := t.TempDir()
+	testFile := filepath.Join(dir, "img.jpg")
+	if err := os.WriteFile(testFile, []byte("fake jpg"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	store := media.NewFileMediaStore()
+	tool := NewSendFileTool(dir, false, 0, store)
+	tool.SetContext("telegram", "chat456")
+
+	result := tool.Execute(context.Background(), map[string]any{
+		"path":     testFile,
+		"filename": "my-photo.jpg",
+	})
+	if result.IsError {
+		t.Fatalf("unexpected error: %s", result.ForLLM)
+	}
+	if len(result.Media) != 1 {
+		t.Fatalf("expected 1 media ref, got %d", len(result.Media))
+	}
+}
+
+func TestSendFileTool_AllowsWhitelistedMediaTempPath(t *testing.T) {
+	workspace := t.TempDir()
+	mediaDir := media.TempDir()
+	if err := os.MkdirAll(mediaDir, 0o700); err != nil {
+		t.Fatalf("MkdirAll(mediaDir) error = %v", err)
+	}
+
+	testFile, err := os.CreateTemp(mediaDir, "send-file-*.txt")
+	if err != nil {
+		t.Fatalf("CreateTemp(mediaDir) error = %v", err)
+	}
+	testPath := testFile.Name()
+	if _, err := testFile.WriteString("forward me"); err != nil {
+		testFile.Close()
+		t.Fatalf("WriteString(testFile) error = %v", err)
+	}
+	if err := testFile.Close(); err != nil {
+		t.Fatalf("Close(testFile) error = %v", err)
+	}
+	t.Cleanup(func() { _ = os.Remove(testPath) })
+
+	pattern := regexp.MustCompile(
+		"^" + regexp.QuoteMeta(filepath.Clean(mediaDir)) + "(?:" + regexp.QuoteMeta(string(os.PathSeparator)) + "|$)",
+	)
+
+	store := media.NewFileMediaStore()
+	tool := NewSendFileTool(workspace, true, 0, store, []*regexp.Regexp{pattern})
+	tool.SetContext("feishu", "chat123")
+
+	result := tool.Execute(context.Background(), map[string]any{"path": testPath})
+	if result.IsError {
+		t.Fatalf("expected whitelisted temp media file to be sendable, got: %s", result.ForLLM)
+	}
+	if len(result.Media) != 1 {
+		t.Fatalf("expected 1 media ref, got %d", len(result.Media))
+	}
+}
+
+func TestDetectMediaType_MagicBytes(t *testing.T) {
+	dir := t.TempDir()
+
+	// Minimal valid PNG header
+	pngHeader := []byte{0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A}
+	pngFile := filepath.Join(dir, "image.dat") // wrong extension, but valid PNG bytes
+	if err := os.WriteFile(pngFile, pngHeader, 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	got := detectMediaType(pngFile)
+	if got != "image/png" {
+		t.Errorf("expected image/png from magic bytes, got %q", got)
+	}
+}
+
+func TestDetectMediaType_FallbackToExtension(t *testing.T) {
+	dir := t.TempDir()
+
+	// File with unrecognizable content but known extension
+	txtFile := filepath.Join(dir, "readme.txt")
+	if err := os.WriteFile(txtFile, []byte("hello world"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	got := detectMediaType(txtFile)
+	// text/plain or similar — just verify it's not application/octet-stream
+	if got == "application/octet-stream" {
+		t.Errorf("expected extension-based MIME for .txt, got %q", got)
+	}
+}
+
+func TestDetectMediaType_UnknownFallsToOctetStream(t *testing.T) {
+	dir := t.TempDir()
+
+	// File with no extension and random bytes
+	unknownFile := filepath.Join(dir, "mystery")
+	if err := os.WriteFile(unknownFile, []byte{0x00, 0x01, 0x02}, 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	got := detectMediaType(unknownFile)
+	if got != "application/octet-stream" {
+		t.Errorf("expected application/octet-stream, got %q", got)
+	}
+}
diff --git a/pkg/tools/shell.go b/pkg/tools/shell.go
index a0c83eb1e..78ad2b26d 100644
--- a/pkg/tools/shell.go
+++ b/pkg/tools/shell.go
@@ -14,6 +14,7 @@ import (
 	"time"
 
 	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/constants"
 )
 
 type ExecTool struct {
@@ -22,7 +23,9 @@ type ExecTool struct {
 	denyPatterns        []*regexp.Regexp
 	allowPatterns       []*regexp.Regexp
 	customAllowPatterns []*regexp.Regexp
+	allowedPathPatterns []*regexp.Regexp
 	restrictToWorkspace bool
+	allowRemote         bool
 }
 
 var (
@@ -59,7 +62,7 @@ var (
 		regexp.MustCompile(`\bchown\b`),
 		regexp.MustCompile(`\bpkill\b`),
 		regexp.MustCompile(`\bkillall\b`),
-		regexp.MustCompile(`\bkill\s+-[9]\b`),
+		regexp.MustCompile(`\bkill\b`),
 		regexp.MustCompile(`\bcurl\b.*\|\s*(sh|bash)`),
 		regexp.MustCompile(`\bwget\b.*\|\s*(sh|bash)`),
 		regexp.MustCompile(`\bnpm\s+install\s+-g\b`),
@@ -93,17 +96,28 @@ var (
 	}
 )
 
-func NewExecTool(workingDir string, restrict bool) (*ExecTool, error) {
-	return NewExecToolWithConfig(workingDir, restrict, nil)
+func NewExecTool(workingDir string, restrict bool, allowPaths ...[]*regexp.Regexp) (*ExecTool, error) {
+	return NewExecToolWithConfig(workingDir, restrict, nil, allowPaths...)
 }
 
-func NewExecToolWithConfig(workingDir string, restrict bool, config *config.Config) (*ExecTool, error) {
+func NewExecToolWithConfig(
+	workingDir string,
+	restrict bool,
+	config *config.Config,
+	allowPaths ...[]*regexp.Regexp,
+) (*ExecTool, error) {
 	denyPatterns := make([]*regexp.Regexp, 0)
 	customAllowPatterns := make([]*regexp.Regexp, 0)
+	var allowedPathPatterns []*regexp.Regexp
+	allowRemote := true
+	if len(allowPaths) > 0 {
+		allowedPathPatterns = allowPaths[0]
+	}
 
 	if config != nil {
 		execConfig := config.Tools.Exec
 		enableDenyPatterns := execConfig.EnableDenyPatterns
+		allowRemote = execConfig.AllowRemote
 		if enableDenyPatterns {
 			denyPatterns = append(denyPatterns, defaultDenyPatterns...)
 			if len(execConfig.CustomDenyPatterns) > 0 {
@@ -131,13 +145,20 @@ func NewExecToolWithConfig(workingDir string, restrict bool, config *config.Conf
 		denyPatterns = append(denyPatterns, defaultDenyPatterns...)
 	}
 
+	timeout := 60 * time.Second
+	if config != nil && config.Tools.Exec.TimeoutSeconds > 0 {
+		timeout = time.Duration(config.Tools.Exec.TimeoutSeconds) * time.Second
+	}
+
 	return &ExecTool{
 		workingDir:          workingDir,
-		timeout:             60 * time.Second,
+		timeout:             timeout,
 		denyPatterns:        denyPatterns,
 		allowPatterns:       nil,
 		customAllowPatterns: customAllowPatterns,
+		allowedPathPatterns: allowedPathPatterns,
 		restrictToWorkspace: restrict,
+		allowRemote:         allowRemote,
 	}, nil
 }
 
@@ -172,10 +193,23 @@ func (t *ExecTool) Execute(ctx context.Context, args map[string]any) *ToolResult
 		return ErrorResult("command is required")
 	}
 
+	// GHSA-pv8c-p6jf-3fpp: block exec from remote channels (e.g. Telegram webhooks)
+	// unless explicitly opted-in via config. Fail-closed: empty channel = blocked.
+	if !t.allowRemote {
+		channel := ToolChannel(ctx)
+		if channel == "" {
+			channel, _ = args["__channel"].(string)
+		}
+		channel = strings.TrimSpace(channel)
+		if channel == "" || !constants.IsInternalChannel(channel) {
+			return ErrorResult("exec is restricted to internal channels")
+		}
+	}
+
 	cwd := t.workingDir
 	if wd, ok := args["working_dir"].(string); ok && wd != "" {
 		if t.restrictToWorkspace && t.workingDir != "" {
-			resolvedWD, err := validatePath(wd, t.workingDir, true)
+			resolvedWD, err := validatePathWithAllowPaths(wd, t.workingDir, true, t.allowedPathPatterns)
 			if err != nil {
 				return ErrorResult("Command blocked by safety guard (" + err.Error() + ")")
 			}
@@ -196,6 +230,29 @@ func (t *ExecTool) Execute(ctx context.Context, args map[string]any) *ToolResult
 		return ErrorResult(guardError)
 	}
 
+	// Re-resolve symlinks immediately before execution to shrink the TOCTOU window
+	// between validation and cmd.Dir assignment.
+	if t.restrictToWorkspace && t.workingDir != "" && cwd != t.workingDir {
+		resolved, err := filepath.EvalSymlinks(cwd)
+		if err != nil {
+			return ErrorResult(fmt.Sprintf("Command blocked by safety guard (path resolution failed: %v)", err))
+		}
+		if isAllowedPath(resolved, t.allowedPathPatterns) {
+			cwd = resolved
+		} else {
+			absWorkspace, _ := filepath.Abs(t.workingDir)
+			wsResolved, _ := filepath.EvalSymlinks(absWorkspace)
+			if wsResolved == "" {
+				wsResolved = absWorkspace
+			}
+			rel, err := filepath.Rel(wsResolved, resolved)
+			if err != nil || !filepath.IsLocal(rel) {
+				return ErrorResult("Command blocked by safety guard (working directory escaped workspace)")
+			}
+			cwd = resolved
+		}
+	}
+
 	// timeout == 0 means no timeout
 	var cmdCtx context.Context
 	var cancel context.CancelFunc
@@ -254,13 +311,30 @@ func (t *ExecTool) Execute(ctx context.Context, args map[string]any) *ToolResult
 	if err != nil {
 		if errors.Is(cmdCtx.Err(), context.DeadlineExceeded) {
 			msg := fmt.Sprintf("Command timed out after %v", t.timeout)
+			if output != "" {
+				msg += "\n\nPartial output before timeout:\n" + output
+			}
 			return &ToolResult{
 				ForLLM:  msg,
 				ForUser: msg,
 				IsError: true,
+				Err:     fmt.Errorf("command timeout: %w", err),
 			}
 		}
-		output += fmt.Sprintf("\nExit code: %v", err)
+
+		// Extract detailed exit information
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) {
+			exitCode := exitErr.ExitCode()
+			output += fmt.Sprintf("\n\n[Command exited with code %d]", exitCode)
+
+			// Add signal information if killed by signal (Unix)
+			if exitCode == -1 {
+				output += " (killed by signal)"
+			}
+		} else {
+			output += fmt.Sprintf("\n\n[Command failed: %v]", err)
+		}
 	}
 
 	if output == "" {
@@ -331,9 +405,37 @@ func (t *ExecTool) guardCommand(command, cwd string) string {
 			return ""
 		}
 
-		matches := absolutePathPattern.FindAllString(cmd, -1)
+		// Web URL schemes whose path components (starting with //) should be exempt
+		// from workspace sandbox checks. file: is intentionally excluded so that
+		// file:// URIs are still validated against the workspace boundary.
+		webSchemes := []string{"http:", "https:", "ftp:", "ftps:", "sftp:", "ssh:", "git:"}
+
+		matchIndices := absolutePathPattern.FindAllStringIndex(cmd, -1)
+
+		for _, loc := range matchIndices {
+			raw := cmd[loc[0]:loc[1]]
+
+			// Skip URL path components that look like they're from web URLs.
+			// When a URL like "https://github.com" is parsed, the regex captures
+			// "//github.com" as a match (the path portion after "https:").
+			// Use the exact match position (loc[0]) so that duplicate //path substrings
+			// in the same command are each evaluated at their own position.
+			if strings.HasPrefix(raw, "//") && loc[0] > 0 {
+				before := cmd[:loc[0]]
+				isWebURL := false
+
+				for _, scheme := range webSchemes {
+					if strings.HasSuffix(before, scheme) {
+						isWebURL = true
+						break
+					}
+				}
+
+				if isWebURL {
+					continue
+				}
+			}
 
-		for _, raw := range matches {
 			p, err := filepath.Abs(raw)
 			if err != nil {
 				continue
@@ -342,6 +444,9 @@ func (t *ExecTool) guardCommand(command, cwd string) string {
 			if safePaths[p] {
 				continue
 			}
+			if isAllowedPath(p, t.allowedPathPatterns) {
+				continue
+			}
 
 			rel, err := filepath.Rel(cwdPath, p)
 			if err != nil {
diff --git a/pkg/tools/shell_test.go b/pkg/tools/shell_test.go
index a6abca8ea..f8f83ea74 100644
--- a/pkg/tools/shell_test.go
+++ b/pkg/tools/shell_test.go
@@ -151,6 +151,26 @@ func TestShellTool_DangerousCommand(t *testing.T) {
 	}
 }
 
+func TestShellTool_DangerousCommand_KillBlocked(t *testing.T) {
+	tool, err := NewExecTool("", false)
+	if err != nil {
+		t.Errorf("unable to configure exec tool: %s", err)
+	}
+
+	ctx := context.Background()
+	args := map[string]any{
+		"command": "kill 12345",
+	}
+
+	result := tool.Execute(ctx, args)
+	if !result.IsError {
+		t.Errorf("Expected kill command to be blocked")
+	}
+	if !strings.Contains(result.ForLLM, "blocked") && !strings.Contains(result.ForUser, "blocked") {
+		t.Errorf("Expected blocked message, got ForLLM: %s, ForUser: %s", result.ForLLM, result.ForUser)
+	}
+}
+
 // TestShellTool_MissingCommand verifies error handling for missing command
 func TestShellTool_MissingCommand(t *testing.T) {
 	tool, err := NewExecTool("", false)
@@ -281,6 +301,85 @@ func TestShellTool_WorkingDir_SymlinkEscape(t *testing.T) {
 	}
 }
 
+// TestShellTool_RemoteChannelBlockedByDefault verifies exec is blocked for remote channels
+func TestShellTool_RemoteChannelBlockedByDefault(t *testing.T) {
+	cfg := &config.Config{}
+	cfg.Tools.Exec.EnableDenyPatterns = true
+	cfg.Tools.Exec.AllowRemote = false
+
+	tool, err := NewExecToolWithConfig("", false, cfg)
+	if err != nil {
+		t.Fatalf("NewExecToolWithConfig() error: %v", err)
+	}
+	ctx := WithToolContext(context.Background(), "telegram", "chat-1")
+	result := tool.Execute(ctx, map[string]any{"command": "echo hi"})
+
+	if !result.IsError {
+		t.Fatal("expected remote-channel exec to be blocked")
+	}
+	if !strings.Contains(result.ForLLM, "restricted to internal channels") {
+		t.Errorf("expected 'restricted to internal channels' message, got: %s", result.ForLLM)
+	}
+}
+
+// TestShellTool_InternalChannelAllowed verifies exec is allowed for internal channels
+func TestShellTool_InternalChannelAllowed(t *testing.T) {
+	cfg := &config.Config{}
+	cfg.Tools.Exec.EnableDenyPatterns = true
+	cfg.Tools.Exec.AllowRemote = false
+
+	tool, err := NewExecToolWithConfig("", false, cfg)
+	if err != nil {
+		t.Fatalf("NewExecToolWithConfig() error: %v", err)
+	}
+	ctx := WithToolContext(context.Background(), "cli", "direct")
+	result := tool.Execute(ctx, map[string]any{"command": "echo hi"})
+
+	if result.IsError {
+		t.Fatalf("expected internal channel exec to succeed, got: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "hi") {
+		t.Errorf("expected output to contain 'hi', got: %s", result.ForLLM)
+	}
+}
+
+// TestShellTool_EmptyChannelBlockedWhenNotAllowRemote verifies fail-closed when no channel context
+func TestShellTool_EmptyChannelBlockedWhenNotAllowRemote(t *testing.T) {
+	cfg := &config.Config{}
+	cfg.Tools.Exec.EnableDenyPatterns = true
+	cfg.Tools.Exec.AllowRemote = false
+
+	tool, err := NewExecToolWithConfig("", false, cfg)
+	if err != nil {
+		t.Fatalf("NewExecToolWithConfig() error: %v", err)
+	}
+	result := tool.Execute(context.Background(), map[string]any{
+		"command": "echo hi",
+	})
+
+	if !result.IsError {
+		t.Fatal("expected exec with empty channel to be blocked when allowRemote=false")
+	}
+}
+
+// TestShellTool_AllowRemoteBypassesChannelCheck verifies allowRemote=true permits any channel
+func TestShellTool_AllowRemoteBypassesChannelCheck(t *testing.T) {
+	cfg := &config.Config{}
+	cfg.Tools.Exec.EnableDenyPatterns = true
+	cfg.Tools.Exec.AllowRemote = true
+
+	tool, err := NewExecToolWithConfig("", false, cfg)
+	if err != nil {
+		t.Fatalf("NewExecToolWithConfig() error: %v", err)
+	}
+	ctx := WithToolContext(context.Background(), "telegram", "chat-1")
+	result := tool.Execute(ctx, map[string]any{"command": "echo hi"})
+
+	if result.IsError {
+		t.Fatalf("expected allowRemote=true to permit remote channel, got: %s", result.ForLLM)
+	}
+}
+
 // TestShellTool_RestrictToWorkspace verifies workspace restriction
 func TestShellTool_RestrictToWorkspace(t *testing.T) {
 	tmpDir := t.TempDir()
@@ -390,6 +489,69 @@ func TestShellTool_SafePathsInWorkspaceRestriction(t *testing.T) {
 	}
 }
 
+// TestShellTool_ExitCodeDetails verifies that exit codes are captured with details
+func TestShellTool_ExitCodeDetails(t *testing.T) {
+	tool, err := NewExecTool("", false)
+	if err != nil {
+		t.Fatalf("unable to configure exec tool: %s", err)
+	}
+
+	ctx := context.Background()
+	args := map[string]any{
+		"command": "sh -c 'exit 42'",
+	}
+
+	result := tool.Execute(ctx, args)
+
+	if !result.IsError {
+		t.Error("expected error for non-zero exit code")
+	}
+
+	// Should contain the exit code in the message (new format: "exited with code 42")
+	if !strings.Contains(result.ForLLM, "42") {
+		t.Errorf("expected exit code 42 in error message, got: %s", result.ForLLM)
+	}
+
+	// Verify the new detailed message format
+	if !strings.Contains(result.ForLLM, "exited with code") {
+		t.Errorf("expected 'exited with code' in message, got: %s", result.ForLLM)
+	}
+
+	// Err field is set by the exec system (may or may not be set depending on implementation)
+	// The important thing is that IsError=true
+	t.Logf("Exit code result: %s", result.ForLLM)
+}
+
+// TestShellTool_TimeoutWithPartialOutput verifies timeout includes partial output
+func TestShellTool_TimeoutWithPartialOutput(t *testing.T) {
+	tool, err := NewExecTool("", false)
+	if err != nil {
+		t.Fatalf("unable to configure exec tool: %s", err)
+	}
+
+	tool.SetTimeout(1 * time.Second) // Give more time for echo to complete
+
+	ctx := context.Background()
+	// Use a command that outputs immediately then sleeps
+	args := map[string]any{
+		"command": "echo 'partial output before timeout' && sleep 30",
+	}
+
+	result := tool.Execute(ctx, args)
+
+	if !result.IsError {
+		t.Error("expected error for timeout")
+	}
+
+	// Should mention timeout
+	if !strings.Contains(result.ForLLM, "timed out") {
+		t.Errorf("expected 'timed out' in message, got: %s", result.ForLLM)
+	}
+
+	// Log the result for debugging (partial output depends on shell behavior)
+	t.Logf("Timeout result: %s", result.ForLLM)
+}
+
 // TestShellTool_CustomAllowPatterns verifies that custom allow patterns exempt
 // commands from deny pattern checks.
 func TestShellTool_CustomAllowPatterns(t *testing.T) {
@@ -423,3 +585,101 @@ func TestShellTool_CustomAllowPatterns(t *testing.T) {
 		t.Errorf("'git push upstream main' should still be blocked by deny pattern")
 	}
 }
+
+// TestShellTool_URLsNotBlocked verifies that commands containing URLs are not
+// incorrectly blocked by the workspace restriction safety guard (issue #1203).
+func TestShellTool_URLsNotBlocked(t *testing.T) {
+	tmpDir := t.TempDir()
+	tool, err := NewExecTool(tmpDir, true)
+	if err != nil {
+		t.Fatalf("unable to configure exec tool: %s", err)
+	}
+
+	// These commands contain URLs and should NOT be blocked by workspace restriction.
+	// The URL path components (e.g., "//github.com") should be recognized as URLs,
+	// not as file system paths.
+	commands := []string{
+		"agent-browser open https://github.com",
+		"curl https://api.example.com/data",
+		"wget http://example.com/file",
+		"browser open https://github.com/user/repo",
+		"fetch ftp://ftp.example.com/file.txt",
+		"git clone https://github.com/sipeed/picoclaw.git",
+	}
+
+	for _, cmd := range commands {
+		result := tool.Execute(context.Background(), map[string]any{"command": cmd})
+		if result.IsError && strings.Contains(result.ForLLM, "path outside working dir") {
+			t.Errorf("command with URL should not be blocked by workspace check: %s\n  error: %s", cmd, result.ForLLM)
+		}
+	}
+}
+
+// TestShellTool_FileURISandboxing verifies that file:// URIs that escape the
+// workspace are still blocked, even though other URLs are allowed (issue #1254).
+func TestShellTool_FileURISandboxing(t *testing.T) {
+	tmpDir := t.TempDir()
+	tool, err := NewExecTool(tmpDir, true)
+	if err != nil {
+		t.Fatalf("unable to configure exec tool: %s", err)
+	}
+
+	// These file:// URIs should be blocked if they reference paths outside the workspace.
+	// Unlike web URLs (http://, https://, ftp://), file:// URIs can be used to escape the sandbox.
+	blockedCommands := []string{
+		"cat file:///etc/passwd",
+		"cat file:///etc/hosts",
+		"cat file:///root/.ssh/id_rsa",
+	}
+
+	for _, cmd := range blockedCommands {
+		result := tool.Execute(context.Background(), map[string]any{"command": cmd})
+		if !result.IsError || !strings.Contains(result.ForLLM, "path outside working dir") {
+			t.Errorf("file:// URI outside workspace should be blocked: %s", cmd)
+		}
+	}
+
+	// These file:// URIs should be allowed if they reference paths inside the workspace.
+	// Create a test file inside the temp directory
+	testFile := filepath.Join(tmpDir, "test.txt")
+	if err := os.WriteFile(testFile, []byte("test content"), 0o644); err != nil {
+		t.Fatalf("failed to create test file: %s", err)
+	}
+
+	allowedCommands := []string{
+		"cat file://" + testFile,
+	}
+
+	for _, cmd := range allowedCommands {
+		result := tool.Execute(context.Background(), map[string]any{"command": cmd})
+		if result.IsError && strings.Contains(result.ForLLM, "path outside working dir") {
+			t.Errorf("file:// URI inside workspace should be allowed: %s\n  error: %s", cmd, result.ForLLM)
+		}
+	}
+}
+
+// TestShellTool_URLBypassPrevented verifies that a command cannot bypass the workspace
+// sandbox by smuggling a real path after a URL that contains the same //path substring.
+// e.g. "echo https://etc/passwd && cat //etc/passwd" must still be blocked.
+func TestShellTool_URLBypassPrevented(t *testing.T) {
+	tmpDir := t.TempDir()
+	tool, err := NewExecTool(tmpDir, true)
+	if err != nil {
+		t.Fatalf("unable to configure exec tool: %s", err)
+	}
+
+	// The path //etc/passwd appears twice: once as the host part of an https URL
+	// and once as a real (escaped) absolute path. The guard must block the command
+	// because the second occurrence is a genuine out-of-workspace path.
+	blockedCommands := []string{
+		"echo https://etc/passwd && cat //etc/passwd",
+		"curl https://host/file && ls //etc",
+	}
+
+	for _, cmd := range blockedCommands {
+		result := tool.Execute(context.Background(), map[string]any{"command": cmd})
+		if !result.IsError || !strings.Contains(result.ForLLM, "path outside working dir") {
+			t.Errorf("bypass attempt should be blocked: %q\n  got: %s", cmd, result.ForLLM)
+		}
+	}
+}
diff --git a/pkg/tools/spawn.go b/pkg/tools/spawn.go
index 8b166b41f..d019d511a 100644
--- a/pkg/tools/spawn.go
+++ b/pkg/tools/spawn.go
@@ -7,24 +7,30 @@ import (
 )
 
 type SpawnTool struct {
-	manager        *SubagentManager
-	originChannel  string
-	originChatID   string
+	spawner        SubTurnSpawner
+	defaultModel   string
+	maxTokens      int
+	temperature    float64
 	allowlistCheck func(targetAgentID string) bool
-	callback       AsyncCallback // For async completion notification
 }
 
+// Compile-time check: SpawnTool implements AsyncExecutor.
+var _ AsyncExecutor = (*SpawnTool)(nil)
+
 func NewSpawnTool(manager *SubagentManager) *SpawnTool {
+	if manager == nil {
+		return &SpawnTool{}
+	}
 	return &SpawnTool{
-		manager:       manager,
-		originChannel: "cli",
-		originChatID:  "direct",
+		defaultModel: manager.defaultModel,
+		maxTokens:    manager.maxTokens,
+		temperature:  manager.temperature,
 	}
 }
 
-// SetCallback implements AsyncTool interface for async completion notification
-func (t *SpawnTool) SetCallback(cb AsyncCallback) {
-	t.callback = cb
+// SetSpawner sets the SubTurnSpawner for direct sub-turn execution.
+func (t *SpawnTool) SetSpawner(spawner SubTurnSpawner) {
+	t.spawner = spawner
 }
 
 func (t *SpawnTool) Name() string {
@@ -56,16 +62,29 @@ func (t *SpawnTool) Parameters() map[string]any {
 	}
 }
 
-func (t *SpawnTool) SetContext(channel, chatID string) {
-	t.originChannel = channel
-	t.originChatID = chatID
-}
-
 func (t *SpawnTool) SetAllowlistChecker(check func(targetAgentID string) bool) {
 	t.allowlistCheck = check
 }
 
 func (t *SpawnTool) Execute(ctx context.Context, args map[string]any) *ToolResult {
+	return t.execute(ctx, args, nil)
+}
+
+// ExecuteAsync implements AsyncExecutor. The callback is passed through to the
+// subagent manager as a call parameter — never stored on the SpawnTool instance.
+func (t *SpawnTool) ExecuteAsync(
+	ctx context.Context,
+	args map[string]any,
+	cb AsyncCallback,
+) *ToolResult {
+	return t.execute(ctx, args, cb)
+}
+
+func (t *SpawnTool) execute(
+	ctx context.Context,
+	args map[string]any,
+	cb AsyncCallback,
+) *ToolResult {
 	task, ok := args["task"].(string)
 	if !ok || strings.TrimSpace(task) == "" {
 		return ErrorResult("task is required and must be a non-empty string")
@@ -81,16 +100,53 @@ func (t *SpawnTool) Execute(ctx context.Context, args map[string]any) *ToolResul
 		}
 	}
 
-	if t.manager == nil {
-		return ErrorResult("Subagent manager not configured")
+	// Build system prompt for spawned subagent
+	systemPrompt := fmt.Sprintf(
+		`You are a spawned subagent running in the background. Complete the given task independently and report back when done.
+
+Task: %s`,
+		task,
+	)
+
+	if label != "" {
+		systemPrompt = fmt.Sprintf(
+			`You are a spawned subagent labeled "%s" running in the background. Complete the given task independently and report back when done.
+
+Task: %s`,
+			label,
+			task,
+		)
 	}
 
-	// Pass callback to manager for async completion notification
-	result, err := t.manager.Spawn(ctx, task, label, agentID, t.originChannel, t.originChatID, t.callback)
-	if err != nil {
-		return ErrorResult(fmt.Sprintf("failed to spawn subagent: %v", err))
+	// Use spawner if available (direct SpawnSubTurn call)
+	if t.spawner != nil {
+		// Launch async sub-turn in goroutine
+		go func() {
+			result, err := t.spawner.SpawnSubTurn(ctx, SubTurnConfig{
+				Model:        t.defaultModel,
+				Tools:        nil, // Will inherit from parent via context
+				SystemPrompt: systemPrompt,
+				MaxTokens:    t.maxTokens,
+				Temperature:  t.temperature,
+				Async:        true, // Async execution
+			})
+			if err != nil {
+				result = ErrorResult(fmt.Sprintf("Spawn failed: %v", err)).WithError(err)
+			}
+
+			// Call callback if provided
+			if cb != nil {
+				cb(ctx, result)
+			}
+		}()
+
+		// Return immediate acknowledgment
+		if label != "" {
+			return AsyncResult(fmt.Sprintf("Spawned subagent '%s' for task: %s", label, task))
+		}
+		return AsyncResult(fmt.Sprintf("Spawned subagent for task: %s", task))
 	}
 
-	// Return AsyncResult since the task runs in background
-	return AsyncResult(result)
+	// Fallback: spawner not configured
+	return ErrorResult("Subagent manager not configured")
 }
diff --git a/pkg/tools/spawn_status.go b/pkg/tools/spawn_status.go
new file mode 100644
index 000000000..416fd2226
--- /dev/null
+++ b/pkg/tools/spawn_status.go
@@ -0,0 +1,178 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+)
+
+// SpawnStatusTool reports the status of subagents that were spawned via the
+// spawn tool. It can query a specific task by ID, or list every known task with
+// a summary count broken-down by status.
+type SpawnStatusTool struct {
+	manager *SubagentManager
+}
+
+// NewSpawnStatusTool creates a SpawnStatusTool backed by the given manager.
+func NewSpawnStatusTool(manager *SubagentManager) *SpawnStatusTool {
+	return &SpawnStatusTool{manager: manager}
+}
+
+func (t *SpawnStatusTool) Name() string {
+	return "spawn_status"
+}
+
+func (t *SpawnStatusTool) Description() string {
+	return "Get the status of spawned subagents. " +
+		"Returns a list of all subagents and their current state " +
+		"(running, completed, failed, or canceled), or retrieves details " +
+		"for a specific subagent task when task_id is provided. " +
+		"Results are scoped to the current conversation's channel and chat ID; " +
+		"all tasks are listed only when no channel/chat context is injected " +
+		"(e.g. direct programmatic calls via Execute)."
+}
+
+func (t *SpawnStatusTool) Parameters() map[string]any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"task_id": map[string]any{
+				"type": "string",
+				"description": "Optional task ID (e.g. \"subagent-1\") to inspect a specific " +
+					"subagent. When omitted, all visible subagents are listed.",
+			},
+		},
+		"required": []string{},
+	}
+}
+
+func (t *SpawnStatusTool) Execute(ctx context.Context, args map[string]any) *ToolResult {
+	if t.manager == nil {
+		return ErrorResult("Subagent manager not configured")
+	}
+
+	// Derive the calling conversation's identity so we can scope results to the
+	// current chat only — preventing cross-conversation task leakage in
+	// multi-user deployments.
+	callerChannel := ToolChannel(ctx)
+	callerChatID := ToolChatID(ctx)
+
+	var taskID string
+	if rawTaskID, ok := args["task_id"]; ok && rawTaskID != nil {
+		taskIDStr, ok := rawTaskID.(string)
+		if !ok {
+			return ErrorResult("task_id must be a string")
+		}
+		taskID = strings.TrimSpace(taskIDStr)
+	}
+
+	if taskID != "" {
+		// GetTaskCopy returns a consistent snapshot under the manager lock,
+		// eliminating any data race with the concurrent subagent goroutine.
+		taskCopy, ok := t.manager.GetTaskCopy(taskID)
+		if !ok {
+			return ErrorResult(fmt.Sprintf("No subagent found with task ID: %s", taskID))
+		}
+
+		// Restrict lookup to tasks that belong to this conversation.
+		if callerChannel != "" && taskCopy.OriginChannel != "" && taskCopy.OriginChannel != callerChannel {
+			return ErrorResult(fmt.Sprintf("No subagent found with task ID: %s", taskID))
+		}
+		if callerChatID != "" && taskCopy.OriginChatID != "" && taskCopy.OriginChatID != callerChatID {
+			return ErrorResult(fmt.Sprintf("No subagent found with task ID: %s", taskID))
+		}
+
+		return NewToolResult(spawnStatusFormatTask(&taskCopy))
+	}
+
+	// ListTaskCopies returns consistent snapshots under the manager lock.
+	origTasks := t.manager.ListTaskCopies()
+	if len(origTasks) == 0 {
+		return NewToolResult("No subagents have been spawned yet.")
+	}
+
+	tasks := make([]*SubagentTask, 0, len(origTasks))
+	for i := range origTasks {
+		cpy := &origTasks[i]
+
+		// Filter to tasks that originate from the current conversation only.
+		if callerChannel != "" && cpy.OriginChannel != "" && cpy.OriginChannel != callerChannel {
+			continue
+		}
+		if callerChatID != "" && cpy.OriginChatID != "" && cpy.OriginChatID != callerChatID {
+			continue
+		}
+
+		tasks = append(tasks, cpy)
+	}
+
+	if len(tasks) == 0 {
+		return NewToolResult("No subagents found for this conversation.")
+	}
+
+	// Order by creation time (ascending) so spawning order is preserved.
+	// Fall back to ID string for tasks created in the same millisecond.
+	sort.Slice(tasks, func(i, j int) bool {
+		if tasks[i].Created != tasks[j].Created {
+			return tasks[i].Created < tasks[j].Created
+		}
+		return tasks[i].ID < tasks[j].ID
+	})
+
+	counts := map[string]int{}
+	for _, task := range tasks {
+		counts[task.Status]++
+	}
+
+	var sb strings.Builder
+	sb.WriteString(fmt.Sprintf("Subagent status report (%d total):\n", len(tasks)))
+	for _, status := range []string{"running", "completed", "failed", "canceled"} {
+		if n := counts[status]; n > 0 {
+			label := strings.ToUpper(status[:1]) + status[1:] + ":"
+			sb.WriteString(fmt.Sprintf("  %-10s %d\n", label, n))
+		}
+	}
+	sb.WriteString("\n")
+
+	for _, task := range tasks {
+		sb.WriteString(spawnStatusFormatTask(task))
+		sb.WriteString("\n\n")
+	}
+
+	return NewToolResult(strings.TrimRight(sb.String(), "\n"))
+}
+
+// spawnStatusFormatTask renders a single SubagentTask as a human-readable block.
+func spawnStatusFormatTask(task *SubagentTask) string {
+	var sb strings.Builder
+
+	header := fmt.Sprintf("[%s] status=%s", task.ID, task.Status)
+	if task.Label != "" {
+		header += fmt.Sprintf("  label=%q", task.Label)
+	}
+	if task.AgentID != "" {
+		header += fmt.Sprintf("  agent=%s", task.AgentID)
+	}
+	if task.Created > 0 {
+		created := time.UnixMilli(task.Created).UTC().Format("2006-01-02 15:04:05 UTC")
+		header += fmt.Sprintf("  created=%s", created)
+	}
+	sb.WriteString(header)
+
+	if task.Task != "" {
+		sb.WriteString(fmt.Sprintf("\n  task:   %s", task.Task))
+	}
+	if task.Result != "" {
+		result := task.Result
+		const maxResultLen = 300
+		runes := []rune(result)
+		if len(runes) > maxResultLen {
+			result = string(runes[:maxResultLen]) + "…"
+		}
+		sb.WriteString(fmt.Sprintf("\n  result: %s", result))
+	}
+
+	return sb.String()
+}
diff --git a/pkg/tools/spawn_status_test.go b/pkg/tools/spawn_status_test.go
new file mode 100644
index 000000000..9c772d61a
--- /dev/null
+++ b/pkg/tools/spawn_status_test.go
@@ -0,0 +1,406 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestSpawnStatusTool_Name(t *testing.T) {
+	provider := &MockLLMProvider{}
+	workspace := t.TempDir()
+	manager := NewSubagentManager(provider, "test-model", workspace)
+	tool := NewSpawnStatusTool(manager)
+
+	if tool.Name() != "spawn_status" {
+		t.Errorf("Expected name 'spawn_status', got '%s'", tool.Name())
+	}
+}
+
+func TestSpawnStatusTool_Description(t *testing.T) {
+	provider := &MockLLMProvider{}
+	workspace := t.TempDir()
+	manager := NewSubagentManager(provider, "test-model", workspace)
+	tool := NewSpawnStatusTool(manager)
+
+	desc := tool.Description()
+	if desc == "" {
+		t.Error("Description should not be empty")
+	}
+	if !strings.Contains(strings.ToLower(desc), "subagent") {
+		t.Errorf("Description should mention 'subagent', got: %s", desc)
+	}
+}
+
+func TestSpawnStatusTool_Parameters(t *testing.T) {
+	provider := &MockLLMProvider{}
+	workspace := t.TempDir()
+	manager := NewSubagentManager(provider, "test-model", workspace)
+	tool := NewSpawnStatusTool(manager)
+
+	params := tool.Parameters()
+	if params["type"] != "object" {
+		t.Errorf("Expected type 'object', got: %v", params["type"])
+	}
+	props, ok := params["properties"].(map[string]any)
+	if !ok {
+		t.Fatal("Expected 'properties' to be a map")
+	}
+	if _, hasTaskID := props["task_id"]; !hasTaskID {
+		t.Error("Expected 'task_id' parameter in properties")
+	}
+}
+
+func TestSpawnStatusTool_NilManager(t *testing.T) {
+	tool := &SpawnStatusTool{manager: nil}
+	result := tool.Execute(context.Background(), map[string]any{})
+	if !result.IsError {
+		t.Error("Expected error result when manager is nil")
+	}
+}
+
+func TestSpawnStatusTool_Empty(t *testing.T) {
+	provider := &MockLLMProvider{}
+	workspace := t.TempDir()
+	manager := NewSubagentManager(provider, "test-model", workspace)
+	tool := NewSpawnStatusTool(manager)
+
+	result := tool.Execute(context.Background(), map[string]any{})
+	if result.IsError {
+		t.Fatalf("Expected success, got error: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "No subagents") {
+		t.Errorf("Expected 'No subagents' message, got: %s", result.ForLLM)
+	}
+}
+
+func TestSpawnStatusTool_ListAll(t *testing.T) {
+	provider := &MockLLMProvider{}
+	workspace := t.TempDir()
+	manager := NewSubagentManager(provider, "test-model", workspace)
+
+	now := time.Now().UnixMilli()
+	manager.mu.Lock()
+	manager.tasks["subagent-1"] = &SubagentTask{
+		ID:      "subagent-1",
+		Task:    "Do task A",
+		Label:   "task-a",
+		Status:  "running",
+		Created: now,
+	}
+	manager.tasks["subagent-2"] = &SubagentTask{
+		ID:      "subagent-2",
+		Task:    "Do task B",
+		Label:   "task-b",
+		Status:  "completed",
+		Result:  "Done successfully",
+		Created: now,
+	}
+	manager.tasks["subagent-3"] = &SubagentTask{
+		ID:     "subagent-3",
+		Task:   "Do task C",
+		Status: "failed",
+		Result: "Error: something went wrong",
+	}
+	manager.mu.Unlock()
+
+	tool := NewSpawnStatusTool(manager)
+	result := tool.Execute(context.Background(), map[string]any{})
+
+	if result.IsError {
+		t.Fatalf("Expected success, got error: %s", result.ForLLM)
+	}
+
+	// Summary header
+	if !strings.Contains(result.ForLLM, "3 total") {
+		t.Errorf("Expected total count in header, got: %s", result.ForLLM)
+	}
+
+	// Individual task IDs
+	for _, id := range []string{"subagent-1", "subagent-2", "subagent-3"} {
+		if !strings.Contains(result.ForLLM, id) {
+			t.Errorf("Expected task %s in output, got:\n%s", id, result.ForLLM)
+		}
+	}
+
+	// Status values
+	for _, status := range []string{"running", "completed", "failed"} {
+		if !strings.Contains(result.ForLLM, status) {
+			t.Errorf("Expected status '%s' in output, got:\n%s", status, result.ForLLM)
+		}
+	}
+
+	// Result content
+	if !strings.Contains(result.ForLLM, "Done successfully") {
+		t.Errorf("Expected result text in output, got:\n%s", result.ForLLM)
+	}
+}
+
+func TestSpawnStatusTool_GetByID(t *testing.T) {
+	provider := &MockLLMProvider{}
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
+
+	manager.mu.Lock()
+	manager.tasks["subagent-42"] = &SubagentTask{
+		ID:      "subagent-42",
+		Task:    "Specific task",
+		Label:   "my-task",
+		Status:  "failed",
+		Result:  "Something went wrong",
+		Created: time.Now().UnixMilli(),
+	}
+	manager.mu.Unlock()
+
+	tool := NewSpawnStatusTool(manager)
+	result := tool.Execute(context.Background(), map[string]any{"task_id": "subagent-42"})
+
+	if result.IsError {
+		t.Fatalf("Expected success, got error: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "subagent-42") {
+		t.Errorf("Expected task ID in output, got: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "failed") {
+		t.Errorf("Expected status 'failed' in output, got: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "Something went wrong") {
+		t.Errorf("Expected result text in output, got: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "my-task") {
+		t.Errorf("Expected label in output, got: %s", result.ForLLM)
+	}
+}
+
+func TestSpawnStatusTool_GetByID_NotFound(t *testing.T) {
+	provider := &MockLLMProvider{}
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
+	tool := NewSpawnStatusTool(manager)
+
+	result := tool.Execute(context.Background(), map[string]any{"task_id": "nonexistent-999"})
+	if !result.IsError {
+		t.Errorf("Expected error for nonexistent task, got: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "nonexistent-999") {
+		t.Errorf("Expected task ID in error message, got: %s", result.ForLLM)
+	}
+}
+
+func TestSpawnStatusTool_TaskID_NonString(t *testing.T) {
+	provider := &MockLLMProvider{}
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
+	tool := NewSpawnStatusTool(manager)
+
+	for _, badVal := range []any{42, 3.14, true, map[string]any{"x": 1}, []string{"a"}} {
+		result := tool.Execute(context.Background(), map[string]any{"task_id": badVal})
+		if !result.IsError {
+			t.Errorf("Expected error for task_id=%T(%v), got success: %s", badVal, badVal, result.ForLLM)
+		}
+		if !strings.Contains(result.ForLLM, "task_id must be a string") {
+			t.Errorf("Expected type-error message, got: %s", result.ForLLM)
+		}
+	}
+}
+
+func TestSpawnStatusTool_ResultTruncation(t *testing.T) {
+	provider := &MockLLMProvider{}
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
+
+	longResult := strings.Repeat("X", 500)
+	manager.mu.Lock()
+	manager.tasks["subagent-1"] = &SubagentTask{
+		ID:     "subagent-1",
+		Task:   "Long task",
+		Status: "completed",
+		Result: longResult,
+	}
+	manager.mu.Unlock()
+
+	tool := NewSpawnStatusTool(manager)
+	result := tool.Execute(context.Background(), map[string]any{"task_id": "subagent-1"})
+
+	if result.IsError {
+		t.Fatalf("Unexpected error: %s", result.ForLLM)
+	}
+	// Output should be shorter than the raw result due to truncation
+	if len(result.ForLLM) >= len(longResult) {
+		t.Errorf("Expected result to be truncated, but ForLLM is %d chars", len(result.ForLLM))
+	}
+	if !strings.Contains(result.ForLLM, "…") {
+		t.Errorf("Expected truncation indicator '…' in output, got: %s", result.ForLLM)
+	}
+}
+
+func TestSpawnStatusTool_ResultTruncation_Unicode(t *testing.T) {
+	provider := &MockLLMProvider{}
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
+
+	// Each CJK rune is 3 bytes; 400 runes = 1200 bytes — well over the 300-rune limit.
+	cjkChar := string(rune(0x5b57))
+	longResult := strings.Repeat(cjkChar, 400)
+	manager.mu.Lock()
+	manager.tasks["subagent-1"] = &SubagentTask{
+		ID:     "subagent-1",
+		Task:   "Unicode task",
+		Status: "completed",
+		Result: longResult,
+	}
+	manager.mu.Unlock()
+
+	tool := NewSpawnStatusTool(manager)
+	result := tool.Execute(context.Background(), map[string]any{"task_id": "subagent-1"})
+
+	if result.IsError {
+		t.Fatalf("Unexpected error: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "…") {
+		t.Errorf("Expected truncation indicator in output")
+	}
+	// The truncated result must be valid UTF-8 (no split rune boundaries).
+	if !strings.Contains(result.ForLLM, cjkChar) {
+		t.Errorf("Expected CJK runes to appear intact in output")
+	}
+}
+
+func TestSpawnStatusTool_StatusCounts(t *testing.T) {
+	provider := &MockLLMProvider{}
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
+
+	manager.mu.Lock()
+	for i, status := range []string{"running", "running", "completed", "failed", "canceled"} {
+		id := fmt.Sprintf("subagent-%d", i+1)
+		manager.tasks[id] = &SubagentTask{ID: id, Task: "t", Status: status}
+	}
+	manager.mu.Unlock()
+
+	tool := NewSpawnStatusTool(manager)
+	result := tool.Execute(context.Background(), map[string]any{})
+
+	if result.IsError {
+		t.Fatalf("Unexpected error: %s", result.ForLLM)
+	}
+	// The summary line should mention all statuses that have counts
+	for _, want := range []string{"Running:", "Completed:", "Failed:", "Canceled:"} {
+		if !strings.Contains(result.ForLLM, want) {
+			t.Errorf("Expected %q in summary, got:\n%s", want, result.ForLLM)
+		}
+	}
+}
+
+func TestSpawnStatusTool_SortByCreatedTimestamp(t *testing.T) {
+	provider := &MockLLMProvider{}
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
+
+	now := time.Now().UnixMilli()
+	manager.mu.Lock()
+	// Intentionally insert with out-of-order IDs and timestamps that reflect
+	// true spawn order: subagent-2 was spawned first, subagent-10 second.
+	manager.tasks["subagent-10"] = &SubagentTask{
+		ID: "subagent-10", Task: "second", Status: "running",
+		Created: now + 1,
+	}
+	manager.tasks["subagent-2"] = &SubagentTask{
+		ID: "subagent-2", Task: "first", Status: "running",
+		Created: now,
+	}
+	manager.mu.Unlock()
+
+	tool := NewSpawnStatusTool(manager)
+	result := tool.Execute(context.Background(), map[string]any{})
+
+	if result.IsError {
+		t.Fatalf("Unexpected error: %s", result.ForLLM)
+	}
+
+	pos2 := strings.Index(result.ForLLM, "subagent-2")
+	pos10 := strings.Index(result.ForLLM, "subagent-10")
+	if pos2 < 0 || pos10 < 0 {
+		t.Fatalf("Both task IDs should appear in output:\n%s", result.ForLLM)
+	}
+	if pos2 > pos10 {
+		t.Errorf("Expected subagent-2 (created first) to appear before subagent-10, but got:\n%s", result.ForLLM)
+	}
+}
+
+func TestSpawnStatusTool_ChannelFiltering_ListAll(t *testing.T) {
+	provider := &MockLLMProvider{}
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
+
+	manager.mu.Lock()
+	manager.tasks["subagent-1"] = &SubagentTask{
+		ID: "subagent-1", Task: "mine", Status: "running",
+		OriginChannel: "telegram", OriginChatID: "chat-A",
+	}
+	manager.tasks["subagent-2"] = &SubagentTask{
+		ID: "subagent-2", Task: "other user", Status: "running",
+		OriginChannel: "telegram", OriginChatID: "chat-B",
+	}
+	manager.mu.Unlock()
+
+	tool := NewSpawnStatusTool(manager)
+
+	// Caller is chat-A — should only see subagent-1.
+	ctx := WithToolContext(context.Background(), "telegram", "chat-A")
+	result := tool.Execute(ctx, map[string]any{})
+
+	if result.IsError {
+		t.Fatalf("Unexpected error: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "subagent-1") {
+		t.Errorf("Expected own task in output, got:\n%s", result.ForLLM)
+	}
+	if strings.Contains(result.ForLLM, "subagent-2") {
+		t.Errorf("Should NOT see other chat's task, got:\n%s", result.ForLLM)
+	}
+}
+
+func TestSpawnStatusTool_ChannelFiltering_GetByID(t *testing.T) {
+	provider := &MockLLMProvider{}
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
+
+	manager.mu.Lock()
+	manager.tasks["subagent-99"] = &SubagentTask{
+		ID: "subagent-99", Task: "secret", Status: "completed", Result: "private data",
+		OriginChannel: "slack", OriginChatID: "room-Z",
+	}
+	manager.mu.Unlock()
+
+	tool := NewSpawnStatusTool(manager)
+
+	// Different chat trying to look up subagent-99 by ID.
+	ctx := WithToolContext(context.Background(), "slack", "room-OTHER")
+	result := tool.Execute(ctx, map[string]any{"task_id": "subagent-99"})
+
+	if !result.IsError {
+		t.Errorf("Expected error (cross-chat lookup blocked), got: %s", result.ForLLM)
+	}
+}
+
+func TestSpawnStatusTool_ChannelFiltering_NoContext(t *testing.T) {
+	provider := &MockLLMProvider{}
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
+
+	manager.mu.Lock()
+	manager.tasks["subagent-1"] = &SubagentTask{
+		ID: "subagent-1", Task: "t", Status: "completed",
+		OriginChannel: "telegram", OriginChatID: "chat-A",
+	}
+	manager.mu.Unlock()
+
+	tool := NewSpawnStatusTool(manager)
+
+	// No ToolContext injected (e.g. a direct programmatic call that bypasses
+	// WithToolContext entirely) — callerChannel and callerChatID are both "".
+	// Note: the normal CLI path uses ProcessDirectWithChannel("cli", "direct"),
+	// which *does* inject a non-empty context; this test covers the case where
+	// no context injection happens at all.
+	// The filter conditions require a non-empty caller value, so all tasks pass through.
+	result := tool.Execute(context.Background(), map[string]any{})
+	if result.IsError {
+		t.Fatalf("Unexpected error: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "subagent-1") {
+		t.Errorf("Expected task visible from no-context caller, got:\n%s", result.ForLLM)
+	}
+}
diff --git a/pkg/tools/spawn_test.go b/pkg/tools/spawn_test.go
index 0646c82a9..fda6bbd89 100644
--- a/pkg/tools/spawn_test.go
+++ b/pkg/tools/spawn_test.go
@@ -6,9 +6,27 @@ import (
 	"testing"
 )
 
+// mockSpawner implements SubTurnSpawner for testing
+type mockSpawner struct{}
+
+func (m *mockSpawner) SpawnSubTurn(ctx context.Context, cfg SubTurnConfig) (*ToolResult, error) {
+	// Extract task from system prompt for response
+	task := cfg.SystemPrompt
+	if strings.Contains(task, "Task: ") {
+		parts := strings.Split(task, "Task: ")
+		if len(parts) > 1 {
+			task = parts[1]
+		}
+	}
+	return &ToolResult{
+		ForLLM:  "Task completed: " + task,
+		ForUser: "Task completed",
+	}, nil
+}
+
 func TestSpawnTool_Execute_EmptyTask(t *testing.T) {
 	provider := &MockLLMProvider{}
-	manager := NewSubagentManager(provider, "test-model", "/tmp/test", nil)
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
 	tool := NewSpawnTool(manager)
 
 	ctx := context.Background()
@@ -42,8 +60,9 @@ func TestSpawnTool_Execute_EmptyTask(t *testing.T) {
 
 func TestSpawnTool_Execute_ValidTask(t *testing.T) {
 	provider := &MockLLMProvider{}
-	manager := NewSubagentManager(provider, "test-model", "/tmp/test", nil)
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
 	tool := NewSpawnTool(manager)
+	tool.SetSpawner(&mockSpawner{})
 
 	ctx := context.Background()
 	args := map[string]any{
diff --git a/pkg/tools/subagent.go b/pkg/tools/subagent.go
index 69f1a49a2..9a1a8b802 100644
--- a/pkg/tools/subagent.go
+++ b/pkg/tools/subagent.go
@@ -4,12 +4,34 @@ import (
 	"context"
 	"fmt"
 	"sync"
+	"sync/atomic"
 	"time"
 
-	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
+// SubTurnSpawner is an interface for spawning sub-turns.
+// This avoids circular dependency between tools and agent packages.
+type SubTurnSpawner interface {
+	SpawnSubTurn(ctx context.Context, cfg SubTurnConfig) (*ToolResult, error)
+}
+
+// SubTurnConfig holds configuration for spawning a sub-turn.
+type SubTurnConfig struct {
+	Model              string
+	Tools              []Tool
+	SystemPrompt       string
+	MaxTokens          int
+	Temperature        float64
+	Async              bool          // true for async (spawn), false for sync (subagent)
+	Critical           bool          // continue running after parent finishes gracefully
+	Timeout            time.Duration // 0 = use default (5 minutes)
+	MaxContextRunes    int           // 0 = auto, -1 = no limit, >0 = explicit limit
+	ActualSystemPrompt string
+	InitialMessages    []providers.Message
+	InitialTokenBudget *atomic.Int64 // Shared token budget for team members; nil if no budget
+}
+
 type SubagentTask struct {
 	ID            string
 	Task          string
@@ -22,12 +44,20 @@ type SubagentTask struct {
 	Created       int64
 }
 
+type SpawnSubTurnFunc func(
+	ctx context.Context,
+	task, label, agentID string,
+	tools *ToolRegistry,
+	maxTokens int,
+	temperature float64,
+	hasMaxTokens, hasTemperature bool,
+) (*ToolResult, error)
+
 type SubagentManager struct {
 	tasks          map[string]*SubagentTask
 	mu             sync.RWMutex
 	provider       providers.LLMProvider
 	defaultModel   string
-	bus            *bus.MessageBus
 	workspace      string
 	tools          *ToolRegistry
 	maxIterations  int
@@ -36,18 +66,17 @@ type SubagentManager struct {
 	hasMaxTokens   bool
 	hasTemperature bool
 	nextID         int
+	spawner        SpawnSubTurnFunc
 }
 
 func NewSubagentManager(
 	provider providers.LLMProvider,
 	defaultModel, workspace string,
-	bus *bus.MessageBus,
 ) *SubagentManager {
 	return &SubagentManager{
 		tasks:         make(map[string]*SubagentTask),
 		provider:      provider,
 		defaultModel:  defaultModel,
-		bus:           bus,
 		workspace:     workspace,
 		tools:         NewToolRegistry(),
 		maxIterations: 10,
@@ -55,6 +84,12 @@ func NewSubagentManager(
 	}
 }
 
+func (sm *SubagentManager) SetSpawner(spawner SpawnSubTurnFunc) {
+	sm.mu.Lock()
+	defer sm.mu.Unlock()
+	sm.spawner = spawner
+}
+
 // SetLLMOptions sets max tokens and temperature for subagent LLM calls.
 func (sm *SubagentManager) SetLLMOptions(maxTokens int, temperature float64) {
 	sm.mu.Lock()
@@ -112,25 +147,16 @@ func (sm *SubagentManager) Spawn(
 	return fmt.Sprintf("Spawned subagent for task: %s", task), nil
 }
 
-func (sm *SubagentManager) runTask(ctx context.Context, task *SubagentTask, callback AsyncCallback) {
+func (sm *SubagentManager) runTask(
+	ctx context.Context,
+	task *SubagentTask,
+	callback AsyncCallback,
+) {
 	task.Status = "running"
 	task.Created = time.Now().UnixMilli()
-
-	// Build system prompt for subagent
-	systemPrompt := `You are a subagent. Complete the given task independently and report the result.
-You have access to tools - use them as needed to complete your task.
-After completing the task, provide a clear summary of what was done.`
-
-	messages := []providers.Message{
-		{
-			Role:    "system",
-			Content: systemPrompt,
-		},
-		{
-			Role:    "user",
-			Content: task.Task,
-		},
-	}
+	// TODO(eventbus): once subagents are modeled as child turns inside
+	// pkg/agent, emit SubTurnEnd and SubTurnResultDelivered from the parent
+	// AgentLoop instead of this legacy manager.
 
 	// Check if context is already canceled before starting
 	select {
@@ -143,8 +169,8 @@ After completing the task, provide a clear summary of what was done.`
 	default:
 	}
 
-	// Run tool loop with access to tools
 	sm.mu.RLock()
+	spawner := sm.spawner
 	tools := sm.tools
 	maxIter := sm.maxIterations
 	maxTokens := sm.maxTokens
@@ -153,27 +179,69 @@ After completing the task, provide a clear summary of what was done.`
 	hasTemperature := sm.hasTemperature
 	sm.mu.RUnlock()
 
-	var llmOptions map[string]any
-	if hasMaxTokens || hasTemperature {
-		llmOptions = map[string]any{}
-		if hasMaxTokens {
-			llmOptions["max_tokens"] = maxTokens
+	var result *ToolResult
+	var err error
+
+	if spawner != nil {
+		result, err = spawner(
+			ctx,
+			task.Task,
+			task.Label,
+			task.AgentID,
+			tools,
+			maxTokens,
+			temperature,
+			hasMaxTokens,
+			hasTemperature,
+		)
+	} else {
+		// Fallback to legacy RunToolLoop
+		systemPrompt := `You are a subagent. Complete the given task independently and report the result.
+You have access to tools - use them as needed to complete your task.
+After completing the task, provide a clear summary of what was done.`
+
+		messages := []providers.Message{
+			{Role: "system", Content: systemPrompt},
+			{Role: "user", Content: task.Task},
 		}
-		if hasTemperature {
-			llmOptions["temperature"] = temperature
+
+		var llmOptions map[string]any
+		if hasMaxTokens || hasTemperature {
+			llmOptions = map[string]any{}
+			if hasMaxTokens {
+				llmOptions["max_tokens"] = maxTokens
+			}
+			if hasTemperature {
+				llmOptions["temperature"] = temperature
+			}
+		}
+
+		var loopResult *ToolLoopResult
+		loopResult, err = RunToolLoop(ctx, ToolLoopConfig{
+			Provider:      sm.provider,
+			Model:         sm.defaultModel,
+			Tools:         tools,
+			MaxIterations: maxIter,
+			LLMOptions:    llmOptions,
+		}, messages, task.OriginChannel, task.OriginChatID)
+
+		if err == nil {
+			result = &ToolResult{
+				ForLLM: fmt.Sprintf(
+					"Subagent '%s' completed (iterations: %d): %s",
+					task.Label,
+					loopResult.Iterations,
+					loopResult.Content,
+				),
+				ForUser: loopResult.Content,
+				Silent:  false,
+				IsError: false,
+				Async:   false,
+			}
 		}
 	}
 
-	loopResult, err := RunToolLoop(ctx, ToolLoopConfig{
-		Provider:      sm.provider,
-		Model:         sm.defaultModel,
-		Tools:         tools,
-		MaxIterations: maxIter,
-		LLMOptions:    llmOptions,
-	}, messages, task.OriginChannel, task.OriginChatID)
-
 	sm.mu.Lock()
-	var result *ToolResult
 	defer func() {
 		sm.mu.Unlock()
 		// Call callback if provided and result is set
@@ -200,33 +268,7 @@ After completing the task, provide a clear summary of what was done.`
 		}
 	} else {
 		task.Status = "completed"
-		task.Result = loopResult.Content
-		result = &ToolResult{
-			ForLLM: fmt.Sprintf(
-				"Subagent '%s' completed (iterations: %d): %s",
-				task.Label,
-				loopResult.Iterations,
-				loopResult.Content,
-			),
-			ForUser: loopResult.Content,
-			Silent:  false,
-			IsError: false,
-			Async:   false,
-		}
-	}
-
-	// Send announce message back to main agent
-	if sm.bus != nil {
-		announceContent := fmt.Sprintf("Task '%s' completed.\n\nResult:\n%s", task.Label, task.Result)
-		pubCtx, pubCancel := context.WithTimeout(context.Background(), 5*time.Second)
-		defer pubCancel()
-		sm.bus.PublishInbound(pubCtx, bus.InboundMessage{
-			Channel:  "system",
-			SenderID: fmt.Sprintf("subagent:%s", task.ID),
-			// Format: "original_channel:original_chat_id" for routing back
-			ChatID:  fmt.Sprintf("%s:%s", task.OriginChannel, task.OriginChatID),
-			Content: announceContent,
-		})
+		task.Result = result.ForLLM
 	}
 }
 
@@ -237,6 +279,18 @@ func (sm *SubagentManager) GetTask(taskID string) (*SubagentTask, bool) {
 	return task, ok
 }
 
+// GetTaskCopy returns a copy of the task with the given ID, taken under the
+// read lock, so the caller receives a consistent snapshot with no data race.
+func (sm *SubagentManager) GetTaskCopy(taskID string) (SubagentTask, bool) {
+	sm.mu.RLock()
+	defer sm.mu.RUnlock()
+	task, ok := sm.tasks[taskID]
+	if !ok {
+		return SubagentTask{}, false
+	}
+	return *task, true
+}
+
 func (sm *SubagentManager) ListTasks() []*SubagentTask {
 	sm.mu.RLock()
 	defer sm.mu.RUnlock()
@@ -248,21 +302,42 @@ func (sm *SubagentManager) ListTasks() []*SubagentTask {
 	return tasks
 }
 
+// ListTaskCopies returns value copies of all tasks, taken under the read lock,
+// so callers receive consistent snapshots with no data race.
+func (sm *SubagentManager) ListTaskCopies() []SubagentTask {
+	sm.mu.RLock()
+	defer sm.mu.RUnlock()
+
+	copies := make([]SubagentTask, 0, len(sm.tasks))
+	for _, task := range sm.tasks {
+		copies = append(copies, *task)
+	}
+	return copies
+}
+
 // SubagentTool executes a subagent task synchronously and returns the result.
-// Unlike SpawnTool which runs tasks asynchronously, SubagentTool waits for completion
-// and returns the result directly in the ToolResult.
+// It directly calls SubTurnSpawner with Async=false for synchronous execution.
 type SubagentTool struct {
-	manager       *SubagentManager
-	originChannel string
-	originChatID  string
+	spawner      SubTurnSpawner
+	defaultModel string
+	maxTokens    int
+	temperature  float64
 }
 
 func NewSubagentTool(manager *SubagentManager) *SubagentTool {
-	return &SubagentTool{
-		manager:       manager,
-		originChannel: "cli",
-		originChatID:  "direct",
+	if manager == nil {
+		return &SubagentTool{}
 	}
+	return &SubagentTool{
+		defaultModel: manager.defaultModel,
+		maxTokens:    manager.maxTokens,
+		temperature:  manager.temperature,
+	}
+}
+
+// SetSpawner sets the SubTurnSpawner for direct sub-turn execution.
+func (t *SubagentTool) SetSpawner(spawner SubTurnSpawner) {
+	t.spawner = spawner
 }
 
 func (t *SubagentTool) Name() string {
@@ -290,11 +365,6 @@ func (t *SubagentTool) Parameters() map[string]any {
 	}
 }
 
-func (t *SubagentTool) SetContext(channel, chatID string) {
-	t.originChannel = channel
-	t.originChatID = chatID
-}
-
 func (t *SubagentTool) Execute(ctx context.Context, args map[string]any) *ToolResult {
 	task, ok := args["task"].(string)
 	if !ok {
@@ -303,75 +373,64 @@ func (t *SubagentTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 
 	label, _ := args["label"].(string)
 
-	if t.manager == nil {
-		return ErrorResult("Subagent manager not configured").WithError(fmt.Errorf("manager is nil"))
+	// Build system prompt for subagent
+	systemPrompt := fmt.Sprintf(
+		`You are a subagent. Complete the given task independently and provide a clear, concise result.
+
+Task: %s`,
+		task,
+	)
+
+	if label != "" {
+		systemPrompt = fmt.Sprintf(
+			`You are a subagent labeled "%s". Complete the given task independently and provide a clear, concise result.
+
+Task: %s`,
+			label,
+			task,
+		)
 	}
 
-	// Build messages for subagent
-	messages := []providers.Message{
-		{
-			Role:    "system",
-			Content: "You are a subagent. Complete the given task independently and provide a clear, concise result.",
-		},
-		{
-			Role:    "user",
-			Content: task,
-		},
-	}
-
-	// Use RunToolLoop to execute with tools (same as async SpawnTool)
-	sm := t.manager
-	sm.mu.RLock()
-	tools := sm.tools
-	maxIter := sm.maxIterations
-	maxTokens := sm.maxTokens
-	temperature := sm.temperature
-	hasMaxTokens := sm.hasMaxTokens
-	hasTemperature := sm.hasTemperature
-	sm.mu.RUnlock()
-
-	var llmOptions map[string]any
-	if hasMaxTokens || hasTemperature {
-		llmOptions = map[string]any{}
-		if hasMaxTokens {
-			llmOptions["max_tokens"] = maxTokens
+	// Use spawner if available (direct SpawnSubTurn call)
+	if t.spawner != nil {
+		result, err := t.spawner.SpawnSubTurn(ctx, SubTurnConfig{
+			Model:        t.defaultModel,
+			Tools:        nil, // Will inherit from parent via context
+			SystemPrompt: systemPrompt,
+			MaxTokens:    t.maxTokens,
+			Temperature:  t.temperature,
+			Async:        false, // Synchronous execution
+		})
+		if err != nil {
+			return ErrorResult(fmt.Sprintf("Subagent execution failed: %v", err)).WithError(err)
 		}
-		if hasTemperature {
-			llmOptions["temperature"] = temperature
+
+		// Format result for display
+		userContent := result.ForLLM
+		if result.ForUser != "" {
+			userContent = result.ForUser
+		}
+		maxUserLen := 500
+		if len(userContent) > maxUserLen {
+			userContent = userContent[:maxUserLen] + "..."
+		}
+
+		labelStr := label
+		if labelStr == "" {
+			labelStr = "(unnamed)"
+		}
+		llmContent := fmt.Sprintf("Subagent task completed:\nLabel: %s\nResult: %s",
+			labelStr, result.ForLLM)
+
+		return &ToolResult{
+			ForLLM:  llmContent,
+			ForUser: userContent,
+			Silent:  false,
+			IsError: result.IsError,
+			Async:   false,
 		}
 	}
 
-	loopResult, err := RunToolLoop(ctx, ToolLoopConfig{
-		Provider:      sm.provider,
-		Model:         sm.defaultModel,
-		Tools:         tools,
-		MaxIterations: maxIter,
-		LLMOptions:    llmOptions,
-	}, messages, t.originChannel, t.originChatID)
-	if err != nil {
-		return ErrorResult(fmt.Sprintf("Subagent execution failed: %v", err)).WithError(err)
-	}
-
-	// ForUser: Brief summary for user (truncated if too long)
-	userContent := loopResult.Content
-	maxUserLen := 500
-	if len(userContent) > maxUserLen {
-		userContent = userContent[:maxUserLen] + "..."
-	}
-
-	// ForLLM: Full execution details
-	labelStr := label
-	if labelStr == "" {
-		labelStr = "(unnamed)"
-	}
-	llmContent := fmt.Sprintf("Subagent task completed:\nLabel: %s\nIterations: %d\nResult: %s",
-		labelStr, loopResult.Iterations, loopResult.Content)
-
-	return &ToolResult{
-		ForLLM:  llmContent,
-		ForUser: userContent,
-		Silent:  false,
-		IsError: false,
-		Async:   false,
-	}
+	// Fallback: spawner not configured
+	return ErrorResult("Subagent manager not configured").WithError(fmt.Errorf("spawner not set"))
 }
diff --git a/pkg/tools/subagent_tool_test.go b/pkg/tools/subagent_tool_test.go
index 59bfdffae..89ac7d4b5 100644
--- a/pkg/tools/subagent_tool_test.go
+++ b/pkg/tools/subagent_tool_test.go
@@ -5,7 +5,6 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/sipeed/picoclaw/pkg/bus"
 	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
@@ -47,34 +46,28 @@ func (m *MockLLMProvider) GetContextWindow() int {
 
 func TestSubagentManager_SetLLMOptions_AppliesToRunToolLoop(t *testing.T) {
 	provider := &MockLLMProvider{}
-	manager := NewSubagentManager(provider, "test-model", "/tmp/test", nil)
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
 	manager.SetLLMOptions(2048, 0.6)
-	tool := NewSubagentTool(manager)
-	tool.SetContext("cli", "direct")
 
-	ctx := context.Background()
-	args := map[string]any{"task": "Do something"}
-	result := tool.Execute(ctx, args)
-
-	if result == nil || result.IsError {
-		t.Fatalf("Expected successful result, got: %+v", result)
+	// Verify options are set on manager
+	if manager.maxTokens != 2048 {
+		t.Errorf("manager.maxTokens = %d, want 2048", manager.maxTokens)
 	}
-
-	if provider.lastOptions == nil {
-		t.Fatal("Expected LLM options to be passed, got nil")
+	if manager.temperature != 0.6 {
+		t.Errorf("manager.temperature = %f, want 0.6", manager.temperature)
 	}
-	if provider.lastOptions["max_tokens"] != 2048 {
-		t.Fatalf("max_tokens = %v, want %d", provider.lastOptions["max_tokens"], 2048)
+	if !manager.hasMaxTokens {
+		t.Error("manager.hasMaxTokens should be true")
 	}
-	if provider.lastOptions["temperature"] != 0.6 {
-		t.Fatalf("temperature = %v, want %v", provider.lastOptions["temperature"], 0.6)
+	if !manager.hasTemperature {
+		t.Error("manager.hasTemperature should be true")
 	}
 }
 
 // TestSubagentTool_Name verifies tool name
 func TestSubagentTool_Name(t *testing.T) {
 	provider := &MockLLMProvider{}
-	manager := NewSubagentManager(provider, "test-model", "/tmp/test", nil)
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
 	tool := NewSubagentTool(manager)
 
 	if tool.Name() != "subagent" {
@@ -85,7 +78,7 @@ func TestSubagentTool_Name(t *testing.T) {
 // TestSubagentTool_Description verifies tool description
 func TestSubagentTool_Description(t *testing.T) {
 	provider := &MockLLMProvider{}
-	manager := NewSubagentManager(provider, "test-model", "/tmp/test", nil)
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
 	tool := NewSubagentTool(manager)
 
 	desc := tool.Description()
@@ -100,7 +93,7 @@ func TestSubagentTool_Description(t *testing.T) {
 // TestSubagentTool_Parameters verifies tool parameters schema
 func TestSubagentTool_Parameters(t *testing.T) {
 	provider := &MockLLMProvider{}
-	manager := NewSubagentManager(provider, "test-model", "/tmp/test", nil)
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
 	tool := NewSubagentTool(manager)
 
 	params := tool.Parameters()
@@ -147,28 +140,14 @@ func TestSubagentTool_Parameters(t *testing.T) {
 	}
 }
 
-// TestSubagentTool_SetContext verifies context setting
-func TestSubagentTool_SetContext(t *testing.T) {
-	provider := &MockLLMProvider{}
-	manager := NewSubagentManager(provider, "test-model", "/tmp/test", nil)
-	tool := NewSubagentTool(manager)
-
-	tool.SetContext("test-channel", "test-chat")
-
-	// Verify context is set (we can't directly access private fields,
-	// but we can verify it doesn't crash)
-	// The actual context usage is tested in Execute tests
-}
-
 // TestSubagentTool_Execute_Success tests successful execution
 func TestSubagentTool_Execute_Success(t *testing.T) {
 	provider := &MockLLMProvider{}
-	msgBus := bus.NewMessageBus()
-	manager := NewSubagentManager(provider, "test-model", "/tmp/test", msgBus)
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
 	tool := NewSubagentTool(manager)
-	tool.SetContext("telegram", "chat-123")
+	tool.SetSpawner(&mockSpawner{})
 
-	ctx := context.Background()
+	ctx := WithToolContext(context.Background(), "telegram", "chat-123")
 	args := map[string]any{
 		"task":  "Write a haiku about coding",
 		"label": "haiku-task",
@@ -219,9 +198,9 @@ func TestSubagentTool_Execute_Success(t *testing.T) {
 // TestSubagentTool_Execute_NoLabel tests execution without label
 func TestSubagentTool_Execute_NoLabel(t *testing.T) {
 	provider := &MockLLMProvider{}
-	msgBus := bus.NewMessageBus()
-	manager := NewSubagentManager(provider, "test-model", "/tmp/test", msgBus)
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
 	tool := NewSubagentTool(manager)
+	tool.SetSpawner(&mockSpawner{})
 
 	ctx := context.Background()
 	args := map[string]any{
@@ -243,7 +222,7 @@ func TestSubagentTool_Execute_NoLabel(t *testing.T) {
 // TestSubagentTool_Execute_MissingTask tests error handling for missing task
 func TestSubagentTool_Execute_MissingTask(t *testing.T) {
 	provider := &MockLLMProvider{}
-	manager := NewSubagentManager(provider, "test-model", "/tmp/test", nil)
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
 	tool := NewSubagentTool(manager)
 
 	ctx := context.Background()
@@ -293,16 +272,13 @@ func TestSubagentTool_Execute_NilManager(t *testing.T) {
 // TestSubagentTool_Execute_ContextPassing verifies context is properly used
 func TestSubagentTool_Execute_ContextPassing(t *testing.T) {
 	provider := &MockLLMProvider{}
-	msgBus := bus.NewMessageBus()
-	manager := NewSubagentManager(provider, "test-model", "/tmp/test", msgBus)
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
 	tool := NewSubagentTool(manager)
+	tool.SetSpawner(&mockSpawner{})
 
-	// Set context
 	channel := "test-channel"
 	chatID := "test-chat"
-	tool.SetContext(channel, chatID)
-
-	ctx := context.Background()
+	ctx := WithToolContext(context.Background(), channel, chatID)
 	args := map[string]any{
 		"task": "Test context passing",
 	}
@@ -322,9 +298,9 @@ func TestSubagentTool_Execute_ContextPassing(t *testing.T) {
 func TestSubagentTool_ForUserTruncation(t *testing.T) {
 	// Create a mock provider that returns very long content
 	provider := &MockLLMProvider{}
-	msgBus := bus.NewMessageBus()
-	manager := NewSubagentManager(provider, "test-model", "/tmp/test", msgBus)
+	manager := NewSubagentManager(provider, "test-model", "/tmp/test")
 	tool := NewSubagentTool(manager)
+	tool.SetSpawner(&mockSpawner{})
 
 	ctx := context.Background()
 
diff --git a/pkg/tools/toolloop.go b/pkg/tools/toolloop.go
index cdfe0d6ce..387813e94 100644
--- a/pkg/tools/toolloop.go
+++ b/pkg/tools/toolloop.go
@@ -10,6 +10,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"sync"
 
 	"github.com/sipeed/picoclaw/pkg/logger"
 	"github.com/sipeed/picoclaw/pkg/providers"
@@ -121,37 +122,50 @@ func RunToolLoop(
 		}
 		messages = append(messages, assistantMsg)
 
-		// 7. Execute tool calls
-		for _, tc := range normalizedToolCalls {
-			argsJSON, _ := json.Marshal(tc.Arguments)
-			argsPreview := utils.Truncate(string(argsJSON), 200)
-			logger.InfoCF("toolloop", fmt.Sprintf("Tool call: %s(%s)", tc.Name, argsPreview),
-				map[string]any{
-					"tool":      tc.Name,
-					"iteration": iteration,
-				})
+		// 7. Execute tool calls in parallel
+		type indexedResult struct {
+			result *ToolResult
+			tc     providers.ToolCall
+		}
 
-			// Execute tool (no async callback for subagents - they run independently)
-			var toolResult *ToolResult
-			if config.Tools != nil {
-				toolResult = config.Tools.ExecuteWithContext(ctx, tc.Name, tc.Arguments, channel, chatID, nil)
-			} else {
-				toolResult = ErrorResult("No tools available")
-			}
+		results := make([]indexedResult, len(normalizedToolCalls))
+		var wg sync.WaitGroup
 
-			// Determine content for LLM
-			contentForLLM := toolResult.ForLLM
-			if contentForLLM == "" && toolResult.Err != nil {
-				contentForLLM = toolResult.Err.Error()
-			}
+		for i, tc := range normalizedToolCalls {
+			results[i].tc = tc
 
-			// Add tool result message
-			toolResultMsg := providers.Message{
+			wg.Add(1)
+			go func(idx int, tc providers.ToolCall) {
+				defer wg.Done()
+
+				argsJSON, _ := json.Marshal(tc.Arguments)
+				argsPreview := utils.Truncate(string(argsJSON), 200)
+				logger.InfoCF("toolloop", fmt.Sprintf("Tool call: %s(%s)", tc.Name, argsPreview),
+					map[string]any{
+						"tool":      tc.Name,
+						"iteration": iteration,
+					})
+
+				var toolResult *ToolResult
+				if config.Tools != nil {
+					toolResult = config.Tools.ExecuteWithContext(ctx, tc.Name, tc.Arguments, channel, chatID, nil)
+				} else {
+					toolResult = ErrorResult("No tools available")
+				}
+				results[idx].result = toolResult
+			}(i, tc)
+		}
+		wg.Wait()
+
+		// Append results in original order
+		for _, r := range results {
+			contentForLLM := r.result.ContentForLLM()
+
+			messages = append(messages, providers.Message{
 				Role:       "tool",
 				Content:    contentForLLM,
-				ToolCallID: tc.ID,
-			}
-			messages = append(messages, toolResultMsg)
+				ToolCallID: r.tc.ID,
+			})
 		}
 	}
 
diff --git a/pkg/tools/validate.go b/pkg/tools/validate.go
new file mode 100644
index 000000000..940344708
--- /dev/null
+++ b/pkg/tools/validate.go
@@ -0,0 +1,209 @@
+package tools
+
+import (
+	"fmt"
+	"math"
+)
+
+// validateToolArgs validates args against a JSON Schema-like map.
+// schema is expected to have optional keys: "properties", "required", "additionalProperties".
+func validateToolArgs(schema map[string]any, args map[string]any) error {
+	if len(schema) == 0 {
+		return nil
+	}
+
+	if args == nil {
+		args = map[string]any{}
+	}
+
+	if err := checkRequired(schema, args); err != nil {
+		return err
+	}
+
+	propsRaw, ok := schema["properties"]
+	if !ok {
+		return nil // no properties defined — accept any args
+	}
+
+	props, ok := propsRaw.(map[string]any)
+	if !ok {
+		return nil
+	}
+
+	additional := allowsAdditional(schema)
+
+	for key, val := range args {
+		propSchemaRaw, known := props[key]
+		if !known {
+			if !additional {
+				return fmt.Errorf("unexpected property %q", key)
+			}
+			continue
+		}
+		propSchema, ok := propSchemaRaw.(map[string]any)
+		if !ok {
+			continue // can't validate without a proper schema map
+		}
+		if err := checkType(key, val, propSchema); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+// checkRequired verifies that every field listed in schema["required"] is present in args.
+func checkRequired(schema map[string]any, args map[string]any) error {
+	reqRaw, ok := schema["required"]
+	if !ok {
+		return nil
+	}
+
+	var required []string
+
+	switch r := reqRaw.(type) {
+	case []string:
+		required = r
+	case []any:
+		for _, v := range r {
+			s, ok := v.(string)
+			if ok {
+				required = append(required, s)
+			}
+		}
+	default:
+		return nil
+	}
+
+	for _, field := range required {
+		if _, present := args[field]; !present {
+			return fmt.Errorf("missing required property %q", field)
+		}
+	}
+	return nil
+}
+
+// allowsAdditional returns true when the schema explicitly sets
+// "additionalProperties" to true, or when the key is absent (default: reject extras).
+func allowsAdditional(schema map[string]any) bool {
+	v, ok := schema["additionalProperties"]
+	if !ok {
+		return false
+	}
+	b, ok := v.(bool)
+	return ok && b
+}
+
+// checkType validates that val matches the JSON Schema type declared in propSchema.
+func checkType(key string, val any, propSchema map[string]any) error {
+	typeRaw, ok := propSchema["type"]
+	if !ok {
+		return nil // no type constraint
+	}
+	typeName, ok := typeRaw.(string)
+	if !ok {
+		return nil
+	}
+
+	switch typeName {
+	case "string":
+		if _, ok := val.(string); !ok {
+			return fmt.Errorf("property %q: expected string, got %T", key, val)
+		}
+	case "integer":
+		switch v := val.(type) {
+		case float64:
+			if v != math.Trunc(v) {
+				return fmt.Errorf("property %q: expected integer, got float64 with fractional part", key)
+			}
+		case int:
+			// ok
+		case int64:
+			// ok
+		default:
+			return fmt.Errorf("property %q: expected integer, got %T", key, val)
+		}
+	case "number":
+		switch val.(type) {
+		case float64, int, int64:
+			// ok
+		default:
+			return fmt.Errorf("property %q: expected number, got %T", key, val)
+		}
+	case "boolean":
+		if _, ok := val.(bool); !ok {
+			return fmt.Errorf("property %q: expected boolean, got %T", key, val)
+		}
+	case "array":
+		arr, ok := val.([]any)
+		if !ok {
+			return fmt.Errorf("property %q: expected array, got %T", key, val)
+		}
+		if err := checkArrayItems(key, arr, propSchema); err != nil {
+			return err
+		}
+	case "object":
+		obj, ok := val.(map[string]any)
+		if !ok {
+			return fmt.Errorf("property %q: expected object, got %T", key, val)
+		}
+		if err := validateToolArgs(propSchema, obj); err != nil {
+			return fmt.Errorf("property %q: %w", key, err)
+		}
+	}
+
+	if err := checkEnum(key, val, propSchema); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// checkArrayItems validates each element of arr against the "items" sub-schema.
+func checkArrayItems(key string, arr []any, propSchema map[string]any) error {
+	itemsRaw, ok := propSchema["items"]
+	if !ok {
+		return nil
+	}
+	itemSchema, ok := itemsRaw.(map[string]any)
+	if !ok {
+		return nil
+	}
+	for i, elem := range arr {
+		elemKey := fmt.Sprintf("%s[%d]", key, i)
+		if err := checkType(elemKey, elem, itemSchema); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// checkEnum validates that val is one of the allowed enum values in propSchema.
+func checkEnum(key string, val any, propSchema map[string]any) error {
+	enumRaw, ok := propSchema["enum"]
+	if !ok {
+		return nil
+	}
+
+	switch ev := enumRaw.(type) {
+	case []any:
+		for _, allowed := range ev {
+			if val == allowed {
+				return nil
+			}
+		}
+	case []string:
+		s, ok := val.(string)
+		if ok {
+			for _, allowed := range ev {
+				if s == allowed {
+					return nil
+				}
+			}
+		}
+	default:
+		return nil // unknown enum format, skip
+	}
+
+	return fmt.Errorf("property %q: value %v is not in enum", key, val)
+}
diff --git a/pkg/tools/validate_test.go b/pkg/tools/validate_test.go
new file mode 100644
index 000000000..e7f4f619a
--- /dev/null
+++ b/pkg/tools/validate_test.go
@@ -0,0 +1,465 @@
+package tools
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+// Ensure imports are used.
+var (
+	_ = context.Background
+	_ = strings.Contains
+)
+
+func TestValidateToolArgs(t *testing.T) {
+	baseSchema := map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"name": map[string]any{"type": "string"},
+			"age":  map[string]any{"type": "integer"},
+		},
+		"required": []string{"name"},
+	}
+
+	tests := []struct {
+		name    string
+		schema  map[string]any
+		args    map[string]any
+		wantErr string // empty means no error expected
+	}{
+		{
+			name:   "valid args all required present",
+			schema: baseSchema,
+			args:   map[string]any{"name": "alice", "age": float64(30)},
+		},
+		{
+			name:    "missing required field",
+			schema:  baseSchema,
+			args:    map[string]any{"age": float64(30)},
+			wantErr: "missing required property \"name\"",
+		},
+		{
+			name:    "wrong type string field gets number",
+			schema:  baseSchema,
+			args:    map[string]any{"name": float64(42)},
+			wantErr: "expected string",
+		},
+		{
+			name:    "nil args with required fields",
+			schema:  baseSchema,
+			args:    nil,
+			wantErr: "missing required property \"name\"",
+		},
+		{
+			name: "nil args no required fields",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"name": map[string]any{"type": "string"},
+				},
+			},
+			args: nil,
+		},
+		{
+			name: "empty args no required fields",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"name": map[string]any{"type": "string"},
+				},
+			},
+			args: map[string]any{},
+		},
+		{
+			name:   "optional field correct type",
+			schema: baseSchema,
+			args:   map[string]any{"name": "bob", "age": float64(25)},
+		},
+		{
+			name:    "optional field wrong type",
+			schema:  baseSchema,
+			args:    map[string]any{"name": "bob", "age": "twenty"},
+			wantErr: "expected integer",
+		},
+		{
+			name:   "integer as float64 no fractional part",
+			schema: baseSchema,
+			args:   map[string]any{"name": "carol", "age": float64(42)},
+		},
+		{
+			name:    "actual float for integer field",
+			schema:  baseSchema,
+			args:    map[string]any{"name": "dave", "age": float64(42.5)},
+			wantErr: "expected integer, got float64 with fractional part",
+		},
+		{
+			name: "number type accepts float",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"score": map[string]any{"type": "number"},
+				},
+			},
+			args: map[string]any{"score": float64(3.14)},
+		},
+		{
+			name: "number type accepts integer",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"score": map[string]any{"type": "number"},
+				},
+			},
+			args: map[string]any{"score": float64(10)},
+		},
+		{
+			name: "boolean type valid",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"flag": map[string]any{"type": "boolean"},
+				},
+			},
+			args: map[string]any{"flag": true},
+		},
+		{
+			name: "boolean type wrong",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"flag": map[string]any{"type": "boolean"},
+				},
+			},
+			args:    map[string]any{"flag": "true"},
+			wantErr: "expected boolean",
+		},
+		{
+			name: "required as []any from MCP deserialization",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"cmd": map[string]any{"type": "string"},
+				},
+				"required": []any{"cmd"},
+			},
+			args:    map[string]any{},
+			wantErr: "missing required property \"cmd\"",
+		},
+		{
+			name: "enum valid value []any",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"color": map[string]any{"type": "string", "enum": []any{"red", "green", "blue"}},
+				},
+			},
+			args: map[string]any{"color": "red"},
+		},
+		{
+			name: "enum invalid value []any",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"color": map[string]any{"type": "string", "enum": []any{"red", "green", "blue"}},
+				},
+			},
+			args:    map[string]any{"color": "yellow"},
+			wantErr: "not in enum",
+		},
+		{
+			name: "enum valid value []string",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"color": map[string]any{"type": "string", "enum": []string{"red", "green", "blue"}},
+				},
+			},
+			args: map[string]any{"color": "green"},
+		},
+		{
+			name: "enum invalid value []string",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"color": map[string]any{"type": "string", "enum": []string{"red", "green", "blue"}},
+				},
+			},
+			args:    map[string]any{"color": "yellow"},
+			wantErr: "not in enum",
+		},
+		{
+			name:    "extra unexpected property rejected",
+			schema:  baseSchema,
+			args:    map[string]any{"name": "eve", "hobby": "chess"},
+			wantErr: "unexpected property \"hobby\"",
+		},
+		{
+			name: "extra property allowed with additionalProperties true",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"name": map[string]any{"type": "string"},
+				},
+				"additionalProperties": true,
+			},
+			args: map[string]any{"name": "eve", "hobby": "chess"},
+		},
+		{
+			name: "nested object valid",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"address": map[string]any{
+						"type": "object",
+						"properties": map[string]any{
+							"city": map[string]any{"type": "string"},
+						},
+						"required": []string{"city"},
+					},
+				},
+			},
+			args: map[string]any{
+				"address": map[string]any{"city": "Berlin"},
+			},
+		},
+		{
+			name: "nested object wrong type",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"address": map[string]any{
+						"type": "object",
+						"properties": map[string]any{
+							"city": map[string]any{"type": "string"},
+						},
+					},
+				},
+			},
+			args:    map[string]any{"address": "not an object"},
+			wantErr: "expected object",
+		},
+		{
+			name: "array with valid element types",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"tags": map[string]any{
+						"type":  "array",
+						"items": map[string]any{"type": "string"},
+					},
+				},
+			},
+			args: map[string]any{"tags": []any{"a", "b", "c"}},
+		},
+		{
+			name: "array with wrong element types",
+			schema: map[string]any{
+				"type": "object",
+				"properties": map[string]any{
+					"tags": map[string]any{
+						"type":  "array",
+						"items": map[string]any{"type": "string"},
+					},
+				},
+			},
+			args:    map[string]any{"tags": []any{"a", float64(2)}},
+			wantErr: "expected string",
+		},
+		{
+			name: "schema with no properties key accepts any args",
+			schema: map[string]any{
+				"type": "object",
+			},
+			args: map[string]any{"anything": "goes"},
+		},
+		{
+			name:   "empty schema accepts anything",
+			schema: map[string]any{},
+			args:   map[string]any{"foo": "bar"},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateToolArgs(tc.schema, tc.args)
+			if tc.wantErr == "" {
+				if err != nil {
+					t.Fatalf("expected no error, got: %v", err)
+				}
+				return
+			}
+			if err == nil {
+				t.Fatalf("expected error containing %q, got nil", tc.wantErr)
+			}
+			if !strings.Contains(err.Error(), tc.wantErr) {
+				t.Fatalf("expected error containing %q, got: %v", tc.wantErr, err)
+			}
+		})
+	}
+}
+
+func TestValidateToolArgs_RegistryIntegration(t *testing.T) {
+	r := NewToolRegistry()
+	r.Register(&mockRegistryTool{
+		name: "read_file",
+		desc: "reads a file",
+		params: map[string]any{
+			"type": "object",
+			"properties": map[string]any{
+				"path": map[string]any{"type": "string"},
+			},
+			"required": []string{"path"},
+		},
+		result: SilentResult("file contents"),
+	})
+
+	// Valid args — should succeed
+	result := r.Execute(context.Background(), "read_file", map[string]any{"path": "/tmp/x"})
+	if result.IsError {
+		t.Errorf("expected success, got error: %s", result.ForLLM)
+	}
+
+	// Missing required field — should fail with validation error
+	result = r.Execute(context.Background(), "read_file", map[string]any{})
+	if !result.IsError {
+		t.Error("expected validation error for missing required field")
+	}
+	if !strings.Contains(result.ForLLM, "missing required p") {
+		t.Errorf("expected 'missing required p...' in error, got %q", result.ForLLM)
+	}
+	if result.Err == nil {
+		t.Error("expected Err to be set via WithError")
+	}
+
+	// Wrong type — should fail with validation error
+	result = r.Execute(context.Background(), "read_file", map[string]any{"path": 123.0})
+	if !result.IsError {
+		t.Error("expected validation error for wrong type")
+	}
+	if !strings.Contains(result.ForLLM, "expected string") {
+		t.Errorf("expected 'expected string' in error, got %q", result.ForLLM)
+	}
+
+	// Extra property — should fail with validation error
+	result = r.Execute(context.Background(), "read_file", map[string]any{"path": "/x", "__inject": true})
+	if !result.IsError {
+		t.Error("expected validation error for extra property")
+	}
+	if !strings.Contains(result.ForLLM, "unexpected prop") {
+		t.Errorf("expected 'unexpected prop...' in error, got %q", result.ForLLM)
+	}
+}
+
+func TestValidateToolArgs_RealSchemas(t *testing.T) {
+	execSchema := map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"command":     map[string]any{"type": "string"},
+			"working_dir": map[string]any{"type": "string"},
+		},
+		"required": []string{"command"},
+	}
+
+	cronSchema := map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"action": map[string]any{
+				"type": "string",
+				"enum": []any{"add", "list", "remove", "enable", "disable"},
+			},
+		},
+		"required": []string{"action"},
+	}
+
+	webSearchSchema := map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"query": map[string]any{"type": "string"},
+			"count": map[string]any{"type": "integer"},
+		},
+		"required": []string{"query"},
+	}
+
+	tests := []struct {
+		name    string
+		schema  map[string]any
+		args    map[string]any
+		wantErr string
+	}{
+		// ExecTool
+		{
+			name:   "exec valid args",
+			schema: execSchema,
+			args:   map[string]any{"command": "ls -la", "working_dir": "/tmp"},
+		},
+		{
+			name:    "exec missing required command",
+			schema:  execSchema,
+			args:    map[string]any{"working_dir": "/tmp"},
+			wantErr: "missing required property \"command\"",
+		},
+		{
+			name:    "exec wrong type for command",
+			schema:  execSchema,
+			args:    map[string]any{"command": float64(123)},
+			wantErr: "expected string",
+		},
+		{
+			name:    "exec extra injected arg",
+			schema:  execSchema,
+			args:    map[string]any{"command": "ls", "malicious": "payload"},
+			wantErr: "unexpected property \"malicious\"",
+		},
+
+		// CronTool
+		{
+			name:   "cron valid enum value",
+			schema: cronSchema,
+			args:   map[string]any{"action": "add"},
+		},
+		{
+			name:    "cron invalid enum value",
+			schema:  cronSchema,
+			args:    map[string]any{"action": "destroy"},
+			wantErr: "not in enum",
+		},
+
+		// WebSearchTool
+		{
+			name:   "websearch valid args",
+			schema: webSearchSchema,
+			args:   map[string]any{"query": "golang testing", "count": float64(10)},
+		},
+		{
+			name:    "websearch missing required query",
+			schema:  webSearchSchema,
+			args:    map[string]any{"count": float64(5)},
+			wantErr: "missing required property \"query\"",
+		},
+		{
+			name:    "websearch wrong type for count",
+			schema:  webSearchSchema,
+			args:    map[string]any{"query": "test", "count": "ten"},
+			wantErr: "expected integer",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			err := validateToolArgs(tc.schema, tc.args)
+			if tc.wantErr == "" {
+				if err != nil {
+					t.Fatalf("expected no error, got: %v", err)
+				}
+				return
+			}
+			if err == nil {
+				t.Fatalf("expected error containing %q, got nil", tc.wantErr)
+			}
+			if !strings.Contains(err.Error(), tc.wantErr) {
+				t.Fatalf("expected error containing %q, got: %v", tc.wantErr, err)
+			}
+		})
+	}
+}
diff --git a/pkg/tools/web.go b/pkg/tools/web.go
index 10498126b..7ff724802 100644
--- a/pkg/tools/web.go
+++ b/pkg/tools/web.go
@@ -7,15 +7,23 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"mime"
+	"net"
 	"net/http"
 	"net/url"
 	"regexp"
 	"strings"
+	"sync/atomic"
 	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/utils"
 )
 
 const (
-	userAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+	userAgent       = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+	userAgentHonest = "picoclaw/%s (+https://github.com/sipeed/picoclaw; AI assistant bot)"
 
 	// HTTP client timeouts for web tool providers.
 	searchTimeout     = 10 * time.Second // Brave, Tavily, DuckDuckGo
@@ -39,41 +47,42 @@ var (
 	reDDGSnippet = regexp.MustCompile(`<a class="result__snippet[^"]*".*?>([\s\S]*?)</a>`)
 )
 
-// createHTTPClient creates an HTTP client with optional proxy support
-func createHTTPClient(proxyURL string, timeout time.Duration) (*http.Client, error) {
-	client := &http.Client{
-		Timeout: timeout,
-		Transport: &http.Transport{
-			MaxIdleConns:        10,
-			IdleConnTimeout:     30 * time.Second,
-			DisableCompression:  false,
-			TLSHandshakeTimeout: 15 * time.Second,
-		},
-	}
+type APIKeyPool struct {
+	keys    []string
+	current uint32
+}
 
-	if proxyURL != "" {
-		proxy, err := url.Parse(proxyURL)
-		if err != nil {
-			return nil, fmt.Errorf("invalid proxy URL: %w", err)
-		}
-		scheme := strings.ToLower(proxy.Scheme)
-		switch scheme {
-		case "http", "https", "socks5", "socks5h":
-		default:
-			return nil, fmt.Errorf(
-				"unsupported proxy scheme %q (supported: http, https, socks5, socks5h)",
-				proxy.Scheme,
-			)
-		}
-		if proxy.Host == "" {
-			return nil, fmt.Errorf("invalid proxy URL: missing host")
-		}
-		client.Transport.(*http.Transport).Proxy = http.ProxyURL(proxy)
-	} else {
-		client.Transport.(*http.Transport).Proxy = http.ProxyFromEnvironment
+func NewAPIKeyPool(keys []string) *APIKeyPool {
+	return &APIKeyPool{
+		keys: keys,
 	}
+}
 
-	return client, nil
+type APIKeyIterator struct {
+	pool     *APIKeyPool
+	startIdx uint32
+	attempt  uint32
+}
+
+func (p *APIKeyPool) NewIterator() *APIKeyIterator {
+	if len(p.keys) == 0 {
+		return &APIKeyIterator{pool: p}
+	}
+	idx := atomic.AddUint32(&p.current, 1) - 1
+	return &APIKeyIterator{
+		pool:     p,
+		startIdx: idx,
+	}
+}
+
+func (it *APIKeyIterator) Next() (string, bool) {
+	length := uint32(len(it.pool.keys))
+	if length == 0 || it.attempt >= length {
+		return "", false
+	}
+	key := it.pool.keys[(it.startIdx+it.attempt)%length]
+	it.attempt++
+	return key, true
 }
 
 type SearchProvider interface {
@@ -81,72 +90,97 @@ type SearchProvider interface {
 }
 
 type BraveSearchProvider struct {
-	apiKey string
-	proxy  string
-	client *http.Client
+	keyPool *APIKeyPool
+	proxy   string
+	client  *http.Client
 }
 
 func (p *BraveSearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
 	searchURL := fmt.Sprintf("https://api.search.brave.com/res/v1/web/search?q=%s&count=%d",
 		url.QueryEscape(query), count)
 
-	req, err := http.NewRequestWithContext(ctx, "GET", searchURL, nil)
-	if err != nil {
-		return "", fmt.Errorf("failed to create request: %w", err)
-	}
+	var lastErr error
+	iter := p.keyPool.NewIterator()
 
-	req.Header.Set("Accept", "application/json")
-	req.Header.Set("X-Subscription-Token", p.apiKey)
-
-	resp, err := p.client.Do(req)
-	if err != nil {
-		return "", fmt.Errorf("request failed: %w", err)
-	}
-	defer resp.Body.Close()
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", fmt.Errorf("failed to read response: %w", err)
-	}
-
-	var searchResp struct {
-		Web struct {
-			Results []struct {
-				Title       string `json:"title"`
-				URL         string `json:"url"`
-				Description string `json:"description"`
-			} `json:"results"`
-		} `json:"web"`
-	}
-
-	if err := json.Unmarshal(body, &searchResp); err != nil {
-		// Log error body for debugging
-		fmt.Printf("Brave API Error Body: %s\n", string(body))
-		return "", fmt.Errorf("failed to parse response: %w", err)
-	}
-
-	results := searchResp.Web.Results
-	if len(results) == 0 {
-		return fmt.Sprintf("No results for: %s", query), nil
-	}
-
-	var lines []string
-	lines = append(lines, fmt.Sprintf("Results for: %s", query))
-	for i, item := range results {
-		if i >= count {
+	for {
+		apiKey, ok := iter.Next()
+		if !ok {
 			break
 		}
-		lines = append(lines, fmt.Sprintf("%d. %s\n   %s", i+1, item.Title, item.URL))
-		if item.Description != "" {
-			lines = append(lines, fmt.Sprintf("   %s", item.Description))
+
+		req, err := http.NewRequestWithContext(ctx, "GET", searchURL, nil)
+		if err != nil {
+			return "", fmt.Errorf("failed to create request: %w", err)
 		}
+
+		req.Header.Set("Accept", "application/json")
+		req.Header.Set("X-Subscription-Token", apiKey)
+
+		resp, err := p.client.Do(req)
+		if err != nil {
+			lastErr = fmt.Errorf("request failed: %w", err)
+			continue
+		}
+
+		body, err := io.ReadAll(resp.Body)
+		resp.Body.Close()
+
+		if err != nil {
+			lastErr = fmt.Errorf("failed to read response: %w", err)
+			continue
+		}
+
+		if resp.StatusCode != http.StatusOK {
+			lastErr = fmt.Errorf("API error (status %d): %s", resp.StatusCode, string(body))
+			if resp.StatusCode == http.StatusTooManyRequests ||
+				resp.StatusCode == http.StatusUnauthorized ||
+				resp.StatusCode == http.StatusForbidden ||
+				resp.StatusCode >= 500 {
+				continue
+			}
+			return "", lastErr
+		}
+
+		var searchResp struct {
+			Web struct {
+				Results []struct {
+					Title       string `json:"title"`
+					URL         string `json:"url"`
+					Description string `json:"description"`
+				} `json:"results"`
+			} `json:"web"`
+		}
+
+		if err := json.Unmarshal(body, &searchResp); err != nil {
+			// Log error body for debugging
+			return "", fmt.Errorf("failed to parse response: %w", err)
+		}
+
+		results := searchResp.Web.Results
+		if len(results) == 0 {
+			return fmt.Sprintf("No results for: %s", query), nil
+		}
+
+		var lines []string
+		lines = append(lines, fmt.Sprintf("Results for: %s", query))
+		for i, item := range results {
+			if i >= count {
+				break
+			}
+			lines = append(lines, fmt.Sprintf("%d. %s\n   %s", i+1, item.Title, item.URL))
+			if item.Description != "" {
+				lines = append(lines, fmt.Sprintf("   %s", item.Description))
+			}
+		}
+
+		return strings.Join(lines, "\n"), nil
 	}
 
-	return strings.Join(lines, "\n"), nil
+	return "", fmt.Errorf("all api keys failed, last error: %w", lastErr)
 }
 
 type TavilySearchProvider struct {
-	apiKey  string
+	keyPool *APIKeyPool
 	baseURL string
 	proxy   string
 	client  *http.Client
@@ -158,74 +192,96 @@ func (p *TavilySearchProvider) Search(ctx context.Context, query string, count i
 		searchURL = "https://api.tavily.com/search"
 	}
 
-	payload := map[string]any{
-		"api_key":             p.apiKey,
-		"query":               query,
-		"search_depth":        "advanced",
-		"include_answer":      false,
-		"include_images":      false,
-		"include_raw_content": false,
-		"max_results":         count,
-	}
+	var lastErr error
+	iter := p.keyPool.NewIterator()
 
-	bodyBytes, err := json.Marshal(payload)
-	if err != nil {
-		return "", fmt.Errorf("failed to marshal payload: %w", err)
-	}
-
-	req, err := http.NewRequestWithContext(ctx, "POST", searchURL, bytes.NewBuffer(bodyBytes))
-	if err != nil {
-		return "", fmt.Errorf("failed to create request: %w", err)
-	}
-
-	req.Header.Set("Content-Type", "application/json")
-	req.Header.Set("User-Agent", userAgent)
-
-	resp, err := p.client.Do(req)
-	if err != nil {
-		return "", fmt.Errorf("request failed: %w", err)
-	}
-	defer resp.Body.Close()
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		return "", fmt.Errorf("failed to read response: %w", err)
-	}
-
-	if resp.StatusCode != http.StatusOK {
-		return "", fmt.Errorf("tavily api error (status %d): %s", resp.StatusCode, string(body))
-	}
-
-	var searchResp struct {
-		Results []struct {
-			Title   string `json:"title"`
-			URL     string `json:"url"`
-			Content string `json:"content"`
-		} `json:"results"`
-	}
-
-	if err := json.Unmarshal(body, &searchResp); err != nil {
-		return "", fmt.Errorf("failed to parse response: %w", err)
-	}
-
-	results := searchResp.Results
-	if len(results) == 0 {
-		return fmt.Sprintf("No results for: %s", query), nil
-	}
-
-	var lines []string
-	lines = append(lines, fmt.Sprintf("Results for: %s (via Tavily)", query))
-	for i, item := range results {
-		if i >= count {
+	for {
+		apiKey, ok := iter.Next()
+		if !ok {
 			break
 		}
-		lines = append(lines, fmt.Sprintf("%d. %s\n   %s", i+1, item.Title, item.URL))
-		if item.Content != "" {
-			lines = append(lines, fmt.Sprintf("   %s", item.Content))
+
+		payload := map[string]any{
+			"api_key":             apiKey,
+			"query":               query,
+			"search_depth":        "advanced",
+			"include_answer":      false,
+			"include_images":      false,
+			"include_raw_content": false,
+			"max_results":         count,
 		}
+
+		bodyBytes, err := json.Marshal(payload)
+		if err != nil {
+			return "", fmt.Errorf("failed to marshal payload: %w", err)
+		}
+
+		req, err := http.NewRequestWithContext(ctx, "POST", searchURL, bytes.NewBuffer(bodyBytes))
+		if err != nil {
+			return "", fmt.Errorf("failed to create request: %w", err)
+		}
+
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("User-Agent", userAgent)
+
+		resp, err := p.client.Do(req)
+		if err != nil {
+			lastErr = fmt.Errorf("request failed: %w", err)
+			continue
+		}
+
+		body, err := io.ReadAll(resp.Body)
+		resp.Body.Close()
+
+		if err != nil {
+			lastErr = fmt.Errorf("failed to read response: %w", err)
+			continue
+		}
+
+		if resp.StatusCode != http.StatusOK {
+			lastErr = fmt.Errorf("tavily api error (status %d): %s", resp.StatusCode, string(body))
+			if resp.StatusCode == http.StatusTooManyRequests ||
+				resp.StatusCode == http.StatusUnauthorized ||
+				resp.StatusCode == http.StatusForbidden ||
+				resp.StatusCode >= 500 {
+				continue
+			}
+			return "", lastErr
+		}
+
+		var searchResp struct {
+			Results []struct {
+				Title   string `json:"title"`
+				URL     string `json:"url"`
+				Content string `json:"content"`
+			} `json:"results"`
+		}
+
+		if err := json.Unmarshal(body, &searchResp); err != nil {
+			return "", fmt.Errorf("failed to parse response: %w", err)
+		}
+
+		results := searchResp.Results
+		if len(results) == 0 {
+			return fmt.Sprintf("No results for: %s", query), nil
+		}
+
+		var lines []string
+		lines = append(lines, fmt.Sprintf("Results for: %s (via Tavily)", query))
+		for i, item := range results {
+			if i >= count {
+				break
+			}
+			lines = append(lines, fmt.Sprintf("%d. %s\n   %s", i+1, item.Title, item.URL))
+			if item.Content != "" {
+				lines = append(lines, fmt.Sprintf("   %s", item.Content))
+			}
+		}
+
+		return strings.Join(lines, "\n"), nil
 	}
 
-	return strings.Join(lines, "\n"), nil
+	return "", fmt.Errorf("all api keys failed, last error: %w", lastErr)
 }
 
 type DuckDuckGoSearchProvider struct {
@@ -320,42 +376,195 @@ func stripTags(content string) string {
 }
 
 type PerplexitySearchProvider struct {
-	apiKey string
-	proxy  string
-	client *http.Client
+	keyPool *APIKeyPool
+	proxy   string
+	client  *http.Client
 }
 
 func (p *PerplexitySearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
 	searchURL := "https://api.perplexity.ai/chat/completions"
 
-	payload := map[string]any{
-		"model": "sonar",
-		"messages": []map[string]string{
-			{
-				"role":    "system",
-				"content": "You are a search assistant. Provide concise search results with titles, URLs, and brief descriptions in the following format:\n1. Title\n   URL\n   Description\n\nDo not add extra commentary.",
+	var lastErr error
+	iter := p.keyPool.NewIterator()
+
+	for {
+		apiKey, ok := iter.Next()
+		if !ok {
+			break
+		}
+
+		payload := map[string]any{
+			"model": "sonar",
+			"messages": []map[string]string{
+				{
+					"role":    "system",
+					"content": "You are a search assistant. Provide concise search results with titles, URLs, and brief descriptions in the following format:\n1. Title\n   URL\n   Description\n\nDo not add extra commentary.",
+				},
+				{
+					"role":    "user",
+					"content": fmt.Sprintf("Search for: %s. Provide up to %d relevant results.", query, count),
+				},
 			},
-			{
-				"role":    "user",
-				"content": fmt.Sprintf("Search for: %s. Provide up to %d relevant results.", query, count),
-			},
-		},
-		"max_tokens": 1000,
+			"max_tokens": 1000,
+		}
+
+		payloadBytes, err := json.Marshal(payload)
+		if err != nil {
+			return "", fmt.Errorf("failed to marshal request: %w", err)
+		}
+
+		req, err := http.NewRequestWithContext(ctx, "POST", searchURL, strings.NewReader(string(payloadBytes)))
+		if err != nil {
+			return "", fmt.Errorf("failed to create request: %w", err)
+		}
+
+		req.Header.Set("Content-Type", "application/json")
+		req.Header.Set("Authorization", "Bearer "+apiKey)
+		req.Header.Set("User-Agent", userAgent)
+
+		resp, err := p.client.Do(req)
+		if err != nil {
+			lastErr = fmt.Errorf("request failed: %w", err)
+			continue
+		}
+
+		body, err := io.ReadAll(resp.Body)
+		resp.Body.Close()
+
+		if err != nil {
+			lastErr = fmt.Errorf("failed to read response: %w", err)
+			continue
+		}
+
+		if resp.StatusCode != http.StatusOK {
+			lastErr = fmt.Errorf("Perplexity API error: %s", string(body))
+			if resp.StatusCode == http.StatusTooManyRequests ||
+				resp.StatusCode == http.StatusUnauthorized ||
+				resp.StatusCode == http.StatusForbidden ||
+				resp.StatusCode >= 500 {
+				continue
+			}
+			return "", lastErr
+		}
+
+		var searchResp struct {
+			Choices []struct {
+				Message struct {
+					Content string `json:"content"`
+				} `json:"message"`
+			} `json:"choices"`
+		}
+
+		if err := json.Unmarshal(body, &searchResp); err != nil {
+			return "", fmt.Errorf("failed to parse response: %w", err)
+		}
+
+		if len(searchResp.Choices) == 0 {
+			return fmt.Sprintf("No results for: %s", query), nil
+		}
+
+		return fmt.Sprintf("Results for: %s (via Perplexity)\n%s", query, searchResp.Choices[0].Message.Content), nil
 	}
 
-	payloadBytes, err := json.Marshal(payload)
+	return "", fmt.Errorf("all api keys failed, last error: %w", lastErr)
+}
+
+type SearXNGSearchProvider struct {
+	baseURL string
+}
+
+func (p *SearXNGSearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
+	searchURL := fmt.Sprintf("%s/search?q=%s&format=json&categories=general",
+		strings.TrimSuffix(p.baseURL, "/"),
+		url.QueryEscape(query))
+
+	req, err := http.NewRequestWithContext(ctx, "GET", searchURL, nil)
 	if err != nil {
-		return "", fmt.Errorf("failed to marshal request: %w", err)
+		return "", fmt.Errorf("failed to create request: %w", err)
 	}
 
-	req, err := http.NewRequestWithContext(ctx, "POST", searchURL, strings.NewReader(string(payloadBytes)))
+	client := &http.Client{Timeout: 10 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("SearXNG returned status %d", resp.StatusCode)
+	}
+
+	var result struct {
+		Results []struct {
+			Title   string  `json:"title"`
+			URL     string  `json:"url"`
+			Content string  `json:"content"`
+			Engine  string  `json:"engine"`
+			Score   float64 `json:"score"`
+		} `json:"results"`
+	}
+
+	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
+		return "", fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	if len(result.Results) == 0 {
+		return fmt.Sprintf("No results for: %s", query), nil
+	}
+
+	// Limit results to requested count
+	if len(result.Results) > count {
+		result.Results = result.Results[:count]
+	}
+
+	// Format results in standard PicoClaw format
+	var b strings.Builder
+	b.WriteString(fmt.Sprintf("Results for: %s (via SearXNG)\n", query))
+	for i, r := range result.Results {
+		b.WriteString(fmt.Sprintf("%d. %s\n", i+1, r.Title))
+		b.WriteString(fmt.Sprintf("   %s\n", r.URL))
+		if r.Content != "" {
+			b.WriteString(fmt.Sprintf("   %s\n", r.Content))
+		}
+	}
+
+	return b.String(), nil
+}
+
+type GLMSearchProvider struct {
+	apiKey       string
+	baseURL      string
+	searchEngine string
+	proxy        string
+	client       *http.Client
+}
+
+func (p *GLMSearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
+	searchURL := p.baseURL
+	if searchURL == "" {
+		searchURL = "https://open.bigmodel.cn/api/paas/v4/web_search"
+	}
+
+	payload := map[string]any{
+		"search_query":  query,
+		"search_engine": p.searchEngine,
+		"search_intent": false,
+		"count":         count,
+		"content_size":  "medium",
+	}
+
+	bodyBytes, err := json.Marshal(payload)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal payload: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", searchURL, bytes.NewReader(bodyBytes))
 	if err != nil {
 		return "", fmt.Errorf("failed to create request: %w", err)
 	}
 
 	req.Header.Set("Content-Type", "application/json")
 	req.Header.Set("Authorization", "Bearer "+p.apiKey)
-	req.Header.Set("User-Agent", userAgent)
 
 	resp, err := p.client.Do(req)
 	if err != nil {
@@ -363,32 +572,126 @@ func (p *PerplexitySearchProvider) Search(ctx context.Context, query string, cou
 	}
 	defer resp.Body.Close()
 
-	body, err := io.ReadAll(resp.Body)
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
 	if err != nil {
 		return "", fmt.Errorf("failed to read response: %w", err)
 	}
 
 	if resp.StatusCode != http.StatusOK {
-		return "", fmt.Errorf("Perplexity API error: %s", string(body))
+		return "", fmt.Errorf("GLM Search API error (status %d): %s", resp.StatusCode, string(body))
 	}
 
 	var searchResp struct {
-		Choices []struct {
-			Message struct {
-				Content string `json:"content"`
-			} `json:"message"`
-		} `json:"choices"`
+		SearchResult []struct {
+			Title   string `json:"title"`
+			Content string `json:"content"`
+			Link    string `json:"link"`
+		} `json:"search_result"`
 	}
 
 	if err := json.Unmarshal(body, &searchResp); err != nil {
 		return "", fmt.Errorf("failed to parse response: %w", err)
 	}
 
-	if len(searchResp.Choices) == 0 {
+	results := searchResp.SearchResult
+	if len(results) == 0 {
 		return fmt.Sprintf("No results for: %s", query), nil
 	}
 
-	return fmt.Sprintf("Results for: %s (via Perplexity)\n%s", query, searchResp.Choices[0].Message.Content), nil
+	var lines []string
+	lines = append(lines, fmt.Sprintf("Results for: %s (via GLM Search)", query))
+	for i, item := range results {
+		if i >= count {
+			break
+		}
+		lines = append(lines, fmt.Sprintf("%d. %s\n   %s", i+1, item.Title, item.Link))
+		if item.Content != "" {
+			lines = append(lines, fmt.Sprintf("   %s", item.Content))
+		}
+	}
+
+	return strings.Join(lines, "\n"), nil
+}
+
+type BaiduSearchProvider struct {
+	apiKey  string
+	baseURL string
+	proxy   string
+	client  *http.Client
+}
+
+func (p *BaiduSearchProvider) Search(ctx context.Context, query string, count int) (string, error) {
+	searchURL := p.baseURL
+	if searchURL == "" {
+		searchURL = "https://qianfan.baidubce.com/v2/ai_search/web_search"
+	}
+
+	payload := map[string]any{
+		"messages": []map[string]string{
+			{
+				"role":    "user",
+				"content": query,
+			},
+		},
+		"search_source":        "baidu_search_v2",
+		"resource_type_filter": []map[string]any{{"type": "web", "top_k": count}},
+	}
+
+	bodyBytes, err := json.Marshal(payload)
+	if err != nil {
+		return "", fmt.Errorf("failed to marshal payload: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, "POST", searchURL, bytes.NewReader(bodyBytes))
+	if err != nil {
+		return "", fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("Authorization", "Bearer "+p.apiKey)
+
+	resp, err := p.client.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("baidu search request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return "", fmt.Errorf("failed to read response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("baidu search API error %d: %s", resp.StatusCode, string(body))
+	}
+
+	var result struct {
+		References []struct {
+			Title   string `json:"title"`
+			URL     string `json:"url"`
+			Content string `json:"content"`
+		} `json:"references"`
+	}
+	if err := json.Unmarshal(body, &result); err != nil {
+		return "", fmt.Errorf("failed to parse response: %w", err)
+	}
+
+	if len(result.References) == 0 {
+		return fmt.Sprintf("No results for: %s", query), nil
+	}
+
+	lines := []string{fmt.Sprintf("Results for: %s (via Baidu Search)", query)}
+	for i, item := range result.References {
+		if i >= count {
+			break
+		}
+		lines = append(lines, fmt.Sprintf("%d. %s\n   %s", i+1, item.Title, item.URL))
+		if item.Content != "" {
+			lines = append(lines, fmt.Sprintf("   %s", item.Content))
+		}
+	}
+
+	return strings.Join(lines, "\n"), nil
 }
 
 type WebSearchTool struct {
@@ -397,51 +700,71 @@ type WebSearchTool struct {
 }
 
 type WebSearchToolOptions struct {
-	BraveAPIKey          string
-	BraveMaxResults      int
-	BraveEnabled         bool
-	TavilyAPIKey         string
-	TavilyBaseURL        string
-	TavilyMaxResults     int
-	TavilyEnabled        bool
-	DuckDuckGoMaxResults int
-	DuckDuckGoEnabled    bool
-	PerplexityAPIKey     string
-	PerplexityMaxResults int
-	PerplexityEnabled    bool
-	Proxy                string
+	BraveAPIKeys          []string
+	BraveMaxResults       int
+	BraveEnabled          bool
+	TavilyAPIKeys         []string
+	TavilyBaseURL         string
+	TavilyMaxResults      int
+	TavilyEnabled         bool
+	DuckDuckGoMaxResults  int
+	DuckDuckGoEnabled     bool
+	PerplexityAPIKeys     []string
+	PerplexityMaxResults  int
+	PerplexityEnabled     bool
+	SearXNGBaseURL        string
+	SearXNGMaxResults     int
+	SearXNGEnabled        bool
+	GLMSearchAPIKey       string
+	GLMSearchBaseURL      string
+	GLMSearchEngine       string
+	GLMSearchMaxResults   int
+	GLMSearchEnabled      bool
+	BaiduSearchAPIKey     string
+	BaiduSearchBaseURL    string
+	BaiduSearchMaxResults int
+	BaiduSearchEnabled    bool
+	Proxy                 string
 }
 
 func NewWebSearchTool(opts WebSearchToolOptions) (*WebSearchTool, error) {
 	var provider SearchProvider
 	maxResults := 5
-
-	// Priority: Perplexity > Brave > Tavily > DuckDuckGo
-	if opts.PerplexityEnabled && opts.PerplexityAPIKey != "" {
-		client, err := createHTTPClient(opts.Proxy, perplexityTimeout)
+	// Priority: Perplexity > Brave > SearXNG > Tavily > DuckDuckGo > Baidu Search > GLM Search
+	if opts.PerplexityEnabled && len(opts.PerplexityAPIKeys) > 0 {
+		client, err := utils.CreateHTTPClient(opts.Proxy, perplexityTimeout)
 		if err != nil {
 			return nil, fmt.Errorf("failed to create HTTP client for Perplexity: %w", err)
 		}
-		provider = &PerplexitySearchProvider{apiKey: opts.PerplexityAPIKey, proxy: opts.Proxy, client: client}
+		provider = &PerplexitySearchProvider{
+			keyPool: NewAPIKeyPool(opts.PerplexityAPIKeys),
+			proxy:   opts.Proxy,
+			client:  client,
+		}
 		if opts.PerplexityMaxResults > 0 {
 			maxResults = opts.PerplexityMaxResults
 		}
-	} else if opts.BraveEnabled && opts.BraveAPIKey != "" {
-		client, err := createHTTPClient(opts.Proxy, searchTimeout)
+	} else if opts.BraveEnabled && len(opts.BraveAPIKeys) > 0 {
+		client, err := utils.CreateHTTPClient(opts.Proxy, searchTimeout)
 		if err != nil {
 			return nil, fmt.Errorf("failed to create HTTP client for Brave: %w", err)
 		}
-		provider = &BraveSearchProvider{apiKey: opts.BraveAPIKey, proxy: opts.Proxy, client: client}
+		provider = &BraveSearchProvider{keyPool: NewAPIKeyPool(opts.BraveAPIKeys), proxy: opts.Proxy, client: client}
 		if opts.BraveMaxResults > 0 {
 			maxResults = opts.BraveMaxResults
 		}
-	} else if opts.TavilyEnabled && opts.TavilyAPIKey != "" {
-		client, err := createHTTPClient(opts.Proxy, searchTimeout)
+	} else if opts.SearXNGEnabled && opts.SearXNGBaseURL != "" {
+		provider = &SearXNGSearchProvider{baseURL: opts.SearXNGBaseURL}
+		if opts.SearXNGMaxResults > 0 {
+			maxResults = opts.SearXNGMaxResults
+		}
+	} else if opts.TavilyEnabled && len(opts.TavilyAPIKeys) > 0 {
+		client, err := utils.CreateHTTPClient(opts.Proxy, searchTimeout)
 		if err != nil {
 			return nil, fmt.Errorf("failed to create HTTP client for Tavily: %w", err)
 		}
 		provider = &TavilySearchProvider{
-			apiKey:  opts.TavilyAPIKey,
+			keyPool: NewAPIKeyPool(opts.TavilyAPIKeys),
 			baseURL: opts.TavilyBaseURL,
 			proxy:   opts.Proxy,
 			client:  client,
@@ -450,7 +773,7 @@ func NewWebSearchTool(opts WebSearchToolOptions) (*WebSearchTool, error) {
 			maxResults = opts.TavilyMaxResults
 		}
 	} else if opts.DuckDuckGoEnabled {
-		client, err := createHTTPClient(opts.Proxy, searchTimeout)
+		client, err := utils.CreateHTTPClient(opts.Proxy, searchTimeout)
 		if err != nil {
 			return nil, fmt.Errorf("failed to create HTTP client for DuckDuckGo: %w", err)
 		}
@@ -458,6 +781,39 @@ func NewWebSearchTool(opts WebSearchToolOptions) (*WebSearchTool, error) {
 		if opts.DuckDuckGoMaxResults > 0 {
 			maxResults = opts.DuckDuckGoMaxResults
 		}
+	} else if opts.BaiduSearchEnabled && opts.BaiduSearchAPIKey != "" {
+		client, err := utils.CreateHTTPClient(opts.Proxy, perplexityTimeout)
+		if err != nil {
+			return nil, fmt.Errorf("failed to create HTTP client for Baidu Search: %w", err)
+		}
+		provider = &BaiduSearchProvider{
+			apiKey:  opts.BaiduSearchAPIKey,
+			baseURL: opts.BaiduSearchBaseURL,
+			proxy:   opts.Proxy,
+			client:  client,
+		}
+		if opts.BaiduSearchMaxResults > 0 {
+			maxResults = opts.BaiduSearchMaxResults
+		}
+	} else if opts.GLMSearchEnabled && opts.GLMSearchAPIKey != "" {
+		client, err := utils.CreateHTTPClient(opts.Proxy, searchTimeout)
+		if err != nil {
+			return nil, fmt.Errorf("failed to create HTTP client for GLM Search: %w", err)
+		}
+		searchEngine := opts.GLMSearchEngine
+		if searchEngine == "" {
+			searchEngine = "search_std"
+		}
+		provider = &GLMSearchProvider{
+			apiKey:       opts.GLMSearchAPIKey,
+			baseURL:      opts.GLMSearchBaseURL,
+			searchEngine: searchEngine,
+			proxy:        opts.Proxy,
+			client:       client,
+		}
+		if opts.GLMSearchMaxResults > 0 {
+			maxResults = opts.GLMSearchMaxResults
+		}
 	} else {
 		return nil, nil
 	}
@@ -523,26 +879,67 @@ type WebFetchTool struct {
 	maxChars        int
 	proxy           string
 	client          *http.Client
+	format          string
 	fetchLimitBytes int64
+	whitelist       *privateHostWhitelist
 }
 
-func NewWebFetchTool(maxChars int, fetchLimitBytes int64) (*WebFetchTool, error) {
+type privateHostWhitelist struct {
+	exact map[string]struct{}
+	cidrs []*net.IPNet
+}
+
+func NewWebFetchTool(maxChars int, format string, fetchLimitBytes int64) (*WebFetchTool, error) {
 	// createHTTPClient cannot fail with an empty proxy string.
-	return NewWebFetchToolWithProxy(maxChars, "", fetchLimitBytes)
+	return NewWebFetchToolWithConfig(maxChars, "", format, fetchLimitBytes, nil)
 }
 
-func NewWebFetchToolWithProxy(maxChars int, proxy string, fetchLimitBytes int64) (*WebFetchTool, error) {
+// allowPrivateWebFetchHosts controls whether loopback/private hosts are allowed.
+// This is false in normal runtime to reduce SSRF exposure, and tests can override it temporarily.
+var allowPrivateWebFetchHosts atomic.Bool
+
+func NewWebFetchToolWithProxy(
+	maxChars int,
+	proxy string,
+	format string,
+	fetchLimitBytes int64,
+	privateHostWhitelist []string,
+) (*WebFetchTool, error) {
+	return NewWebFetchToolWithConfig(maxChars, proxy, format, fetchLimitBytes, privateHostWhitelist)
+}
+
+func NewWebFetchToolWithConfig(
+	maxChars int,
+	proxy string,
+	format string,
+	fetchLimitBytes int64,
+	privateHostWhitelist []string,
+) (*WebFetchTool, error) {
 	if maxChars <= 0 {
 		maxChars = defaultMaxChars
 	}
-	client, err := createHTTPClient(proxy, fetchTimeout)
+	whitelist, err := newPrivateHostWhitelist(privateHostWhitelist)
+	if err != nil {
+		return nil, fmt.Errorf("failed to parse web fetch private host whitelist: %w", err)
+	}
+	client, err := utils.CreateHTTPClient(proxy, fetchTimeout)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create HTTP client for web fetch: %w", err)
 	}
+	if transport, ok := client.Transport.(*http.Transport); ok {
+		dialer := &net.Dialer{
+			Timeout:   15 * time.Second,
+			KeepAlive: 30 * time.Second,
+		}
+		transport.DialContext = newSafeDialContext(dialer, whitelist)
+	}
 	client.CheckRedirect = func(req *http.Request, via []*http.Request) error {
 		if len(via) >= maxRedirects {
 			return fmt.Errorf("stopped after %d redirects", maxRedirects)
 		}
+		if isObviousPrivateHost(req.URL.Hostname(), whitelist) {
+			return fmt.Errorf("redirect target is private or local network host")
+		}
 		return nil
 	}
 	if fetchLimitBytes <= 0 {
@@ -552,7 +949,9 @@ func NewWebFetchToolWithProxy(maxChars int, proxy string, fetchLimitBytes int64)
 		maxChars:        maxChars,
 		proxy:           proxy,
 		client:          client,
+		format:          format,
 		fetchLimitBytes: fetchLimitBytes,
+		whitelist:       whitelist,
 	}, nil
 }
 
@@ -601,6 +1000,13 @@ func (t *WebFetchTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 		return ErrorResult("missing domain in URL")
 	}
 
+	// Lightweight pre-flight: block obvious localhost/literal-IP without DNS resolution.
+	// The real SSRF guard is newSafeDialContext at connect time.
+	hostname := parsedURL.Hostname()
+	if isObviousPrivateHost(hostname, t.whitelist) {
+		return ErrorResult("fetching private or local network hosts is not allowed")
+	}
+
 	maxChars := t.maxChars
 	if mc, ok := args["maxChars"].(float64); ok {
 		if int(mc) > 100 {
@@ -608,57 +1014,128 @@ func (t *WebFetchTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 		}
 	}
 
-	req, err := http.NewRequestWithContext(ctx, "GET", urlStr, nil)
-	if err != nil {
-		return ErrorResult(fmt.Sprintf("failed to create request: %v", err))
+	doFetch := func(ua string) (*http.Response, []byte, error) {
+		req, reqErr := http.NewRequestWithContext(ctx, "GET", urlStr, nil)
+		if reqErr != nil {
+			return nil, nil, fmt.Errorf("failed to create request: %w", reqErr)
+		}
+		req.Header.Set("User-Agent", ua)
+		resp, doErr := t.client.Do(req)
+		if doErr != nil {
+			return nil, nil, fmt.Errorf("request failed: %w", doErr)
+		}
+		resp.Body = http.MaxBytesReader(nil, resp.Body, t.fetchLimitBytes)
+
+		b, readErr := io.ReadAll(resp.Body)
+		return resp, b, readErr
 	}
 
-	req.Header.Set("User-Agent", userAgent)
-
-	resp, err := t.client.Do(req)
-	if err != nil {
-		return ErrorResult(fmt.Sprintf("request failed: %v", err))
+	resp, body, err := doFetch(userAgent)
+	if resp != nil && resp.Body != nil {
+		defer resp.Body.Close()
 	}
 
-	resp.Body = http.MaxBytesReader(nil, resp.Body, t.fetchLimitBytes)
-
-	defer resp.Body.Close()
-
-	body, err := io.ReadAll(resp.Body)
 	if err != nil {
 		var maxBytesErr *http.MaxBytesError
 		if errors.As(err, &maxBytesErr) {
 			return ErrorResult(fmt.Sprintf("failed to read response: size exceeded %d bytes limit", t.fetchLimitBytes))
 		}
-		return ErrorResult(fmt.Sprintf("failed to read response: %v", err))
+		return ErrorResult(err.Error())
 	}
 
+	// Cloudflare (and similar WAFs) signal bot challenges with 403 + cf-mitigated: challenge.
+	// Retry once with an honest User-Agent that identifies picoclaw, which some
+	// operators explicitly allow-list for AI assistants.
+	if resp.StatusCode == http.StatusForbidden && resp.Header.Get("Cf-Mitigated") == "challenge" {
+		logger.DebugCF("tool", "Cloudflare challenge detected, retrying with honest User-Agent",
+			map[string]any{"url": urlStr})
+		honestUA := fmt.Sprintf(userAgentHonest, config.Version)
+		resp2, body2, err2 := doFetch(honestUA)
+		if resp2 != nil && resp2.Body != nil {
+			defer resp2.Body.Close()
+		}
+
+		if err2 == nil {
+			resp, body = resp2, body2
+		} else {
+			var maxBytesErr *http.MaxBytesError
+			if errors.As(err2, &maxBytesErr) {
+				return ErrorResult(
+					fmt.Sprintf("failed to read response: size exceeded %d bytes limit", t.fetchLimitBytes),
+				)
+			}
+			return ErrorResult(err2.Error())
+		}
+	}
+
+	bodyStr := string(body)
 	contentType := resp.Header.Get("Content-Type")
 
+	mediaType, params, err := mime.ParseMediaType(contentType)
+	if err != nil {
+		// The most common error here is "mime: no media type" if the header is empty.
+		logger.WarnCF("tool", "Failed to parse Content-Type", map[string]any{
+			"raw_header": contentType,
+			"error":      err.Error(),
+		})
+
+		// security fallback
+		mediaType = "application/octet-stream"
+	}
+
+	charset, hasCharset := params["charset"]
+	if hasCharset {
+		// If the charset is not utf-8, we might have to convert the bodyStr
+		// before passing it to the HTML/Markdown parser
+		if strings.ToLower(charset) != "utf-8" {
+			logger.WarnCF("tool", "Note: the content is not in UTF-8", map[string]any{"charset": charset})
+		}
+	}
+
 	var text, extractor string
 
-	if strings.Contains(contentType, "application/json") {
+	switch {
+	case mediaType == "application/json":
 		var jsonData any
-		if err := json.Unmarshal(body, &jsonData); err == nil {
-			formatted, _ := json.MarshalIndent(jsonData, "", "  ")
-			text = string(formatted)
-			extractor = "json"
-		} else {
-			text = string(body)
+		if err := json.Unmarshal(body, &jsonData); err != nil {
+			text = bodyStr
 			extractor = "raw"
+			break
 		}
-	} else if strings.Contains(contentType, "text/html") || len(body) > 0 &&
-		(strings.HasPrefix(string(body), "<!DOCTYPE") || strings.HasPrefix(strings.ToLower(string(body)), "<html")) {
-		text = t.extractText(string(body))
-		extractor = "text"
-	} else {
-		text = string(body)
+
+		formatted, err := json.MarshalIndent(jsonData, "", "  ")
+		if err != nil {
+			text = bodyStr
+			extractor = "raw"
+			break
+		}
+
+		text = string(formatted)
+		extractor = "json"
+
+	case mediaType == "text/html" || looksLikeHTML(bodyStr):
+		switch strings.ToLower(t.format) {
+		case "markdown":
+			var err error
+			text, err = utils.HtmlToMarkdown(bodyStr)
+			if err != nil {
+				return ErrorResult(fmt.Sprintf("failed to HTML to markdown: %v", err))
+			}
+			extractor = "markdown"
+
+		default:
+			text = t.extractText(bodyStr)
+			extractor = "text"
+		}
+
+	default:
+		text = bodyStr
 		extractor = "raw"
 	}
 
 	truncated := len(text) > maxChars
 	if truncated {
-		text = text[:maxChars]
+		text = text[:maxChars] + "\n[Content truncated due to size limit]"
 	}
 
 	result := map[string]any{
@@ -684,6 +1161,17 @@ func (t *WebFetchTool) Execute(ctx context.Context, args map[string]any) *ToolRe
 	}
 }
 
+func looksLikeHTML(body string) bool {
+	if body == "" {
+		return false
+	}
+
+	lower := strings.ToLower(body)
+
+	return strings.HasPrefix(body, "<!doctype") ||
+		strings.HasPrefix(lower, "<html")
+}
+
 func (t *WebFetchTool) extractText(htmlContent string) string {
 	result := reScript.ReplaceAllLiteralString(htmlContent, "")
 	result = reStyle.ReplaceAllLiteralString(result, "")
@@ -705,3 +1193,192 @@ func (t *WebFetchTool) extractText(htmlContent string) string {
 
 	return strings.Join(cleanLines, "\n")
 }
+
+// newSafeDialContext re-resolves DNS at connect time to mitigate DNS rebinding (TOCTOU)
+// where a hostname resolves to a public IP during pre-flight but a private IP at connect time.
+func newSafeDialContext(
+	dialer *net.Dialer,
+	whitelist *privateHostWhitelist,
+) func(context.Context, string, string) (net.Conn, error) {
+	return func(ctx context.Context, network, address string) (net.Conn, error) {
+		if allowPrivateWebFetchHosts.Load() {
+			return dialer.DialContext(ctx, network, address)
+		}
+
+		host, port, err := net.SplitHostPort(address)
+		if err != nil {
+			return nil, fmt.Errorf("invalid target address %q: %w", address, err)
+		}
+		if host == "" {
+			return nil, fmt.Errorf("empty target host")
+		}
+
+		if ip := net.ParseIP(host); ip != nil {
+			if shouldBlockPrivateIP(ip, whitelist) {
+				return nil, fmt.Errorf("blocked private or local target: %s", host)
+			}
+			return dialer.DialContext(ctx, network, net.JoinHostPort(ip.String(), port))
+		}
+
+		ipAddrs, err := net.DefaultResolver.LookupIPAddr(ctx, host)
+		if err != nil {
+			return nil, fmt.Errorf("failed to resolve %s: %w", host, err)
+		}
+
+		attempted := 0
+		var lastErr error
+		for _, ipAddr := range ipAddrs {
+			if shouldBlockPrivateIP(ipAddr.IP, whitelist) {
+				continue
+			}
+			attempted++
+			conn, err := dialer.DialContext(ctx, network, net.JoinHostPort(ipAddr.IP.String(), port))
+			if err == nil {
+				return conn, nil
+			}
+			lastErr = err
+		}
+
+		if attempted == 0 {
+			return nil, fmt.Errorf("all resolved addresses for %s are private, restricted, or not whitelisted", host)
+		}
+		if lastErr != nil {
+			return nil, fmt.Errorf("failed connecting to public addresses for %s: %w", host, lastErr)
+		}
+		return nil, fmt.Errorf("failed connecting to public addresses for %s", host)
+	}
+}
+
+func newPrivateHostWhitelist(entries []string) (*privateHostWhitelist, error) {
+	if len(entries) == 0 {
+		return nil, nil
+	}
+
+	whitelist := &privateHostWhitelist{
+		exact: make(map[string]struct{}),
+		cidrs: make([]*net.IPNet, 0, len(entries)),
+	}
+	for _, entry := range entries {
+		entry = strings.TrimSpace(entry)
+		if entry == "" {
+			continue
+		}
+		if ip := net.ParseIP(entry); ip != nil {
+			whitelist.exact[normalizeWhitelistIP(ip).String()] = struct{}{}
+			continue
+		}
+		_, network, err := net.ParseCIDR(entry)
+		if err != nil {
+			return nil, fmt.Errorf("invalid entry %q: expected IP or CIDR", entry)
+		}
+		whitelist.cidrs = append(whitelist.cidrs, network)
+	}
+
+	if len(whitelist.exact) == 0 && len(whitelist.cidrs) == 0 {
+		return nil, nil
+	}
+	return whitelist, nil
+}
+
+func (w *privateHostWhitelist) Contains(ip net.IP) bool {
+	if w == nil || ip == nil {
+		return false
+	}
+
+	normalized := normalizeWhitelistIP(ip)
+	if _, ok := w.exact[normalized.String()]; ok {
+		return true
+	}
+	for _, network := range w.cidrs {
+		if network.Contains(normalized) {
+			return true
+		}
+	}
+	return false
+}
+
+func normalizeWhitelistIP(ip net.IP) net.IP {
+	if ip == nil {
+		return nil
+	}
+	if ip4 := ip.To4(); ip4 != nil {
+		return ip4
+	}
+	return ip
+}
+
+func shouldBlockPrivateIP(ip net.IP, whitelist *privateHostWhitelist) bool {
+	return isPrivateOrRestrictedIP(ip) && !whitelist.Contains(ip)
+}
+
+// isObviousPrivateHost performs a lightweight, no-DNS check for obviously private hosts.
+// It catches localhost, literal private IPs, and empty hosts. It does NOT resolve DNS —
+// the real SSRF guard is newSafeDialContext which checks IPs at connect time.
+func isObviousPrivateHost(host string, whitelist *privateHostWhitelist) bool {
+	if allowPrivateWebFetchHosts.Load() {
+		return false
+	}
+
+	h := strings.ToLower(strings.TrimSpace(host))
+	h = strings.TrimSuffix(h, ".")
+	if h == "" {
+		return true
+	}
+
+	if h == "localhost" || strings.HasSuffix(h, ".localhost") {
+		return true
+	}
+
+	if ip := net.ParseIP(h); ip != nil {
+		return shouldBlockPrivateIP(ip, whitelist)
+	}
+
+	return false
+}
+
+// isPrivateOrRestrictedIP returns true for IPs that should never be reached via web_fetch:
+// RFC 1918, loopback, link-local (incl. cloud metadata 169.254.x.x), carrier-grade NAT,
+// IPv6 unique-local (fc00::/7), 6to4 (2002::/16), and Teredo (2001:0000::/32).
+func isPrivateOrRestrictedIP(ip net.IP) bool {
+	if ip == nil {
+		return true
+	}
+
+	if ip.IsLoopback() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() ||
+		ip.IsMulticast() || ip.IsUnspecified() {
+		return true
+	}
+
+	if ip4 := ip.To4(); ip4 != nil {
+		// IPv4 private, loopback, link-local, and carrier-grade NAT ranges.
+		if ip4[0] == 10 ||
+			ip4[0] == 127 ||
+			ip4[0] == 0 ||
+			(ip4[0] == 172 && ip4[1] >= 16 && ip4[1] <= 31) ||
+			(ip4[0] == 192 && ip4[1] == 168) ||
+			(ip4[0] == 169 && ip4[1] == 254) ||
+			(ip4[0] == 100 && ip4[1] >= 64 && ip4[1] <= 127) {
+			return true
+		}
+		return false
+	}
+
+	if len(ip) == net.IPv6len {
+		// IPv6 unique local addresses (fc00::/7)
+		if (ip[0] & 0xfe) == 0xfc {
+			return true
+		}
+		// 6to4 addresses (2002::/16): check the embedded IPv4 at bytes [2:6].
+		if ip[0] == 0x20 && ip[1] == 0x02 {
+			embedded := net.IPv4(ip[2], ip[3], ip[4], ip[5])
+			return isPrivateOrRestrictedIP(embedded)
+		}
+		// Teredo (2001:0000::/32): client IPv4 is at bytes [12:16], XOR-inverted.
+		if ip[0] == 0x20 && ip[1] == 0x01 && ip[2] == 0x00 && ip[3] == 0x00 {
+			client := net.IPv4(ip[12]^0xff, ip[13]^0xff, ip[14]^0xff, ip[15]^0xff)
+			return isPrivateOrRestrictedIP(client)
+		}
+	}
+
+	return false
+}
diff --git a/pkg/tools/web_test.go b/pkg/tools/web_test.go
index 8a8b88131..98c763193 100644
--- a/pkg/tools/web_test.go
+++ b/pkg/tools/web_test.go
@@ -5,6 +5,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@@ -14,10 +15,15 @@ import (
 	"github.com/sipeed/picoclaw/pkg/logger"
 )
 
-const testFetchLimit = int64(10 * 1024 * 1024)
+const (
+	testFetchLimit = int64(10 * 1024 * 1024)
+	format         = "plaintext"
+)
 
 // TestWebTool_WebFetch_Success verifies successful URL fetching
 func TestWebTool_WebFetch_Success(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "text/html")
 		w.WriteHeader(http.StatusOK)
@@ -25,7 +31,7 @@ func TestWebTool_WebFetch_Success(t *testing.T) {
 	}))
 	defer server.Close()
 
-	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
 	if err != nil {
 		t.Fatalf("Failed to create web fetch tool: %v", err)
 	}
@@ -55,6 +61,8 @@ func TestWebTool_WebFetch_Success(t *testing.T) {
 
 // TestWebTool_WebFetch_JSON verifies JSON content handling
 func TestWebTool_WebFetch_JSON(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
 	testData := map[string]string{"key": "value", "number": "123"}
 	expectedJSON, _ := json.MarshalIndent(testData, "", "  ")
 
@@ -65,7 +73,7 @@ func TestWebTool_WebFetch_JSON(t *testing.T) {
 	}))
 	defer server.Close()
 
-	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
 	if err != nil {
 		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
 	}
@@ -90,7 +98,7 @@ func TestWebTool_WebFetch_JSON(t *testing.T) {
 
 // TestWebTool_WebFetch_InvalidURL verifies error handling for invalid URL
 func TestWebTool_WebFetch_InvalidURL(t *testing.T) {
-	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
 	if err != nil {
 		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
 	}
@@ -115,7 +123,7 @@ func TestWebTool_WebFetch_InvalidURL(t *testing.T) {
 
 // TestWebTool_WebFetch_UnsupportedScheme verifies error handling for non-http URLs
 func TestWebTool_WebFetch_UnsupportedScheme(t *testing.T) {
-	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
 	if err != nil {
 		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
 	}
@@ -140,7 +148,7 @@ func TestWebTool_WebFetch_UnsupportedScheme(t *testing.T) {
 
 // TestWebTool_WebFetch_MissingURL verifies error handling for missing URL
 func TestWebTool_WebFetch_MissingURL(t *testing.T) {
-	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
 	if err != nil {
 		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
 	}
@@ -163,6 +171,8 @@ func TestWebTool_WebFetch_MissingURL(t *testing.T) {
 
 // TestWebTool_WebFetch_Truncation verifies content truncation
 func TestWebTool_WebFetch_Truncation(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
 	longContent := strings.Repeat("x", 20000)
 
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
@@ -172,7 +182,7 @@ func TestWebTool_WebFetch_Truncation(t *testing.T) {
 	}))
 	defer server.Close()
 
-	tool, err := NewWebFetchTool(1000, testFetchLimit) // Limit to 1000 chars
+	tool, err := NewWebFetchTool(1000, format, testFetchLimit) // Limit to 1000 chars
 	if err != nil {
 		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
 	}
@@ -202,9 +212,137 @@ func TestWebTool_WebFetch_Truncation(t *testing.T) {
 	if truncated, ok := resultMap["truncated"].(bool); !ok || !truncated {
 		t.Errorf("Expected 'truncated' to be true in result")
 	}
+
+	// Text should end with the truncation notice
+	if text, ok := resultMap["text"].(string); ok {
+		if !strings.HasSuffix(text, "[Content truncated due to size limit]") {
+			t.Errorf("Expected text to end with truncation notice, got: %q", text[max(0, len(text)-60):])
+		}
+	}
+}
+
+// TestWebTool_WebFetch_TruncationNotice verifies the truncation notice is appended
+// for all content formats (text/plain, text/html, markdown, application/json).
+func TestWebTool_WebFetch_TruncationNotice(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
+	const truncationNotice = "[Content truncated due to size limit]"
+	const maxChars = 100
+
+	tests := []struct {
+		name        string
+		contentType string
+		body        string
+		format      string
+	}{
+		{
+			name:        "plain text",
+			contentType: "text/plain",
+			body:        strings.Repeat("a", 500),
+			format:      "plaintext",
+		},
+		{
+			name:        "html plaintext extractor",
+			contentType: "text/html",
+			body:        "<html><body>" + strings.Repeat("b", 500) + "</body></html>",
+			format:      "plaintext",
+		},
+		{
+			name:        "html markdown extractor",
+			contentType: "text/html",
+			body:        "<html><body>" + strings.Repeat("c", 500) + "</body></html>",
+			format:      "markdown",
+		},
+		{
+			name:        "json",
+			contentType: "application/json",
+			body:        `"` + strings.Repeat("d", 500) + `"`,
+			format:      "plaintext",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.Header().Set("Content-Type", tt.contentType)
+				w.WriteHeader(http.StatusOK)
+				w.Write([]byte(tt.body))
+			}))
+			defer server.Close()
+
+			tool, err := NewWebFetchTool(maxChars, tt.format, testFetchLimit)
+			if err != nil {
+				t.Fatalf("NewWebFetchTool() error: %v", err)
+			}
+
+			result := tool.Execute(context.Background(), map[string]any{"url": server.URL})
+			if result.IsError {
+				t.Fatalf("unexpected error: %s", result.ForLLM)
+			}
+
+			var resultMap map[string]any
+			if err := json.Unmarshal([]byte(result.ForLLM), &resultMap); err != nil {
+				t.Fatalf("failed to unmarshal result JSON: %v", err)
+			}
+
+			text, ok := resultMap["text"].(string)
+			if !ok {
+				t.Fatal("missing 'text' field in result")
+			}
+
+			if !strings.HasSuffix(text, truncationNotice) {
+				t.Errorf("expected text to end with %q, got suffix: %q", truncationNotice, text[max(0, len(text)-60):])
+			}
+
+			if truncated, ok := resultMap["truncated"].(bool); !ok || !truncated {
+				t.Errorf("expected truncated=true in result")
+			}
+		})
+	}
+}
+
+// TestWebTool_WebFetch_NoTruncationNoticeWhenFitsInLimit verifies that the notice
+// is NOT appended when the content fits within the limit.
+func TestWebTool_WebFetch_NoTruncationNoticeWhenFitsInLimit(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
+	const truncationNotice = "[Content truncated due to size limit]"
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("short content"))
+	}))
+	defer server.Close()
+
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("NewWebFetchTool() error: %v", err)
+	}
+
+	result := tool.Execute(context.Background(), map[string]any{"url": server.URL})
+	if result.IsError {
+		t.Fatalf("unexpected error: %s", result.ForLLM)
+	}
+
+	var resultMap map[string]any
+	if err := json.Unmarshal([]byte(result.ForLLM), &resultMap); err != nil {
+		t.Fatalf("failed to unmarshal result JSON: %v", err)
+	}
+
+	text, _ := resultMap["text"].(string)
+	if strings.Contains(text, truncationNotice) {
+		t.Errorf("expected no truncation notice for content within limit, got: %q", text)
+	}
+
+	if truncated, _ := resultMap["truncated"].(bool); truncated {
+		t.Errorf("expected truncated=false for content within limit")
+	}
 }
 
 func TestWebFetchTool_PayloadTooLarge(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
 	// Create a mock HTTP server
 	ts := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "text/html")
@@ -220,7 +358,7 @@ func TestWebFetchTool_PayloadTooLarge(t *testing.T) {
 	defer ts.Close()
 
 	// Initialize the tool
-	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
 	if err != nil {
 		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
 	}
@@ -249,7 +387,7 @@ func TestWebFetchTool_PayloadTooLarge(t *testing.T) {
 
 // TestWebTool_WebSearch_NoApiKey verifies that no tool is created when API key is missing
 func TestWebTool_WebSearch_NoApiKey(t *testing.T) {
-	tool, err := NewWebSearchTool(WebSearchToolOptions{BraveEnabled: true, BraveAPIKey: ""})
+	tool, err := NewWebSearchTool(WebSearchToolOptions{BraveEnabled: true, BraveAPIKeys: nil})
 	if err != nil {
 		t.Fatalf("Unexpected error: %v", err)
 	}
@@ -269,7 +407,11 @@ func TestWebTool_WebSearch_NoApiKey(t *testing.T) {
 
 // TestWebTool_WebSearch_MissingQuery verifies error handling for missing query
 func TestWebTool_WebSearch_MissingQuery(t *testing.T) {
-	tool, err := NewWebSearchTool(WebSearchToolOptions{BraveEnabled: true, BraveAPIKey: "test-key", BraveMaxResults: 5})
+	tool, err := NewWebSearchTool(WebSearchToolOptions{
+		BraveEnabled:    true,
+		BraveAPIKeys:    []string{"test-key"},
+		BraveMaxResults: 5,
+	})
 	if err != nil {
 		t.Fatalf("Unexpected error: %v", err)
 	}
@@ -286,6 +428,8 @@ func TestWebTool_WebSearch_MissingQuery(t *testing.T) {
 
 // TestWebTool_WebFetch_HTMLExtraction verifies HTML text extraction
 func TestWebTool_WebFetch_HTMLExtraction(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "text/html")
 		w.WriteHeader(http.StatusOK)
@@ -297,7 +441,7 @@ func TestWebTool_WebFetch_HTMLExtraction(t *testing.T) {
 	}))
 	defer server.Close()
 
-	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
 	if err != nil {
 		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
 	}
@@ -400,9 +544,344 @@ func TestWebFetchTool_extractText(t *testing.T) {
 	}
 }
 
+func withPrivateWebFetchHostsAllowed(t *testing.T) {
+	t.Helper()
+	previous := allowPrivateWebFetchHosts.Load()
+	allowPrivateWebFetchHosts.Store(true)
+	t.Cleanup(func() {
+		allowPrivateWebFetchHosts.Store(previous)
+	})
+}
+
+func serverHostAndPort(t *testing.T, rawURL string) (string, string) {
+	t.Helper()
+	hostPort := strings.TrimPrefix(rawURL, "http://")
+	hostPort = strings.TrimPrefix(hostPort, "https://")
+	host, port, err := net.SplitHostPort(hostPort)
+	if err != nil {
+		t.Fatalf("failed to split host/port from %q: %v", rawURL, err)
+	}
+	return host, port
+}
+
+func singleHostCIDR(t *testing.T, host string) string {
+	t.Helper()
+	ip := net.ParseIP(host)
+	if ip == nil {
+		t.Fatalf("failed to parse IP %q", host)
+	}
+	if ip.To4() != nil {
+		return ip.String() + "/32"
+	}
+	return ip.String() + "/128"
+}
+
+func TestWebTool_WebFetch_PrivateHostBlocked(t *testing.T) {
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("Failed to create web fetch tool: %v", err)
+	}
+	result := tool.Execute(context.Background(), map[string]any{
+		"url": "http://127.0.0.1:0",
+	})
+
+	if !result.IsError {
+		t.Errorf("expected error for private host URL, got success")
+	}
+	if !strings.Contains(result.ForLLM, "private or local network") &&
+		!strings.Contains(result.ForUser, "private or local network") {
+		t.Errorf("expected private host block message, got %q", result.ForLLM)
+	}
+}
+
+func TestWebTool_WebFetch_PrivateHostAllowedByExactWhitelist(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("exact whitelist ok"))
+	}))
+	defer server.Close()
+
+	host, _ := serverHostAndPort(t, server.URL)
+	tool, err := NewWebFetchToolWithConfig(50000, "", format, testFetchLimit, []string{host})
+	if err != nil {
+		t.Fatalf("Failed to create web fetch tool: %v", err)
+	}
+
+	result := tool.Execute(context.Background(), map[string]any{
+		"url": server.URL,
+	})
+	if result.IsError {
+		t.Fatalf("expected success for exact whitelisted private IP, got %q", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "exact whitelist ok") {
+		t.Fatalf("expected fetched content, got %q", result.ForLLM)
+	}
+}
+
+func TestWebTool_WebFetch_PrivateHostAllowedByCIDRWhitelist(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("cidr whitelist ok"))
+	}))
+	defer server.Close()
+
+	host, _ := serverHostAndPort(t, server.URL)
+	tool, err := NewWebFetchToolWithConfig(50000, "", format, testFetchLimit, []string{singleHostCIDR(t, host)})
+	if err != nil {
+		t.Fatalf("Failed to create web fetch tool: %v", err)
+	}
+
+	result := tool.Execute(context.Background(), map[string]any{
+		"url": server.URL,
+	})
+	if result.IsError {
+		t.Fatalf("expected success for CIDR-whitelisted private IP, got %q", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "cidr whitelist ok") {
+		t.Fatalf("expected fetched content, got %q", result.ForLLM)
+	}
+}
+
+func TestWebTool_WebFetch_PrivateHostAllowedForTests(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("ok"))
+	}))
+	defer server.Close()
+
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("Failed to create web fetch tool: %v", err)
+	}
+	result := tool.Execute(context.Background(), map[string]any{
+		"url": server.URL,
+	})
+
+	if result.IsError {
+		t.Errorf("expected success when private host access is allowed in tests, got %q", result.ForLLM)
+	}
+}
+
+// TestWebFetch_BlocksIPv4MappedIPv6Loopback verifies ::ffff:127.0.0.1 is blocked
+func TestWebFetch_BlocksIPv4MappedIPv6Loopback(t *testing.T) {
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("Failed to create web fetch tool: %v", err)
+	}
+	result := tool.Execute(context.Background(), map[string]any{
+		"url": "http://[::ffff:127.0.0.1]:0",
+	})
+
+	if !result.IsError {
+		t.Error("expected error for IPv4-mapped IPv6 loopback URL, got success")
+	}
+}
+
+// TestWebFetch_BlocksMetadataIP verifies 169.254.169.254 is blocked
+func TestWebFetch_BlocksMetadataIP(t *testing.T) {
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("Failed to create web fetch tool: %v", err)
+	}
+	result := tool.Execute(context.Background(), map[string]any{
+		"url": "http://169.254.169.254/latest/meta-data",
+	})
+
+	if !result.IsError {
+		t.Error("expected error for cloud metadata IP, got success")
+	}
+}
+
+// TestWebFetch_BlocksIPv6UniqueLocal verifies fc00::/7 addresses are blocked
+func TestWebFetch_BlocksIPv6UniqueLocal(t *testing.T) {
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("Failed to create web fetch tool: %v", err)
+	}
+	result := tool.Execute(context.Background(), map[string]any{
+		"url": "http://[fd00::1]:0",
+	})
+
+	if !result.IsError {
+		t.Error("expected error for IPv6 unique local address, got success")
+	}
+}
+
+// TestWebFetch_Blocks6to4WithPrivateEmbed verifies 6to4 with private embedded IPv4 is blocked
+func TestWebFetch_Blocks6to4WithPrivateEmbed(t *testing.T) {
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("Failed to create web fetch tool: %v", err)
+	}
+	// 2002:7f00:0001::1 embeds 127.0.0.1
+	result := tool.Execute(context.Background(), map[string]any{
+		"url": "http://[2002:7f00:0001::1]:0",
+	})
+
+	if !result.IsError {
+		t.Error("expected error for 6to4 with private embedded IPv4, got success")
+	}
+}
+
+// TestWebFetch_Allows6to4WithPublicEmbed verifies 6to4 with public embedded IPv4 is NOT blocked
+func TestWebFetch_Allows6to4WithPublicEmbed(t *testing.T) {
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("Failed to create web fetch tool: %v", err)
+	}
+	// 2002:0801:0101::1 embeds 8.1.1.1 (public) — pre-flight should pass,
+	// connection will fail (no listener) but that's after the SSRF check.
+	result := tool.Execute(context.Background(), map[string]any{
+		"url": "http://[2002:0801:0101::1]:0",
+	})
+
+	// Should NOT be blocked by SSRF check — error should be connection failure, not "private"
+	if result.IsError && strings.Contains(result.ForLLM, "private") {
+		t.Error("6to4 with public embedded IPv4 should not be blocked as private")
+	}
+}
+
+// TestWebFetch_RedirectToPrivateBlocked verifies redirects to private IPs are blocked
+func TestWebFetch_RedirectToPrivateBlocked(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Redirect to a private IP
+		http.Redirect(w, r, "http://10.0.0.1/secret", http.StatusFound)
+	}))
+	defer server.Close()
+
+	// Temporarily disable private host allowance for the redirect check
+	allowPrivateWebFetchHosts.Store(false)
+	defer allowPrivateWebFetchHosts.Store(true)
+
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("Failed to create web fetch tool: %v", err)
+	}
+	result := tool.Execute(context.Background(), map[string]any{
+		"url": server.URL,
+	})
+
+	if !result.IsError {
+		t.Error("expected error when redirecting to private IP, got success")
+	}
+}
+
+func TestNewSafeDialContext_BlocksPrivateDNSResolutionWithoutWhitelist(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("failed to listen on loopback: %v", err)
+	}
+	defer listener.Close()
+
+	_, port, err := net.SplitHostPort(listener.Addr().String())
+	if err != nil {
+		t.Fatalf("failed to split listener address: %v", err)
+	}
+
+	dialContext := newSafeDialContext(&net.Dialer{Timeout: time.Second}, nil)
+	_, err = dialContext(context.Background(), "tcp", net.JoinHostPort("localhost", port))
+	if err == nil {
+		t.Fatal("expected localhost DNS resolution to be blocked without whitelist")
+	}
+	if !strings.Contains(err.Error(), "private") && !strings.Contains(err.Error(), "whitelisted") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestNewSafeDialContext_AllowsWhitelistedPrivateDNSResolution(t *testing.T) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("failed to listen on loopback: %v", err)
+	}
+	defer listener.Close()
+
+	accepted := make(chan struct{}, 1)
+	go func() {
+		conn, acceptErr := listener.Accept()
+		if acceptErr != nil {
+			return
+		}
+		conn.Close()
+		accepted <- struct{}{}
+	}()
+
+	_, port, err := net.SplitHostPort(listener.Addr().String())
+	if err != nil {
+		t.Fatalf("failed to split listener address: %v", err)
+	}
+
+	whitelist, err := newPrivateHostWhitelist([]string{"127.0.0.0/8"})
+	if err != nil {
+		t.Fatalf("failed to parse whitelist: %v", err)
+	}
+
+	dialContext := newSafeDialContext(&net.Dialer{Timeout: time.Second}, whitelist)
+	conn, err := dialContext(context.Background(), "tcp", net.JoinHostPort("localhost", port))
+	if err != nil {
+		t.Fatalf("expected localhost DNS resolution to succeed with whitelist, got %v", err)
+	}
+	conn.Close()
+
+	select {
+	case <-accepted:
+	case <-time.After(time.Second):
+		t.Fatal("expected localhost listener to accept a connection")
+	}
+}
+
+// TestIsPrivateOrRestrictedIP_Table tests IP classification logic
+func TestIsPrivateOrRestrictedIP_Table(t *testing.T) {
+	tests := []struct {
+		ip      string
+		blocked bool
+		desc    string
+	}{
+		{"127.0.0.1", true, "IPv4 loopback"},
+		{"10.0.0.1", true, "IPv4 private class A"},
+		{"172.16.0.1", true, "IPv4 private class B"},
+		{"192.168.1.1", true, "IPv4 private class C"},
+		{"169.254.169.254", true, "link-local / cloud metadata"},
+		{"100.64.0.1", true, "carrier-grade NAT"},
+		{"0.0.0.0", true, "unspecified"},
+		{"8.8.8.8", false, "public DNS"},
+		{"1.1.1.1", false, "public DNS"},
+		{"::1", true, "IPv6 loopback"},
+		{"::ffff:127.0.0.1", true, "IPv4-mapped IPv6 loopback"},
+		{"::ffff:10.0.0.1", true, "IPv4-mapped IPv6 private"},
+		{"fc00::1", true, "IPv6 unique local"},
+		{"fd00::1", true, "IPv6 unique local"},
+		{"2002:7f00:0001::1", true, "6to4 with embedded 127.x (private)"},
+		{"2002:0a00:0001::1", true, "6to4 with embedded 10.0.0.1 (private)"},
+		{"2002:0801:0101::1", false, "6to4 with embedded 8.1.1.1 (public)"},
+		{"2001:0000:4136:e378:8000:63bf:f5ff:fffe", true, "Teredo with client 10.0.0.1 (private)"},
+		{"2001:0000:4136:e378:8000:63bf:f7f6:fefe", false, "Teredo with client 8.9.1.1 (public)"},
+		{"2607:f8b0:4004:800::200e", false, "public IPv6 (Google)"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.desc, func(t *testing.T) {
+			ip := net.ParseIP(tt.ip)
+			if ip == nil {
+				t.Fatalf("failed to parse IP: %s", tt.ip)
+			}
+			got := isPrivateOrRestrictedIP(ip)
+			if got != tt.blocked {
+				t.Errorf("isPrivateOrRestrictedIP(%s) = %v, want %v", tt.ip, got, tt.blocked)
+			}
+		})
+	}
+}
+
 // TestWebTool_WebFetch_MissingDomain verifies error handling for URL without domain
 func TestWebTool_WebFetch_MissingDomain(t *testing.T) {
-	tool, err := NewWebFetchTool(50000, testFetchLimit)
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
 	if err != nil {
 		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
 	}
@@ -425,110 +904,8 @@ func TestWebTool_WebFetch_MissingDomain(t *testing.T) {
 	}
 }
 
-func TestCreateHTTPClient_ProxyConfigured(t *testing.T) {
-	client, err := createHTTPClient("http://127.0.0.1:7890", 12*time.Second)
-	if err != nil {
-		t.Fatalf("createHTTPClient() error: %v", err)
-	}
-	if client.Timeout != 12*time.Second {
-		t.Fatalf("client.Timeout = %v, want %v", client.Timeout, 12*time.Second)
-	}
-
-	tr, ok := client.Transport.(*http.Transport)
-	if !ok {
-		t.Fatalf("client.Transport type = %T, want *http.Transport", client.Transport)
-	}
-	if tr.Proxy == nil {
-		t.Fatal("transport.Proxy is nil, want non-nil")
-	}
-
-	req, err := http.NewRequest("GET", "https://example.com", nil)
-	if err != nil {
-		t.Fatalf("http.NewRequest() error: %v", err)
-	}
-	proxyURL, err := tr.Proxy(req)
-	if err != nil {
-		t.Fatalf("transport.Proxy(req) error: %v", err)
-	}
-	if proxyURL == nil || proxyURL.String() != "http://127.0.0.1:7890" {
-		t.Fatalf("proxy URL = %v, want %q", proxyURL, "http://127.0.0.1:7890")
-	}
-}
-
-func TestCreateHTTPClient_InvalidProxy(t *testing.T) {
-	_, err := createHTTPClient("://bad-proxy", 10*time.Second)
-	if err == nil {
-		t.Fatal("createHTTPClient() expected error for invalid proxy URL, got nil")
-	}
-}
-
-func TestCreateHTTPClient_Socks5ProxyConfigured(t *testing.T) {
-	client, err := createHTTPClient("socks5://127.0.0.1:1080", 8*time.Second)
-	if err != nil {
-		t.Fatalf("createHTTPClient() error: %v", err)
-	}
-
-	tr, ok := client.Transport.(*http.Transport)
-	if !ok {
-		t.Fatalf("client.Transport type = %T, want *http.Transport", client.Transport)
-	}
-	req, err := http.NewRequest("GET", "https://example.com", nil)
-	if err != nil {
-		t.Fatalf("http.NewRequest() error: %v", err)
-	}
-	proxyURL, err := tr.Proxy(req)
-	if err != nil {
-		t.Fatalf("transport.Proxy(req) error: %v", err)
-	}
-	if proxyURL == nil || proxyURL.String() != "socks5://127.0.0.1:1080" {
-		t.Fatalf("proxy URL = %v, want %q", proxyURL, "socks5://127.0.0.1:1080")
-	}
-}
-
-func TestCreateHTTPClient_UnsupportedProxyScheme(t *testing.T) {
-	_, err := createHTTPClient("ftp://127.0.0.1:21", 10*time.Second)
-	if err == nil {
-		t.Fatal("createHTTPClient() expected error for unsupported scheme, got nil")
-	}
-	if !strings.Contains(err.Error(), "unsupported proxy scheme") {
-		t.Fatalf("error = %q, want to contain %q", err.Error(), "unsupported proxy scheme")
-	}
-}
-
-func TestCreateHTTPClient_ProxyFromEnvironmentWhenConfigEmpty(t *testing.T) {
-	t.Setenv("HTTP_PROXY", "http://127.0.0.1:8888")
-	t.Setenv("http_proxy", "http://127.0.0.1:8888")
-	t.Setenv("HTTPS_PROXY", "http://127.0.0.1:8888")
-	t.Setenv("https_proxy", "http://127.0.0.1:8888")
-	t.Setenv("ALL_PROXY", "")
-	t.Setenv("all_proxy", "")
-	t.Setenv("NO_PROXY", "")
-	t.Setenv("no_proxy", "")
-
-	client, err := createHTTPClient("", 10*time.Second)
-	if err != nil {
-		t.Fatalf("createHTTPClient() error: %v", err)
-	}
-
-	tr, ok := client.Transport.(*http.Transport)
-	if !ok {
-		t.Fatalf("client.Transport type = %T, want *http.Transport", client.Transport)
-	}
-	if tr.Proxy == nil {
-		t.Fatal("transport.Proxy is nil, want proxy function from environment")
-	}
-
-	req, err := http.NewRequest("GET", "https://example.com", nil)
-	if err != nil {
-		t.Fatalf("http.NewRequest() error: %v", err)
-	}
-	if _, err := tr.Proxy(req); err != nil {
-		t.Fatalf("transport.Proxy(req) error: %v", err)
-	}
-}
-
 func TestNewWebFetchToolWithProxy(t *testing.T) {
-	tool, err := NewWebFetchToolWithProxy(1024, "http://127.0.0.1:7890", testFetchLimit)
+	tool, err := NewWebFetchToolWithProxy(1024, "http://127.0.0.1:7890", format, testFetchLimit, nil)
 	if err != nil {
 		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
 	} else if tool.maxChars != 1024 {
@@ -539,7 +916,7 @@ func TestNewWebFetchToolWithProxy(t *testing.T) {
 		t.Fatalf("proxy = %q, want %q", tool.proxy, "http://127.0.0.1:7890")
 	}
 
-	tool, err = NewWebFetchToolWithProxy(0, "http://127.0.0.1:7890", testFetchLimit)
+	tool, err = NewWebFetchToolWithProxy(0, "http://127.0.0.1:7890", format, testFetchLimit, nil)
 	if err != nil {
 		logger.ErrorCF("agent", "Failed to create web fetch tool", map[string]any{"error": err.Error()})
 	}
@@ -549,11 +926,21 @@ func TestNewWebFetchToolWithProxy(t *testing.T) {
 	}
 }
 
+func TestNewWebFetchToolWithConfig_InvalidPrivateHostWhitelist(t *testing.T) {
+	_, err := NewWebFetchToolWithConfig(1024, "", format, testFetchLimit, []string{"not-an-ip-or-cidr"})
+	if err == nil {
+		t.Fatal("expected invalid whitelist entry to fail")
+	}
+	if !strings.Contains(err.Error(), "invalid entry") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
 func TestNewWebSearchTool_PropagatesProxy(t *testing.T) {
 	t.Run("perplexity", func(t *testing.T) {
 		tool, err := NewWebSearchTool(WebSearchToolOptions{
 			PerplexityEnabled:    true,
-			PerplexityAPIKey:     "k",
+			PerplexityAPIKeys:    []string{"k"},
 			PerplexityMaxResults: 3,
 			Proxy:                "http://127.0.0.1:7890",
 		})
@@ -572,7 +959,7 @@ func TestNewWebSearchTool_PropagatesProxy(t *testing.T) {
 	t.Run("brave", func(t *testing.T) {
 		tool, err := NewWebSearchTool(WebSearchToolOptions{
 			BraveEnabled:    true,
-			BraveAPIKey:     "k",
+			BraveAPIKeys:    []string{"k"},
 			BraveMaxResults: 3,
 			Proxy:           "http://127.0.0.1:7890",
 		})
@@ -650,7 +1037,7 @@ func TestWebTool_TavilySearch_Success(t *testing.T) {
 
 	tool, err := NewWebSearchTool(WebSearchToolOptions{
 		TavilyEnabled:    true,
-		TavilyAPIKey:     "test-key",
+		TavilyAPIKeys:    []string{"test-key"},
 		TavilyBaseURL:    server.URL,
 		TavilyMaxResults: 5,
 	})
@@ -681,3 +1068,363 @@ func TestWebTool_TavilySearch_Success(t *testing.T) {
 		t.Errorf("Expected 'via Tavily' in output, got: %s", result.ForUser)
 	}
 }
+
+// TestWebFetchTool_CloudflareChallenge_RetryWithHonestUA verifies that a 403 response
+// with cf-mitigated: challenge triggers a retry using the honest picoclaw User-Agent,
+// and that the retry response is returned when it succeeds.
+func TestWebFetchTool_CloudflareChallenge_RetryWithHonestUA(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
+	requestCount := 0
+	var receivedUAs []string
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestCount++
+		receivedUAs = append(receivedUAs, r.Header.Get("User-Agent"))
+
+		if requestCount == 1 {
+			// First request: simulate Cloudflare challenge
+			w.Header().Set("Cf-Mitigated", "challenge")
+			w.Header().Set("Content-Type", "text/html")
+			w.WriteHeader(http.StatusForbidden)
+			w.Write([]byte("<html><body>Cloudflare challenge</body></html>"))
+			return
+		}
+		// Second request (honest UA retry): success
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusOK)
+		w.Write([]byte("real content"))
+	}))
+	defer server.Close()
+
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("NewWebFetchTool() error: %v", err)
+	}
+
+	result := tool.Execute(context.Background(), map[string]any{"url": server.URL})
+
+	if result.IsError {
+		t.Fatalf("expected success after retry, got error: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForLLM, "real content") {
+		t.Errorf("expected retry response content, got: %s", result.ForLLM)
+	}
+	if requestCount != 2 {
+		t.Errorf("expected exactly 2 requests, got %d", requestCount)
+	}
+
+	// First request must use the generic user agent
+	if receivedUAs[0] != userAgent {
+		t.Errorf("first request UA = %q, want %q", receivedUAs[0], userAgent)
+	}
+	// Second request must use the honest picoclaw user agent
+	if !strings.Contains(receivedUAs[1], "picoclaw") {
+		t.Errorf("retry request UA = %q, want it to contain 'picoclaw'", receivedUAs[1])
+	}
+}
+
+// TestWebFetchTool_CloudflareChallenge_NoRetryOnOtherErrors verifies that a plain 403
+// (without cf-mitigated: challenge) does NOT trigger a retry.
+func TestWebFetchTool_CloudflareChallenge_NoRetryOnOtherErrors(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
+	requestCount := 0
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestCount++
+		w.Header().Set("Content-Type", "text/plain")
+		w.WriteHeader(http.StatusForbidden)
+		w.Write([]byte("plain forbidden"))
+	}))
+	defer server.Close()
+
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("NewWebFetchTool() error: %v", err)
+	}
+
+	tool.Execute(context.Background(), map[string]any{"url": server.URL})
+
+	if requestCount != 1 {
+		t.Errorf("expected exactly 1 request for plain 403, got %d", requestCount)
+	}
+}
+
+// TestWebFetchTool_CloudflareChallenge_RetryFailsToo verifies that if the honest-UA
+// retry also fails (e.g. still blocked), the error from the retry is returned.
+func TestWebFetchTool_CloudflareChallenge_RetryFailsToo(t *testing.T) {
+	withPrivateWebFetchHostsAllowed(t)
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// Always return CF challenge regardless of UA
+		w.Header().Set("Cf-Mitigated", "challenge")
+		w.Header().Set("Content-Type", "text/html")
+		w.WriteHeader(http.StatusForbidden)
+		w.Write([]byte("<html><body>still blocked</body></html>"))
+	}))
+	defer server.Close()
+
+	tool, err := NewWebFetchTool(50000, format, testFetchLimit)
+	if err != nil {
+		t.Fatalf("NewWebFetchTool() error: %v", err)
+	}
+
+	result := tool.Execute(context.Background(), map[string]any{"url": server.URL})
+
+	// Should not be an error — the retry response is used as-is (403 is a valid HTTP response)
+	if result.IsError {
+		t.Fatalf("expected non-error result even when retry is also blocked, got: %s", result.ForLLM)
+	}
+	// Status in the JSON result should reflect the 403
+	if !strings.Contains(result.ForLLM, "403") {
+		t.Errorf("expected status 403 in result, got: %s", result.ForLLM)
+	}
+}
+
+func TestAPIKeyPool(t *testing.T) {
+	pool := NewAPIKeyPool([]string{"key1", "key2", "key3"})
+	if len(pool.keys) != 3 {
+		t.Fatalf("expected 3 keys, got %d", len(pool.keys))
+	}
+	if pool.keys[0] != "key1" || pool.keys[1] != "key2" || pool.keys[2] != "key3" {
+		t.Fatalf("unexpected keys: %v", pool.keys)
+	}
+
+	// Test Iterator: each iterator should cover all keys exactly once
+	iter := pool.NewIterator()
+	expected := []string{"key1", "key2", "key3"}
+	for i, want := range expected {
+		k, ok := iter.Next()
+		if !ok {
+			t.Fatalf("iter.Next() returned false at step %d", i)
+		}
+		if k != want {
+			t.Errorf("step %d: expected %s, got %s", i, want, k)
+		}
+	}
+	// Should be exhausted
+	if _, ok := iter.Next(); ok {
+		t.Errorf("expected iterator exhausted after all keys")
+	}
+
+	// Second iterator starts at next position (load balancing)
+	iter2 := pool.NewIterator()
+	k, ok := iter2.Next()
+	if !ok {
+		t.Fatal("iter2.Next() returned false")
+	}
+	if k != "key2" {
+		t.Errorf("expected key2 (round-robin), got %s", k)
+	}
+
+	// Empty pool
+	emptyPool := NewAPIKeyPool([]string{})
+	emptyIter := emptyPool.NewIterator()
+	if _, ok := emptyIter.Next(); ok {
+		t.Errorf("expected false for empty pool")
+	}
+
+	// Single key pool
+	singlePool := NewAPIKeyPool([]string{"single"})
+	singleIter := singlePool.NewIterator()
+	if k, ok := singleIter.Next(); !ok || k != "single" {
+		t.Errorf("expected single, got %s (ok=%v)", k, ok)
+	}
+	if _, ok := singleIter.Next(); ok {
+		t.Errorf("expected exhausted after single key")
+	}
+}
+
+func TestWebTool_TavilySearch_Failover(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var payload map[string]any
+		if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
+			t.Fatalf("failed to decode payload: %v", err)
+		}
+
+		apiKey := payload["api_key"].(string)
+
+		if apiKey == "key1" {
+			w.WriteHeader(http.StatusTooManyRequests)
+			w.Write([]byte("Rate limited"))
+			return
+		}
+
+		if apiKey == "key2" {
+			// Success
+			response := map[string]any{
+				"results": []map[string]any{
+					{
+						"title":   "Success Result",
+						"url":     "https://example.com/success",
+						"content": "Success content",
+					},
+				},
+			}
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+			json.NewEncoder(w).Encode(response)
+			return
+		}
+
+		w.WriteHeader(http.StatusBadRequest)
+	}))
+	defer server.Close()
+
+	tool, err := NewWebSearchTool(WebSearchToolOptions{
+		TavilyEnabled:    true,
+		TavilyAPIKeys:    []string{"key1", "key2"},
+		TavilyBaseURL:    server.URL,
+		TavilyMaxResults: 5,
+	})
+	if err != nil {
+		t.Fatalf("NewWebSearchTool() error: %v", err)
+	}
+
+	ctx := context.Background()
+	args := map[string]any{
+		"query": "test query",
+	}
+
+	result := tool.Execute(ctx, args)
+
+	if result.IsError {
+		t.Errorf("Expected success, got Error: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForUser, "Success Result") {
+		t.Errorf("Expected failover to second key and success result, got: %s", result.ForUser)
+	}
+}
+
+func TestWebTool_GLMSearch_Success(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != "POST" {
+			t.Errorf("Expected POST request, got %s", r.Method)
+		}
+		if r.Header.Get("Content-Type") != "application/json" {
+			t.Errorf("Expected Content-Type application/json, got %s", r.Header.Get("Content-Type"))
+		}
+		if r.Header.Get("Authorization") != "Bearer test-glm-key" {
+			t.Errorf("Expected Authorization Bearer test-glm-key, got %s", r.Header.Get("Authorization"))
+		}
+
+		var payload map[string]any
+		json.NewDecoder(r.Body).Decode(&payload)
+		if payload["search_query"] != "test query" {
+			t.Errorf("Expected search_query 'test query', got %v", payload["search_query"])
+		}
+		if payload["search_engine"] != "search_std" {
+			t.Errorf("Expected search_engine 'search_std', got %v", payload["search_engine"])
+		}
+
+		response := map[string]any{
+			"id":      "web-search-test",
+			"created": 1709568000,
+			"search_result": []map[string]any{
+				{
+					"title":        "Test GLM Result",
+					"content":      "GLM search snippet",
+					"link":         "https://example.com/glm",
+					"media":        "Example",
+					"publish_date": "2026-03-04",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusOK)
+		json.NewEncoder(w).Encode(response)
+	}))
+	defer server.Close()
+
+	tool, err := NewWebSearchTool(WebSearchToolOptions{
+		GLMSearchEnabled: true,
+		GLMSearchAPIKey:  "test-glm-key",
+		GLMSearchBaseURL: server.URL,
+		GLMSearchEngine:  "search_std",
+	})
+	if err != nil {
+		t.Fatalf("NewWebSearchTool() error: %v", err)
+	}
+
+	result := tool.Execute(context.Background(), map[string]any{
+		"query": "test query",
+	})
+
+	if result.IsError {
+		t.Errorf("Expected success, got IsError=true: %s", result.ForLLM)
+	}
+	if !strings.Contains(result.ForUser, "Test GLM Result") {
+		t.Errorf("Expected 'Test GLM Result' in output, got: %s", result.ForUser)
+	}
+	if !strings.Contains(result.ForUser, "https://example.com/glm") {
+		t.Errorf("Expected URL in output, got: %s", result.ForUser)
+	}
+	if !strings.Contains(result.ForUser, "via GLM Search") {
+		t.Errorf("Expected 'via GLM Search' in output, got: %s", result.ForUser)
+	}
+}
+
+func TestWebTool_GLMSearch_APIError(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+		w.Write([]byte(`{"error":"invalid api key"}`))
+	}))
+	defer server.Close()
+
+	tool, err := NewWebSearchTool(WebSearchToolOptions{
+		GLMSearchEnabled: true,
+		GLMSearchAPIKey:  "bad-key",
+		GLMSearchBaseURL: server.URL,
+		GLMSearchEngine:  "search_std",
+	})
+	if err != nil {
+		t.Fatalf("NewWebSearchTool() error: %v", err)
+	}
+
+	result := tool.Execute(context.Background(), map[string]any{
+		"query": "test query",
+	})
+
+	if !result.IsError {
+		t.Errorf("Expected IsError=true for 401 response")
+	}
+	if !strings.Contains(result.ForLLM, "status 401") {
+		t.Errorf("Expected status 401 in error, got: %s", result.ForLLM)
+	}
+}
+
+func TestWebTool_GLMSearch_Priority(t *testing.T) {
+	// GLM Search should only be selected when all other providers are disabled
+	tool, err := NewWebSearchTool(WebSearchToolOptions{
+		DuckDuckGoEnabled:    true,
+		DuckDuckGoMaxResults: 5,
+		GLMSearchEnabled:     true,
+		GLMSearchAPIKey:      "test-key",
+		GLMSearchBaseURL:     "https://example.com",
+		GLMSearchEngine:      "search_std",
+	})
+	if err != nil {
+		t.Fatalf("NewWebSearchTool() error: %v", err)
+	}
+
+	// DuckDuckGo should win over GLM Search
+	if _, ok := tool.provider.(*DuckDuckGoSearchProvider); !ok {
+		t.Errorf("Expected DuckDuckGoSearchProvider when both enabled, got %T", tool.provider)
+	}
+
+	// With DuckDuckGo disabled, GLM Search should be selected
+	tool2, err := NewWebSearchTool(WebSearchToolOptions{
+		DuckDuckGoEnabled: false,
+		GLMSearchEnabled:  true,
+		GLMSearchAPIKey:   "test-key",
+		GLMSearchBaseURL:  "https://example.com",
+		GLMSearchEngine:   "search_std",
+	})
+	if err != nil {
+		t.Fatalf("NewWebSearchTool() error: %v", err)
+	}
+	if _, ok := tool2.provider.(*GLMSearchProvider); !ok {
+		t.Errorf("Expected GLMSearchProvider when only GLM enabled, got %T", tool2.provider)
+	}
+}
diff --git a/pkg/utils/bm25.go b/pkg/utils/bm25.go
new file mode 100644
index 000000000..95c63f0e3
--- /dev/null
+++ b/pkg/utils/bm25.go
@@ -0,0 +1,272 @@
+// Package utils provides shared, reusable algorithms.
+// This file implements a generic BM25 search engine.
+//
+// Usage:
+//
+//	type MyDoc struct { ID string; Body string }
+//
+//	corpus := []MyDoc{...}
+//	engine := bm25.New(corpus, func(d MyDoc) string {
+//	    return d.ID + " " + d.Body
+//	})
+//	results := engine.Search("my query", 5)
+package utils
+
+import (
+	"math"
+	"sort"
+	"strings"
+)
+
+// ── Tuning defaults ───────────────────────────────────────────────────────────
+
+const (
+	// DefaultBM25K1 is the term-frequency saturation factor (typical range 1.2–2.0).
+	// Higher values give more weight to repeated terms.
+	DefaultBM25K1 = 1.2
+
+	// DefaultBM25B is the document-length normalization factor (0 = none, 1 = full).
+	DefaultBM25B = 0.75
+)
+
+// BM25Engine is a query-time BM25 search engine over a generic corpus.
+// T is the document type; the caller supplies a TextFunc that extracts the
+// searchable text from each document.
+//
+// The engine is stateless between queries: no caching, no invalidation logic.
+// All indexing work is performed inside Search() on every call, making it
+// safe to use on corpora that change frequently.
+type BM25Engine[T any] struct {
+	corpus   []T
+	textFunc func(T) string
+	k1       float64
+	b        float64
+}
+
+// BM25Option is a functional option to configure a BM25Engine.
+type BM25Option func(*bm25Config)
+
+type bm25Config struct {
+	k1 float64
+	b  float64
+}
+
+// WithK1 overrides the term-frequency saturation constant (default 1.2).
+func WithK1(k1 float64) BM25Option {
+	return func(c *bm25Config) { c.k1 = k1 }
+}
+
+// WithB overrides the document-length normalization factor (default 0.75).
+func WithB(b float64) BM25Option {
+	return func(c *bm25Config) { c.b = b }
+}
+
+// NewBM25Engine creates a BM25Engine for the given corpus.
+//
+//   - corpus   : slice of documents of any type T.
+//   - textFunc : function that returns the searchable text for a document.
+//   - opts     : optional tuning (WithK1, WithB).
+//
+// The corpus slice is referenced, not copied. Callers must not mutate it
+// concurrently with Search().
+func NewBM25Engine[T any](corpus []T, textFunc func(T) string, opts ...BM25Option) *BM25Engine[T] {
+	cfg := bm25Config{k1: DefaultBM25K1, b: DefaultBM25B}
+	for _, o := range opts {
+		o(&cfg)
+	}
+	return &BM25Engine[T]{
+		corpus:   corpus,
+		textFunc: textFunc,
+		k1:       cfg.k1,
+		b:        cfg.b,
+	}
+}
+
+// BM25Result is a single ranked result from a Search call.
+type BM25Result[T any] struct {
+	Document T
+	Score    float32
+}
+
+// Search ranks the corpus against query and returns the top-k results.
+// Returns an empty slice (not nil) when there are no matches.
+//
+// Complexity: O(N×L) for indexing + O(|Q|×avgPostingLen) for scoring,
+// where N = corpus size, L = average document length, Q = query terms.
+// Top-k extraction uses a fixed-size min-heap: O(candidates × log k).
+func (e *BM25Engine[T]) Search(query string, topK int) []BM25Result[T] {
+	if topK <= 0 {
+		return []BM25Result[T]{}
+	}
+
+	queryTerms := bm25Tokenize(query)
+	if len(queryTerms) == 0 {
+		return []BM25Result[T]{}
+	}
+
+	N := len(e.corpus)
+	if N == 0 {
+		return []BM25Result[T]{}
+	}
+
+	// Step 1: build per-document tf + raw doc lengths
+	type docEntry struct {
+		tf     map[string]uint32
+		rawLen int
+	}
+
+	entries := make([]docEntry, N)
+	df := make(map[string]int, 64)
+	totalLen := 0
+
+	for i, doc := range e.corpus {
+		tokens := bm25Tokenize(e.textFunc(doc))
+		totalLen += len(tokens)
+
+		tf := make(map[string]uint32, len(tokens))
+		for _, t := range tokens {
+			tf[t]++
+		}
+		// df: each term counts once per document (iterate the map, keys are unique)
+		for t := range tf {
+			df[t]++
+		}
+
+		entries[i] = docEntry{tf: tf, rawLen: len(tokens)}
+	}
+
+	avgDocLen := float64(totalLen) / float64(N)
+
+	// Step 2: pre-compute IDF and per-doc length normalization
+	// IDF (Robertson smoothing): log( (N - df(t) + 0.5) / (df(t) + 0.5) + 1 )
+	idf := make(map[string]float32, len(df))
+	for term, freq := range df {
+		idf[term] = float32(math.Log(
+			(float64(N)-float64(freq)+0.5)/(float64(freq)+0.5) + 1,
+		))
+	}
+
+	// docLenNorm[i] = k1 * (1 - b + b * |doc_i| / avgDocLen)
+	// Stored as float32 — sufficient precision for ranking.
+	docLenNorm := make([]float32, N)
+	for i, entry := range entries {
+		docLenNorm[i] = float32(e.k1 * (1 - e.b + e.b*float64(entry.rawLen)/avgDocLen))
+	}
+
+	// Step 3: build inverted index (posting lists)
+	// Iterate the tf map directly — map keys are already unique, no seen-set needed.
+	posting := make(map[string][]int32, len(df))
+	for i, entry := range entries {
+		for term := range entry.tf {
+			posting[term] = append(posting[term], int32(i))
+		}
+	}
+
+	// Step 4: score via posting lists
+	// Deduplicate query terms to avoid double-weighting the same term.
+	unique := bm25Dedupe(queryTerms)
+
+	scores := make(map[int32]float32)
+	for _, term := range unique {
+		termIDF, ok := idf[term]
+		if !ok {
+			continue // term not in vocabulary → zero contribution
+		}
+		for _, docID := range posting[term] {
+			freq := float32(entries[docID].tf[term])
+			// TF_norm = freq * (k1+1) / (freq + docLenNorm)
+			tfNorm := freq * float32(e.k1+1) / (freq + docLenNorm[docID])
+			scores[docID] += termIDF * tfNorm
+		}
+	}
+
+	if len(scores) == 0 {
+		return []BM25Result[T]{}
+	}
+
+	// Step 5: top-K via fixed-size min-heap
+	heap := make([]bm25ScoredDoc, 0, topK)
+
+	for docID, sc := range scores {
+		switch {
+		case len(heap) < topK:
+			heap = append(heap, bm25ScoredDoc{docID: docID, score: sc})
+			if len(heap) == topK {
+				bm25MinHeapify(heap)
+			}
+		case sc > heap[0].score:
+			heap[0] = bm25ScoredDoc{docID: docID, score: sc}
+			bm25SiftDown(heap, 0)
+		}
+	}
+
+	sort.Slice(heap, func(i, j int) bool { return heap[i].score > heap[j].score })
+
+	out := make([]BM25Result[T], len(heap))
+	for i, h := range heap {
+		out[i] = BM25Result[T]{
+			Document: e.corpus[h.docID],
+			Score:    h.score,
+		}
+	}
+	return out
+}
+
+// bm25Tokenize splits s into lowercase tokens, stripping edge punctuation.
+func bm25Tokenize(s string) []string {
+	raw := strings.Fields(strings.ToLower(s))
+	out := raw[:0] // reuse backing array to avoid extra allocation
+	for _, t := range raw {
+		t = strings.Trim(t, ".,;:!?\"'()/\\-_")
+		if t != "" {
+			out = append(out, t)
+		}
+	}
+	return out
+}
+
+// bm25Dedupe returns a new slice with duplicate tokens removed,
+// preserving first-occurrence order.
+func bm25Dedupe(tokens []string) []string {
+	seen := make(map[string]struct{}, len(tokens))
+	out := make([]string, 0, len(tokens))
+	for _, t := range tokens {
+		if _, ok := seen[t]; !ok {
+			seen[t] = struct{}{}
+			out = append(out, t)
+		}
+	}
+	return out
+}
+
+type bm25ScoredDoc struct {
+	docID int32
+	score float32
+}
+
+// bm25MinHeapify builds a min-heap in-place using Floyd's algorithm: O(k).
+func bm25MinHeapify(h []bm25ScoredDoc) {
+	for i := len(h)/2 - 1; i >= 0; i-- {
+		bm25SiftDown(h, i)
+	}
+}
+
+// bm25SiftDown restores the min-heap property starting at node i: O(log k).
+func bm25SiftDown(h []bm25ScoredDoc, i int) {
+	n := len(h)
+	for {
+		smallest := i
+		l, r := 2*i+1, 2*i+2
+		if l < n && h[l].score < h[smallest].score {
+			smallest = l
+		}
+		if r < n && h[r].score < h[smallest].score {
+			smallest = r
+		}
+		if smallest == i {
+			break
+		}
+		h[i], h[smallest] = h[smallest], h[i]
+		i = smallest
+	}
+}
diff --git a/pkg/utils/bm25_test.go b/pkg/utils/bm25_test.go
new file mode 100644
index 000000000..4bc85b246
--- /dev/null
+++ b/pkg/utils/bm25_test.go
@@ -0,0 +1,175 @@
+package utils
+
+import (
+	"reflect"
+	"testing"
+)
+
+// testDoc is a generic structure for use in tests.
+type testDoc struct {
+	ID   int
+	Text string
+}
+
+func extractText(d testDoc) string {
+	return d.Text
+}
+
+func TestBM25Search_EdgeCases(t *testing.T) {
+	corpus := []testDoc{
+		{1, "hello world"},
+		{2, "foo bar"},
+	}
+	engine := NewBM25Engine(corpus, extractText)
+
+	tests := []struct {
+		name  string
+		query string
+		topK  int
+	}{
+		{"Zero topK", "hello", 0},
+		{"Negative topK", "hello", -1},
+		{"Empty query", "", 5},
+		{"Query with only punctuation", "...,,,!!!", 5},
+		{"No matches found", "golang", 5},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			results := engine.Search(tt.query, tt.topK)
+			if len(results) != 0 {
+				t.Errorf("expected 0 results, got %d", len(results))
+			}
+			// Check that it never returns nil, but an empty slice
+			if results == nil {
+				t.Errorf("expected empty slice, got nil")
+			}
+		})
+	}
+}
+
+func TestBM25Search_EmptyCorpus(t *testing.T) {
+	engine := NewBM25Engine([]testDoc{}, extractText)
+	results := engine.Search("hello", 5)
+	if len(results) != 0 || results == nil {
+		t.Errorf("expected empty slice from empty corpus, got %v", results)
+	}
+}
+
+func TestBM25Search_RankingLogic(t *testing.T) {
+	corpus := []testDoc{
+		{1, "the quick brown fox jumps over the lazy dog"},
+		{2, "quick fox"},
+		{3, "quick quick quick fox"}, // High Term Frequency (TF)
+		{4, "completely irrelevant document here"},
+	}
+	engine := NewBM25Engine(corpus, extractText)
+
+	t.Run("Term Frequency (TF) boosts score", func(t *testing.T) {
+		results := engine.Search("quick", 5)
+		if len(results) < 3 {
+			t.Fatalf("expected at least 3 results, got %d", len(results))
+		}
+		// Doc 3 has the word "quick" repeated 3 times, it should beat Doc 2
+		if results[0].Document.ID != 3 {
+			t.Errorf("expected doc 3 to rank first due to high TF, got doc %d", results[0].Document.ID)
+		}
+	})
+
+	t.Run("Document Length penalty", func(t *testing.T) {
+		results := engine.Search("fox", 5)
+		if len(results) < 3 {
+			t.Fatalf("expected at least 3 results, got %d", len(results))
+		}
+		// Doc 2 ("quick fox") is much shorter than Doc 1 ("the quick brown fox..."),
+		// so, with equal Term Frequency for the word "fox" (1 time), Doc 2 wins.
+		if results[0].Document.ID != 2 {
+			t.Errorf("expected doc 2 to rank first due to shorter length, got doc %d", results[0].Document.ID)
+		}
+	})
+
+	t.Run("TopK limits results", func(t *testing.T) {
+		results := engine.Search("quick", 2)
+		if len(results) != 2 {
+			t.Errorf("expected exactly 2 results, got %d", len(results))
+		}
+	})
+}
+
+func TestBM25Tokenize(t *testing.T) {
+	tests := []struct {
+		input    string
+		expected []string
+	}{
+		{"Hello World", []string{"hello", "world"}},
+		{"  spaces   everywhere  ", []string{"spaces", "everywhere"}},
+		{"punctuation... test!!!", []string{"punctuation", "test"}},
+		{"(parentheses) and-hyphens", []string{"parentheses", "and-hyphens"}}, // hyphens trimmed from edges
+		{"internal-hyphen is kept", []string{"internal-hyphen", "is", "kept"}},
+		{".,;?!", []string{}}, // Becomes empty after trim
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.input, func(t *testing.T) {
+			got := bm25Tokenize(tt.input)
+			if len(got) == 0 && len(tt.expected) == 0 {
+				return // Both empty
+			}
+			if !reflect.DeepEqual(got, tt.expected) {
+				t.Errorf("bm25Tokenize(%q) = %v, want %v", tt.input, got, tt.expected)
+			}
+		})
+	}
+}
+
+func TestBM25Dedupe(t *testing.T) {
+	input := []string{"apple", "banana", "apple", "orange", "banana"}
+	expected := []string{"apple", "banana", "orange"}
+
+	got := bm25Dedupe(input)
+	if !reflect.DeepEqual(got, expected) {
+		t.Errorf("bm25Dedupe() = %v, want %v", got, expected)
+	}
+}
+
+func TestBM25Options(t *testing.T) {
+	corpus := []testDoc{{1, "test"}}
+
+	engine := NewBM25Engine(
+		corpus,
+		extractText,
+		WithK1(2.5),
+		WithB(0.9),
+	)
+
+	if engine.k1 != 2.5 {
+		t.Errorf("expected k1 to be 2.5, got %v", engine.k1)
+	}
+	if engine.b != 0.9 {
+		t.Errorf("expected b to be 0.9, got %v", engine.b)
+	}
+}
+
+func TestBM25Search_SortingStability(t *testing.T) {
+	// Ensure that sorting by heap returns in correct descending order
+	corpus := []testDoc{
+		{1, "golang is good"},
+		{2, "golang golang"},
+		{3, "golang golang golang"},
+		{4, "golang golang golang golang"},
+	}
+	engine := NewBM25Engine(corpus, extractText)
+	results := engine.Search("golang", 10)
+
+	if len(results) != 4 {
+		t.Fatalf("expected 4 results, got %d", len(results))
+	}
+
+	// Score should be strictly decreasing
+	for i := 1; i < len(results); i++ {
+		if results[i].Score > results[i-1].Score {
+			t.Errorf("results not sorted correctly: result %d score (%v) > result %d score (%v)",
+				i, results[i].Score, i-1, results[i-1].Score)
+		}
+	}
+}
diff --git a/pkg/utils/context.go b/pkg/utils/context.go
new file mode 100644
index 000000000..2007de9a3
--- /dev/null
+++ b/pkg/utils/context.go
@@ -0,0 +1,173 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// Inspired by and based on nanobot: https://github.com/HKUDS/nanobot
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package utils
+
+import (
+	"encoding/json"
+	"fmt"
+	"unicode/utf8"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// CalculateDefaultMaxContextRunes computes a default context limit based on the model's context window.
+// Strategy: Use 75% of the context window and convert to rune estimate.
+//
+// Token-to-rune conversion ratios (conservative estimates):
+//   - English: ~4 chars per token
+//   - Chinese: ~1.5-2 chars per token
+//   - Mixed: ~3 chars per token (used here for safety)
+func CalculateDefaultMaxContextRunes(contextWindow int) int {
+	if contextWindow <= 0 {
+		// Conservative fallback when context window is unknown
+		return 8000 // ~2000 tokens
+	}
+
+	// Use 75% of context window to leave headroom
+	targetTokens := int(float64(contextWindow) * 0.75)
+
+	// Convert tokens to runes using conservative ratio
+	const avgCharsPerToken = 3
+	return targetTokens * avgCharsPerToken
+}
+
+// ResolveMaxContextRunes determines the final MaxContextRunes value to use.
+// Priority: explicit config > auto-calculate > conservative default
+func ResolveMaxContextRunes(configValue, contextWindow int) int {
+	switch {
+	case configValue > 0:
+		// Explicitly configured, use as-is
+		return configValue
+	case configValue == -1:
+		// Explicitly disabled
+		return -1
+	default:
+		// 0 or unset: auto-calculate
+		return CalculateDefaultMaxContextRunes(contextWindow)
+	}
+}
+
+// MeasureContextRunes calculates the total rune count of a message list.
+// Includes content, reasoning content, and estimates for tool calls.
+func MeasureContextRunes(messages []providers.Message) int {
+	totalRunes := 0
+	for _, msg := range messages {
+		totalRunes += utf8.RuneCountInString(msg.Content)
+		totalRunes += utf8.RuneCountInString(msg.ReasoningContent)
+
+		// Tool calls: serialize to JSON and count
+		if len(msg.ToolCalls) > 0 {
+			for _, tc := range msg.ToolCalls {
+				totalRunes += utf8.RuneCountInString(tc.Name)
+				// Arguments: serialize and count
+				if argsJSON, err := json.Marshal(tc.Arguments); err == nil {
+					totalRunes += utf8.RuneCount(argsJSON)
+				} else {
+					// Fallback estimate if serialization fails
+					totalRunes += 100
+				}
+			}
+		}
+
+		// ToolCallID
+		totalRunes += utf8.RuneCountInString(msg.ToolCallID)
+	}
+	return totalRunes
+}
+
+// TruncateContextSmart intelligently truncates message history to fit within maxRunes.
+//
+// Strategy:
+//  1. Always preserve system messages (they define the agent's behavior)
+//  2. Keep the most recent messages (they contain current context)
+//  3. Drop older middle messages when necessary
+//  4. Insert a truncation notice to inform the LLM
+//
+// Returns the truncated message list.
+func TruncateContextSmart(messages []providers.Message, maxRunes int) []providers.Message {
+	if len(messages) == 0 {
+		return messages
+	}
+
+	// Separate system messages from others
+	var systemMsgs []providers.Message
+	var otherMsgs []providers.Message
+
+	for _, msg := range messages {
+		if msg.Role == "system" {
+			systemMsgs = append(systemMsgs, msg)
+		} else {
+			otherMsgs = append(otherMsgs, msg)
+		}
+	}
+
+	// Calculate system message size
+	systemRunes := 0
+	for _, msg := range systemMsgs {
+		systemRunes += utf8.RuneCountInString(msg.Content)
+		systemRunes += utf8.RuneCountInString(msg.ReasoningContent)
+	}
+
+	// Reserve space for truncation notice (estimate ~80 runes)
+	const truncationNoticeEstimate = 80
+
+	// Allocate remaining space for other messages
+	remainingRunes := maxRunes - systemRunes - truncationNoticeEstimate
+	if remainingRunes <= 0 {
+		// System messages already exceed limit - return only system messages
+		return systemMsgs
+	}
+
+	// Collect recent messages in reverse order until we hit the limit
+	var keptMsgs []providers.Message
+	currentRunes := 0
+
+	for i := len(otherMsgs) - 1; i >= 0; i-- {
+		msg := otherMsgs[i]
+		msgRunes := utf8.RuneCountInString(msg.Content) +
+			utf8.RuneCountInString(msg.ReasoningContent)
+
+		// Estimate tool call size
+		if len(msg.ToolCalls) > 0 {
+			for _, tc := range msg.ToolCalls {
+				msgRunes += utf8.RuneCountInString(tc.Name)
+				if argsJSON, err := json.Marshal(tc.Arguments); err == nil {
+					msgRunes += utf8.RuneCount(argsJSON)
+				} else {
+					msgRunes += 100
+				}
+			}
+		}
+		msgRunes += utf8.RuneCountInString(msg.ToolCallID)
+
+		if currentRunes+msgRunes > remainingRunes {
+			// Would exceed limit, stop collecting
+			break
+		}
+
+		// Prepend to maintain chronological order
+		keptMsgs = append([]providers.Message{msg}, keptMsgs...)
+		currentRunes += msgRunes
+	}
+
+	// If we dropped messages, add a truncation notice
+	result := systemMsgs
+	if len(keptMsgs) < len(otherMsgs) {
+		droppedCount := len(otherMsgs) - len(keptMsgs)
+		truncationNotice := providers.Message{
+			Role: "system",
+			Content: fmt.Sprintf(
+				"[Context truncated: %d earlier messages omitted to stay within context limits]",
+				droppedCount,
+			),
+		}
+		result = append(result, truncationNotice)
+	}
+
+	result = append(result, keptMsgs...)
+	return result
+}
diff --git a/pkg/utils/context_test.go b/pkg/utils/context_test.go
new file mode 100644
index 000000000..450a29249
--- /dev/null
+++ b/pkg/utils/context_test.go
@@ -0,0 +1,450 @@
+// PicoClaw - Ultra-lightweight personal AI agent
+// License: MIT
+//
+// Copyright (c) 2026 PicoClaw contributors
+
+package utils
+
+import (
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+func TestCalculateDefaultMaxContextRunes(t *testing.T) {
+	tests := []struct {
+		name          string
+		contextWindow int
+		want          int
+	}{
+		{
+			name:          "zero context window uses fallback",
+			contextWindow: 0,
+			want:          8000,
+		},
+		{
+			name:          "negative context window uses fallback",
+			contextWindow: -1,
+			want:          8000,
+		},
+		{
+			name:          "small context window (4k tokens)",
+			contextWindow: 4000,
+			want:          9000, // 4000 * 0.75 * 3 = 9000
+		},
+		{
+			name:          "medium context window (128k tokens)",
+			contextWindow: 128000,
+			want:          288000, // 128000 * 0.75 * 3 = 288000
+		},
+		{
+			name:          "large context window (1M tokens)",
+			contextWindow: 1000000,
+			want:          2250000, // 1000000 * 0.75 * 3 = 2250000
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := CalculateDefaultMaxContextRunes(tt.contextWindow)
+			if got != tt.want {
+				t.Errorf("CalculateDefaultMaxContextRunes(%d) = %d, want %d",
+					tt.contextWindow, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestResolveMaxContextRunes(t *testing.T) {
+	tests := []struct {
+		name          string
+		configValue   int
+		contextWindow int
+		want          int
+	}{
+		{
+			name:          "explicit positive value",
+			configValue:   12000,
+			contextWindow: 4000,
+			want:          12000,
+		},
+		{
+			name:          "explicit disable (-1)",
+			configValue:   -1,
+			contextWindow: 4000,
+			want:          -1,
+		},
+		{
+			name:          "zero uses auto-calculate",
+			configValue:   0,
+			contextWindow: 4000,
+			want:          9000, // 4000 * 0.75 * 3
+		},
+		{
+			name:          "unset (0) with unknown context window",
+			configValue:   0,
+			contextWindow: 0,
+			want:          8000, // fallback
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ResolveMaxContextRunes(tt.configValue, tt.contextWindow)
+			if got != tt.want {
+				t.Errorf("ResolveMaxContextRunes(%d, %d) = %d, want %d",
+					tt.configValue, tt.contextWindow, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestMeasureContextRunes(t *testing.T) {
+	tests := []struct {
+		name     string
+		messages []providers.Message
+		want     int
+	}{
+		{
+			name:     "empty messages",
+			messages: []providers.Message{},
+			want:     0,
+		},
+		{
+			name: "single simple message",
+			messages: []providers.Message{
+				{Role: "user", Content: "Hello"},
+			},
+			want: 5, // "Hello" = 5 runes
+		},
+		{
+			name: "message with reasoning",
+			messages: []providers.Message{
+				{
+					Role:             "assistant",
+					Content:          "Answer",
+					ReasoningContent: "Thinking",
+				},
+			},
+			want: 14, // "Answer" (6) + "Thinking" (8) = 14
+		},
+		{
+			name: "message with tool call",
+			messages: []providers.Message{
+				{
+					Role:    "assistant",
+					Content: "Using tool",
+					ToolCalls: []providers.ToolCall{
+						{
+							Name:      "test_tool",
+							Arguments: map[string]any{"key": "value"},
+						},
+					},
+				},
+			},
+			want: 10 + 9 + 15, // "Using tool" + "test_tool" + {"key":"value"}
+		},
+		{
+			name: "multiple messages",
+			messages: []providers.Message{
+				{Role: "system", Content: "You are helpful"},
+				{Role: "user", Content: "Hi"},
+				{Role: "assistant", Content: "Hello!"},
+			},
+			want: 15 + 2 + 6, // 15 + 2 + 6 = 23
+		},
+		{
+			name: "unicode characters",
+			messages: []providers.Message{
+				{Role: "user", Content: "\u4f60\u597d\u4e16\u754c"}, // 4 Chinese characters
+			},
+			want: 4,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := MeasureContextRunes(tt.messages)
+			if got != tt.want {
+				t.Errorf("MeasureContextRunes() = %d, want %d", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestTruncateContextSmart(t *testing.T) {
+	tests := []struct {
+		name     string
+		messages []providers.Message
+		maxRunes int
+		wantLen  int
+		wantHas  []string // Content strings that should be present
+		wantNot  []string // Content strings that should be absent
+	}{
+		{
+			name:     "empty messages",
+			messages: []providers.Message{},
+			maxRunes: 100,
+			wantLen:  0,
+		},
+		{
+			name: "no truncation needed",
+			messages: []providers.Message{
+				{Role: "system", Content: "System"},
+				{Role: "user", Content: "Hello"},
+			},
+			maxRunes: 100,
+			wantLen:  2,
+			wantHas:  []string{"System", "Hello"},
+		},
+		{
+			name: "truncate when limit is tight",
+			messages: []providers.Message{
+				{Role: "system", Content: "System"},
+				{Role: "user", Content: "Message 1 with some content here"},
+				{Role: "assistant", Content: "Response 1 with some content here"},
+				{Role: "user", Content: "Message 2 with some content here"},
+				{Role: "assistant", Content: "Response 2 with some content here"},
+				{Role: "user", Content: "Latest"},
+			},
+			maxRunes: 120, // Tight limit to force truncation
+			wantLen:  -1,  // Don't check exact length, just verify truncation occurred
+			wantHas:  []string{"System", "Latest"},
+			wantNot:  []string{"Message 1", "Response 1"},
+		},
+		{
+			name: "system messages exceed limit",
+			messages: []providers.Message{
+				{Role: "system", Content: "Very long system message"},
+				{Role: "user", Content: "User message"},
+			},
+			maxRunes: 10, // Less than system message
+			wantLen:  1,  // Only system message
+			wantHas:  []string{"Very long system message"},
+			wantNot:  []string{"User message"},
+		},
+		{
+			name: "preserve multiple system messages",
+			messages: []providers.Message{
+				{Role: "system", Content: "Sys1"},
+				{Role: "system", Content: "Sys2"},
+				{Role: "user", Content: "Old"},
+				{Role: "user", Content: "New"},
+			},
+			maxRunes: 200, // Generous limit
+			wantLen:  4,   // Both system + truncation notice + new
+			wantHas:  []string{"Sys1", "Sys2", "New"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := TruncateContextSmart(tt.messages, tt.maxRunes)
+
+			if tt.wantLen >= 0 && len(got) != tt.wantLen {
+				t.Errorf("TruncateContextSmart() returned %d messages, want %d",
+					len(got), tt.wantLen)
+			}
+
+			// Check for expected content
+			allContent := ""
+			for _, msg := range got {
+				allContent += msg.Content + " "
+			}
+
+			for _, want := range tt.wantHas {
+				found := false
+				for _, msg := range got {
+					if msg.Content == want || containsSubstring(msg.Content, want) {
+						found = true
+						break
+					}
+				}
+				if !found {
+					t.Errorf("Expected content %q not found in truncated messages", want)
+				}
+			}
+
+			for _, notWant := range tt.wantNot {
+				for _, msg := range got {
+					if containsSubstring(msg.Content, notWant) {
+						t.Errorf("Unexpected content %q found in truncated messages", notWant)
+					}
+				}
+			}
+		})
+	}
+}
+
+func containsSubstring(s, substr string) bool {
+	return len(s) >= len(substr) && findSubstring(s, substr)
+}
+
+func findSubstring(s, substr string) bool {
+	for i := 0; i <= len(s)-len(substr); i++ {
+		if s[i:i+len(substr)] == substr {
+			return true
+		}
+	}
+	return false
+}
+
+// TestSubTurnConfigMaxContextRunes verifies that MaxContextRunes configuration
+// is properly integrated into the SubTurn execution flow.
+func TestSubTurnConfigMaxContextRunes(t *testing.T) {
+	tests := []struct {
+		name            string
+		maxContextRunes int
+		contextWindow   int
+		wantResolved    int
+	}{
+		{
+			name:            "default (0) auto-calculates from context window",
+			maxContextRunes: 0,
+			contextWindow:   4000,
+			wantResolved:    9000, // 4000 * 0.75 * 3
+		},
+		{
+			name:            "explicit value is used",
+			maxContextRunes: 12000,
+			contextWindow:   4000,
+			wantResolved:    12000,
+		},
+		{
+			name:            "disabled (-1) returns -1",
+			maxContextRunes: -1,
+			contextWindow:   4000,
+			wantResolved:    -1,
+		},
+		{
+			name:            "fallback when context window unknown",
+			maxContextRunes: 0,
+			contextWindow:   0,
+			wantResolved:    8000, // conservative fallback
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ResolveMaxContextRunes(tt.maxContextRunes, tt.contextWindow)
+			if got != tt.wantResolved {
+				t.Errorf("utils.ResolveMaxContextRunes(%d, %d) = %d, want %d",
+					tt.maxContextRunes, tt.contextWindow, got, tt.wantResolved)
+			}
+		})
+	}
+}
+
+// TestContextTruncationFlow verifies the complete context truncation flow:
+// 1. Messages accumulate beyond soft limit
+// 2. Truncation is triggered
+// 3. System messages are preserved
+// 4. Recent messages are kept
+func TestContextTruncationFlow(t *testing.T) {
+	// Build a message history that exceeds the limit
+	messages := []providers.Message{
+		{Role: "system", Content: "You are a helpful assistant"}, // ~27 runes
+		{Role: "user", Content: "First question"},                // ~14 runes
+		{Role: "assistant", Content: "First answer"},             // ~12 runes
+		{Role: "user", Content: "Second question"},               // ~15 runes
+		{Role: "assistant", Content: "Second answer"},            // ~13 runes
+		{Role: "user", Content: "Third question"},                // ~14 runes
+		{Role: "assistant", Content: "Third answer"},             // ~12 runes
+		{Role: "user", Content: "Latest question"},               // ~15 runes
+	}
+
+	// Total: ~122 runes
+	totalRunes := MeasureContextRunes(messages)
+	if totalRunes < 100 {
+		t.Errorf("Expected total runes > 100, got %d", totalRunes)
+	}
+
+	// Set limit to 150 runes - should force truncation of old messages
+	// but preserve system + truncation notice + recent messages
+	maxRunes := 150
+	truncated := TruncateContextSmart(messages, maxRunes)
+
+	// Verify truncation occurred
+	if len(truncated) >= len(messages) {
+		t.Errorf("Expected truncation, but got %d messages (original: %d)",
+			len(truncated), len(messages))
+	}
+
+	// Verify system message is preserved
+	foundSystem := false
+	for _, msg := range truncated {
+		if msg.Role == "system" && msg.Content == "You are a helpful assistant" {
+			foundSystem = true
+			break
+		}
+	}
+	if !foundSystem {
+		t.Error("System message was not preserved after truncation")
+	}
+
+	// Verify latest message is preserved
+	foundLatest := false
+	for _, msg := range truncated {
+		if msg.Content == "Latest question" {
+			foundLatest = true
+			break
+		}
+	}
+	if !foundLatest {
+		t.Error("Latest message was not preserved after truncation")
+	}
+
+	// Verify truncation notice is present
+	foundNotice := false
+	for _, msg := range truncated {
+		if msg.Role == "system" && containsSubstring(msg.Content, "truncated") {
+			foundNotice = true
+			break
+		}
+	}
+	if !foundNotice {
+		t.Error("Truncation notice was not added")
+	}
+
+	// Verify result is within limit (with some tolerance for estimation)
+	resultRunes := MeasureContextRunes(truncated)
+	if resultRunes > maxRunes+20 { // Allow 20 rune tolerance
+		t.Errorf("Truncated context (%d runes) significantly exceeds limit (%d runes)",
+			resultRunes, maxRunes)
+	}
+}
+
+// TestContextTruncationPreservesToolCalls verifies that tool calls are
+// properly handled during context truncation.
+func TestContextTruncationPreservesToolCalls(t *testing.T) {
+	messages := []providers.Message{
+		{Role: "system", Content: "System"},
+		{Role: "user", Content: "Old message that should be dropped"},
+		{
+			Role:    "assistant",
+			Content: "Recent tool use",
+			ToolCalls: []providers.ToolCall{
+				{
+					Name:      "important_tool",
+					Arguments: map[string]any{"key": "value"},
+				},
+			},
+		},
+	}
+
+	// Set a generous limit that should keep the tool call message
+	maxRunes := 200
+	truncated := TruncateContextSmart(messages, maxRunes)
+
+	// Verify tool call message is preserved
+	foundToolCall := false
+	for _, msg := range truncated {
+		if len(msg.ToolCalls) > 0 && msg.ToolCalls[0].Name == "important_tool" {
+			foundToolCall = true
+			break
+		}
+	}
+	if !foundToolCall {
+		t.Error("Tool call message was not preserved during truncation")
+	}
+}
diff --git a/pkg/utils/http_client.go b/pkg/utils/http_client.go
new file mode 100644
index 000000000..bda7c5c83
--- /dev/null
+++ b/pkg/utils/http_client.go
@@ -0,0 +1,48 @@
+package utils
+
+import (
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// CreateHTTPClient creates an HTTP client with optional proxy support.
+// If proxyURL is empty, it uses the system environment proxy settings.
+// Supported proxy schemes: http, https, socks5, socks5h.
+func CreateHTTPClient(proxyURL string, timeout time.Duration) (*http.Client, error) {
+	client := &http.Client{
+		Timeout: timeout,
+		Transport: &http.Transport{
+			MaxIdleConns:        10,
+			IdleConnTimeout:     30 * time.Second,
+			DisableCompression:  false,
+			TLSHandshakeTimeout: 15 * time.Second,
+		},
+	}
+
+	if proxyURL != "" {
+		proxy, err := url.Parse(proxyURL)
+		if err != nil {
+			return nil, fmt.Errorf("invalid proxy URL: %w", err)
+		}
+		scheme := strings.ToLower(proxy.Scheme)
+		switch scheme {
+		case "http", "https", "socks5", "socks5h":
+		default:
+			return nil, fmt.Errorf(
+				"unsupported proxy scheme %q (supported: http, https, socks5, socks5h)",
+				proxy.Scheme,
+			)
+		}
+		if proxy.Host == "" {
+			return nil, fmt.Errorf("invalid proxy URL: missing host")
+		}
+		client.Transport.(*http.Transport).Proxy = http.ProxyURL(proxy)
+	} else {
+		client.Transport.(*http.Transport).Proxy = http.ProxyFromEnvironment
+	}
+
+	return client, nil
+}
diff --git a/pkg/utils/http_client_test.go b/pkg/utils/http_client_test.go
new file mode 100644
index 000000000..ff3d0429b
--- /dev/null
+++ b/pkg/utils/http_client_test.go
@@ -0,0 +1,110 @@
+package utils
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestCreateHTTPClient_ProxyConfigured(t *testing.T) {
+	client, err := CreateHTTPClient("http://127.0.0.1:7890", 12*time.Second)
+	if err != nil {
+		t.Fatalf("createHTTPClient() error: %v", err)
+	}
+	if client.Timeout != 12*time.Second {
+		t.Fatalf("client.Timeout = %v, want %v", client.Timeout, 12*time.Second)
+	}
+
+	tr, ok := client.Transport.(*http.Transport)
+	if !ok {
+		t.Fatalf("client.Transport type = %T, want *http.Transport", client.Transport)
+	}
+	if tr.Proxy == nil {
+		t.Fatal("transport.Proxy is nil, want non-nil")
+	}
+
+	req, err := http.NewRequest("GET", "https://example.com", nil)
+	if err != nil {
+		t.Fatalf("http.NewRequest() error: %v", err)
+	}
+	proxyURL, err := tr.Proxy(req)
+	if err != nil {
+		t.Fatalf("transport.Proxy(req) error: %v", err)
+	}
+	if proxyURL == nil || proxyURL.String() != "http://127.0.0.1:7890" {
+		t.Fatalf("proxy URL = %v, want %q", proxyURL, "http://127.0.0.1:7890")
+	}
+}
+
+func TestCreateHTTPClient_InvalidProxy(t *testing.T) {
+	_, err := CreateHTTPClient("://bad-proxy", 10*time.Second)
+	if err == nil {
+		t.Fatal("createHTTPClient() expected error for invalid proxy URL, got nil")
+	}
+}
+
+func TestCreateHTTPClient_Socks5ProxyConfigured(t *testing.T) {
+	client, err := CreateHTTPClient("socks5://127.0.0.1:1080", 8*time.Second)
+	if err != nil {
+		t.Fatalf("createHTTPClient() error: %v", err)
+	}
+
+	tr, ok := client.Transport.(*http.Transport)
+	if !ok {
+		t.Fatalf("client.Transport type = %T, want *http.Transport", client.Transport)
+	}
+	req, err := http.NewRequest("GET", "https://example.com", nil)
+	if err != nil {
+		t.Fatalf("http.NewRequest() error: %v", err)
+	}
+	proxyURL, err := tr.Proxy(req)
+	if err != nil {
+		t.Fatalf("transport.Proxy(req) error: %v", err)
+	}
+	if proxyURL == nil || proxyURL.String() != "socks5://127.0.0.1:1080" {
+		t.Fatalf("proxy URL = %v, want %q", proxyURL, "socks5://127.0.0.1:1080")
+	}
+}
+
+func TestCreateHTTPClient_UnsupportedProxyScheme(t *testing.T) {
+	_, err := CreateHTTPClient("ftp://127.0.0.1:21", 10*time.Second)
+	if err == nil {
+		t.Fatal("createHTTPClient() expected error for unsupported scheme, got nil")
+	}
+	if !strings.Contains(err.Error(), "unsupported proxy scheme") {
+		t.Fatalf("error = %q, want to contain %q", err.Error(), "unsupported proxy scheme")
+	}
+}
+
+func TestCreateHTTPClient_ProxyFromEnvironmentWhenConfigEmpty(t *testing.T) {
+	t.Setenv("HTTP_PROXY", "http://127.0.0.1:8888")
+	t.Setenv("http_proxy", "http://127.0.0.1:8888")
+	t.Setenv("HTTPS_PROXY", "http://127.0.0.1:8888")
+	t.Setenv("https_proxy", "http://127.0.0.1:8888")
+	t.Setenv("ALL_PROXY", "")
+	t.Setenv("all_proxy", "")
+	t.Setenv("NO_PROXY", "")
+	t.Setenv("no_proxy", "")
+
+	client, err := CreateHTTPClient("", 10*time.Second)
+	if err != nil {
+		t.Fatalf("createHTTPClient() error: %v", err)
+	}
+
+	tr, ok := client.Transport.(*http.Transport)
+	if !ok {
+		t.Fatalf("client.Transport type = %T, want *http.Transport", client.Transport)
+	}
+	if tr.Proxy == nil {
+		t.Fatal("transport.Proxy is nil, want proxy function from environment")
+	}
+
+	req, err := http.NewRequest("GET", "https://example.com", nil)
+	if err != nil {
+		t.Fatalf("http.NewRequest() error: %v", err)
+	}
+	if _, err := tr.Proxy(req); err != nil {
+		t.Fatalf("transport.Proxy(req) error: %v", err)
+	}
+}
diff --git a/pkg/utils/markdown.go b/pkg/utils/markdown.go
new file mode 100644
index 000000000..c7873252a
--- /dev/null
+++ b/pkg/utils/markdown.go
@@ -0,0 +1,411 @@
+package utils
+
+import (
+	"bytes"
+	"net/url"
+	"regexp"
+	"strconv"
+	"strings"
+
+	"golang.org/x/net/html"
+)
+
+var (
+	reSpaces           = regexp.MustCompile(`[ \t]+`)
+	reNewlines         = regexp.MustCompile(`\n{3,}`)
+	reEmptyListItem    = regexp.MustCompile(`(?m)^[-*]\s*$`)
+	reImageOnlyLink    = regexp.MustCompile(`\[!\[\]\(<[^>]*>\)\]\(<[^>]*>\)`)
+	reEmptyHeader      = regexp.MustCompile(`(?m)^#{1,6}\s*$`)
+	reLeadingLineSpace = regexp.MustCompile(`(?m)^([ \t])([^ \t\n])`)
+)
+
+var skipTags = map[string]bool{
+	"script": true, "style": true, "head": true,
+	"noscript": true, "template": true,
+	"nav": true, "footer": true, "aside": true, "header": true, "form": true, "dialog": true,
+}
+
+func isSafeHref(href string) bool {
+	lower := strings.ToLower(strings.TrimSpace(href))
+	if strings.HasPrefix(lower, "javascript:") || strings.HasPrefix(lower, "vbscript:") ||
+		strings.HasPrefix(lower, "data:") {
+		return false
+	}
+	u, err := url.Parse(strings.TrimSpace(href))
+	if err != nil {
+		return false
+	}
+	scheme := strings.ToLower(u.Scheme)
+	return scheme == "" || scheme == "http" || scheme == "https" || scheme == "mailto"
+}
+
+func isSafeImageSrc(src string) bool {
+	lower := strings.ToLower(strings.TrimSpace(src))
+	if strings.HasPrefix(lower, "data:image/") {
+		return true
+	}
+	return isSafeHref(src)
+}
+
+func escapeMdAlt(s string) string {
+	s = strings.ReplaceAll(s, `\`, `\\`)
+	s = strings.ReplaceAll(s, `[`, `\[`)
+	s = strings.ReplaceAll(s, `]`, `\]`)
+	return s
+}
+
+func getAttr(n *html.Node, key string) string {
+	for _, a := range n.Attr {
+		if a.Key == key {
+			return a.Val
+		}
+	}
+	return ""
+}
+
+func normalizeAttr(val string) string {
+	val = strings.ReplaceAll(val, "\n", "")
+	val = strings.ReplaceAll(val, "\r", "")
+	val = strings.ReplaceAll(val, "\t", "")
+	return strings.TrimSpace(val)
+}
+
+func isUnlikelyNode(n *html.Node) bool {
+	if n.Type != html.ElementNode {
+		return false
+	}
+	classId := strings.ToLower(getAttr(n, "class") + " " + getAttr(n, "id"))
+	if classId == " " {
+		return false
+	}
+	if strings.Contains(classId, "article") || strings.Contains(classId, "main") ||
+		strings.Contains(classId, "content") {
+		return false
+	}
+	unlikelyKeywords := []string{
+		"menu",
+		"nav",
+		"footer",
+		"sidebar",
+		"cookie",
+		"banner",
+		"sponsor",
+		"advert",
+		"popup",
+		"modal",
+		"newsletter",
+		"share",
+		"social",
+	}
+	for _, keyword := range unlikelyKeywords {
+		if strings.Contains(classId, keyword) {
+			return true
+		}
+	}
+	return false
+}
+
+type converter struct {
+	stack      []*bytes.Buffer
+	linkHrefs  []string
+	linkStates []bool
+	emphStack  []string // Tracks "**", "*", "~~" for buffered emphasis
+	olCounters []int
+	inPre      bool
+	listDepth  int
+}
+
+func newConverter() *converter {
+	return &converter{
+		stack: []*bytes.Buffer{{}},
+	}
+}
+
+func (c *converter) write(s string) {
+	c.stack[len(c.stack)-1].WriteString(s)
+}
+
+func (c *converter) pushBuf() {
+	c.stack = append(c.stack, &bytes.Buffer{})
+}
+
+func (c *converter) popBuf() string {
+	top := c.stack[len(c.stack)-1]
+	c.stack = c.stack[:len(c.stack)-1]
+	return top.String()
+}
+
+func (c *converter) walk(n *html.Node) {
+	if n.Type == html.ElementNode {
+		if skipTags[n.Data] {
+			return
+		}
+		if isUnlikelyNode(n) {
+			return
+		}
+	}
+
+	if n.Type == html.TextNode {
+		text := n.Data
+		if !c.inPre {
+			text = strings.ReplaceAll(text, "\n", " ")
+			text = reSpaces.ReplaceAllString(text, " ")
+		}
+		if text != "" {
+			c.write(text)
+		}
+		return
+	}
+
+	if n.Type != html.ElementNode {
+		for ch := n.FirstChild; ch != nil; ch = ch.NextSibling {
+			c.walk(ch)
+		}
+		return
+	}
+
+	// Opening Tags
+	switch n.Data {
+	// Buffer emphasis content so we can TrimSpace the inner text,
+	// avoiding the regex-across-boundaries bug.
+	case "b", "strong":
+		c.emphStack = append(c.emphStack, "**")
+		c.pushBuf()
+	case "i", "em":
+		c.emphStack = append(c.emphStack, "*")
+		c.pushBuf()
+	case "del", "s":
+		c.emphStack = append(c.emphStack, "~~")
+		c.pushBuf()
+
+	case "a":
+		href := normalizeAttr(getAttr(n, "href"))
+		if href != "" && !isSafeHref(href) {
+			href = "#"
+		}
+		hasHref := href != ""
+		c.linkStates = append(c.linkStates, hasHref)
+		if hasHref {
+			c.linkHrefs = append(c.linkHrefs, href)
+			c.pushBuf()
+		}
+
+	case "h1":
+		c.write("\n\n# ")
+	case "h2":
+		c.write("\n\n## ")
+	case "h3":
+		c.write("\n\n### ")
+	case "h4":
+		c.write("\n\n#### ")
+	case "h5":
+		c.write("\n\n##### ")
+	case "h6":
+		c.write("\n\n###### ")
+
+	case "p":
+		c.write("\n\n")
+	case "br":
+		c.write("\n")
+	case "hr":
+		c.write("\n\n---\n\n")
+
+	case "ol":
+		c.olCounters = append(c.olCounters, 1)
+		// Only write leading newline for top-level list.
+		if c.listDepth == 0 {
+			c.write("\n")
+		}
+		c.listDepth++
+	case "ul":
+		if c.listDepth == 0 {
+			c.write("\n")
+		}
+		c.listDepth++
+	case "li":
+		c.write("\n")
+		if c.listDepth > 1 {
+			c.write(strings.Repeat("    ", c.listDepth-1))
+		}
+		if n.Parent != nil && n.Parent.Data == "ol" && len(c.olCounters) > 0 {
+			idx := c.olCounters[len(c.olCounters)-1]
+			c.write(strconv.Itoa(idx) + ". ")
+			c.olCounters[len(c.olCounters)-1]++
+		} else {
+			c.write("- ")
+		}
+
+	case "pre":
+		c.inPre = true
+		c.write("\n\n```\n")
+	case "code":
+		if !c.inPre {
+			c.write("`")
+		}
+
+	case "blockquote":
+		c.pushBuf()
+		for ch := n.FirstChild; ch != nil; ch = ch.NextSibling {
+			c.walk(ch)
+		}
+		inner := strings.TrimSpace(c.popBuf())
+		lines := strings.Split(inner, "\n")
+		var quoted []string
+		for _, l := range lines {
+			if strings.TrimSpace(l) == "" {
+				quoted = append(quoted, ">")
+			} else {
+				quoted = append(quoted, "> "+l)
+			}
+		}
+		var deduped []string
+		for i, line := range quoted {
+			if line == ">" && i > 0 && deduped[len(deduped)-1] == ">" {
+				continue
+			}
+			deduped = append(deduped, line)
+		}
+		c.write("\n\n" + strings.Join(deduped, "\n") + "\n\n")
+		return
+
+	case "img":
+		src := normalizeAttr(getAttr(n, "src"))
+		if src == "" {
+			src = normalizeAttr(getAttr(n, "data-src"))
+		}
+		if src == "" {
+			return
+		}
+		alt := escapeMdAlt(normalizeAttr(getAttr(n, "alt")))
+		if isSafeImageSrc(src) {
+			c.write("![" + alt + "](" + src + ")")
+		}
+		return
+	}
+
+	// Traverse Children
+	for ch := n.FirstChild; ch != nil; ch = ch.NextSibling {
+		c.walk(ch)
+	}
+
+	// Closing Tags
+	switch n.Data {
+	// Pop buffer, trim, wrap with the correct marker.
+	case "b", "strong", "i", "em", "del", "s":
+		if len(c.emphStack) == 0 {
+			break
+		}
+		marker := c.emphStack[len(c.emphStack)-1]
+		c.emphStack = c.emphStack[:len(c.emphStack)-1]
+		inner := strings.TrimSpace(c.popBuf())
+		if inner != "" {
+			c.write(marker + inner + marker)
+		}
+
+	case "a":
+		if len(c.linkStates) == 0 {
+			break
+		}
+		hasHref := c.linkStates[len(c.linkStates)-1]
+		c.linkStates = c.linkStates[:len(c.linkStates)-1]
+		if !hasHref {
+			break
+		}
+		href := c.linkHrefs[len(c.linkHrefs)-1]
+		c.linkHrefs = c.linkHrefs[:len(c.linkHrefs)-1]
+		inner := strings.TrimSpace(c.popBuf())
+		if strings.Contains(inner, "\n") {
+			lines := strings.Split(inner, "\n")
+			linked := false
+			for i, l := range lines {
+				cleanLine := strings.TrimSpace(l)
+				if cleanLine != "" && !strings.HasPrefix(cleanLine, "![") && !linked {
+					lines[i] = "[" + cleanLine + "](" + href + ")"
+					linked = true
+				}
+			}
+			c.write(strings.Join(lines, "\n"))
+		} else {
+			c.write("[" + inner + "](" + href + ")")
+		}
+
+	case "h1",
+		"h2",
+		"h3",
+		"h4",
+		"h5",
+		"h6",
+		"p",
+		"div",
+		"section",
+		"article",
+		"header",
+		"footer",
+		"aside",
+		"nav",
+		"figure":
+		c.write("\n")
+
+	case "ol":
+		c.listDepth--
+		if len(c.olCounters) > 0 {
+			c.olCounters = c.olCounters[:len(c.olCounters)-1]
+		}
+		if c.listDepth == 0 {
+			c.write("\n")
+		}
+	case "ul":
+		c.listDepth--
+		if c.listDepth == 0 {
+			c.write("\n")
+		}
+
+	case "pre":
+		c.inPre = false
+		c.write("\n```\n\n")
+	case "code":
+		if !c.inPre {
+			c.write("`")
+		}
+	}
+}
+
+func HtmlToMarkdown(htmlStr string) (string, error) {
+	doc, err := html.Parse(strings.NewReader(htmlStr))
+	if err != nil {
+		return "", err
+	}
+
+	c := newConverter()
+	c.walk(doc)
+
+	res := c.stack[0].String()
+
+	// Post-processing
+	res = reImageOnlyLink.ReplaceAllString(res, "")
+	res = reEmptyListItem.ReplaceAllString(res, "")
+	res = reEmptyHeader.ReplaceAllString(res, "")
+
+	lines := strings.Split(res, "\n")
+	var cleanLines []string
+	for _, line := range lines {
+		line = strings.TrimRight(line, " \t")
+		cleanTest := strings.TrimSpace(line)
+		if cleanTest == "[](</>)" || cleanTest == "[](#)" || cleanTest == "-" {
+			cleanLines = append(cleanLines, "")
+			continue
+		}
+		cleanLines = append(cleanLines, line)
+	}
+	res = strings.Join(cleanLines, "\n")
+
+	res = strings.TrimSpace(res)
+	res = reNewlines.ReplaceAllString(res, "\n\n")
+
+	// Strip a single leading space from lines that are NOT list indentation.
+	// "(?m)^([ \t])([^ \t\n])" matches exactly one space/tab at line start followed
+	// by a non-whitespace char, so "    - nested" (4 spaces) is left untouched.
+	res = reLeadingLineSpace.ReplaceAllString(res, "$2")
+
+	return res, nil
+}
diff --git a/pkg/utils/markdown_test.go b/pkg/utils/markdown_test.go
new file mode 100644
index 000000000..72277fb91
--- /dev/null
+++ b/pkg/utils/markdown_test.go
@@ -0,0 +1,245 @@
+package utils
+
+import (
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+func TestHtmlToMarkdown(t *testing.T) {
+	// Define our test cases
+	tests := []struct {
+		name     string
+		input    string
+		expected string
+	}{
+		{
+			name:     "Removes scripts and styles",
+			input:    `<script>alert("hello");</script><style>body { color: red; }</style><p>Clean text</p>`,
+			expected: "Clean text",
+		},
+		{
+			name:     "Extracts links correctly",
+			input:    `Visit my <a href="https://example.com">website</a> for info.`,
+			expected: "Visit my [website](https://example.com) for info.",
+		},
+		{
+			name:     "Converts headers (H1, H2, H3)",
+			input:    `<h1>Main Title</h1><h2>Subtitle</h2><h3>Section</h3>`,
+			expected: "# Main Title\n\n## Subtitle\n\n### Section",
+		},
+		{
+			name:     "Handles bold and italics",
+			input:    `Text <b>bold</b> and <strong>strong</strong>, then <i>italic</i> and <em>em</em>.`,
+			expected: "Text **bold** and **strong**, then *italic* and *em*.",
+		},
+		{
+			name:     "Converts lists",
+			input:    `<ul><li>First element</li><li>Second element</li></ul>`,
+			expected: "- First element\n- Second element",
+		},
+		{
+			name:     "Handles paragraphs and line breaks (<br>)",
+			input:    `<p>First paragraph</p><p>Second paragraph with<br>a line break.</p>`,
+			expected: "First paragraph\n\nSecond paragraph with\na line break.",
+		},
+		{
+			name:     "Decodes HTML entities",
+			input:    `Math: 5 &gt; 3 &amp; 2 &lt; 4. A &quot;quote&quot;.`,
+			expected: "Math: 5 > 3 & 2 < 4. A \"quote\".",
+		},
+		{
+			name:     "Cleans up residual HTML tags",
+			input:    `<div><span>Text inside div and span</span></div>`,
+			expected: "Text inside div and span",
+		},
+		{
+			name:     "Removes multiple spaces and excessive empty lines",
+			input:    `This   text    has too many spaces. <br><br><br><br> And too many newlines.`,
+			expected: "This text has too many spaces.\n\nAnd too many newlines.",
+		},
+		{
+			name:  "Nested lists with indentation",
+			input: "<ul><li>One<ul><li>Two</li></ul></li></ul>",
+			// Expect the sub-element to have 4 spaces of indentation
+			expected: "- One\n    - Two",
+		},
+		{
+			name:  "Image support",
+			input: `<img src="image.jpg" alt="alternative text">`,
+			// Correct Markdown syntax for images
+			expected: "![alternative text](image.jpg)",
+		},
+		{
+			name:  "Image support without alt-text",
+			input: `<img src="image.jpg">`,
+			// If alt is missing, square brackets remain empty
+			expected: "![](image.jpg)",
+		},
+		{
+			name: "XSS Bypass on Links (Obfuscated HTML entities)",
+			// The Go HTML parser resolves entities, so this becomes "javascript:alert(1)"
+			input: `<a href="jav&#x09;ascript:alert(1)">Click here</a>`,
+			// Our isSafeHref (if updated with net/url) should neutralize it to "#"
+			expected: "[Click here](#)",
+		},
+		{
+			name:  "Empty link or used as anchor",
+			input: `<a name="top"></a>`,
+			// With no text or href, it shouldn't print anything (not even empty brackets)
+			expected: "",
+		},
+		{
+			name:  "Link without href but with text (Textual anchor)",
+			input: `<a id="top">Back to top</a>`,
+			// Should extract only plain text, without generating a broken Markdown link like [Back to top](#) or [Back to top]()
+			expected: "Back to top",
+		},
+		{
+			name:  "Badly spaced bold and italics (Edge Case)",
+			input: `<b> Text </b>`,
+			// In Markdown `** Text **` is often not formatted correctly. The ideal is `**Text**`
+			expected: "**Text**",
+		},
+		{
+			name: "Complex Test - Real Article",
+			input: `
+             <h1>Article Title</h1>
+             <p>This is an <strong>introductory text</strong> with a <a href="http://link.com">link</a>.</p>
+             <h2>Subtitle</h2>
+             <ul>
+                <li>Point one</li>
+                <li>Point two</li>
+             </ul>
+             <script>console.log("do not show me")</script>
+          `,
+			// Note: The indentation of the real HTML test will generate spaces that
+			// regex will clean up.
+			expected: "# Article Title\n\nThis is an **introductory text** with a [link](http://link.com).\n\n## Subtitle\n\n- Point one\n- Point two",
+		},
+		{
+			name:     "Ordered list (OL)",
+			input:    `<ol><li>First</li><li>Second</li><li>Third</li></ol>`,
+			expected: "1. First\n2. Second\n3. Third",
+		},
+		{
+			name:     "Ordered list nested in unordered list",
+			input:    `<ul><li>Fruits<ol><li>Apples</li><li>Pears</li></ol></li><li>Vegetables</li></ul>`,
+			expected: "- Fruits\n    1. Apples\n    2. Pears\n- Vegetables",
+		},
+		{
+			name:     "Code block (pre/code)",
+			input:    "<pre><code>func main() {\n    fmt.Println(\"hello\")\n}</code></pre>",
+			expected: "```\nfunc main() {\n    fmt.Println(\"hello\")\n}\n```",
+		},
+		{
+			name:     "Inline code",
+			input:    `<p>Use the command <code>go test ./...</code> to run the tests.</p>`,
+			expected: "Use the command `go test ./...` to run the tests.",
+		},
+		{
+			name:     "Simple blockquote",
+			input:    `<blockquote><p>An important quote.</p></blockquote>`,
+			expected: "> An important quote.",
+		},
+		{
+			name:     "Multiline blockquote",
+			input:    `<blockquote><p>First line of the quote.</p><p>Second line of the quote.</p></blockquote>`,
+			expected: "> First line of the quote.\n>\n> Second line of the quote.",
+		},
+		{
+			name:     "Strikethrough text (del/s)",
+			input:    `This text is <del>deleted</del> and this is <s>crossed out</s>.`,
+			expected: "This text is ~~deleted~~ and this is ~~crossed out~~.",
+		},
+		{
+			name:     "Horizontal separator (HR)",
+			input:    `<p>Above the line</p><hr><p>Below the line</p>`,
+			expected: "Above the line\n\n---\n\nBelow the line",
+		},
+		{
+			name:     "Bold nested in link",
+			input:    `<a href="https://example.com"><strong>Linked bold text</strong></a>`,
+			expected: "[**Linked bold text**](https://example.com)",
+		},
+		{
+			name:     "data-src Image (lazy loading)",
+			input:    `<img data-src="lazy.jpg" alt="Lazy image">`,
+			expected: "![Lazy image](lazy.jpg)",
+		},
+		{
+			name:  "Image with javascript: src blocked",
+			input: `<img src="javascript:alert(1)" alt="XSS">`,
+			// src is not safe, so the image is not emitted
+			expected: "",
+		},
+		{
+			name:     "Link with data: href blocked",
+			input:    `<a href="data:text/html,<script>alert(1)</script>">Click</a>`,
+			expected: "[Click](#)",
+		},
+		{
+			name:     "Deeply nested divs",
+			input:    `<div><div><div><div><p>Deeply nested text</p></div></div></div></div>`,
+			expected: "Deeply nested text",
+		},
+		{
+			name:     "Non-consecutive headers (H1, H3, H5)",
+			input:    `<h1>Title</h1><h3>Subsection</h3><h5>Sub-subsection</h5>`,
+			expected: "# Title\n\n### Subsection\n\n##### Sub-subsection",
+		},
+		{
+			name:     "Paragraph with mixed multiple emphasis",
+			input:    `<p><strong>Important:</strong> read the <strong><em>critical instructions</em></strong> <em>carefully</em>.</p>`,
+			expected: "**Important:** read the ***critical instructions*** *carefully*.",
+		},
+		{
+			name: "Article with nav and aside sections (noise to filter)",
+			input: `
+        <nav><a href="/home">Home</a><a href="/about-us">About us</a></nav>
+        <article>
+            <h2>Article title</h2>
+            <p>This is the body of the article.</p>
+        </article>
+        <aside><p>Advertisement</p></aside>
+       `,
+			expected: "## Article title\n\nThis is the body of the article.",
+		},
+		{
+			name:     "Text with mixed special HTML entities",
+			input:    `Copyright &copy; 2024 &mdash; All rights reserved &reg;`,
+			expected: "Copyright © 2024 — All rights reserved ®",
+		},
+		{
+			name:     "Mailto link",
+			input:    `Write to us at <a href="mailto:info@example.com">info@example.com</a>`,
+			expected: "Write to us at [info@example.com](mailto:info@example.com)",
+		},
+		{
+			name:  "Image inside a link (clickable figure)",
+			input: `<a href="https://example.com"><img src="photo.jpg" alt="Photo"></a>`,
+			// The image-link without text must not generate broken markup
+			expected: "[![Photo](photo.jpg)](https://example.com)",
+		},
+		{
+			name:     "Empty content or only whitespace",
+			input:    `   <p>  </p>  <div>   </div>  `,
+			expected: "",
+		},
+	}
+
+	// Iterate over all test cases
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := HtmlToMarkdown(tt.input)
+			if err != nil {
+				logger.ErrorCF("tool", "Failed to parse html to markdown: %s", map[string]any{"error": err.Error()})
+			}
+
+			if got != tt.expected {
+				t.Errorf("\nTest case failed: %s\nInput:    %q\nGot:      %q\nExpected: %q",
+					tt.name, tt.input, got, tt.expected)
+			}
+		})
+	}
+}
diff --git a/pkg/utils/media.go b/pkg/utils/media.go
index a34889fb8..823ca155e 100644
--- a/pkg/utils/media.go
+++ b/pkg/utils/media.go
@@ -1,8 +1,10 @@
 package utils
 
 import (
+	"fmt"
 	"io"
 	"net/http"
+	"net/url"
 	"os"
 	"path/filepath"
 	"strings"
@@ -11,11 +13,24 @@ import (
 	"github.com/google/uuid"
 
 	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/media"
 )
 
+var audioExtensions = []string{".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".wma"}
+
+func AudioFormat(path string) (string, error) {
+	ext := strings.ToLower(filepath.Ext(path))
+	for _, supportedExt := range audioExtensions {
+		if ext == supportedExt {
+			return strings.TrimPrefix(ext, "."), nil
+		}
+	}
+
+	return "", fmt.Errorf("unsupported audio format for %q", path)
+}
+
 // IsAudioFile checks if a file is an audio file based on its filename extension and content type.
 func IsAudioFile(filename, contentType string) bool {
-	audioExtensions := []string{".mp3", ".wav", ".ogg", ".m4a", ".flac", ".aac", ".wma"}
 	audioTypes := []string{"audio/", "application/ogg", "application/x-ogg"}
 
 	for _, ext := range audioExtensions {
@@ -52,11 +67,12 @@ type DownloadOptions struct {
 	Timeout      time.Duration
 	ExtraHeaders map[string]string
 	LoggerPrefix string
+	ProxyURL     string
 }
 
 // DownloadFile downloads a file from URL to a local temp directory.
 // Returns the local file path or empty string on error.
-func DownloadFile(url, filename string, opts DownloadOptions) string {
+func DownloadFile(urlStr, filename string, opts DownloadOptions) string {
 	// Set defaults
 	if opts.Timeout == 0 {
 		opts.Timeout = 60 * time.Second
@@ -65,7 +81,7 @@ func DownloadFile(url, filename string, opts DownloadOptions) string {
 		opts.LoggerPrefix = "utils"
 	}
 
-	mediaDir := filepath.Join(os.TempDir(), "picoclaw_media")
+	mediaDir := media.TempDir()
 	if err := os.MkdirAll(mediaDir, 0o700); err != nil {
 		logger.ErrorCF(opts.LoggerPrefix, "Failed to create media directory", map[string]any{
 			"error": err.Error(),
@@ -78,7 +94,7 @@ func DownloadFile(url, filename string, opts DownloadOptions) string {
 	localPath := filepath.Join(mediaDir, uuid.New().String()[:8]+"_"+safeName)
 
 	// Create HTTP request
-	req, err := http.NewRequest("GET", url, nil)
+	req, err := http.NewRequest("GET", urlStr, nil)
 	if err != nil {
 		logger.ErrorCF(opts.LoggerPrefix, "Failed to create download request", map[string]any{
 			"error": err.Error(),
@@ -92,11 +108,24 @@ func DownloadFile(url, filename string, opts DownloadOptions) string {
 	}
 
 	client := &http.Client{Timeout: opts.Timeout}
+	if opts.ProxyURL != "" {
+		proxyURL, parseErr := url.Parse(opts.ProxyURL)
+		if parseErr != nil {
+			logger.ErrorCF(opts.LoggerPrefix, "Invalid proxy URL for download", map[string]any{
+				"error": parseErr.Error(),
+				"proxy": opts.ProxyURL,
+			})
+			return ""
+		}
+		client.Transport = &http.Transport{
+			Proxy: http.ProxyURL(proxyURL),
+		}
+	}
 	resp, err := client.Do(req)
 	if err != nil {
 		logger.ErrorCF(opts.LoggerPrefix, "Failed to download file", map[string]any{
 			"error": err.Error(),
-			"url":   url,
+			"url":   urlStr,
 		})
 		return ""
 	}
@@ -105,7 +134,7 @@ func DownloadFile(url, filename string, opts DownloadOptions) string {
 	if resp.StatusCode != http.StatusOK {
 		logger.ErrorCF(opts.LoggerPrefix, "File download returned non-200 status", map[string]any{
 			"status": resp.StatusCode,
-			"url":    url,
+			"url":    urlStr,
 		})
 		return ""
 	}
diff --git a/pkg/utils/string.go b/pkg/utils/string.go
index 02f346db4..dbaafdb7f 100644
--- a/pkg/utils/string.go
+++ b/pkg/utils/string.go
@@ -2,9 +2,18 @@ package utils
 
 import (
 	"strings"
+	"sync/atomic"
 	"unicode"
 )
 
+// Global variable to disable truncation
+var disableTruncation atomic.Bool
+
+// SetDisableTruncation globally enables or disables string truncation
+func SetDisableTruncation(enabled bool) {
+	disableTruncation.Store(enabled)
+}
+
 // SanitizeMessageContent removes Unicode control characters, format characters (RTL overrides,
 // zero-width characters), and other non-graphic characters that could confuse an LLM
 // or cause display issues in the agent UI.
@@ -30,6 +39,10 @@ func SanitizeMessageContent(input string) string {
 // Handles multi-byte Unicode characters properly.
 // If the string is truncated, "..." is appended to indicate truncation.
 func Truncate(s string, maxLen int) string {
+	// If the no-truncate flag is active, it returns the full string
+	if disableTruncation.Load() {
+		return s
+	}
 	if maxLen <= 0 {
 		return ""
 	}
diff --git a/pkg/voice/audio_model_transcriber.go b/pkg/voice/audio_model_transcriber.go
new file mode 100644
index 000000000..f3ca81961
--- /dev/null
+++ b/pkg/voice/audio_model_transcriber.go
@@ -0,0 +1,95 @@
+package voice
+
+import (
+	"context"
+	"encoding/base64"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+type AudioModelTranscriber struct {
+	provider providers.LLMProvider
+	modelID  string
+	prompt   string
+}
+
+const (
+	defaultTranscriptionPrompt = "Transcribe this audio."
+)
+
+func NewAudioModelTranscriber(modelCfg *config.ModelConfig) *AudioModelTranscriber {
+	if modelCfg == nil {
+		return nil
+	}
+
+	logger.DebugCF("voice", "Creating audio model transcriber", map[string]any{
+		"has_api_key": modelCfg.APIKey() != "",
+		"api_base":    modelCfg.APIBase,
+		"model":       modelCfg.Model,
+	})
+
+	provider, modelID, err := providers.CreateProviderFromConfig(modelCfg)
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to create audio model provider", map[string]any{"error": err})
+		return nil
+	}
+
+	return &AudioModelTranscriber{
+		provider: provider,
+		modelID:  modelID,
+		prompt:   defaultTranscriptionPrompt,
+	}
+}
+
+func (t *AudioModelTranscriber) Transcribe(ctx context.Context, audioFilePath string) (*TranscriptionResponse, error) {
+	logger.InfoCF("voice", "Starting audio model transcription", map[string]any{
+		"audio_file": audioFilePath,
+		"model":      t.modelID,
+	})
+
+	audioBytes, err := os.ReadFile(audioFilePath)
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to read audio file", map[string]any{"path": audioFilePath, "error": err})
+		return nil, fmt.Errorf("failed to read audio file: %w", err)
+	}
+
+	format, err := utils.AudioFormat(audioFilePath)
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to detect audio format", map[string]any{"path": audioFilePath, "error": err})
+		return nil, err
+	}
+
+	resp, err := t.provider.Chat(ctx, []providers.Message{
+		{
+			Role:    "user",
+			Content: t.prompt,
+			Media: []string{
+				fmt.Sprintf("data:audio/%s;base64,%s", format, base64.StdEncoding.EncodeToString(audioBytes)),
+			},
+		},
+	}, nil, t.modelID, map[string]any{
+		"temperature": 0,
+	})
+	if err != nil {
+		logger.ErrorCF("voice", "Audio model transcription request failed", map[string]any{"error": err})
+		return nil, fmt.Errorf("transcription request failed: %w", err)
+	}
+
+	text := strings.TrimSpace(resp.Content)
+	logger.InfoCF("voice", "Audio model transcription completed successfully", map[string]any{
+		"text_length":           len(text),
+		"transcription_preview": utils.Truncate(text, 50),
+	})
+
+	return &TranscriptionResponse{Text: text}, nil
+}
+
+func (t *AudioModelTranscriber) Name() string {
+	return "audio-model"
+}
diff --git a/pkg/voice/audio_model_transcriber_test.go b/pkg/voice/audio_model_transcriber_test.go
new file mode 100644
index 000000000..c33e3bf97
--- /dev/null
+++ b/pkg/voice/audio_model_transcriber_test.go
@@ -0,0 +1,203 @@
+package voice
+
+import (
+	"context"
+	"encoding/base64"
+	"errors"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+var _ Transcriber = (*AudioModelTranscriber)(nil)
+
+type fakeLLMProvider struct {
+	chatFunc func(
+		ctx context.Context,
+		messages []providers.Message,
+		tools []providers.ToolDefinition,
+		model string,
+		options map[string]any,
+	) (*providers.LLMResponse, error)
+}
+
+func (p *fakeLLMProvider) Chat(
+	ctx context.Context,
+	messages []providers.Message,
+	tools []providers.ToolDefinition,
+	model string,
+	options map[string]any,
+) (*providers.LLMResponse, error) {
+	if p.chatFunc == nil {
+		return nil, nil
+	}
+	return p.chatFunc(ctx, messages, tools, model, options)
+}
+
+func (p *fakeLLMProvider) GetDefaultModel() string {
+	return ""
+}
+
+func TestAudioModelTranscriberName(t *testing.T) {
+	tr := &AudioModelTranscriber{}
+	if got := tr.Name(); got != "audio-model" {
+		t.Errorf("Name() = %q, want %q", got, "audio-model")
+	}
+}
+
+func TestNewAudioModelTranscriberInvalidConfig(t *testing.T) {
+	tests := []struct {
+		name string
+		cfg  *config.ModelConfig
+	}{
+		{
+			name: "nil config",
+			cfg:  nil,
+		},
+		{
+			name: "missing api key",
+			cfg: &config.ModelConfig{
+				Model: "gemini/gemini-2.5-flash",
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tr := NewAudioModelTranscriber(tt.cfg); tr != nil {
+				t.Fatalf("NewAudioModelTranscriber() = %#v, want nil", tr)
+			}
+		})
+	}
+}
+
+func TestAudioModelTranscriberTranscribe(t *testing.T) {
+	tmpDir := t.TempDir()
+	audioPath := filepath.Join(tmpDir, "clip.ogg")
+	audioData := []byte("fake-audio-data")
+	if err := os.WriteFile(audioPath, audioData, 0o644); err != nil {
+		t.Fatalf("failed to write fake audio file: %v", err)
+	}
+
+	t.Run("success", func(t *testing.T) {
+		tr := &AudioModelTranscriber{
+			provider: &fakeLLMProvider{
+				chatFunc: func(
+					ctx context.Context,
+					messages []providers.Message,
+					tools []providers.ToolDefinition,
+					model string,
+					options map[string]any,
+				) (*providers.LLMResponse, error) {
+					if ctx == nil {
+						t.Fatal("context should not be nil")
+					}
+					if tools != nil {
+						t.Fatalf("tools = %#v, want nil", tools)
+					}
+					if model != "gemini-2.5-flash" {
+						t.Fatalf("model = %q, want %q", model, "gemini-2.5-flash")
+					}
+					if len(messages) != 1 {
+						t.Fatalf("len(messages) = %d, want 1", len(messages))
+					}
+					msg := messages[0]
+					if msg.Role != "user" {
+						t.Fatalf("role = %q, want %q", msg.Role, "user")
+					}
+					if msg.Content != defaultTranscriptionPrompt {
+						t.Fatalf("prompt = %q, want %q", msg.Content, defaultTranscriptionPrompt)
+					}
+					if len(msg.Media) != 1 {
+						t.Fatalf("len(media) = %d, want 1", len(msg.Media))
+					}
+					wantMedia := "data:audio/ogg;base64," + base64.StdEncoding.EncodeToString(audioData)
+					if msg.Media[0] != wantMedia {
+						t.Fatalf("media = %q, want %q", msg.Media[0], wantMedia)
+					}
+					if len(options) != 1 {
+						t.Fatalf("options = %#v, want only temperature", options)
+					}
+					if got := options["temperature"]; got != 0 {
+						t.Fatalf("temperature = %#v, want 0", got)
+					}
+
+					return &providers.LLMResponse{Content: "  hello from gemini \n"}, nil
+				},
+			},
+			modelID: "gemini-2.5-flash",
+			prompt:  defaultTranscriptionPrompt,
+		}
+
+		resp, err := tr.Transcribe(context.Background(), audioPath)
+		if err != nil {
+			t.Fatalf("Transcribe() error: %v", err)
+		}
+		if resp.Text != "hello from gemini" {
+			t.Fatalf("Text = %q, want %q", resp.Text, "hello from gemini")
+		}
+	})
+
+	t.Run("provider error", func(t *testing.T) {
+		tr := &AudioModelTranscriber{
+			provider: &fakeLLMProvider{
+				chatFunc: func(
+					ctx context.Context,
+					messages []providers.Message,
+					tools []providers.ToolDefinition,
+					model string,
+					options map[string]any,
+				) (*providers.LLMResponse, error) {
+					return nil, errors.New("upstream failure")
+				},
+			},
+			modelID: "gemini-2.5-flash",
+			prompt:  defaultTranscriptionPrompt,
+		}
+
+		_, err := tr.Transcribe(context.Background(), audioPath)
+		if err == nil {
+			t.Fatal("expected error for provider failure, got nil")
+		}
+		if got := err.Error(); got != "transcription request failed: upstream failure" {
+			t.Fatalf("error = %q, want %q", got, "transcription request failed: upstream failure")
+		}
+	})
+
+	t.Run("missing file", func(t *testing.T) {
+		tr := &AudioModelTranscriber{
+			provider: &fakeLLMProvider{},
+			modelID:  "gemini-2.5-flash",
+			prompt:   defaultTranscriptionPrompt,
+		}
+
+		_, err := tr.Transcribe(context.Background(), filepath.Join(tmpDir, "nonexistent.ogg"))
+		if err == nil {
+			t.Fatal("expected error for missing file, got nil")
+		}
+	})
+
+	t.Run("unsupported audio format", func(t *testing.T) {
+		badPath := filepath.Join(tmpDir, "clip.txt")
+		if err := os.WriteFile(badPath, []byte("not-audio"), 0o644); err != nil {
+			t.Fatalf("failed to write fake file: %v", err)
+		}
+
+		tr := &AudioModelTranscriber{
+			provider: &fakeLLMProvider{},
+			modelID:  "gemini-2.5-flash",
+			prompt:   defaultTranscriptionPrompt,
+		}
+
+		_, err := tr.Transcribe(context.Background(), badPath)
+		if err == nil {
+			t.Fatal("expected error for unsupported audio format, got nil")
+		}
+		if got := err.Error(); got != `unsupported audio format for "`+badPath+`"` {
+			t.Fatalf("error = %q, want unsupported format error", got)
+		}
+	})
+}
diff --git a/pkg/voice/elevenlabs_transcriber.go b/pkg/voice/elevenlabs_transcriber.go
new file mode 100644
index 000000000..93db10f8d
--- /dev/null
+++ b/pkg/voice/elevenlabs_transcriber.go
@@ -0,0 +1,141 @@
+package voice
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+// ElevenLabsTranscriber uses the ElevenLabs Scribe API for speech-to-text.
+type ElevenLabsTranscriber struct {
+	apiKey     string
+	apiBase    string
+	httpClient *http.Client
+}
+
+func NewElevenLabsTranscriber(apiKey string) *ElevenLabsTranscriber {
+	logger.DebugCF("voice", "Creating ElevenLabs transcriber", map[string]any{"has_api_key": apiKey != ""})
+
+	return &ElevenLabsTranscriber{
+		apiKey:  apiKey,
+		apiBase: "https://api.elevenlabs.io",
+		httpClient: &http.Client{
+			Timeout: 120 * time.Second,
+		},
+	}
+}
+
+func (t *ElevenLabsTranscriber) Transcribe(ctx context.Context, audioFilePath string) (*TranscriptionResponse, error) {
+	logger.InfoCF("voice", "Starting ElevenLabs transcription", map[string]any{"audio_file": audioFilePath})
+
+	audioFile, err := os.Open(audioFilePath)
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to open audio file", map[string]any{"path": audioFilePath, "error": err})
+		return nil, fmt.Errorf("failed to open audio file: %w", err)
+	}
+	defer audioFile.Close()
+
+	fileInfo, err := audioFile.Stat()
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to get file info", map[string]any{"path": audioFilePath, "error": err})
+		return nil, fmt.Errorf("failed to get file info: %w", err)
+	}
+
+	logger.DebugCF("voice", "Audio file details", map[string]any{
+		"size_bytes": fileInfo.Size(),
+		"file_name":  filepath.Base(audioFilePath),
+	})
+
+	var requestBody bytes.Buffer
+	writer := multipart.NewWriter(&requestBody)
+
+	part, err := writer.CreateFormFile("file", filepath.Base(audioFilePath))
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to create form file", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to create form file: %w", err)
+	}
+
+	if _, err = io.Copy(part, audioFile); err != nil {
+		logger.ErrorCF("voice", "Failed to copy file content", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to copy file content: %w", err)
+	}
+
+	if err = writer.WriteField("model_id", "scribe_v1"); err != nil {
+		return nil, fmt.Errorf("failed to write model_id field: %w", err)
+	}
+
+	if err = writer.Close(); err != nil {
+		logger.ErrorCF("voice", "Failed to close multipart writer", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to close multipart writer: %w", err)
+	}
+
+	url := t.apiBase + "/v1/speech-to-text"
+	req, err := http.NewRequestWithContext(ctx, "POST", url, &requestBody)
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to create request", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", writer.FormDataContentType())
+	req.Header.Set("Xi-Api-Key", t.apiKey)
+
+	logger.DebugCF("voice", "Sending transcription request to ElevenLabs API", map[string]any{
+		"url":                url,
+		"request_size_bytes": requestBody.Len(),
+		"file_size_bytes":    fileInfo.Size(),
+	})
+
+	resp, err := t.httpClient.Do(req)
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to send request", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to send request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to read response", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		logger.ErrorCF("voice", "ElevenLabs API error", map[string]any{
+			"status_code": resp.StatusCode,
+			"response":    string(body),
+		})
+		return nil, fmt.Errorf("ElevenLabs API error (status %d): %s", resp.StatusCode, string(body))
+	}
+
+	logger.DebugCF("voice", "Received response from ElevenLabs API", map[string]any{
+		"status_code":         resp.StatusCode,
+		"response_size_bytes": len(body),
+	})
+
+	var result TranscriptionResponse
+	if err := json.Unmarshal(body, &result); err != nil {
+		logger.ErrorCF("voice", "Failed to unmarshal response", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to unmarshal response: %w", err)
+	}
+
+	logger.InfoCF("voice", "ElevenLabs transcription completed successfully", map[string]any{
+		"text_length":           len(result.Text),
+		"language":              result.Language,
+		"transcription_preview": utils.Truncate(result.Text, 50),
+	})
+
+	return &result, nil
+}
+
+func (t *ElevenLabsTranscriber) Name() string {
+	return "elevenlabs"
+}
diff --git a/pkg/voice/elevenlabs_transcriber_test.go b/pkg/voice/elevenlabs_transcriber_test.go
new file mode 100644
index 000000000..78be8958a
--- /dev/null
+++ b/pkg/voice/elevenlabs_transcriber_test.go
@@ -0,0 +1,83 @@
+package voice
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// Ensure ElevenLabsTranscriber satisfies the Transcriber interface at compile time.
+var _ Transcriber = (*ElevenLabsTranscriber)(nil)
+
+func TestElevenLabsTranscriberName(t *testing.T) {
+	tr := NewElevenLabsTranscriber("sk_test")
+	if got := tr.Name(); got != "elevenlabs" {
+		t.Errorf("Name() = %q, want %q", got, "elevenlabs")
+	}
+}
+
+func TestElevenLabsTranscribe(t *testing.T) {
+	tmpDir := t.TempDir()
+	audioPath := filepath.Join(tmpDir, "clip.ogg")
+	if err := os.WriteFile(audioPath, []byte("fake-audio-data"), 0o644); err != nil {
+		t.Fatalf("failed to write fake audio file: %v", err)
+	}
+
+	t.Run("success", func(t *testing.T) {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.URL.Path != "/v1/speech-to-text" {
+				t.Errorf("unexpected path: %s", r.URL.Path)
+			}
+			if r.Header.Get("Xi-Api-Key") != "sk_test" {
+				t.Errorf("unexpected xi-api-key header: %s", r.Header.Get("Xi-Api-Key"))
+			}
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(TranscriptionResponse{
+				Text:     "hello from elevenlabs",
+				Language: "en",
+			})
+		}))
+		defer srv.Close()
+
+		tr := NewElevenLabsTranscriber("sk_test")
+		tr.apiBase = srv.URL
+
+		resp, err := tr.Transcribe(context.Background(), audioPath)
+		if err != nil {
+			t.Fatalf("Transcribe() error: %v", err)
+		}
+		if resp.Text != "hello from elevenlabs" {
+			t.Errorf("Text = %q, want %q", resp.Text, "hello from elevenlabs")
+		}
+		if resp.Language != "en" {
+			t.Errorf("Language = %q, want %q", resp.Language, "en")
+		}
+	})
+
+	t.Run("api error", func(t *testing.T) {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			http.Error(w, `{"error":"invalid_api_key"}`, http.StatusUnauthorized)
+		}))
+		defer srv.Close()
+
+		tr := NewElevenLabsTranscriber("sk_bad")
+		tr.apiBase = srv.URL
+
+		_, err := tr.Transcribe(context.Background(), audioPath)
+		if err == nil {
+			t.Fatal("expected error for non-200 response, got nil")
+		}
+	})
+
+	t.Run("missing file", func(t *testing.T) {
+		tr := NewElevenLabsTranscriber("sk_test")
+		_, err := tr.Transcribe(context.Background(), filepath.Join(tmpDir, "nonexistent.ogg"))
+		if err == nil {
+			t.Fatal("expected error for missing file, got nil")
+		}
+	})
+}
diff --git a/pkg/voice/groq_transcriber.go b/pkg/voice/groq_transcriber.go
new file mode 100644
index 000000000..b42e598f7
--- /dev/null
+++ b/pkg/voice/groq_transcriber.go
@@ -0,0 +1,151 @@
+package voice
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/utils"
+)
+
+type GroqTranscriber struct {
+	apiKey     string
+	apiBase    string
+	httpClient *http.Client
+}
+
+func NewGroqTranscriber(apiKey string) *GroqTranscriber {
+	logger.DebugCF("voice", "Creating Groq transcriber", map[string]any{"has_api_key": apiKey != ""})
+
+	apiBase := "https://api.groq.com/openai/v1"
+	return &GroqTranscriber{
+		apiKey:  apiKey,
+		apiBase: apiBase,
+		httpClient: &http.Client{
+			Timeout: 60 * time.Second,
+		},
+	}
+}
+
+func (t *GroqTranscriber) Transcribe(ctx context.Context, audioFilePath string) (*TranscriptionResponse, error) {
+	logger.InfoCF("voice", "Starting transcription", map[string]any{"audio_file": audioFilePath})
+
+	audioFile, err := os.Open(audioFilePath)
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to open audio file", map[string]any{"path": audioFilePath, "error": err})
+		return nil, fmt.Errorf("failed to open audio file: %w", err)
+	}
+	defer audioFile.Close()
+
+	fileInfo, err := audioFile.Stat()
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to get file info", map[string]any{"path": audioFilePath, "error": err})
+		return nil, fmt.Errorf("failed to get file info: %w", err)
+	}
+
+	logger.DebugCF("voice", "Audio file details", map[string]any{
+		"size_bytes": fileInfo.Size(),
+		"file_name":  filepath.Base(audioFilePath),
+	})
+
+	var requestBody bytes.Buffer
+	writer := multipart.NewWriter(&requestBody)
+
+	part, err := writer.CreateFormFile("file", filepath.Base(audioFilePath))
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to create form file", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to create form file: %w", err)
+	}
+
+	copied, err := io.Copy(part, audioFile)
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to copy file content", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to copy file content: %w", err)
+	}
+
+	logger.DebugCF("voice", "File copied to request", map[string]any{"bytes_copied": copied})
+
+	if err = writer.WriteField("model", "whisper-large-v3"); err != nil {
+		logger.ErrorCF("voice", "Failed to write model field", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to write model field: %w", err)
+	}
+
+	if err = writer.WriteField("response_format", "json"); err != nil {
+		logger.ErrorCF("voice", "Failed to write response_format field", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to write response_format field: %w", err)
+	}
+
+	if err = writer.Close(); err != nil {
+		logger.ErrorCF("voice", "Failed to close multipart writer", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to close multipart writer: %w", err)
+	}
+
+	url := t.apiBase + "/audio/transcriptions"
+	req, err := http.NewRequestWithContext(ctx, "POST", url, &requestBody)
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to create request", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to create request: %w", err)
+	}
+
+	req.Header.Set("Content-Type", writer.FormDataContentType())
+	req.Header.Set("Authorization", "Bearer "+t.apiKey)
+
+	logger.DebugCF("voice", "Sending transcription request to Groq API", map[string]any{
+		"url":                url,
+		"request_size_bytes": requestBody.Len(),
+		"file_size_bytes":    fileInfo.Size(),
+	})
+
+	resp, err := t.httpClient.Do(req)
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to send request", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to send request: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	if err != nil {
+		logger.ErrorCF("voice", "Failed to read response", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to read response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		logger.ErrorCF("voice", "API error", map[string]any{
+			"status_code": resp.StatusCode,
+			"response":    string(body),
+		})
+		return nil, fmt.Errorf("API error (status %d): %s", resp.StatusCode, string(body))
+	}
+
+	logger.DebugCF("voice", "Received response from Groq API", map[string]any{
+		"status_code":         resp.StatusCode,
+		"response_size_bytes": len(body),
+	})
+
+	var result TranscriptionResponse
+	if err := json.Unmarshal(body, &result); err != nil {
+		logger.ErrorCF("voice", "Failed to unmarshal response", map[string]any{"error": err})
+		return nil, fmt.Errorf("failed to unmarshal response: %w", err)
+	}
+
+	logger.InfoCF("voice", "Transcription completed successfully", map[string]any{
+		"text_length":           len(result.Text),
+		"language":              result.Language,
+		"duration_seconds":      result.Duration,
+		"transcription_preview": utils.Truncate(result.Text, 50),
+	})
+
+	return &result, nil
+}
+
+func (t *GroqTranscriber) Name() string {
+	return "groq"
+}
diff --git a/pkg/voice/groq_transcriber_test.go b/pkg/voice/groq_transcriber_test.go
new file mode 100644
index 000000000..fdcaa7580
--- /dev/null
+++ b/pkg/voice/groq_transcriber_test.go
@@ -0,0 +1,84 @@
+package voice
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+var _ Transcriber = (*GroqTranscriber)(nil)
+
+func TestGroqTranscriberName(t *testing.T) {
+	tr := NewGroqTranscriber("sk-test")
+	if got := tr.Name(); got != "groq" {
+		t.Errorf("Name() = %q, want %q", got, "groq")
+	}
+}
+
+func TestGroqTranscribe(t *testing.T) {
+	// Write a minimal fake audio file so the transcriber can open and send it.
+	tmpDir := t.TempDir()
+	audioPath := filepath.Join(tmpDir, "clip.ogg")
+	if err := os.WriteFile(audioPath, []byte("fake-audio-data"), 0o644); err != nil {
+		t.Fatalf("failed to write fake audio file: %v", err)
+	}
+
+	t.Run("success", func(t *testing.T) {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.URL.Path != "/audio/transcriptions" {
+				t.Errorf("unexpected path: %s", r.URL.Path)
+			}
+			if r.Header.Get("Authorization") != "Bearer sk-test" {
+				t.Errorf("unexpected Authorization header: %s", r.Header.Get("Authorization"))
+			}
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(TranscriptionResponse{
+				Text:     "hello world",
+				Language: "en",
+				Duration: 1.5,
+			})
+		}))
+		defer srv.Close()
+
+		tr := NewGroqTranscriber("sk-test")
+		tr.apiBase = srv.URL
+
+		resp, err := tr.Transcribe(context.Background(), audioPath)
+		if err != nil {
+			t.Fatalf("Transcribe() error: %v", err)
+		}
+		if resp.Text != "hello world" {
+			t.Errorf("Text = %q, want %q", resp.Text, "hello world")
+		}
+		if resp.Language != "en" {
+			t.Errorf("Language = %q, want %q", resp.Language, "en")
+		}
+	})
+
+	t.Run("api error", func(t *testing.T) {
+		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			http.Error(w, `{"error":"invalid_api_key"}`, http.StatusUnauthorized)
+		}))
+		defer srv.Close()
+
+		tr := NewGroqTranscriber("sk-bad")
+		tr.apiBase = srv.URL
+
+		_, err := tr.Transcribe(context.Background(), audioPath)
+		if err == nil {
+			t.Fatal("expected error for non-200 response, got nil")
+		}
+	})
+
+	t.Run("missing file", func(t *testing.T) {
+		tr := NewGroqTranscriber("sk-test")
+		_, err := tr.Transcribe(context.Background(), filepath.Join(tmpDir, "nonexistent.ogg"))
+		if err == nil {
+			t.Fatal("expected error for missing file, got nil")
+		}
+	})
+}
diff --git a/pkg/voice/transcriber.go b/pkg/voice/transcriber.go
index f973e77fe..f56fdeedd 100644
--- a/pkg/voice/transcriber.go
+++ b/pkg/voice/transcriber.go
@@ -1,25 +1,16 @@
 package voice
 
 import (
-	"bytes"
 	"context"
-	"encoding/json"
-	"fmt"
-	"io"
-	"mime/multipart"
-	"net/http"
-	"os"
-	"path/filepath"
-	"time"
+	"strings"
 
-	"github.com/sipeed/picoclaw/pkg/logger"
-	"github.com/sipeed/picoclaw/pkg/utils"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
 )
 
-type GroqTranscriber struct {
-	apiKey     string
-	apiBase    string
-	httpClient *http.Client
+type Transcriber interface {
+	Name() string
+	Transcribe(ctx context.Context, audioFilePath string) (*TranscriptionResponse, error)
 }
 
 type TranscriptionResponse struct {
@@ -28,132 +19,50 @@ type TranscriptionResponse struct {
 	Duration float64 `json:"duration,omitempty"`
 }
 
-func NewGroqTranscriber(apiKey string) *GroqTranscriber {
-	logger.DebugCF("voice", "Creating Groq transcriber", map[string]any{"has_api_key": apiKey != ""})
+func supportsAudioTranscription(model string) bool {
+	protocol, _ := providers.ExtractProtocol(model)
 
-	apiBase := "https://api.groq.com/openai/v1"
-	return &GroqTranscriber{
-		apiKey:  apiKey,
-		apiBase: apiBase,
-		httpClient: &http.Client{
-			Timeout: 60 * time.Second,
-		},
+	switch protocol {
+	case "openai", "azure", "azure-openai",
+		"litellm", "openrouter", "groq", "zhipu", "gemini", "nvidia",
+		"ollama", "moonshot", "shengsuanyun", "deepseek", "cerebras",
+		"vivgrid", "volcengine", "vllm", "qwen", "qwen-intl", "qwen-international", "dashscope-intl",
+		"qwen-us", "dashscope-us", "mistral", "avian", "minimax", "longcat", "modelscope", "novita",
+		"coding-plan", "alibaba-coding", "qwen-coding":
+		// These protocols all go through the OpenAI-compatible or Azure provider path in
+		// providers.CreateProviderFromConfig, so they are the only ones that can supply
+		// the audio media payload shape expected by NewAudioModelTranscriber.
+
+		// TODO: Further restrict this by modelID, since not every model under these
+		// protocols supports audio transcription.
+		return true
+	default:
+		return false
 	}
 }
 
-func (t *GroqTranscriber) Transcribe(ctx context.Context, audioFilePath string) (*TranscriptionResponse, error) {
-	logger.InfoCF("voice", "Starting transcription", map[string]any{"audio_file": audioFilePath})
-
-	audioFile, err := os.Open(audioFilePath)
-	if err != nil {
-		logger.ErrorCF("voice", "Failed to open audio file", map[string]any{"path": audioFilePath, "error": err})
-		return nil, fmt.Errorf("failed to open audio file: %w", err)
-	}
-	defer audioFile.Close()
-
-	fileInfo, err := audioFile.Stat()
-	if err != nil {
-		logger.ErrorCF("voice", "Failed to get file info", map[string]any{"path": audioFilePath, "error": err})
-		return nil, fmt.Errorf("failed to get file info: %w", err)
+// DetectTranscriber inspects cfg and returns the appropriate Transcriber, or
+// nil if no supported transcription provider is configured.
+func DetectTranscriber(cfg *config.Config) Transcriber {
+	if modelName := strings.TrimSpace(cfg.Voice.ModelName); modelName != "" {
+		modelCfg, err := cfg.GetModelConfig(modelName)
+		if err != nil {
+			return nil
+		}
+		if supportsAudioTranscription(modelCfg.Model) {
+			return NewAudioModelTranscriber(modelCfg)
+		}
 	}
 
-	logger.DebugCF("voice", "Audio file details", map[string]any{
-		"size_bytes": fileInfo.Size(),
-		"file_name":  filepath.Base(audioFilePath),
-	})
-
-	var requestBody bytes.Buffer
-	writer := multipart.NewWriter(&requestBody)
-
-	part, err := writer.CreateFormFile("file", filepath.Base(audioFilePath))
-	if err != nil {
-		logger.ErrorCF("voice", "Failed to create form file", map[string]any{"error": err})
-		return nil, fmt.Errorf("failed to create form file: %w", err)
+	// ElevenLabs voice config (supports Scribe STT).
+	if key := strings.TrimSpace(cfg.Voice.ElevenLabsAPIKey); key != "" {
+		return NewElevenLabsTranscriber(key)
 	}
-
-	copied, err := io.Copy(part, audioFile)
-	if err != nil {
-		logger.ErrorCF("voice", "Failed to copy file content", map[string]any{"error": err})
-		return nil, fmt.Errorf("failed to copy file content: %w", err)
+	// Fall back to any model-list entry that uses the groq/ protocol.
+	for _, mc := range cfg.ModelList {
+		if strings.HasPrefix(mc.Model, "groq/") && mc.APIKey() != "" {
+			return NewGroqTranscriber(mc.APIKey())
+		}
 	}
-
-	logger.DebugCF("voice", "File copied to request", map[string]any{"bytes_copied": copied})
-
-	if err = writer.WriteField("model", "whisper-large-v3"); err != nil {
-		logger.ErrorCF("voice", "Failed to write model field", map[string]any{"error": err})
-		return nil, fmt.Errorf("failed to write model field: %w", err)
-	}
-
-	if err = writer.WriteField("response_format", "json"); err != nil {
-		logger.ErrorCF("voice", "Failed to write response_format field", map[string]any{"error": err})
-		return nil, fmt.Errorf("failed to write response_format field: %w", err)
-	}
-
-	if err = writer.Close(); err != nil {
-		logger.ErrorCF("voice", "Failed to close multipart writer", map[string]any{"error": err})
-		return nil, fmt.Errorf("failed to close multipart writer: %w", err)
-	}
-
-	url := t.apiBase + "/audio/transcriptions"
-	req, err := http.NewRequestWithContext(ctx, "POST", url, &requestBody)
-	if err != nil {
-		logger.ErrorCF("voice", "Failed to create request", map[string]any{"error": err})
-		return nil, fmt.Errorf("failed to create request: %w", err)
-	}
-
-	req.Header.Set("Content-Type", writer.FormDataContentType())
-	req.Header.Set("Authorization", "Bearer "+t.apiKey)
-
-	logger.DebugCF("voice", "Sending transcription request to Groq API", map[string]any{
-		"url":                url,
-		"request_size_bytes": requestBody.Len(),
-		"file_size_bytes":    fileInfo.Size(),
-	})
-
-	resp, err := t.httpClient.Do(req)
-	if err != nil {
-		logger.ErrorCF("voice", "Failed to send request", map[string]any{"error": err})
-		return nil, fmt.Errorf("failed to send request: %w", err)
-	}
-	defer resp.Body.Close()
-
-	body, err := io.ReadAll(resp.Body)
-	if err != nil {
-		logger.ErrorCF("voice", "Failed to read response", map[string]any{"error": err})
-		return nil, fmt.Errorf("failed to read response: %w", err)
-	}
-
-	if resp.StatusCode != http.StatusOK {
-		logger.ErrorCF("voice", "API error", map[string]any{
-			"status_code": resp.StatusCode,
-			"response":    string(body),
-		})
-		return nil, fmt.Errorf("API error (status %d): %s", resp.StatusCode, string(body))
-	}
-
-	logger.DebugCF("voice", "Received response from Groq API", map[string]any{
-		"status_code":         resp.StatusCode,
-		"response_size_bytes": len(body),
-	})
-
-	var result TranscriptionResponse
-	if err := json.Unmarshal(body, &result); err != nil {
-		logger.ErrorCF("voice", "Failed to unmarshal response", map[string]any{"error": err})
-		return nil, fmt.Errorf("failed to unmarshal response: %w", err)
-	}
-
-	logger.InfoCF("voice", "Transcription completed successfully", map[string]any{
-		"text_length":           len(result.Text),
-		"language":              result.Language,
-		"duration_seconds":      result.Duration,
-		"transcription_preview": utils.Truncate(result.Text, 50),
-	})
-
-	return &result, nil
-}
-
-func (t *GroqTranscriber) IsAvailable() bool {
-	available := t.apiKey != ""
-	logger.DebugCF("voice", "Checking transcriber availability", map[string]any{"available": available})
-	return available
+	return nil
 }
diff --git a/pkg/voice/transcriber_test.go b/pkg/voice/transcriber_test.go
new file mode 100644
index 000000000..70a7fca8f
--- /dev/null
+++ b/pkg/voice/transcriber_test.go
@@ -0,0 +1,209 @@
+package voice
+
+import (
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestDetectTranscriber(t *testing.T) {
+	tests := []struct {
+		name     string
+		cfg      *config.Config
+		wantNil  bool
+		wantName string
+	}{
+		{
+			name:    "no config",
+			cfg:     &config.Config{},
+			wantNil: true,
+		},
+		{
+			name: "voice model name selects audio model transcriber",
+			cfg: (&config.Config{
+				Voice: config.VoiceConfig{ModelName: "voice-gemini"},
+				ModelList: []*config.ModelConfig{
+					{ModelName: "voice-gemini", Model: "gemini/gemini-2.5-flash"},
+				},
+			}).WithSecurity(&config.SecurityConfig{
+				ModelList: map[string]config.ModelSecurityEntry{
+					"voice-gemini": {
+						APIKeys: []string{"sk-gemini-model"},
+					},
+				},
+			}),
+			wantName: "audio-model",
+		},
+		{
+			name: "groq via model list",
+			cfg: (&config.Config{
+				ModelList: []*config.ModelConfig{
+					{ModelName: "openai", Model: "openai/gpt-4o"},
+					{ModelName: "groq", Model: "groq/llama-3.3-70b"},
+				},
+			}).WithSecurity(&config.SecurityConfig{
+				ModelList: map[string]config.ModelSecurityEntry{
+					"openai": {
+						APIKeys: []string{"sk-openai"},
+					},
+					"groq": {
+						APIKeys: []string{"sk-groq-model"},
+					},
+				},
+			}),
+			wantName: "groq",
+		},
+		{
+			name: "voice model name selects non-gemini audio model transcriber",
+			cfg: (&config.Config{
+				Voice: config.VoiceConfig{ModelName: "voice-openai-audio"},
+				ModelList: []*config.ModelConfig{
+					{ModelName: "voice-openai-audio", Model: "openai/gpt-4o-audio-preview"},
+				},
+			}).WithSecurity(&config.SecurityConfig{
+				ModelList: map[string]config.ModelSecurityEntry{
+					"voice-openai-audio": {
+						APIKeys: []string{"sk-openai"},
+					},
+				},
+			}),
+			wantName: "audio-model",
+		},
+		{
+			name: "voice model name selects azure audio model transcriber",
+			cfg: (&config.Config{
+				Voice: config.VoiceConfig{ModelName: "voice-azure-audio"},
+				ModelList: []*config.ModelConfig{
+					{
+						ModelName: "voice-azure-audio",
+						Model:     "azure/my-audio-deployment",
+						APIBase:   "https://example.openai.azure.com",
+					},
+				},
+			}).WithSecurity(&config.SecurityConfig{
+				ModelList: map[string]config.ModelSecurityEntry{
+					"voice-azure-audio": {
+						APIKeys: []string{"sk-azure"},
+					},
+				},
+			}),
+			wantName: "audio-model",
+		},
+		{
+			name: "voice model name with non openai compatible protocol does not select audio model transcriber",
+			cfg: (&config.Config{
+				Voice: config.VoiceConfig{ModelName: "voice-anthropic"},
+				ModelList: []*config.ModelConfig{
+					{ModelName: "voice-anthropic", Model: "anthropic/claude-sonnet-4.6"},
+				},
+			}).WithSecurity(&config.SecurityConfig{
+				ModelList: map[string]config.ModelSecurityEntry{
+					"voice-anthropic": {
+						APIKeys: []string{"sk-anthropic"},
+					},
+				},
+			}),
+			wantNil: true,
+		},
+		{
+			name: "groq model list entry without key is skipped",
+			cfg: &config.Config{
+				ModelList: []*config.ModelConfig{
+					{Model: "groq/llama-3.3-70b"},
+				},
+			},
+			wantNil: true,
+		},
+		{
+			name: "provider key takes priority over model list",
+			cfg: (&config.Config{
+				ModelList: []*config.ModelConfig{
+					{ModelName: "groq", Model: "groq/llama-3.3-70b"},
+				},
+			}).WithSecurity(&config.SecurityConfig{
+				ModelList: map[string]config.ModelSecurityEntry{
+					"groq": {
+						APIKeys: []string{"sk-groq-model"},
+					},
+				},
+			}),
+			wantName: "groq",
+		},
+		{
+			name: "missing voice model name config returns nil",
+			cfg: (&config.Config{
+				Voice: config.VoiceConfig{ModelName: "missing"},
+				ModelList: []*config.ModelConfig{
+					{ModelName: "other", Model: "gemini/gemini-2.5-flash"},
+				},
+			}).WithSecurity(&config.SecurityConfig{
+				ModelList: map[string]config.ModelSecurityEntry{
+					"other": {
+						APIKeys: []string{"sk-other-model"},
+					},
+				},
+			}),
+			wantNil: true,
+		},
+		{
+			name: "elevenlabs voice config key",
+			cfg: &config.Config{
+				Voice: config.VoiceConfig{ElevenLabsAPIKey: "sk_elevenlabs_test"},
+			},
+			wantName: "elevenlabs",
+		},
+		{
+			name: "elevenlabs takes priority over groq model list",
+			cfg: (&config.Config{
+				Voice: config.VoiceConfig{ElevenLabsAPIKey: "sk_elevenlabs_test"},
+				ModelList: []*config.ModelConfig{
+					{ModelName: "groq", Model: "groq/llama-3.3-70b"},
+				},
+			}).WithSecurity(&config.SecurityConfig{
+				ModelList: map[string]config.ModelSecurityEntry{
+					"groq": {
+						APIKeys: []string{"sk-groq-direct"},
+					},
+				},
+			}),
+			wantName: "elevenlabs",
+		},
+		{
+			name: "voice model name takes priority over elevenlabs",
+			cfg: (&config.Config{
+				Voice: config.VoiceConfig{
+					ModelName:        "voice-gemini",
+					ElevenLabsAPIKey: "sk_elevenlabs_test",
+				},
+				ModelList: []*config.ModelConfig{
+					{ModelName: "voice-gemini", Model: "gemini/gemini-2.5-flash"},
+				},
+			}).WithSecurity(&config.SecurityConfig{
+				ModelList: map[string]config.ModelSecurityEntry{
+					"voice-gemini": {
+						APIKeys: []string{"sk-gemini-model"},
+					},
+				},
+			}),
+			wantName: "audio-model",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			tr := DetectTranscriber(tc.cfg)
+			if tc.wantNil {
+				if tr != nil {
+					t.Errorf("DetectTranscriber() = %v, want nil", tr)
+				}
+				return
+			}
+			if tr == nil {
+				t.Fatal("DetectTranscriber() = nil, want non-nil")
+			}
+			if got := tr.Name(); got != tc.wantName {
+				t.Errorf("Name() = %q, want %q", got, tc.wantName)
+			}
+		})
+	}
+}
diff --git a/scripts/build-macos-app.sh b/scripts/build-macos-app.sh
new file mode 100755
index 000000000..76cc72938
--- /dev/null
+++ b/scripts/build-macos-app.sh
@@ -0,0 +1,106 @@
+#!/bin/bash
+# Build macOS .app bundle for PicoClaw Launcher
+
+set -e
+
+EXECUTABLE=$1
+
+if [ -z "$EXECUTABLE" ]; then
+    echo "Usage: $0 <executable>"
+    exit 1
+fi
+
+echo "executable: $EXECUTABLE"
+
+APP_NAME="PicoClaw Launcher"
+APP_PATH="./build/${APP_NAME}.app"
+APP_CONTENTS="${APP_PATH}/Contents"
+APP_MACOS="${APP_CONTENTS}/MacOS"
+APP_RESOURCES="${APP_CONTENTS}/Resources"
+APP_EXECUTABLE="picoclaw-launcher"
+ICON_SOURCE="./scripts/icon.icns"
+
+# Clean up existing .app
+if [ -d "$APP_PATH" ]; then
+    echo "Removing existing ${APP_PATH}"
+    rm -rf "$APP_PATH"
+fi
+
+# Create directory structure
+echo "Creating .app bundle structure..."
+mkdir -p "$APP_MACOS"
+mkdir -p "$APP_RESOURCES"
+
+# Copy executable
+echo "Copying executable..."
+if [ -f "./web/build/${APP_EXECUTABLE}" ]; then
+    cp "./web/build/${APP_EXECUTABLE}" "${APP_MACOS}/"
+else
+    echo "Error: ./web/build/${APP_EXECUTABLE} not found. Please build the web backend first."
+    echo "Run: make build in web dir"
+    exit 1
+fi
+if [ -f "./build/picoclaw" ]; then
+    cp "./build/picoclaw" "${APP_MACOS}/"
+else
+    echo "Error: ./build/picoclaw not found. Please build the main file first."
+    echo "Run: make build"
+    exit 1
+fi
+chmod +x "${APP_MACOS}/"*
+
+# Create Info.plist
+echo "Creating Info.plist..."
+cat > "${APP_CONTENTS}/Info.plist" << 'EOF'
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleExecutable</key>
+    <string>picoclaw-launcher</string>
+    <key>CFBundleIdentifier</key>
+    <string>com.picoclaw.launcher</string>
+    <key>CFBundleName</key>
+    <string>PicoClaw Launcher</string>
+    <key>CFBundleDisplayName</key>
+    <string>PicoClaw Launcher</string>
+    <key>CFBundleIconFile</key>
+    <string>icon.icns</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleShortVersionString</key>
+    <string>1.0</string>
+    <key>CFBundleVersion</key>
+    <string>1</string>
+    <key>NSHighResolutionCapable</key>
+    <true/>
+    <key>NSSupportsAutomaticGraphicsSwitching</key>
+    <true/>
+    <key>LSRequiresCarbon</key>
+    <true/>
+    <key>LSUIElement</key>
+    <string>1</string>
+</dict>
+</plist>
+EOF
+
+#sips -z 128 128 "$ICON_SOURCE" --out "${ICONSET_PATH}/icon_128x128.png" > /dev/null 2>&1
+#
+## Create icns file
+#iconutil -c icns "$ICONSET_PATH" -o "$ICON_OUTPUT" 2>/dev/null || {
+#    echo "Warning: iconutil failed"
+#}
+
+cp $ICON_SOURCE "${APP_RESOURCES}/icon.icns"
+
+echo ""
+echo "=========================================="
+echo "Successfully created: ${APP_PATH}"
+echo "=========================================="
+echo ""
+echo "To launch PicoClaw:"
+echo "  1. Double-click ${APP_NAME}.app in Finder"
+echo "  2. Or use: open ${APP_PATH}"
+echo ""
+echo "Note: The app will run in the menu bar (systray) without a terminal window."
+echo ""
diff --git a/scripts/icon.icns b/scripts/icon.icns
new file mode 100644
index 000000000..bcf9adcd7
Binary files /dev/null and b/scripts/icon.icns differ
diff --git a/scripts/setup.iss b/scripts/setup.iss
new file mode 100644
index 000000000..c081d4dff
--- /dev/null
+++ b/scripts/setup.iss
@@ -0,0 +1,65 @@
+; Script generated by the Inno Setup Script Wizard.
+; SEE THE DOCUMENTATION FOR DETAILS ON CREATING INNO SETUP SCRIPT FILES!
+
+#define MyAppName "PicoClaw Launcher"
+#define MyAppVersion "1.0"
+#define MyAppPublisher "PicoClaw"
+#define MyAppURL "https://github.com/sipeed/picoclaw"
+#define MyAppExeName "picoclaw-launcher.exe"
+
+[Setup]
+; NOTE: The value of AppId uniquely identifies this application. Do not use the same AppId value in installers for other applications.
+; (To generate a new GUID, click Tools | Generate GUID inside the IDE.)
+AppId={{C8A1B4E7-D5F9-4C2A-8A6E-5F4D3C2A1B0E}
+AppName={#MyAppName}
+AppVersion={#MyAppVersion}
+;AppVerName={#MyAppName} {#MyAppVersion}
+AppPublisher={#MyAppPublisher}
+AppPublisherURL={#MyAppURL}
+AppSupportURL={#MyAppURL}
+AppUpdatesURL={#MyAppURL}
+DefaultDirName={autopf}\PicoClaw
+DefaultGroupName={#MyAppName}
+; "ArchitecturesAllowed=x64compatible" specifies that Setup cannot run
+; on anything but x64 and Windows 11 on Arm.
+ArchitecturesAllowed=x64compatible
+; "ArchitecturesInstallIn64BitMode=x64compatible" requests that the
+; install be done in "64-bit mode" on x64 or Windows 11 on Arm,
+; meaning it should use the native 64-bit Program Files directory and
+; the 64-bit view of the registry.
+ArchitecturesInstallIn64BitMode=x64compatible
+DisableProgramGroupPage=yes
+; Remove the following line to run in administrative install mode (install for all users.)
+PrivilegesRequired=lowest
+OutputDir=build
+OutputBaseFilename=PicoClawSetup
+Compression=lzma
+SolidCompression=yes
+WizardStyle=modern
+; SourceDir=windows
+SetupIconFile=icon.ico
+
+[Languages]
+Name: "english"; MessagesFile: "compiler:Default.isl"
+
+[Tasks]
+Name: "desktopicon"; Description: "{cm:CreateDesktopIcon}"; GroupDescription: "{cm:AdditionalIcons}"; Flags: unchecked
+
+[Dirs]
+
+[Files]
+Source: "..\web\build\picoclaw-launcher.exe"; DestDir: "{app}"; DestName: "{#MyAppExeName}"; Flags: ignoreversion
+Source: "..\build\picoclaw.exe"; DestDir: "{app}"; Flags: ignoreversion
+Source: "..\web\backend\icon.ico"; DestDir: "{app}"; Flags: ignoreversion
+; NOTE: Don't use "Flags: ignoreversion" on any shared system files
+
+[UninstallDelete]
+
+[Icons]
+Name: "{group}\{#MyAppName}"; Filename: "{app}\{#MyAppExeName}"; WorkingDir: "{app}"; IconFilename: "{app}\icon.ico"
+Name: "{group}\Uninstall {#MyAppName}"; Filename: "{uninstallexe}"
+Name: "{autodesktop}\{#MyAppName}"; Filename: "{app}\{#MyAppExeName}"; WorkingDir: "{app}"; Tasks: desktopicon; IconFilename: "{app}\icon.ico"
+
+[Run]
+Filename:"{app}\{#MyAppExeName}"; WorkingDir: "{app}"; Description: "{cm:LaunchProgram,{#StringChange(MyAppName, '&', '&&')}}"; Flags: nowait postinstall skipifsilent
+
diff --git a/scripts/test-docker-mcp.sh b/scripts/test-docker-mcp.sh
new file mode 100755
index 000000000..9d582ffa0
--- /dev/null
+++ b/scripts/test-docker-mcp.sh
@@ -0,0 +1,49 @@
+#!/bin/sh
+# Test script for MCP tools in Docker (full-featured image)
+
+set -e
+
+COMPOSE_FILE="docker/docker-compose.full.yml"
+SERVICE="picoclaw-agent"
+
+echo "🧪 Testing MCP tools in Docker container (full-featured image)..."
+echo ""
+
+# Build the image
+echo "📦 Building Docker image..."
+docker compose -f "$COMPOSE_FILE" build "$SERVICE"
+
+# Test npx
+echo "✅ Testing npx..."
+docker compose -f "$COMPOSE_FILE" run --rm --entrypoint sh "$SERVICE" -c 'npx --version'
+
+# Test npm
+echo "✅ Testing npm..."
+docker compose -f "$COMPOSE_FILE" run --rm --entrypoint sh "$SERVICE" -c 'npm --version'
+
+# Test node
+echo "✅ Testing Node.js..."
+docker compose -f "$COMPOSE_FILE" run --rm --entrypoint sh "$SERVICE" -c 'node --version'
+
+# Test git
+echo "✅ Testing git..."
+docker compose -f "$COMPOSE_FILE" run --rm --entrypoint sh "$SERVICE" -c 'git --version'
+
+# Test python
+echo "✅ Testing Python..."
+docker compose -f "$COMPOSE_FILE" run --rm --entrypoint sh "$SERVICE" -c 'python3 --version'
+
+# Test uv
+echo "✅ Testing uv..."
+docker compose -f "$COMPOSE_FILE" run --rm --entrypoint sh "$SERVICE" -c 'uv --version'
+
+# Test MCP server installation (quick)
+echo "✅ Testing @modelcontextprotocol/server-filesystem MCP server install with npx..."
+docker compose -f "$COMPOSE_FILE" run --rm --entrypoint sh "$SERVICE" -c '</dev/null timeout 5 npx -y @modelcontextprotocol/server-filesystem /tmp || true'
+
+echo ""
+echo "🎉 All MCP tools are working correctly!"
+echo ""
+echo "Next steps:"
+echo "  1. Configure MCP servers in config/config.json"
+echo "  2. Run: docker compose -f $COMPOSE_FILE --profile gateway up"
diff --git a/scripts/test-irc.sh b/scripts/test-irc.sh
new file mode 100755
index 000000000..40db01756
--- /dev/null
+++ b/scripts/test-irc.sh
@@ -0,0 +1,56 @@
+#!/bin/sh
+# Starts a local Ergo IRC server for testing the IRC channel.
+#
+# Requirements: docker
+# Usage: ./scripts/test-irc.sh
+
+set -e
+
+CONTAINER_NAME="picoclaw-test-ergo"
+IRC_PORT=6667
+
+# Clean up any previous instance
+docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
+
+echo "Starting Ergo IRC server on port $IRC_PORT..."
+docker run -d \
+    --name "$CONTAINER_NAME" \
+    -p "$IRC_PORT:6667" \
+    ghcr.io/ergochat/ergo:stable
+
+for i in $(seq 1 10); do
+    if nc -z localhost "$IRC_PORT" 2>/dev/null; then
+        break
+    fi
+    if [ "$i" -eq 10 ]; then
+        echo "ERROR: Server did not start within 10s"
+        exit 1
+    fi
+    sleep 1
+done
+
+echo ""
+echo "IRC server ready on localhost:$IRC_PORT"
+echo ""
+echo "Add this to your ~/.picoclaw/config.json under \"channels\":"
+echo ""
+echo '  "irc": {'
+echo '    "enabled": true,'
+echo '    "server": "localhost:6667",'
+echo '    "tls": false,'
+echo '    "nick": "picobot",'
+echo '    "channels": ["#test"],'
+echo '    "allow_from": [],'
+echo '    "group_trigger": { "mention_only": true }'
+echo '  }'
+echo ""
+echo "Then run picoclaw:"
+echo "  cd packages/picoclaw && go run ./cmd/picoclaw gateway"
+echo ""
+echo "Connect with an IRC client:"
+echo "  irssi:   /connect localhost $IRC_PORT"
+echo "  weechat: /server add test localhost/$IRC_PORT && /connect test"
+echo "  Join #test, then: picobot: hello"
+echo ""
+echo "To stop the IRC server:"
+echo "  docker rm -f $CONTAINER_NAME"
diff --git a/web/Makefile b/web/Makefile
new file mode 100644
index 000000000..06717f2b9
--- /dev/null
+++ b/web/Makefile
@@ -0,0 +1,96 @@
+.PHONY: dev dev-frontend dev-backend build test lint clean
+
+# Go variables
+GO?=CGO_ENABLED=0 go
+WEB_GO?=$(GO)
+GOFLAGS?=-v -tags stdjson
+
+# Build variables
+BUILD_DIR=build
+
+# Version
+VERSION?=$(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
+GIT_COMMIT=$(shell git rev-parse --short=8 HEAD 2>/dev/null || echo "dev")
+BUILD_TIME=$(shell date +%FT%T%z)
+GO_VERSION=$(shell $(WEB_GO) version | awk '{print $$3}')
+CONFIG_PKG=github.com/sipeed/picoclaw/pkg/config
+LDFLAGS=-X $(CONFIG_PKG).Version=$(VERSION) -X $(CONFIG_PKG).GitCommit=$(GIT_COMMIT) -X $(CONFIG_PKG).BuildTime=$(BUILD_TIME) -X $(CONFIG_PKG).GoVersion=$(GO_VERSION) -s -w
+
+
+# OS detection
+UNAME_S:=$(shell uname -s)
+UNAME_M:=$(shell uname -m)
+
+# Platform-specific settings
+ifeq ($(UNAME_S),Linux)
+	PLATFORM=linux
+	ifeq ($(UNAME_M),x86_64)
+		ARCH=amd64
+	else ifeq ($(UNAME_M),aarch64)
+		ARCH=arm64
+	else ifeq ($(UNAME_M),armv81)
+		ARCH=arm64
+	else ifeq ($(UNAME_M),loongarch64)
+		ARCH=loong64
+	else ifeq ($(UNAME_M),riscv64)
+		ARCH=riscv64
+	else ifeq ($(UNAME_M),mipsel)
+		ARCH=mipsle
+	else
+		ARCH=$(UNAME_M)
+	endif
+else ifeq ($(UNAME_S),Darwin)
+	PLATFORM=darwin
+	WEB_GO=CGO_ENABLED=1 go
+	ifeq ($(UNAME_M),x86_64)
+		ARCH=amd64
+	else ifeq ($(UNAME_M),arm64)
+		ARCH=arm64
+	else
+		ARCH=$(UNAME_M)
+	endif
+else ifeq ($(UNAME_S),Windows)
+	PLATFORM=windows
+	ARCH=$(UNAME_M)
+	LDFLAGS=-H=windowsgui $(LDFLAGS)
+else
+	PLATFORM=$(UNAME_S)
+	ARCH=$(UNAME_M)
+endif
+
+# Run both frontend and backend dev servers
+dev:
+	@if [ ! -f $(BUILD_DIR)/picoclaw-launcher ] || [ ! -d backend/dist ]; then \
+		echo "Build artifacts not found, building..."; \
+		$(MAKE) build; \
+	fi
+	@echo "Starting backend and frontend dev servers..."
+	@$(MAKE) dev-backend & $(MAKE) dev-frontend
+
+# Start frontend dev server (Vite, with proxy to backend)
+dev-frontend:
+	cd frontend && pnpm dev
+
+# Start backend dev server
+dev-backend:
+	cd backend && ${WEB_GO} run -ldflags "$(LDFLAGS)" .
+
+# Build frontend and embed into Go binary
+build:
+	cd frontend && pnpm build:backend
+	${WEB_GO} build $(GOFLAGS) -ldflags "$(LDFLAGS)" -o $(BUILD_DIR)/picoclaw-launcher ./backend/
+
+# Run all tests
+test:
+	cd backend && ${WEB_GO} test ./...
+	cd frontend && pnpm lint
+
+# Lint and format
+lint:
+	cd backend && ${WEB_GO} vet ./...
+	cd frontend && pnpm check
+
+# Clean build artifacts
+clean:
+	rm -rf frontend/dist backend/dist $(BUILD_DIR)
+	mkdir -p backend/dist && touch backend/dist/.gitkeep
diff --git a/web/README.md b/web/README.md
new file mode 100644
index 000000000..6ec247bae
--- /dev/null
+++ b/web/README.md
@@ -0,0 +1,51 @@
+# Picoclaw Web
+
+This directory contains the standalone web service for `picoclaw`.
+It provides a complete unified web interface, acting as a dashboard, configuration center, and interactive console (channel client) for the core `picoclaw` engine.
+
+## Architecture
+
+The service is structured as a monorepo containing both the backend and frontend code to ensure high cohesion and simplify deployment.
+
+*   **`backend/`**: The Go-based web server. It provides RESTful APIs, manages WebSocket connections for chat, and handles the lifecycle of the `picoclaw` process. It eventually embeds the compiled frontend assets into a single executable.
+*   **`frontend/`**: The Vite + React + TanStack Router single-page application (SPA). It provides the interactive user interface.
+
+## Getting Started
+
+### Prerequisites
+
+*   Go 1.25+
+*   Node.js 20+ with pnpm
+
+### Development
+
+Run both the frontend dev server and the Go backend simultaneously:
+
+```bash
+make dev
+```
+
+Or run them separately:
+
+```bash
+make dev-frontend   # Vite dev server
+make dev-backend    # Go backend
+```
+
+### Build
+
+Build the frontend and embed it into a single Go binary:
+
+```bash
+make build
+```
+
+The output binary is `backend/picoclaw-web`.
+
+### Other Commands
+
+```bash
+make test    # Run backend tests and frontend lint
+make lint    # Run go vet and prettier/eslint
+make clean   # Remove all build artifacts
+```
diff --git a/web/backend/.gitignore b/web/backend/.gitignore
new file mode 100644
index 000000000..509042171
--- /dev/null
+++ b/web/backend/.gitignore
@@ -0,0 +1,19 @@
+# Go build output
+*.exe
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+picoclaw-web
+
+# Frontend build artifacts (embedded by Go)
+dist/*
+!dist/.gitkeep
+
+# OS
+.DS_Store
+
+# Editors
+.vscode/
+.idea/
\ No newline at end of file
diff --git a/web/backend/api/channels.go b/web/backend/api/channels.go
new file mode 100644
index 000000000..dd4c9af3d
--- /dev/null
+++ b/web/backend/api/channels.go
@@ -0,0 +1,46 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+)
+
+type channelCatalogItem struct {
+	Name      string `json:"name"`
+	ConfigKey string `json:"config_key"`
+	Variant   string `json:"variant,omitempty"`
+}
+
+var channelCatalog = []channelCatalogItem{
+	{Name: "weixin", ConfigKey: "weixin"},
+	{Name: "telegram", ConfigKey: "telegram"},
+	{Name: "discord", ConfigKey: "discord"},
+	{Name: "slack", ConfigKey: "slack"},
+	{Name: "feishu", ConfigKey: "feishu"},
+	{Name: "dingtalk", ConfigKey: "dingtalk"},
+	{Name: "line", ConfigKey: "line"},
+	{Name: "qq", ConfigKey: "qq"},
+	{Name: "onebot", ConfigKey: "onebot"},
+	{Name: "wecom", ConfigKey: "wecom"},
+	{Name: "whatsapp", ConfigKey: "whatsapp", Variant: "bridge"},
+	{Name: "whatsapp_native", ConfigKey: "whatsapp", Variant: "native"},
+	{Name: "pico", ConfigKey: "pico"},
+	{Name: "maixcam", ConfigKey: "maixcam"},
+	{Name: "matrix", ConfigKey: "matrix"},
+	{Name: "irc", ConfigKey: "irc"},
+}
+
+// registerChannelRoutes binds read-only channel catalog endpoints to the ServeMux.
+func (h *Handler) registerChannelRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/channels/catalog", h.handleListChannelCatalog)
+}
+
+// handleListChannelCatalog returns the channels supported by backend.
+//
+//	GET /api/channels/catalog
+func (h *Handler) handleListChannelCatalog(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"channels": channelCatalog,
+	})
+}
diff --git a/web/backend/api/config.go b/web/backend/api/config.go
new file mode 100644
index 000000000..5a7f3cebc
--- /dev/null
+++ b/web/backend/api/config.go
@@ -0,0 +1,263 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"regexp"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// registerConfigRoutes binds configuration management endpoints to the ServeMux.
+func (h *Handler) registerConfigRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/config", h.handleGetConfig)
+	mux.HandleFunc("PUT /api/config", h.handleUpdateConfig)
+	mux.HandleFunc("PATCH /api/config", h.handlePatchConfig)
+}
+
+// handleGetConfig returns the complete system configuration.
+//
+//	GET /api/config
+func (h *Handler) handleGetConfig(w http.ResponseWriter, r *http.Request) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	if err := json.NewEncoder(w).Encode(cfg); err != nil {
+		http.Error(w, "Failed to encode response", http.StatusInternalServerError)
+	}
+}
+
+// handleUpdateConfig updates the complete system configuration.
+//
+//	PUT /api/config
+func (h *Handler) handleUpdateConfig(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "Failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	var cfg config.Config
+	if err = json.Unmarshal(body, &cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+	if execAllowRemoteOmitted(body) {
+		cfg.Tools.Exec.AllowRemote = config.DefaultConfig().Tools.Exec.AllowRemote
+	}
+
+	// Load existing config and copy security credentials before validation,
+	// so that security-managed fields (e.g. pico token) are available.
+	oldCfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+	cfg.SecurityCopyFrom(oldCfg)
+
+	if errs := validateConfig(&cfg); len(errs) > 0 {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		json.NewEncoder(w).Encode(map[string]any{
+			"status": "validation_error",
+			"errors": errs,
+		})
+		return
+	}
+
+	logger.Infof("configuration updated successfully")
+
+	if err := config.SaveConfig(h.configPath, &cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+}
+
+func execAllowRemoteOmitted(body []byte) bool {
+	var raw struct {
+		Tools *struct {
+			Exec *struct {
+				AllowRemote *bool `json:"allow_remote"`
+			} `json:"exec"`
+		} `json:"tools"`
+	}
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return false
+	}
+	return raw.Tools == nil || raw.Tools.Exec == nil || raw.Tools.Exec.AllowRemote == nil
+}
+
+// handlePatchConfig partially updates the system configuration using JSON Merge Patch (RFC 7396).
+// Only the fields present in the request body will be updated; all other fields remain unchanged.
+//
+//	PATCH /api/config
+func (h *Handler) handlePatchConfig(w http.ResponseWriter, r *http.Request) {
+	patchBody, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "Failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	// Validate the patch is valid JSON
+	var patch map[string]any
+	if err = json.Unmarshal(patchBody, &patch); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	// Load existing config and marshal to a map for merging
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	existing, err := json.Marshal(cfg)
+	if err != nil {
+		http.Error(w, "Failed to serialize current config", http.StatusInternalServerError)
+		return
+	}
+
+	var base map[string]any
+	if err = json.Unmarshal(existing, &base); err != nil {
+		http.Error(w, "Failed to parse current config", http.StatusInternalServerError)
+		return
+	}
+
+	// Recursively merge patch into base
+	mergeMap(base, patch)
+
+	// Convert merged map back to Config struct
+	merged, err := json.Marshal(base)
+	if err != nil {
+		http.Error(w, "Failed to serialize merged config", http.StatusInternalServerError)
+		return
+	}
+
+	var newCfg config.Config
+	if err := json.Unmarshal(merged, &newCfg); err != nil {
+		http.Error(w, fmt.Sprintf("Merged config is invalid: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	// Restore security fields (tokens/keys) from the loaded config before validation,
+	// because private fields are lost during JSON round-trip.
+	newCfg.SecurityCopyFrom(cfg)
+	if err := newCfg.ApplySecurity(); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to apply security config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	if errs := validateConfig(&newCfg); len(errs) > 0 {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		json.NewEncoder(w).Encode(map[string]any{
+			"status": "validation_error",
+			"errors": errs,
+		})
+		return
+	}
+
+	if err := config.SaveConfig(h.configPath, &newCfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+}
+
+// validateConfig checks the config for common errors before saving.
+// Returns a list of human-readable error strings; empty means valid.
+func validateConfig(cfg *config.Config) []string {
+	var errs []string
+
+	// Validate model_list entries
+	if err := cfg.ValidateModelList(); err != nil {
+		errs = append(errs, err.Error())
+	}
+
+	// Gateway port range
+	if cfg.Gateway.Port != 0 && (cfg.Gateway.Port < 1 || cfg.Gateway.Port > 65535) {
+		errs = append(errs, fmt.Sprintf("gateway.port %d is out of valid range (1-65535)", cfg.Gateway.Port))
+	}
+
+	// Pico channel: token required when enabled
+	if cfg.Channels.Pico.Enabled && cfg.Channels.Pico.Token() == "" {
+		errs = append(errs, "channels.pico.token is required when pico channel is enabled")
+	}
+
+	// Telegram: token required when enabled
+	if cfg.Channels.Telegram.Enabled && cfg.Channels.Telegram.Token() == "" {
+		errs = append(errs, "channels.telegram.token is required when telegram channel is enabled")
+	}
+
+	// Discord: token required when enabled
+	if cfg.Channels.Discord.Enabled && cfg.Channels.Discord.Token() == "" {
+		errs = append(errs, "channels.discord.token is required when discord channel is enabled")
+	}
+
+	if cfg.Channels.WeCom.Enabled {
+		if cfg.Channels.WeCom.BotID == "" {
+			errs = append(errs, "channels.wecom.bot_id is required when wecom channel is enabled")
+		}
+		if cfg.Channels.WeCom.Secret() == "" {
+			errs = append(errs, "channels.wecom.secret is required when wecom channel is enabled")
+		}
+	}
+
+	if cfg.Tools.Exec.Enabled {
+		if cfg.Tools.Exec.EnableDenyPatterns {
+			errs = append(
+				errs,
+				validateRegexPatterns("tools.exec.custom_deny_patterns", cfg.Tools.Exec.CustomDenyPatterns)...)
+		}
+		errs = append(
+			errs,
+			validateRegexPatterns("tools.exec.custom_allow_patterns", cfg.Tools.Exec.CustomAllowPatterns)...)
+	}
+
+	return errs
+}
+
+func validateRegexPatterns(field string, patterns []string) []string {
+	var errs []string
+	for index, pattern := range patterns {
+		if _, err := regexp.Compile(pattern); err != nil {
+			errs = append(errs, fmt.Sprintf("%s[%d] is not a valid regular expression: %v", field, index, err))
+		}
+	}
+	return errs
+}
+
+// mergeMap recursively merges src into dst (JSON Merge Patch semantics).
+// - If a key in src has a null value, it is deleted from dst.
+// - If both dst and src have a nested object for the same key, merge recursively.
+// - Otherwise the value from src overwrites dst.
+func mergeMap(dst, src map[string]any) {
+	for key, srcVal := range src {
+		if srcVal == nil {
+			delete(dst, key)
+			continue
+		}
+		srcMap, srcIsMap := srcVal.(map[string]any)
+		dstMap, dstIsMap := dst[key].(map[string]any)
+		if srcIsMap && dstIsMap {
+			mergeMap(dstMap, srcMap)
+		} else {
+			dst[key] = srcVal
+		}
+	}
+}
diff --git a/web/backend/api/config_test.go b/web/backend/api/config_test.go
new file mode 100644
index 000000000..9b05546f9
--- /dev/null
+++ b/web/backend/api/config_test.go
@@ -0,0 +1,284 @@
+package api
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestHandleUpdateConfig_PreservesExecAllowRemoteDefaultWhenOmitted(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	req := httptest.NewRequest(http.MethodPut, "/api/config", bytes.NewBufferString(`{
+"version": 1,
+		"agents": {
+			"defaults": {
+				"workspace": "~/.picoclaw/workspace"
+			}
+		},
+		"model_list": [
+			{
+				"model_name": "custom-default",
+				"model": "openai/gpt-4o",
+				"api_keys": ["sk-default"]
+			}
+		]
+	}`))
+	req.Header.Set("Content-Type", "application/json")
+
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	if !cfg.Tools.Exec.AllowRemote {
+		t.Fatal("tools.exec.allow_remote should remain true when omitted from PUT /api/config")
+	}
+}
+
+func TestHandleUpdateConfig_DoesNotInheritDefaultModelFields(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	req := httptest.NewRequest(http.MethodPut, "/api/config", bytes.NewBufferString(`{
+		"agents": {
+			"defaults": {
+				"workspace": "~/.picoclaw/workspace"
+			}
+		},
+		"model_list": [
+			{
+				"model_name": "custom-default",
+				"model": "openai/gpt-4o",
+				"api_key": "sk-default"
+			}
+		]
+	}`))
+	req.Header.Set("Content-Type", "application/json")
+
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	if got := cfg.ModelList[0].APIBase; got != "" {
+		t.Fatalf("model_list[0].api_base = %q, want empty string", got)
+	}
+}
+
+func TestHandlePatchConfig_RejectsInvalidExecRegexPatterns(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	req := httptest.NewRequest(http.MethodPatch, "/api/config", bytes.NewBufferString(`{
+		"tools": {
+			"exec": {
+				"custom_deny_patterns": ["("]
+			}
+		}
+	}`))
+	req.Header.Set("Content-Type", "application/json")
+
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, req)
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusBadRequest, rec.Body.String())
+	}
+	if !bytes.Contains(rec.Body.Bytes(), []byte("custom_deny_patterns")) {
+		t.Fatalf("expected validation error mentioning custom_deny_patterns, body=%s", rec.Body.String())
+	}
+}
+
+func TestHandlePatchConfig_AllowsInvalidExecRegexPatternsWhenExecDisabled(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	req := httptest.NewRequest(http.MethodPatch, "/api/config", bytes.NewBufferString(`{
+		"tools": {
+			"exec": {
+				"enabled": false,
+				"custom_deny_patterns": ["("],
+				"custom_allow_patterns": ["("]
+			}
+		}
+	}`))
+	req.Header.Set("Content-Type", "application/json")
+
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+}
+
+// setupPicoEnabledEnv creates a test environment with Pico channel enabled and
+// its token stored only in .security.yml (not in the JSON payload).
+func setupPicoEnabledEnv(t *testing.T) (string, func()) {
+	t.Helper()
+
+	tmp := t.TempDir()
+	oldHome := os.Getenv("HOME")
+	oldPicoHome := os.Getenv("PICOCLAW_HOME")
+
+	if err := os.Setenv("HOME", tmp); err != nil {
+		t.Fatalf("set HOME: %v", err)
+	}
+	if err := os.Setenv("PICOCLAW_HOME", filepath.Join(tmp, ".picoclaw")); err != nil {
+		t.Fatalf("set PICOCLAW_HOME: %v", err)
+	}
+
+	cfg := config.DefaultConfig()
+	cfg.ModelList = []*config.ModelConfig{{
+		ModelName: "custom-default",
+		Model:     "openai/gpt-4o",
+	}}
+	cfg.Agents.Defaults.ModelName = "custom-default"
+	cfg.Channels.Pico.Enabled = true
+	cfg.WithSecurity(&config.SecurityConfig{
+		ModelList: map[string]config.ModelSecurityEntry{
+			"custom-default": {APIKeys: []string{"sk-default"}},
+		},
+		Channels: &config.ChannelsSecurity{
+			Pico: &config.PicoSecurity{Token: "test-pico-token"},
+		},
+	})
+
+	configPath := filepath.Join(tmp, "config.json")
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig error: %v", err)
+	}
+
+	cleanup := func() {
+		_ = os.Setenv("HOME", oldHome)
+		if oldPicoHome == "" {
+			_ = os.Unsetenv("PICOCLAW_HOME")
+		} else {
+			_ = os.Setenv("PICOCLAW_HOME", oldPicoHome)
+		}
+	}
+	return configPath, cleanup
+}
+
+func TestHandleUpdateConfig_SucceedsWhenPicoTokenInSecurityOnly(t *testing.T) {
+	configPath, cleanup := setupPicoEnabledEnv(t)
+	defer cleanup()
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	// PUT request with pico enabled but no token in JSON — token is in .security.yml
+	req := httptest.NewRequest(http.MethodPut, "/api/config", bytes.NewBufferString(`{
+		"version": 1,
+		"agents": {
+			"defaults": {
+				"workspace": "~/.picoclaw/workspace",
+				"model_name": "custom-default"
+			}
+		},
+		"channels": {
+			"pico": {
+				"enabled": true,
+				"ping_interval": 30,
+				"read_timeout": 60,
+				"write_timeout": 10,
+				"max_connections": 100
+			}
+		},
+		"model_list": [
+			{
+				"model_name": "custom-default",
+				"model": "openai/gpt-4o",
+				"api_keys": ["sk-default"]
+			}
+		]
+	}`))
+	req.Header.Set("Content-Type", "application/json")
+
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("PUT /api/config status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+}
+
+func TestHandlePatchConfig_SucceedsWhenPicoTokenInSecurityOnly(t *testing.T) {
+	configPath, cleanup := setupPicoEnabledEnv(t)
+	defer cleanup()
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	// PATCH request changing an unrelated field — pico token still in .security.yml
+	req := httptest.NewRequest(http.MethodPatch, "/api/config", bytes.NewBufferString(`{
+		"gateway": {
+			"log_level": "info"
+		}
+	}`))
+	req.Header.Set("Content-Type", "application/json")
+
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("PATCH /api/config status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+}
+
+func TestHandlePatchConfig_AllowsInvalidDenyRegexPatternsWhenDenyPatternsDisabled(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	req := httptest.NewRequest(http.MethodPatch, "/api/config", bytes.NewBufferString(`{
+		"tools": {
+			"exec": {
+				"enabled": true,
+				"enable_deny_patterns": false,
+				"custom_deny_patterns": ["("]
+			}
+		}
+	}`))
+	req.Header.Set("Content-Type", "application/json")
+
+	rec := httptest.NewRecorder()
+	mux.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+}
diff --git a/web/backend/api/gateway.go b/web/backend/api/gateway.go
new file mode 100644
index 000000000..4bde5ce82
--- /dev/null
+++ b/web/backend/api/gateway.go
@@ -0,0 +1,870 @@
+package api
+
+import (
+	"bufio"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"runtime"
+	"strconv"
+	"strings"
+	"sync"
+	"syscall"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/health"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/web/backend/utils"
+)
+
+// gateway holds the state for the managed gateway process.
+var gateway = struct {
+	mu               sync.Mutex
+	cmd              *exec.Cmd
+	owned            bool // true if we started the process, false if we attached to an existing one
+	bootDefaultModel string
+	runtimeStatus    string
+	startupDeadline  time.Time
+	logs             *LogBuffer
+}{
+	runtimeStatus: "stopped",
+	logs:          NewLogBuffer(200),
+}
+
+var (
+	gatewayStartupWindow          = 15 * time.Second
+	gatewayRestartGracePeriod     = 5 * time.Second
+	gatewayRestartForceKillWindow = 3 * time.Second
+	gatewayRestartPollInterval    = 100 * time.Millisecond
+)
+
+var gatewayHealthGet = func(url string, timeout time.Duration) (*http.Response, error) {
+	client := http.Client{Timeout: timeout}
+	return client.Get(url)
+}
+
+// getGatewayHealth checks the gateway health endpoint and returns the status response
+// Returns (*health.StatusResponse, statusCode, error). If error is not nil, the other values are not valid.
+func (h *Handler) getGatewayHealth(cfg *config.Config, timeout time.Duration) (*health.StatusResponse, int, error) {
+	port := 18790
+	if cfg != nil && cfg.Gateway.Port != 0 {
+		port = cfg.Gateway.Port
+	}
+
+	probeHost := gatewayProbeHost(h.effectiveGatewayBindHost(cfg))
+	url := "http://" + net.JoinHostPort(probeHost, strconv.Itoa(port)) + "/health"
+
+	return getGatewayHealthByURL(url, timeout)
+}
+
+func getGatewayHealthByURL(url string, timeout time.Duration) (*health.StatusResponse, int, error) {
+	resp, err := gatewayHealthGet(url, timeout)
+	if err != nil {
+		return nil, 0, err
+	}
+	defer resp.Body.Close()
+
+	var healthResponse health.StatusResponse
+	if decErr := json.NewDecoder(resp.Body).Decode(&healthResponse); decErr != nil {
+		return nil, resp.StatusCode, decErr
+	}
+
+	return &healthResponse, resp.StatusCode, nil
+}
+
+// registerGatewayRoutes binds gateway lifecycle endpoints to the ServeMux.
+func (h *Handler) registerGatewayRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/gateway/status", h.handleGatewayStatus)
+	mux.HandleFunc("GET /api/gateway/logs", h.handleGatewayLogs)
+	mux.HandleFunc("POST /api/gateway/logs/clear", h.handleGatewayClearLogs)
+	mux.HandleFunc("POST /api/gateway/start", h.handleGatewayStart)
+	mux.HandleFunc("POST /api/gateway/stop", h.handleGatewayStop)
+	mux.HandleFunc("POST /api/gateway/restart", h.handleGatewayRestart)
+}
+
+// TryAutoStartGateway checks whether gateway start preconditions are met and
+// starts it when possible. Intended to be called by the backend at startup.
+func (h *Handler) TryAutoStartGateway() {
+	// Check if gateway is already running via health endpoint
+	cfg, cfgErr := config.LoadConfig(h.configPath)
+	if cfgErr == nil && cfg != nil {
+		healthResp, statusCode, err := h.getGatewayHealth(cfg, 2*time.Second)
+		if err == nil && statusCode == http.StatusOK {
+			// Gateway is already running, attach to the existing process
+			pid := healthResp.Pid
+			gateway.mu.Lock()
+			defer gateway.mu.Unlock()
+			ready, reason, err := h.gatewayStartReady()
+			if err != nil {
+				logger.ErrorC("gateway", fmt.Sprintf("Skip auto-starting gateway: %v", err))
+				return
+			}
+			if !ready {
+				logger.InfoC("gateway", fmt.Sprintf("Skip auto-starting gateway: %s", reason))
+				return
+			}
+			_, err = h.startGatewayLocked("starting", pid)
+			if err != nil {
+				logger.ErrorC("gateway", fmt.Sprintf("Failed to attach to running gateway (PID: %d): %v", pid, err))
+			}
+			return
+		}
+	}
+
+	gateway.mu.Lock()
+	defer gateway.mu.Unlock()
+
+	if gateway.cmd != nil && gateway.cmd.Process != nil {
+		gateway.cmd = nil
+	}
+
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		logger.ErrorC("gateway", fmt.Sprintf("Skip auto-starting gateway: %v", err))
+		return
+	}
+	if !ready {
+		logger.InfoC("gateway", fmt.Sprintf("Skip auto-starting gateway: %s", reason))
+		return
+	}
+
+	pid, err := h.startGatewayLocked("starting", 0)
+	if err != nil {
+		logger.ErrorC("gateway", fmt.Sprintf("Failed to auto-start gateway: %v", err))
+		return
+	}
+	logger.InfoC("gateway", fmt.Sprintf("Gateway auto-started (PID: %d)", pid))
+}
+
+// gatewayStartReady validates whether current config can start the gateway.
+func (h *Handler) gatewayStartReady() (bool, string, error) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		return false, "", fmt.Errorf("failed to load config: %w", err)
+	}
+
+	modelName := strings.TrimSpace(cfg.Agents.Defaults.GetModelName())
+	if modelName == "" {
+		return false, "no default model configured", nil
+	}
+
+	modelCfg := lookupModelConfig(cfg, modelName)
+	if modelCfg == nil {
+		return false, fmt.Sprintf("default model %q is invalid", modelName), nil
+	}
+
+	if !hasModelConfiguration(modelCfg) {
+		return false, fmt.Sprintf("default model %q has no credentials configured", modelName), nil
+	}
+	if requiresRuntimeProbe(modelCfg) && !probeLocalModelAvailability(modelCfg) {
+		return false, fmt.Sprintf("default model %q is not reachable", modelName), nil
+	}
+
+	return true, "", nil
+}
+
+func lookupModelConfig(cfg *config.Config, modelName string) *config.ModelConfig {
+	modelCfg, err := cfg.GetModelConfig(modelName)
+	if err != nil {
+		return nil
+	}
+	return modelCfg
+}
+
+func gatewayRestartRequired(configDefaultModel, bootDefaultModel, gatewayStatus string) bool {
+	if gatewayStatus != "running" {
+		return false
+	}
+	if strings.TrimSpace(configDefaultModel) == "" || strings.TrimSpace(bootDefaultModel) == "" {
+		return false
+	}
+	return configDefaultModel != bootDefaultModel
+}
+
+func isCmdProcessAliveLocked(cmd *exec.Cmd) bool {
+	if cmd == nil || cmd.Process == nil {
+		return false
+	}
+
+	// Wait() sets ProcessState when the process exits; use it when available.
+	if cmd.ProcessState != nil && cmd.ProcessState.Exited() {
+		return false
+	}
+
+	// Windows does not support Signal(0) probing. If we still own cmd and it
+	// has not reported exit, treat it as alive.
+	if runtime.GOOS == "windows" {
+		return true
+	}
+
+	return cmd.Process.Signal(syscall.Signal(0)) == nil
+}
+
+func setGatewayRuntimeStatusLocked(status string) {
+	gateway.runtimeStatus = status
+	if status == "starting" || status == "restarting" {
+		gateway.startupDeadline = time.Now().Add(gatewayStartupWindow)
+		return
+	}
+	gateway.startupDeadline = time.Time{}
+}
+
+// attachToGatewayProcess attaches to an existing gateway process by PID
+// and updates the gateway state accordingly.
+// Assumes gateway.mu is held by the caller.
+func attachToGatewayProcessLocked(pid int, cfg *config.Config) error {
+	process, err := os.FindProcess(pid)
+	if err != nil {
+		return fmt.Errorf("failed to find process for PID %d: %w", pid, err)
+	}
+
+	gateway.cmd = &exec.Cmd{Process: process}
+	gateway.owned = false // We didn't start this process
+	setGatewayRuntimeStatusLocked("running")
+
+	// Update bootDefaultModel from config
+	if cfg != nil {
+		defaultModelName := strings.TrimSpace(cfg.Agents.Defaults.GetModelName())
+		gateway.bootDefaultModel = defaultModelName
+	}
+
+	logger.InfoC("gateway", fmt.Sprintf("Attached to gateway process (PID: %d)", pid))
+	return nil
+}
+
+func gatewayStatusWithoutHealthLocked() string {
+	if gateway.runtimeStatus == "starting" || gateway.runtimeStatus == "restarting" {
+		if gateway.startupDeadline.IsZero() || time.Now().Before(gateway.startupDeadline) {
+			return gateway.runtimeStatus
+		}
+		return "error"
+	}
+	if gateway.runtimeStatus == "running" {
+		return "running"
+	}
+	if gateway.runtimeStatus == "error" {
+		return "error"
+	}
+	return "stopped"
+}
+
+func waitForGatewayProcessExit(cmd *exec.Cmd, timeout time.Duration) bool {
+	if cmd == nil || cmd.Process == nil {
+		return true
+	}
+
+	deadline := time.Now().Add(timeout)
+	for {
+		if !isCmdProcessAliveLocked(cmd) {
+			return true
+		}
+		if time.Now().After(deadline) {
+			return false
+		}
+		time.Sleep(gatewayRestartPollInterval)
+	}
+}
+
+// StopGateway stops the gateway process if it was started by this handler.
+// This method is called during application shutdown to ensure the gateway subprocess
+// is properly terminated. It only stops processes that were started by this handler,
+// not processes that were attached to from existing instances.
+func (h *Handler) StopGateway() {
+	gateway.mu.Lock()
+	defer gateway.mu.Unlock()
+
+	// Only stop if we own the process (started it ourselves)
+	if !gateway.owned || gateway.cmd == nil || gateway.cmd.Process == nil {
+		return
+	}
+
+	pid, err := stopGatewayLocked()
+	if err != nil {
+		logger.ErrorC("gateway", fmt.Sprintf("Failed to stop gateway (PID %d): %v", pid, err))
+		return
+	}
+
+	logger.InfoC("gateway", fmt.Sprintf("Gateway stopped (PID: %d)", pid))
+}
+
+// stopGatewayLocked sends a stop signal to the gateway process.
+// Assumes gateway.mu is held by the caller.
+// Returns the PID of the stopped process and any error encountered.
+func stopGatewayLocked() (int, error) {
+	if gateway.cmd == nil || gateway.cmd.Process == nil {
+		return 0, nil
+	}
+
+	pid := gateway.cmd.Process.Pid
+
+	// Send SIGTERM for graceful shutdown (SIGKILL on Windows)
+	var sigErr error
+	if runtime.GOOS == "windows" {
+		sigErr = gateway.cmd.Process.Kill()
+	} else {
+		sigErr = gateway.cmd.Process.Signal(syscall.SIGTERM)
+	}
+
+	if sigErr != nil {
+		return pid, sigErr
+	}
+
+	logger.InfoC("gateway", fmt.Sprintf("Sent stop signal to gateway (PID: %d)", pid))
+	gateway.cmd = nil
+	gateway.owned = false
+	gateway.bootDefaultModel = ""
+	setGatewayRuntimeStatusLocked("stopped")
+
+	return pid, nil
+}
+
+func stopGatewayProcessForRestart(cmd *exec.Cmd) error {
+	if cmd == nil || cmd.Process == nil || !isCmdProcessAliveLocked(cmd) {
+		return nil
+	}
+
+	var stopErr error
+	if runtime.GOOS == "windows" {
+		stopErr = cmd.Process.Kill()
+	} else {
+		stopErr = cmd.Process.Signal(syscall.SIGTERM)
+	}
+	if stopErr != nil && isCmdProcessAliveLocked(cmd) {
+		return fmt.Errorf("failed to stop existing gateway: %w", stopErr)
+	}
+
+	if waitForGatewayProcessExit(cmd, gatewayRestartGracePeriod) {
+		return nil
+	}
+
+	if runtime.GOOS != "windows" {
+		killErr := cmd.Process.Signal(syscall.SIGKILL)
+		if killErr != nil && isCmdProcessAliveLocked(cmd) {
+			return fmt.Errorf("failed to force-stop existing gateway: %w", killErr)
+		}
+		if waitForGatewayProcessExit(cmd, gatewayRestartForceKillWindow) {
+			return nil
+		}
+	}
+
+	return fmt.Errorf("existing gateway did not exit before restart")
+}
+
+func (h *Handler) startGatewayLocked(initialStatus string, existingPid int) (int, error) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		return 0, fmt.Errorf("failed to load config: %w", err)
+	}
+	defaultModelName := strings.TrimSpace(cfg.Agents.Defaults.GetModelName())
+
+	var cmd *exec.Cmd
+	var pid int
+
+	if existingPid > 0 {
+		// Attach to existing process
+		pid = existingPid
+		gateway.cmd = nil // Clear first to ensure clean state
+		if err = attachToGatewayProcessLocked(pid, cfg); err != nil {
+			return 0, err
+		}
+
+		return pid, nil
+	}
+
+	// Start new process
+	// Locate the picoclaw executable
+	execPath := utils.FindPicoclawBinary()
+
+	cmd = exec.Command(execPath, "gateway", "-E")
+	cmd.Env = os.Environ()
+	// Forward the launcher's config path via the environment variable that
+	// GetConfigPath() already reads, so the gateway sub-process uses the same
+	// config file without requiring a --config flag on the gateway subcommand.
+	if h.configPath != "" {
+		cmd.Env = append(cmd.Env, config.EnvConfig+"="+h.configPath)
+	}
+	if host := h.gatewayHostOverride(); host != "" {
+		cmd.Env = append(cmd.Env, config.EnvGatewayHost+"="+host)
+	}
+
+	stdoutPipe, err := cmd.StdoutPipe()
+	if err != nil {
+		return 0, fmt.Errorf("failed to create stdout pipe: %w", err)
+	}
+
+	stderrPipe, err := cmd.StderrPipe()
+	if err != nil {
+		return 0, fmt.Errorf("failed to create stderr pipe: %w", err)
+	}
+
+	// Clear old logs for this new run
+	gateway.logs.Reset()
+
+	// Ensure Pico Channel is configured before starting gateway
+	if _, err := h.EnsurePicoChannel(""); err != nil {
+		logger.ErrorC("gateway", fmt.Sprintf("Warning: failed to ensure pico channel: %v", err))
+		// Non-fatal: gateway can still start without pico channel
+	}
+
+	if err := cmd.Start(); err != nil {
+		return 0, fmt.Errorf("failed to start gateway: %w", err)
+	}
+
+	gateway.cmd = cmd
+	gateway.owned = true // We started this process
+	gateway.bootDefaultModel = defaultModelName
+	setGatewayRuntimeStatusLocked(initialStatus)
+	pid = cmd.Process.Pid
+	logger.InfoC("gateway", fmt.Sprintf("Started picoclaw gateway (PID: %d) from %s", pid, execPath))
+
+	// Capture stdout/stderr in background
+	go scanPipe(stdoutPipe, gateway.logs)
+	go scanPipe(stderrPipe, gateway.logs)
+
+	// Wait for exit in background and clean up
+	go func() {
+		if err := cmd.Wait(); err != nil {
+			logger.ErrorC("gateway", fmt.Sprintf("Gateway process exited: %v", err))
+		} else {
+			logger.InfoC("gateway", "Gateway process exited normally")
+		}
+
+		gateway.mu.Lock()
+		if gateway.cmd == cmd {
+			gateway.cmd = nil
+			gateway.bootDefaultModel = ""
+			if gateway.runtimeStatus != "restarting" {
+				setGatewayRuntimeStatusLocked("stopped")
+			}
+		}
+		gateway.mu.Unlock()
+	}()
+
+	// Start a goroutine to probe health and update the runtime state once ready.
+	go func() {
+		for i := 0; i < 30; i++ { // try for up to 15 seconds
+			time.Sleep(500 * time.Millisecond)
+			gateway.mu.Lock()
+			stillOurs := gateway.cmd == cmd
+			gateway.mu.Unlock()
+			if !stillOurs {
+				return
+			}
+			cfg, err := config.LoadConfig(h.configPath)
+			if err != nil {
+				continue
+			}
+			healthResp, statusCode, err := h.getGatewayHealth(cfg, 1*time.Second)
+			if err == nil && statusCode == http.StatusOK && healthResp.Pid == pid {
+				// Verify the health endpoint returns the expected pid
+				gateway.mu.Lock()
+				if gateway.cmd == cmd {
+					setGatewayRuntimeStatusLocked("running")
+				}
+				gateway.mu.Unlock()
+				return
+			}
+		}
+	}()
+
+	return pid, nil
+}
+
+// handleGatewayStart starts the picoclaw gateway subprocess.
+//
+//	POST /api/gateway/start
+func (h *Handler) handleGatewayStart(w http.ResponseWriter, r *http.Request) {
+	// Prevent duplicate starts by checking health endpoint
+	cfg, cfgErr := config.LoadConfig(h.configPath)
+	if cfgErr == nil && cfg != nil {
+		healthResp, statusCode, err := h.getGatewayHealth(cfg, 2*time.Second)
+		if err == nil && statusCode == http.StatusOK {
+			// Gateway is already running, attach to the existing process
+			pid := healthResp.Pid
+			gateway.mu.Lock()
+			ready, reason, err := h.gatewayStartReady()
+			if err != nil {
+				gateway.mu.Unlock()
+				http.Error(
+					w,
+					fmt.Sprintf("Failed to validate gateway start conditions: %v", err),
+					http.StatusInternalServerError,
+				)
+				return
+			}
+			if !ready {
+				gateway.mu.Unlock()
+				w.Header().Set("Content-Type", "application/json")
+				w.WriteHeader(http.StatusBadRequest)
+				json.NewEncoder(w).Encode(map[string]any{
+					"status":  "precondition_failed",
+					"message": reason,
+				})
+				return
+			}
+			_, err = h.startGatewayLocked("starting", pid)
+			gateway.mu.Unlock()
+			if err != nil {
+				logger.ErrorC("gateway", fmt.Sprintf("Failed to attach to running gateway (PID: %d): %v", pid, err))
+				http.Error(w, fmt.Sprintf("Failed to attach to gateway: %v", err), http.StatusInternalServerError)
+				return
+			}
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusOK)
+			json.NewEncoder(w).Encode(map[string]any{
+				"status": "ok",
+				"pid":    pid,
+			})
+			return
+		}
+	}
+
+	gateway.mu.Lock()
+	defer gateway.mu.Unlock()
+
+	if gateway.cmd != nil && gateway.cmd.Process != nil {
+		gateway.cmd = nil
+		setGatewayRuntimeStatusLocked("stopped")
+	}
+
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		http.Error(
+			w,
+			fmt.Sprintf("Failed to validate gateway start conditions: %v", err),
+			http.StatusInternalServerError,
+		)
+		return
+	}
+	if !ready {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusBadRequest)
+		json.NewEncoder(w).Encode(map[string]any{
+			"status":  "precondition_failed",
+			"message": reason,
+		})
+		return
+	}
+
+	pid, err := h.startGatewayLocked("starting", 0)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to start gateway: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"status": "ok",
+		"pid":    pid,
+	})
+}
+
+// handleGatewayStop stops the running gateway subprocess gracefully.
+// Note: Unlike StopGateway (which only stops self-started processes), this API endpoint
+// stops any gateway process, including attached ones. This is intentional for user control.
+//
+//	POST /api/gateway/stop
+func (h *Handler) handleGatewayStop(w http.ResponseWriter, r *http.Request) {
+	gateway.mu.Lock()
+	defer gateway.mu.Unlock()
+
+	if gateway.cmd == nil || gateway.cmd.Process == nil {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]any{
+			"status": "not_running",
+		})
+		return
+	}
+
+	pid, err := stopGatewayLocked()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to stop gateway (PID %d): %v", pid, err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"status": "ok",
+		"pid":    pid,
+	})
+}
+
+// RestartGateway restarts the gateway process. This is a non-blocking operation
+// that stops the current gateway (if running) and starts a new one.
+// Returns the PID of the new gateway process or an error.
+func (h *Handler) RestartGateway() (int, error) {
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		return 0, fmt.Errorf("failed to validate gateway start conditions: %w", err)
+	}
+	if !ready {
+		return 0, &preconditionFailedError{reason: reason}
+	}
+
+	gateway.mu.Lock()
+	previousCmd := gateway.cmd
+	setGatewayRuntimeStatusLocked("restarting")
+	gateway.mu.Unlock()
+
+	if err = stopGatewayProcessForRestart(previousCmd); err != nil {
+		gateway.mu.Lock()
+		if gateway.cmd == previousCmd {
+			if isCmdProcessAliveLocked(previousCmd) {
+				setGatewayRuntimeStatusLocked("running")
+			} else {
+				gateway.cmd = nil
+				gateway.bootDefaultModel = ""
+				setGatewayRuntimeStatusLocked("error")
+			}
+		}
+		gateway.mu.Unlock()
+		return 0, fmt.Errorf("failed to stop gateway: %w", err)
+	}
+
+	gateway.mu.Lock()
+	if gateway.cmd == previousCmd {
+		gateway.cmd = nil
+		gateway.bootDefaultModel = ""
+	}
+	pid, err := h.startGatewayLocked("restarting", 0)
+	if err != nil {
+		gateway.cmd = nil
+		gateway.bootDefaultModel = ""
+		setGatewayRuntimeStatusLocked("error")
+	}
+	gateway.mu.Unlock()
+	if err != nil {
+		return 0, fmt.Errorf("failed to start gateway: %w", err)
+	}
+
+	return pid, nil
+}
+
+// preconditionFailedError is returned when gateway restart preconditions are not met
+type preconditionFailedError struct {
+	reason string
+}
+
+func (e *preconditionFailedError) Error() string {
+	return e.reason
+}
+
+// IsBadRequest returns true if the error should result in a 400 Bad Request status
+func (e *preconditionFailedError) IsBadRequest() bool {
+	return true
+}
+
+// handleGatewayRestart stops the gateway (if running) and starts a new instance.
+//
+//	POST /api/gateway/restart
+func (h *Handler) handleGatewayRestart(w http.ResponseWriter, r *http.Request) {
+	pid, err := h.RestartGateway()
+	if err != nil {
+		// Check if it's a precondition failed error
+		var precondErr *preconditionFailedError
+		if errors.As(err, &precondErr) {
+			w.Header().Set("Content-Type", "application/json")
+			w.WriteHeader(http.StatusBadRequest)
+			json.NewEncoder(w).Encode(map[string]any{
+				"status":  "precondition_failed",
+				"message": precondErr.reason,
+			})
+			return
+		}
+		http.Error(w, fmt.Sprintf("Failed to restart gateway: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"status": "ok",
+		"pid":    pid,
+	})
+}
+
+// handleGatewayClearLogs clears the in-memory gateway log buffer.
+//
+//	POST /api/gateway/logs/clear
+func (h *Handler) handleGatewayClearLogs(w http.ResponseWriter, r *http.Request) {
+	gateway.logs.Clear()
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"status":     "cleared",
+		"log_total":  0,
+		"log_run_id": gateway.logs.RunID(),
+	})
+}
+
+// handleGatewayStatus returns the gateway run status and health info.
+//
+//	GET /api/gateway/status
+func (h *Handler) handleGatewayStatus(w http.ResponseWriter, r *http.Request) {
+	data := h.gatewayStatusData()
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(data)
+}
+
+func (h *Handler) gatewayStatusData() map[string]any {
+	data := map[string]any{}
+	configDefaultModel := ""
+	cfg, cfgErr := config.LoadConfig(h.configPath)
+	if cfgErr == nil && cfg != nil {
+		configDefaultModel = strings.TrimSpace(cfg.Agents.Defaults.GetModelName())
+		if configDefaultModel != "" {
+			data["config_default_model"] = configDefaultModel
+		}
+	}
+
+	// Probe health endpoint to get pid and status
+	healthResp, statusCode, err := h.getGatewayHealth(cfg, 2*time.Second)
+	if err != nil {
+		gateway.mu.Lock()
+		data["gateway_status"] = gatewayStatusWithoutHealthLocked()
+		gateway.mu.Unlock()
+		logger.ErrorC("gateway", fmt.Sprintf("Gateway health check failed: %v", err))
+	} else {
+		logger.InfoC("gateway", fmt.Sprintf("Gateway health status: %d", statusCode))
+		if statusCode != http.StatusOK {
+			gateway.mu.Lock()
+			setGatewayRuntimeStatusLocked("error")
+			gateway.mu.Unlock()
+			data["gateway_status"] = "error"
+			data["status_code"] = statusCode
+		} else {
+			gateway.mu.Lock()
+			setGatewayRuntimeStatusLocked("running")
+			if gateway.cmd == nil || gateway.cmd.Process == nil || gateway.cmd.Process.Pid != healthResp.Pid {
+				oldPid := "none"
+				if gateway.cmd != nil && gateway.cmd.Process != nil {
+					oldPid = fmt.Sprintf("%d", gateway.cmd.Process.Pid)
+				}
+				logger.InfoC(
+					"gateway",
+					fmt.Sprintf(
+						"Detected new gateway PID (old: %s, new: %d), attempting to attach",
+						oldPid,
+						healthResp.Pid,
+					),
+				)
+
+				if err := attachToGatewayProcessLocked(healthResp.Pid, cfg); err != nil {
+					// Failed to find the process, treat as error
+					setGatewayRuntimeStatusLocked("error")
+					data["gateway_status"] = "error"
+					data["pid"] = healthResp.Pid
+					logger.ErrorC(
+						"gateway",
+						fmt.Sprintf("Failed to attach to new gateway process (PID: %d): %v", healthResp.Pid, err),
+					)
+				} else {
+					// Successfully attached, update response data
+					bootDefaultModel := gateway.bootDefaultModel
+					if bootDefaultModel != "" {
+						data["boot_default_model"] = bootDefaultModel
+					}
+					data["gateway_status"] = "running"
+					data["pid"] = healthResp.Pid
+				}
+			}
+
+			bootDefaultModel := gateway.bootDefaultModel
+			if bootDefaultModel != "" {
+				data["boot_default_model"] = bootDefaultModel
+			}
+			data["gateway_status"] = "running"
+			data["pid"] = healthResp.Pid
+			gateway.mu.Unlock()
+		}
+	}
+
+	bootDefaultModel, _ := data["boot_default_model"].(string)
+	gatewayStatus, _ := data["gateway_status"].(string)
+	data["gateway_restart_required"] = gatewayRestartRequired(
+		configDefaultModel,
+		bootDefaultModel,
+		gatewayStatus,
+	)
+
+	ready, reason, readyErr := h.gatewayStartReady()
+	if readyErr != nil {
+		data["gateway_start_allowed"] = false
+		data["gateway_start_reason"] = readyErr.Error()
+	} else {
+		data["gateway_start_allowed"] = ready
+		if !ready {
+			data["gateway_start_reason"] = reason
+		}
+	}
+
+	return data
+}
+
+// handleGatewayLogs returns buffered gateway logs, optionally incrementally.
+//
+//	GET /api/gateway/logs
+func (h *Handler) handleGatewayLogs(w http.ResponseWriter, r *http.Request) {
+	data := gatewayLogsData(r)
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(data)
+}
+
+// gatewayLogsData reads log_offset and log_run_id query params from the request
+// and returns incremental log lines.
+func gatewayLogsData(r *http.Request) map[string]any {
+	data := map[string]any{}
+	clientOffset := 0
+	clientRunID := -1
+
+	if v := r.URL.Query().Get("log_offset"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			clientOffset = n
+		}
+	}
+
+	if v := r.URL.Query().Get("log_run_id"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil {
+			clientRunID = n
+		}
+	}
+
+	runID := gateway.logs.RunID()
+
+	if runID == 0 {
+		data["logs"] = []string{}
+		data["log_total"] = 0
+		data["log_run_id"] = 0
+		return data
+	}
+
+	// If runID changed, reset offset to get all logs from new run
+	offset := clientOffset
+	if clientRunID != runID {
+		offset = 0
+	}
+
+	lines, total, runID := gateway.logs.LinesSince(offset)
+	if lines == nil {
+		lines = []string{}
+	}
+
+	data["logs"] = lines
+	data["log_total"] = total
+	data["log_run_id"] = runID
+	return data
+}
+
+// scanPipe reads lines from r and appends them to buf. Returns when r reaches EOF.
+func scanPipe(r io.Reader, buf *LogBuffer) {
+	scanner := bufio.NewScanner(r)
+	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
+	for scanner.Scan() {
+		buf.Append(scanner.Text())
+	}
+}
diff --git a/web/backend/api/gateway_host.go b/web/backend/api/gateway_host.go
new file mode 100644
index 000000000..592571a28
--- /dev/null
+++ b/web/backend/api/gateway_host.go
@@ -0,0 +1,108 @@
+package api
+
+import (
+	"net"
+	"net/http"
+	"net/url"
+	"strconv"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func (h *Handler) effectiveLauncherPublic() bool {
+	if h.serverPublicExplicit {
+		return h.serverPublic
+	}
+
+	cfg, err := h.loadLauncherConfig()
+	if err == nil {
+		return cfg.Public
+	}
+
+	return h.serverPublic
+}
+
+func (h *Handler) gatewayHostOverride() string {
+	if h.effectiveLauncherPublic() {
+		return "0.0.0.0"
+	}
+	return ""
+}
+
+func (h *Handler) effectiveGatewayBindHost(cfg *config.Config) string {
+	if override := h.gatewayHostOverride(); override != "" {
+		return override
+	}
+	if cfg == nil {
+		return ""
+	}
+	return strings.TrimSpace(cfg.Gateway.Host)
+}
+
+func gatewayProbeHost(bindHost string) string {
+	if bindHost == "" || bindHost == "0.0.0.0" {
+		return "127.0.0.1"
+	}
+	return bindHost
+}
+
+func (h *Handler) gatewayProxyURL() *url.URL {
+	cfg, err := config.LoadConfig(h.configPath)
+	port := 18790
+	bindHost := ""
+	if err == nil && cfg != nil {
+		if cfg.Gateway.Port != 0 {
+			port = cfg.Gateway.Port
+		}
+		bindHost = h.effectiveGatewayBindHost(cfg)
+	}
+
+	return &url.URL{
+		Scheme: "http",
+		Host:   net.JoinHostPort(gatewayProbeHost(bindHost), strconv.Itoa(port)),
+	}
+}
+
+func requestHostName(r *http.Request) string {
+	reqHost, _, err := net.SplitHostPort(r.Host)
+	if err == nil {
+		return reqHost
+	}
+	if strings.TrimSpace(r.Host) != "" {
+		return r.Host
+	}
+	return "127.0.0.1"
+}
+
+func requestWSScheme(r *http.Request) string {
+	if forwarded := strings.TrimSpace(r.Header.Get("X-Forwarded-Proto")); forwarded != "" {
+		proto := strings.ToLower(strings.TrimSpace(strings.Split(forwarded, ",")[0]))
+		if proto == "https" || proto == "wss" {
+			return "wss"
+		}
+		if proto == "http" || proto == "ws" {
+			return "ws"
+		}
+	}
+
+	if r.TLS != nil {
+		return "wss"
+	}
+
+	return "ws"
+}
+
+func (h *Handler) buildWsURL(r *http.Request, cfg *config.Config) string {
+	host := h.effectiveGatewayBindHost(cfg)
+	if host == "" || host == "0.0.0.0" {
+		host = requestHostName(r)
+	}
+	// Use web server port instead of gateway port to avoid exposing extra ports
+	// The WebSocket connection will be proxied by the backend to the gateway
+	wsPort := h.serverPort
+	if wsPort == 0 {
+		wsPort = 18800 // default web server port
+	}
+	return requestWSScheme(r) + "://" + net.JoinHostPort(host, strconv.Itoa(wsPort)) + "/pico/ws"
+}
diff --git a/web/backend/api/gateway_host_test.go b/web/backend/api/gateway_host_test.go
new file mode 100644
index 000000000..ae3434862
--- /dev/null
+++ b/web/backend/api/gateway_host_test.go
@@ -0,0 +1,188 @@
+package api
+
+import (
+	"crypto/tls"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+)
+
+func TestGatewayHostOverrideUsesExplicitRuntimePublic(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	launcherPath := launcherconfig.PathForAppConfig(configPath)
+	if err := launcherconfig.Save(launcherPath, launcherconfig.Config{
+		Port:   18800,
+		Public: false,
+	}); err != nil {
+		t.Fatalf("launcherconfig.Save() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	h.SetServerOptions(18800, true, true, nil)
+
+	if got := h.gatewayHostOverride(); got != "0.0.0.0" {
+		t.Fatalf("gatewayHostOverride() = %q, want %q", got, "0.0.0.0")
+	}
+}
+
+func TestBuildWsURLUsesRequestHostWhenLauncherPublicSaved(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	launcherPath := launcherconfig.PathForAppConfig(configPath)
+	if err := launcherconfig.Save(launcherPath, launcherconfig.Config{
+		Port:   18800,
+		Public: true,
+	}); err != nil {
+		t.Fatalf("launcherconfig.Save() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	h.SetServerOptions(18800, false, false, nil)
+
+	cfg := config.DefaultConfig()
+	cfg.Gateway.Host = "127.0.0.1"
+	cfg.Gateway.Port = 18790
+
+	req := httptest.NewRequest("GET", "http://launcher.local/api/pico/token", nil)
+	req.Host = "192.168.1.9:18800"
+
+	if got := h.buildWsURL(req, cfg); got != "ws://192.168.1.9:18800/pico/ws" {
+		t.Fatalf("buildWsURL() = %q, want %q", got, "ws://192.168.1.9:18800/pico/ws")
+	}
+}
+
+func TestGatewayProbeHostUsesLoopbackForWildcardBind(t *testing.T) {
+	if got := gatewayProbeHost("0.0.0.0"); got != "127.0.0.1" {
+		t.Fatalf("gatewayProbeHost() = %q, want %q", got, "127.0.0.1")
+	}
+}
+
+func TestGatewayProxyURLUsesConfiguredHost(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	cfg := config.DefaultConfig()
+	cfg.Gateway.Host = "192.168.1.10"
+	cfg.Gateway.Port = 18791
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	if got := h.gatewayProxyURL().String(); got != "http://192.168.1.10:18791" {
+		t.Fatalf("gatewayProxyURL() = %q, want %q", got, "http://192.168.1.10:18791")
+	}
+}
+
+func TestGetGatewayHealthUsesConfiguredHost(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	cfg := config.DefaultConfig()
+	cfg.Gateway.Host = "192.168.1.10"
+	cfg.Gateway.Port = 18791
+
+	originalHealthGet := gatewayHealthGet
+	t.Cleanup(func() {
+		gatewayHealthGet = originalHealthGet
+	})
+
+	var requestedURL string
+	gatewayHealthGet = func(url string, timeout time.Duration) (*http.Response, error) {
+		requestedURL = url
+		return nil, errors.New("probe failed")
+	}
+
+	_, statusCode, err := h.getGatewayHealth(cfg, time.Second)
+	_ = statusCode
+	_ = err
+
+	if requestedURL != "http://192.168.1.10:18791/health" {
+		t.Fatalf("health url = %q, want %q", requestedURL, "http://192.168.1.10:18791/health")
+	}
+}
+
+func TestGetGatewayHealthUsesProbeHostForPublicLauncher(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	h.SetServerOptions(18800, true, true, nil)
+
+	cfg := config.DefaultConfig()
+	cfg.Gateway.Host = "127.0.0.1"
+	cfg.Gateway.Port = 18791
+
+	originalHealthGet := gatewayHealthGet
+	t.Cleanup(func() {
+		gatewayHealthGet = originalHealthGet
+	})
+
+	var requestedURL string
+	gatewayHealthGet = func(url string, timeout time.Duration) (*http.Response, error) {
+		requestedURL = url
+		return nil, errors.New("probe failed")
+	}
+
+	_, statusCode, err := h.getGatewayHealth(cfg, time.Second)
+	_ = statusCode
+	_ = err
+
+	if requestedURL != "http://127.0.0.1:18791/health" {
+		t.Fatalf("health url = %q, want %q", requestedURL, "http://127.0.0.1:18791/health")
+	}
+}
+
+func TestBuildWsURLUsesWSSWhenForwardedProtoIsHTTPS(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	cfg := config.DefaultConfig()
+	cfg.Gateway.Host = "0.0.0.0"
+	cfg.Gateway.Port = 18790
+
+	req := httptest.NewRequest("GET", "http://launcher.local/api/pico/token", nil)
+	req.Host = "chat.example.com"
+	req.Header.Set("X-Forwarded-Proto", "https")
+
+	if got := h.buildWsURL(req, cfg); got != "wss://chat.example.com:18800/pico/ws" {
+		t.Fatalf("buildWsURL() = %q, want %q", got, "wss://chat.example.com:18800/pico/ws")
+	}
+}
+
+func TestBuildWsURLUsesWSSWhenRequestIsTLS(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	cfg := config.DefaultConfig()
+	cfg.Gateway.Host = "0.0.0.0"
+	cfg.Gateway.Port = 18790
+
+	req := httptest.NewRequest("GET", "https://launcher.local/api/pico/token", nil)
+	req.Host = "secure.example.com"
+	req.TLS = &tls.ConnectionState{}
+
+	if got := h.buildWsURL(req, cfg); got != "wss://secure.example.com:18800/pico/ws" {
+		t.Fatalf("buildWsURL() = %q, want %q", got, "wss://secure.example.com:18800/pico/ws")
+	}
+}
+
+func TestBuildWsURLPrefersForwardedHTTPOverTLS(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	cfg := config.DefaultConfig()
+	cfg.Gateway.Host = "0.0.0.0"
+	cfg.Gateway.Port = 18790
+
+	req := httptest.NewRequest("GET", "https://launcher.local/api/pico/token", nil)
+	req.Host = "chat.example.com"
+	req.TLS = &tls.ConnectionState{}
+	req.Header.Set("X-Forwarded-Proto", "http")
+
+	if got := h.buildWsURL(req, cfg); got != "ws://chat.example.com:18800/pico/ws" {
+		t.Fatalf("buildWsURL() = %q, want %q", got, "ws://chat.example.com:18800/pico/ws")
+	}
+}
diff --git a/web/backend/api/gateway_test.go b/web/backend/api/gateway_test.go
new file mode 100644
index 000000000..a5ba2bad2
--- /dev/null
+++ b/web/backend/api/gateway_test.go
@@ -0,0 +1,961 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/web/backend/utils"
+)
+
+func startLongRunningProcess(t *testing.T) *exec.Cmd {
+	t.Helper()
+
+	var cmd *exec.Cmd
+	if runtime.GOOS == "windows" {
+		cmd = exec.Command("powershell", "-NoProfile", "-Command", "Start-Sleep -Seconds 30")
+	} else {
+		cmd = exec.Command("sleep", "30")
+	}
+
+	if err := cmd.Start(); err != nil {
+		t.Fatalf("Start() error = %v", err)
+	}
+
+	return cmd
+}
+
+func mockGatewayHealthResponse(statusCode, pid int) *http.Response {
+	return &http.Response{
+		StatusCode: statusCode,
+		Body: io.NopCloser(strings.NewReader(
+			`{"status":"ok","uptime":"1s","pid":` + strconv.Itoa(pid) + `}`,
+		)),
+	}
+}
+
+func startIgnoringTermProcess(t *testing.T) *exec.Cmd {
+	t.Helper()
+
+	if runtime.GOOS == "windows" {
+		t.Skip("TERM handling differs on Windows")
+	}
+
+	cmd := exec.Command("sh", "-c", "trap '' TERM; sleep 30")
+	if err := cmd.Start(); err != nil {
+		t.Fatalf("Start() error = %v", err)
+	}
+
+	return cmd
+}
+
+func resetGatewayTestState(t *testing.T) {
+	t.Helper()
+
+	originalHealthGet := gatewayHealthGet
+	originalRestartGracePeriod := gatewayRestartGracePeriod
+	originalRestartForceKillWindow := gatewayRestartForceKillWindow
+	originalRestartPollInterval := gatewayRestartPollInterval
+	t.Cleanup(func() {
+		gatewayHealthGet = originalHealthGet
+		gatewayRestartGracePeriod = originalRestartGracePeriod
+		gatewayRestartForceKillWindow = originalRestartForceKillWindow
+		gatewayRestartPollInterval = originalRestartPollInterval
+
+		gateway.mu.Lock()
+		gateway.cmd = nil
+		gateway.bootDefaultModel = ""
+		setGatewayRuntimeStatusLocked("stopped")
+		gateway.mu.Unlock()
+	})
+}
+
+func TestGatewayStartReady_NoDefaultModel(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if ready {
+		t.Fatalf("gatewayStartReady() ready = true, want false")
+	}
+	if reason != "no default model configured" {
+		t.Fatalf("gatewayStartReady() reason = %q, want %q", reason, "no default model configured")
+	}
+}
+
+func TestGatewayStartReady_InvalidDefaultModel(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.ModelName = "missing-model"
+	err := config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if ready {
+		t.Fatalf("gatewayStartReady() ready = true, want false")
+	}
+	if reason == "" {
+		t.Fatalf("gatewayStartReady() reason is empty")
+	}
+}
+
+func TestGatewayStartReady_ValidDefaultModel(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
+	cfg.ModelList[0].SetAPIKey("test-key")
+	err := config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if !ready {
+		t.Fatalf("gatewayStartReady() ready = false, want true (reason=%q)", reason)
+	}
+}
+
+func TestGatewayStartReady_DefaultModelWithoutCredential(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
+	cfg.ModelList[0].SetAPIKey("")
+	cfg.ModelList[0].AuthMethod = ""
+	err := config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if ready {
+		t.Fatalf("gatewayStartReady() ready = true, want false")
+	}
+	if !strings.Contains(reason, "no credentials configured") {
+		t.Fatalf("gatewayStartReady() reason = %q, want contains %q", reason, "no credentials configured")
+	}
+}
+
+func TestGatewayStartReady_LocalModelWithoutAPIKey(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetModelProbeHooks(t)
+
+	probeOpenAICompatibleModelFunc = func(apiBase, modelID, apiKey string) bool {
+		return false
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []*config.ModelConfig{{
+		ModelName: "local-vllm",
+		Model:     "vllm/custom-model",
+		APIBase:   "http://localhost:8000/v1",
+	}}
+	cfg.Agents.Defaults.ModelName = "local-vllm"
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if ready {
+		t.Fatalf("gatewayStartReady() ready = true, want false without a running local service")
+	}
+	if !strings.Contains(reason, "not reachable") {
+		t.Fatalf("gatewayStartReady() reason = %q, want contains %q", reason, "not reachable")
+	}
+}
+
+func TestGatewayStartReady_LocalModelWithRunningService(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetModelProbeHooks(t)
+
+	probeOpenAICompatibleModelFunc = func(apiBase, modelID, apiKey string) bool {
+		return apiBase == "http://127.0.0.1:8000/v1" && modelID == "custom-model" && apiKey == ""
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []*config.ModelConfig{{
+		ModelName: "local-vllm",
+		Model:     "vllm/custom-model",
+		APIBase:   "http://127.0.0.1:8000/v1",
+	}}
+	cfg.Agents.Defaults.ModelName = "local-vllm"
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if !ready {
+		t.Fatalf("gatewayStartReady() ready = false, want true with a running local service (reason=%q)", reason)
+	}
+}
+
+func TestGatewayStartReady_RemoteVLLMWithAPIKeyDoesNotProbe(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetModelProbeHooks(t)
+
+	probeOpenAICompatibleModelFunc = func(apiBase, modelID, apiKey string) bool {
+		t.Fatalf("unexpected OpenAI-compatible probe for %q (%q)", apiBase, modelID)
+		return false
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []*config.ModelConfig{{
+		ModelName: "remote-vllm",
+		Model:     "vllm/custom-model",
+		APIBase:   "https://models.example.com/v1",
+	}}
+	cfg.ModelList[0o0].SetAPIKey("remote-key")
+	cfg.Agents.Defaults.ModelName = "remote-vllm"
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if !ready {
+		t.Fatalf("gatewayStartReady() ready = false, want true for remote vllm with api key (reason=%q)", reason)
+	}
+}
+
+func TestGatewayStartReady_LocalOllamaUsesDefaultProbeBase(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetModelProbeHooks(t)
+
+	probeOllamaModelFunc = func(apiBase, modelID string) bool {
+		return apiBase == "http://localhost:11434/v1" && modelID == "llama3"
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []*config.ModelConfig{{
+		ModelName: "local-ollama",
+		Model:     "ollama/llama3",
+	}}
+	cfg.Agents.Defaults.ModelName = "local-ollama"
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if !ready {
+		t.Fatalf("gatewayStartReady() ready = false, want true with default Ollama probe base (reason=%q)", reason)
+	}
+}
+
+func TestGatewayStartReady_OAuthModelRequiresStoredCredential(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []*config.ModelConfig{{
+		ModelName:  "openai-oauth",
+		Model:      "openai/gpt-5.4",
+		AuthMethod: "oauth",
+	}}
+	cfg.Agents.Defaults.ModelName = "openai-oauth"
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	ready, reason, err := h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if ready {
+		t.Fatalf("gatewayStartReady() ready = true, want false without stored credential")
+	}
+	if !strings.Contains(reason, "no credentials configured") {
+		t.Fatalf("gatewayStartReady() reason = %q, want contains %q", reason, "no credentials configured")
+	}
+
+	err = auth.SetCredential(oauthProviderOpenAI, &auth.AuthCredential{
+		AccessToken: "openai-token",
+		Provider:    oauthProviderOpenAI,
+		AuthMethod:  "oauth",
+	})
+	if err != nil {
+		t.Fatalf("SetCredential() error = %v", err)
+	}
+
+	ready, reason, err = h.gatewayStartReady()
+	if err != nil {
+		t.Fatalf("gatewayStartReady() error = %v", err)
+	}
+	if !ready {
+		t.Fatalf("gatewayStartReady() ready = false, want true with stored credential (reason=%q)", reason)
+	}
+}
+
+func TestGatewayStatusIncludesStartConditionWhenNotReady(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/gateway/status", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+
+	allowed, ok := body["gateway_start_allowed"].(bool)
+	if !ok {
+		t.Fatalf("gateway_start_allowed missing or not bool: %#v", body["gateway_start_allowed"])
+	}
+	if allowed {
+		t.Fatalf("gateway_start_allowed = true, want false")
+	}
+	if _, ok := body["gateway_start_reason"].(string); !ok {
+		t.Fatalf("gateway_start_reason missing or not string: %#v", body["gateway_start_reason"])
+	}
+}
+
+func TestGatewayStatusKeepsRunningWhenHealthProbeFailsAfterRunning(t *testing.T) {
+	resetGatewayTestState(t)
+
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	cmd := startLongRunningProcess(t)
+	t.Cleanup(func() {
+		if cmd.Process != nil {
+			_ = cmd.Process.Kill()
+		}
+		_ = cmd.Wait()
+	})
+
+	gateway.mu.Lock()
+	gateway.cmd = cmd
+	gateway.bootDefaultModel = "existing-model"
+	// Simulate a process that has already reached the running state.
+	setGatewayRuntimeStatusLocked("running")
+	gateway.mu.Unlock()
+
+	gatewayHealthGet = func(string, time.Duration) (*http.Response, error) {
+		return nil, errors.New("probe failed")
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/gateway/status", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+
+	if got := body["gateway_status"]; got != "running" {
+		t.Fatalf("gateway_status = %#v, want %q", got, "running")
+	}
+}
+
+func TestGatewayStatusReportsRunningFromHealthProbe(t *testing.T) {
+	resetGatewayTestState(t)
+
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	cmd := startLongRunningProcess(t)
+	t.Cleanup(func() {
+		if cmd.Process != nil {
+			_ = cmd.Process.Kill()
+		}
+		_ = cmd.Wait()
+	})
+
+	gateway.mu.Lock()
+	setGatewayRuntimeStatusLocked("stopped")
+	gateway.mu.Unlock()
+
+	gatewayHealthGet = func(string, time.Duration) (*http.Response, error) {
+		return mockGatewayHealthResponse(http.StatusOK, cmd.Process.Pid), nil
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/gateway/status", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+
+	if got := body["gateway_status"]; got != "running" {
+		t.Fatalf("gateway_status = %#v, want %q", got, "running")
+	}
+	if got := body["pid"]; got != float64(cmd.Process.Pid) {
+		t.Fatalf("pid = %#v, want %d", got, cmd.Process.Pid)
+	}
+	if got := body["gateway_restart_required"]; got != false {
+		t.Fatalf("gateway_restart_required = %#v, want false", got)
+	}
+}
+
+func TestGatewayStatusRequiresRestartAfterDefaultModelChange(t *testing.T) {
+	resetGatewayTestState(t)
+
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
+	cfg.ModelList[0].SetAPIKey("test-key")
+	cfg.ModelList = append(cfg.ModelList, &config.ModelConfig{
+		ModelName: "second-model",
+		Model:     "openai/gpt-4.1",
+	})
+	cfg.ModelList[len(cfg.ModelList)-1].SetAPIKey("second-key")
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	process, err := os.FindProcess(os.Getpid())
+	if err != nil {
+		t.Fatalf("FindProcess() error = %v", err)
+	}
+
+	gateway.mu.Lock()
+	gateway.cmd = &exec.Cmd{Process: process}
+	gateway.bootDefaultModel = cfg.ModelList[0].ModelName
+	setGatewayRuntimeStatusLocked("running")
+	gateway.mu.Unlock()
+
+	updatedCfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	updatedCfg.Agents.Defaults.ModelName = "second-model"
+	if err := config.SaveConfig(configPath, updatedCfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	gatewayHealthGet = func(string, time.Duration) (*http.Response, error) {
+		return mockGatewayHealthResponse(http.StatusOK, os.Getpid()), nil
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/gateway/status", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+
+	if got := body["gateway_status"]; got != "running" {
+		t.Fatalf("gateway_status = %#v, want %q", got, "running")
+	}
+	if got := body["boot_default_model"]; got != cfg.ModelList[0].ModelName {
+		t.Fatalf("boot_default_model = %#v, want %q", got, cfg.ModelList[0].ModelName)
+	}
+	if got := body["config_default_model"]; got != "second-model" {
+		t.Fatalf("config_default_model = %#v, want %q", got, "second-model")
+	}
+	if got := body["gateway_restart_required"]; got != true {
+		t.Fatalf("gateway_restart_required = %#v, want true", got)
+	}
+}
+
+func TestGatewayStatusReturnsErrorAfterStartupWindowExpires(t *testing.T) {
+	resetGatewayTestState(t)
+
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	cmd := startLongRunningProcess(t)
+	t.Cleanup(func() {
+		if cmd.Process != nil {
+			_ = cmd.Process.Kill()
+		}
+		_ = cmd.Wait()
+	})
+
+	gateway.mu.Lock()
+	gateway.cmd = cmd
+	gateway.bootDefaultModel = "existing-model"
+	setGatewayRuntimeStatusLocked("starting")
+	gateway.startupDeadline = time.Now().Add(-time.Second)
+	gateway.mu.Unlock()
+
+	gatewayHealthGet = func(string, time.Duration) (*http.Response, error) {
+		return nil, errors.New("probe failed")
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/gateway/status", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+
+	if got := body["gateway_status"]; got != "error" {
+		t.Fatalf("gateway_status = %#v, want %q", got, "error")
+	}
+}
+
+func TestGatewayStatusReturnsRestartingDuringRestartGap(t *testing.T) {
+	resetGatewayTestState(t)
+
+	// Mock health check to return error, so it won't override our "restarting" status
+	gatewayHealthGet = func(url string, timeout time.Duration) (*http.Response, error) {
+		return nil, errors.New("mock health check error")
+	}
+
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	gateway.mu.Lock()
+	setGatewayRuntimeStatusLocked("restarting")
+	gateway.mu.Unlock()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/gateway/status", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+
+	if got := body["gateway_status"]; got != "restarting" {
+		t.Fatalf("gateway_status = %#v, want %q", got, "restarting")
+	}
+}
+
+func TestGatewayRestartKeepsRunningProcessWhenPreconditionsFail(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
+	cfg.ModelList[0].SetAPIKey("")
+	cfg.ModelList[0].AuthMethod = ""
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	cmd := startLongRunningProcess(t)
+	t.Cleanup(func() {
+		gateway.mu.Lock()
+		if gateway.cmd == cmd {
+			gateway.cmd = nil
+			gateway.bootDefaultModel = ""
+		}
+		gateway.mu.Unlock()
+
+		if cmd.Process != nil {
+			_ = cmd.Process.Kill()
+		}
+		_ = cmd.Wait()
+	})
+
+	gateway.mu.Lock()
+	gateway.cmd = cmd
+	gateway.bootDefaultModel = "existing-model"
+	gateway.mu.Unlock()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/gateway/restart", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusBadRequest)
+	}
+
+	gateway.mu.Lock()
+	stillRunning := gateway.cmd == cmd && isCmdProcessAliveLocked(cmd)
+	gateway.mu.Unlock()
+
+	if !stillRunning {
+		t.Fatalf("gateway process was stopped when restart preconditions failed")
+	}
+}
+
+func TestGatewayRestartKeepsOldProcessWhenItDoesNotExitInTime(t *testing.T) {
+	resetGatewayTestState(t)
+
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
+	cfg.ModelList[0].SetAPIKey("test-key")
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	cmd := startIgnoringTermProcess(t)
+	t.Cleanup(func() {
+		gateway.mu.Lock()
+		if gateway.cmd == cmd {
+			gateway.cmd = nil
+			gateway.bootDefaultModel = ""
+		}
+		gateway.mu.Unlock()
+
+		if cmd.Process != nil {
+			_ = cmd.Process.Kill()
+		}
+		_ = cmd.Wait()
+	})
+
+	gatewayRestartGracePeriod = 150 * time.Millisecond
+	gatewayRestartForceKillWindow = 150 * time.Millisecond
+	gatewayRestartPollInterval = 10 * time.Millisecond
+
+	gateway.mu.Lock()
+	gateway.cmd = cmd
+	gateway.bootDefaultModel = "existing-model"
+	setGatewayRuntimeStatusLocked("running")
+	gateway.mu.Unlock()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/gateway/restart", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusInternalServerError)
+	}
+
+	gateway.mu.Lock()
+	stillRunning := gateway.cmd == cmd && isCmdProcessAliveLocked(cmd)
+	status := gateway.runtimeStatus
+	gateway.mu.Unlock()
+
+	if !stillRunning {
+		t.Fatalf("gateway process was replaced before the old process exited")
+	}
+	if status != "running" {
+		t.Fatalf("runtimeStatus = %q, want %q", status, "running")
+	}
+}
+
+func TestGatewayRestartReturnsErrorStatusWhenReplacementFailsToStart(t *testing.T) {
+	resetGatewayTestState(t)
+
+	// Mock health check to return error, so it won't override our "error" status
+	gatewayHealthGet = func(url string, timeout time.Duration) (*http.Response, error) {
+		return nil, errors.New("mock health check error")
+	}
+
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.ModelName = cfg.ModelList[0].ModelName
+	cfg.ModelList[0].SetAPIKey("test-key")
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	invalidBinaryPath := filepath.Join(t.TempDir(), "fake-picoclaw")
+	if err := os.WriteFile(invalidBinaryPath, []byte("#!/bin/sh\n"), 0o644); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+	t.Setenv("PICOCLAW_BINARY", invalidBinaryPath)
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/gateway/restart", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("restart status = %d, want %d", rec.Code, http.StatusInternalServerError)
+	}
+
+	statusRec := httptest.NewRecorder()
+	statusReq := httptest.NewRequest(http.MethodGet, "/api/gateway/status", nil)
+	mux.ServeHTTP(statusRec, statusReq)
+
+	if statusRec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", statusRec.Code, http.StatusOK)
+	}
+
+	var body map[string]any
+	if err := json.Unmarshal(statusRec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+
+	if got := body["gateway_status"]; got != "error" {
+		t.Fatalf("gateway_status = %#v, want %q", got, "error")
+	}
+}
+
+func TestGatewayStatusExcludesLogsFields(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/gateway/status", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+
+	if _, ok := body["logs"]; ok {
+		t.Fatalf("logs unexpectedly present in status response: %#v", body["logs"])
+	}
+	if _, ok := body["log_total"]; ok {
+		t.Fatalf("log_total unexpectedly present in status response: %#v", body["log_total"])
+	}
+	if _, ok := body["log_run_id"]; ok {
+		t.Fatalf("log_run_id unexpectedly present in status response: %#v", body["log_run_id"])
+	}
+}
+
+func TestGatewayLogsReturnsIncrementalHistory(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	gateway.logs.Clear()
+	gateway.logs.Append("first line")
+	gateway.logs.Append("second line")
+	runID := gateway.logs.RunID()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(
+		http.MethodGet,
+		"/api/gateway/logs?log_offset=1&log_run_id="+strconv.Itoa(runID),
+		nil,
+	)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("logs status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var body map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &body); err != nil {
+		t.Fatalf("unmarshal logs response: %v", err)
+	}
+
+	logs, ok := body["logs"].([]any)
+	if !ok {
+		t.Fatalf("logs missing or not array: %#v", body["logs"])
+	}
+	if len(logs) != 1 || logs[0] != "second line" {
+		t.Fatalf("logs = %#v, want [\"second line\"]", logs)
+	}
+	if got := body["log_total"]; got != float64(2) {
+		t.Fatalf("log_total = %#v, want 2", got)
+	}
+	if got := body["log_run_id"]; got != float64(runID) {
+		t.Fatalf("log_run_id = %#v, want %d", got, runID)
+	}
+}
+
+func TestGatewayClearLogsResetsBufferedHistory(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	gateway.logs.Clear()
+	gateway.logs.Append("first line")
+	gateway.logs.Append("second line")
+	previousRunID := gateway.logs.RunID()
+
+	clearRec := httptest.NewRecorder()
+	clearReq := httptest.NewRequest(http.MethodPost, "/api/gateway/logs/clear", nil)
+	mux.ServeHTTP(clearRec, clearReq)
+
+	if clearRec.Code != http.StatusOK {
+		t.Fatalf("clear status = %d, want %d", clearRec.Code, http.StatusOK)
+	}
+
+	var clearBody map[string]any
+	if err := json.Unmarshal(clearRec.Body.Bytes(), &clearBody); err != nil {
+		t.Fatalf("unmarshal clear response: %v", err)
+	}
+
+	if got := clearBody["status"]; got != "cleared" {
+		t.Fatalf("clear status body = %#v, want %q", got, "cleared")
+	}
+
+	clearRunID, ok := clearBody["log_run_id"].(float64)
+	if !ok {
+		t.Fatalf("log_run_id missing or not number: %#v", clearBody["log_run_id"])
+	}
+	if int(clearRunID) <= previousRunID {
+		t.Fatalf("log_run_id = %d, want > %d", int(clearRunID), previousRunID)
+	}
+
+	logsRec := httptest.NewRecorder()
+	logsReq := httptest.NewRequest(
+		http.MethodGet,
+		"/api/gateway/logs?log_offset=0&log_run_id="+strconv.Itoa(previousRunID),
+		nil,
+	)
+	mux.ServeHTTP(logsRec, logsReq)
+
+	if logsRec.Code != http.StatusOK {
+		t.Fatalf("logs code = %d, want %d", logsRec.Code, http.StatusOK)
+	}
+
+	var logsBody map[string]any
+	if err := json.Unmarshal(logsRec.Body.Bytes(), &logsBody); err != nil {
+		t.Fatalf("unmarshal logs response: %v", err)
+	}
+
+	logs, ok := logsBody["logs"].([]any)
+	if !ok {
+		t.Fatalf("logs missing or not array: %#v", logsBody["logs"])
+	}
+	if len(logs) != 0 {
+		t.Fatalf("logs len = %d, want 0", len(logs))
+	}
+	if got := logsBody["log_total"]; got != float64(0) {
+		t.Fatalf("log_total = %#v, want 0", got)
+	}
+	if got := logsBody["log_run_id"]; got != clearBody["log_run_id"] {
+		t.Fatalf("log_run_id = %#v, want %#v", got, clearBody["log_run_id"])
+	}
+}
+
+func TestFindPicoclawBinary_EnvOverride(t *testing.T) {
+	// Create a temporary file to act as the mock binary
+	tmpDir := t.TempDir()
+	mockBinary := filepath.Join(tmpDir, "picoclaw-mock")
+	if err := os.WriteFile(mockBinary, []byte("mock"), 0o755); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	t.Setenv("PICOCLAW_BINARY", mockBinary)
+
+	got := utils.FindPicoclawBinary()
+	if got != mockBinary {
+		t.Errorf("FindPicoclawBinary() = %q, want %q", got, mockBinary)
+	}
+}
+
+func TestFindPicoclawBinary_EnvOverride_InvalidPath(t *testing.T) {
+	// When PICOCLAW_BINARY points to a non-existent path, fall through to next strategy
+	t.Setenv("PICOCLAW_BINARY", "/nonexistent/picoclaw-binary")
+
+	got := utils.FindPicoclawBinary()
+	// Should not return the invalid path; falls back to "picoclaw" or another found path
+	if got == "/nonexistent/picoclaw-binary" {
+		t.Errorf("FindPicoclawBinary() returned invalid env path %q, expected fallback", got)
+	}
+}
diff --git a/web/backend/api/launcher_config.go b/web/backend/api/launcher_config.go
new file mode 100644
index 000000000..e149d5671
--- /dev/null
+++ b/web/backend/api/launcher_config.go
@@ -0,0 +1,85 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+)
+
+type launcherConfigPayload struct {
+	Port         int      `json:"port"`
+	Public       bool     `json:"public"`
+	AllowedCIDRs []string `json:"allowed_cidrs"`
+}
+
+func (h *Handler) registerLauncherConfigRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/system/launcher-config", h.handleGetLauncherConfig)
+	mux.HandleFunc("PUT /api/system/launcher-config", h.handleUpdateLauncherConfig)
+}
+
+func (h *Handler) launcherConfigPath() string {
+	return launcherconfig.PathForAppConfig(h.configPath)
+}
+
+func (h *Handler) launcherFallbackConfig() launcherconfig.Config {
+	port := h.serverPort
+	if port <= 0 {
+		port = launcherconfig.DefaultPort
+	}
+	return launcherconfig.Config{
+		Port:         port,
+		Public:       h.serverPublic,
+		AllowedCIDRs: append([]string(nil), h.serverCIDRs...),
+	}
+}
+
+func (h *Handler) loadLauncherConfig() (launcherconfig.Config, error) {
+	return launcherconfig.Load(h.launcherConfigPath(), h.launcherFallbackConfig())
+}
+
+func (h *Handler) handleGetLauncherConfig(w http.ResponseWriter, r *http.Request) {
+	cfg, err := h.loadLauncherConfig()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load launcher config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(launcherConfigPayload{
+		Port:         cfg.Port,
+		Public:       cfg.Public,
+		AllowedCIDRs: append([]string(nil), cfg.AllowedCIDRs...),
+	})
+}
+
+func (h *Handler) handleUpdateLauncherConfig(w http.ResponseWriter, r *http.Request) {
+	var payload launcherConfigPayload
+	if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	cfg := launcherconfig.Config{
+		Port:         payload.Port,
+		Public:       payload.Public,
+		AllowedCIDRs: append([]string(nil), payload.AllowedCIDRs...),
+	}
+	if err := launcherconfig.Validate(cfg); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	if err := launcherconfig.Save(h.launcherConfigPath(), cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save launcher config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(launcherConfigPayload{
+		Port:         cfg.Port,
+		Public:       cfg.Public,
+		AllowedCIDRs: append([]string(nil), cfg.AllowedCIDRs...),
+	})
+}
diff --git a/web/backend/api/launcher_config_test.go b/web/backend/api/launcher_config_test.go
new file mode 100644
index 000000000..0d6af823c
--- /dev/null
+++ b/web/backend/api/launcher_config_test.go
@@ -0,0 +1,115 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+)
+
+func TestGetLauncherConfigUsesRuntimeFallback(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	h.SetServerOptions(19999, true, false, []string{"192.168.1.0/24"})
+
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/system/launcher-config", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var got launcherConfigPayload
+	if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
+		t.Fatalf("unmarshal response: %v", err)
+	}
+	if got.Port != 19999 || !got.Public {
+		t.Fatalf("response = %+v, want port=19999 public=true", got)
+	}
+	if len(got.AllowedCIDRs) != 1 || got.AllowedCIDRs[0] != "192.168.1.0/24" {
+		t.Fatalf("response allowed_cidrs = %v, want [192.168.1.0/24]", got.AllowedCIDRs)
+	}
+}
+
+func TestPutLauncherConfigPersists(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(
+		http.MethodPut,
+		"/api/system/launcher-config",
+		strings.NewReader(`{"port":18080,"public":true,"allowed_cidrs":["192.168.1.0/24"]}`),
+	)
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	path := launcherconfig.PathForAppConfig(configPath)
+	cfg, err := launcherconfig.Load(path, launcherconfig.Default())
+	if err != nil {
+		t.Fatalf("launcherconfig.Load() error = %v", err)
+	}
+	if cfg.Port != 18080 || !cfg.Public {
+		t.Fatalf("saved config = %+v, want port=18080 public=true", cfg)
+	}
+	if len(cfg.AllowedCIDRs) != 1 || cfg.AllowedCIDRs[0] != "192.168.1.0/24" {
+		t.Fatalf("saved config allowed_cidrs = %v, want [192.168.1.0/24]", cfg.AllowedCIDRs)
+	}
+}
+
+func TestPutLauncherConfigRejectsInvalidPort(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(
+		http.MethodPut,
+		"/api/system/launcher-config",
+		strings.NewReader(`{"port":70000,"public":false}`),
+	)
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusBadRequest, rec.Body.String())
+	}
+}
+
+func TestPutLauncherConfigRejectsInvalidCIDR(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(
+		http.MethodPut,
+		"/api/system/launcher-config",
+		strings.NewReader(`{"port":18080,"public":false,"allowed_cidrs":["bad-cidr"]}`),
+	)
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusBadRequest, rec.Body.String())
+	}
+}
diff --git a/cmd/picoclaw-launcher/internal/server/logbuffer.go b/web/backend/api/log.go
similarity index 88%
rename from cmd/picoclaw-launcher/internal/server/logbuffer.go
rename to web/backend/api/log.go
index 4d70f6466..f83f6f34c 100644
--- a/cmd/picoclaw-launcher/internal/server/logbuffer.go
+++ b/web/backend/api/log.go
@@ -1,10 +1,10 @@
-package server
+package api
 
 import "sync"
 
 // LogBuffer is a thread-safe ring buffer that stores the most recent N log lines.
 // It supports incremental reads via LinesSince and tracks a runID that increments
-// on each Reset (used to detect gateway restarts).
+// whenever the buffer is reset or cleared so clients can detect log history resets.
 type LogBuffer struct {
 	mu    sync.RWMutex
 	lines []string
@@ -45,6 +45,12 @@ func (b *LogBuffer) Reset() {
 	b.runID++
 }
 
+// Clear removes all buffered lines and increments the runID so clients treat
+// subsequent reads as a new log stream.
+func (b *LogBuffer) Clear() {
+	b.Reset()
+}
+
 // LinesSince returns lines appended after the given offset, the current total count, and the runID.
 // If offset >= total, no lines are returned. If offset is too old (evicted), all buffered lines are returned.
 func (b *LogBuffer) LinesSince(offset int) (lines []string, total int, runID int) {
@@ -89,11 +95,3 @@ func (b *LogBuffer) RunID() int {
 
 	return b.runID
 }
-
-// Total returns the total number of lines appended in the current run.
-func (b *LogBuffer) Total() int {
-	b.mu.RLock()
-	defer b.mu.RUnlock()
-
-	return b.total
-}
diff --git a/web/backend/api/model_status.go b/web/backend/api/model_status.go
new file mode 100644
index 000000000..aeef85119
--- /dev/null
+++ b/web/backend/api/model_status.go
@@ -0,0 +1,327 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"net"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+const modelProbeTimeout = 800 * time.Millisecond
+
+var (
+	probeTCPServiceFunc            = probeTCPService
+	probeOllamaModelFunc           = probeOllamaModel
+	probeOpenAICompatibleModelFunc = probeOpenAICompatibleModel
+)
+
+func hasModelConfiguration(m *config.ModelConfig) bool {
+	authMethod := strings.ToLower(strings.TrimSpace(m.AuthMethod))
+	apiKey := strings.TrimSpace(m.APIKey())
+
+	if authMethod == "oauth" || authMethod == "token" {
+		if provider, ok := oauthProviderForModel(m.Model); ok {
+			cred, err := oauthGetCredential(provider)
+			if err != nil || cred == nil {
+				return false
+			}
+			return strings.TrimSpace(cred.AccessToken) != "" || strings.TrimSpace(cred.RefreshToken) != ""
+		}
+		return true
+	}
+
+	if requiresRuntimeProbe(m) {
+		return true
+	}
+
+	return apiKey != ""
+}
+
+// isModelConfigured reports whether a model is currently available to use.
+// Local models must be reachable; remote/API-key models only need saved config.
+func isModelConfigured(m *config.ModelConfig) bool {
+	if !hasModelConfiguration(m) {
+		return false
+	}
+	if requiresRuntimeProbe(m) {
+		return probeLocalModelAvailability(m)
+	}
+	return true
+}
+
+func requiresRuntimeProbe(m *config.ModelConfig) bool {
+	authMethod := strings.ToLower(strings.TrimSpace(m.AuthMethod))
+	if authMethod == "local" {
+		return true
+	}
+
+	switch modelProtocol(m.Model) {
+	case "claude-cli", "claudecli", "codex-cli", "codexcli", "github-copilot", "copilot":
+		return true
+	case "ollama", "vllm":
+		apiBase := strings.TrimSpace(m.APIBase)
+		return apiBase == "" || hasLocalAPIBase(apiBase)
+	}
+
+	if hasLocalAPIBase(m.APIBase) {
+		return true
+	}
+
+	return false
+}
+
+func probeLocalModelAvailability(m *config.ModelConfig) bool {
+	apiBase := modelProbeAPIBase(m)
+	protocol, modelID := splitModel(m.Model)
+	switch protocol {
+	case "ollama":
+		return probeOllamaModelFunc(apiBase, modelID)
+	case "vllm":
+		return probeOpenAICompatibleModelFunc(apiBase, modelID, m.APIKey())
+	case "github-copilot", "copilot":
+		return probeTCPServiceFunc(apiBase)
+	case "claude-cli", "claudecli", "codex-cli", "codexcli":
+		return true
+	default:
+		if hasLocalAPIBase(apiBase) {
+			return probeOpenAICompatibleModelFunc(apiBase, modelID, m.APIKey())
+		}
+		return false
+	}
+}
+
+func modelProbeAPIBase(m *config.ModelConfig) string {
+	if apiBase := strings.TrimSpace(m.APIBase); apiBase != "" {
+		return normalizeModelProbeAPIBase(apiBase)
+	}
+
+	switch modelProtocol(m.Model) {
+	case "ollama":
+		return "http://localhost:11434/v1"
+	case "vllm":
+		return "http://localhost:8000/v1"
+	case "github-copilot", "copilot":
+		return "localhost:4321"
+	default:
+		return ""
+	}
+}
+
+func normalizeModelProbeAPIBase(raw string) string {
+	u, err := parseAPIBase(raw)
+	if err != nil {
+		return strings.TrimSpace(raw)
+	}
+
+	switch strings.ToLower(u.Hostname()) {
+	case "0.0.0.0":
+		u.Host = net.JoinHostPort("127.0.0.1", u.Port())
+	case "::":
+		u.Host = net.JoinHostPort("::1", u.Port())
+	default:
+		return strings.TrimSpace(raw)
+	}
+
+	if u.Port() == "" {
+		u.Host = u.Hostname()
+	}
+
+	return u.String()
+}
+
+func oauthProviderForModel(model string) (string, bool) {
+	switch modelProtocol(model) {
+	case "openai":
+		return oauthProviderOpenAI, true
+	case "anthropic":
+		return oauthProviderAnthropic, true
+	case "antigravity", "google-antigravity":
+		return oauthProviderGoogleAntigravity, true
+	default:
+		return "", false
+	}
+}
+
+func modelProtocol(model string) string {
+	protocol, _ := splitModel(model)
+	return protocol
+}
+
+func splitModel(model string) (protocol, modelID string) {
+	model = strings.ToLower(strings.TrimSpace(model))
+	protocol, _, found := strings.Cut(model, "/")
+	if !found {
+		return "openai", model
+	}
+	return protocol, strings.TrimSpace(model[strings.Index(model, "/")+1:])
+}
+
+func hasLocalAPIBase(raw string) bool {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return false
+	}
+
+	u, err := url.Parse(raw)
+	if err != nil || u.Hostname() == "" {
+		u, err = url.Parse("//" + raw)
+		if err != nil {
+			return false
+		}
+	}
+
+	switch strings.ToLower(u.Hostname()) {
+	case "localhost", "127.0.0.1", "::1", "0.0.0.0":
+		return true
+	default:
+		return false
+	}
+}
+
+func probeTCPService(raw string) bool {
+	hostPort, err := hostPortFromAPIBase(raw)
+	if err != nil {
+		return false
+	}
+
+	conn, err := net.DialTimeout("tcp", hostPort, modelProbeTimeout)
+	if err != nil {
+		return false
+	}
+	_ = conn.Close()
+	return true
+}
+
+func probeOllamaModel(apiBase, modelID string) bool {
+	root, err := apiRootFromAPIBase(apiBase)
+	if err != nil {
+		return false
+	}
+
+	var resp struct {
+		Models []struct {
+			Name  string `json:"name"`
+			Model string `json:"model"`
+		} `json:"models"`
+	}
+	if err := getJSON(root+"/api/tags", &resp, ""); err != nil {
+		return false
+	}
+
+	for _, model := range resp.Models {
+		if ollamaModelMatches(model.Name, modelID) || ollamaModelMatches(model.Model, modelID) {
+			return true
+		}
+	}
+	return false
+}
+
+func probeOpenAICompatibleModel(apiBase, modelID, apiKey string) bool {
+	if strings.TrimSpace(apiBase) == "" {
+		return false
+	}
+
+	var resp struct {
+		Data []struct {
+			ID string `json:"id"`
+		} `json:"data"`
+	}
+	if err := getJSON(strings.TrimRight(strings.TrimSpace(apiBase), "/")+"/models", &resp, apiKey); err != nil {
+		return false
+	}
+
+	for _, model := range resp.Data {
+		if strings.EqualFold(strings.TrimSpace(model.ID), modelID) {
+			return true
+		}
+	}
+	return false
+}
+
+func getJSON(rawURL string, out any, apiKey string) error {
+	req, err := http.NewRequest(http.MethodGet, rawURL, nil)
+	if err != nil {
+		return err
+	}
+	if apiKey = strings.TrimSpace(apiKey); apiKey != "" {
+		req.Header.Set("Authorization", "Bearer "+apiKey)
+	}
+
+	client := &http.Client{Timeout: modelProbeTimeout}
+	resp, err := client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("unexpected status %d", resp.StatusCode)
+	}
+
+	return json.NewDecoder(resp.Body).Decode(out)
+}
+
+func apiRootFromAPIBase(raw string) (string, error) {
+	u, err := parseAPIBase(raw)
+	if err != nil {
+		return "", err
+	}
+	return (&url.URL{Scheme: u.Scheme, Host: u.Host}).String(), nil
+}
+
+func hostPortFromAPIBase(raw string) (string, error) {
+	u, err := parseAPIBase(raw)
+	if err != nil {
+		return "", err
+	}
+
+	if port := u.Port(); port != "" {
+		return u.Host, nil
+	}
+	switch strings.ToLower(u.Scheme) {
+	case "https":
+		return net.JoinHostPort(u.Hostname(), "443"), nil
+	default:
+		return net.JoinHostPort(u.Hostname(), "80"), nil
+	}
+}
+
+func parseAPIBase(raw string) (*url.URL, error) {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return nil, fmt.Errorf("empty api base")
+	}
+
+	u, err := url.Parse(raw)
+	if err == nil && u.Hostname() != "" {
+		return u, nil
+	}
+
+	u, err = url.Parse("//" + raw)
+	if err != nil || u.Hostname() == "" {
+		return nil, fmt.Errorf("invalid api base %q", raw)
+	}
+	if u.Scheme == "" {
+		u.Scheme = "http"
+	}
+	return u, nil
+}
+
+func ollamaModelMatches(candidate, want string) bool {
+	candidate = strings.TrimSpace(candidate)
+	want = strings.TrimSpace(want)
+	if candidate == "" || want == "" {
+		return false
+	}
+	if strings.EqualFold(candidate, want) {
+		return true
+	}
+
+	base, _, _ := strings.Cut(candidate, ":")
+	return strings.EqualFold(base, want)
+}
diff --git a/web/backend/api/model_status_test.go b/web/backend/api/model_status_test.go
new file mode 100644
index 000000000..df942a9e9
--- /dev/null
+++ b/web/backend/api/model_status_test.go
@@ -0,0 +1,37 @@
+package api
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestProbeLocalModelAvailability_OpenAICompatibleIncludesAPIKey(t *testing.T) {
+	const apiKey = "test-api-key"
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/v1/models" {
+			t.Fatalf("path = %q, want %q", r.URL.Path, "/v1/models")
+		}
+		if got := r.Header.Get("Authorization"); got != "Bearer "+apiKey {
+			http.Error(w, "missing auth", http.StatusUnauthorized)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"data":[{"id":"custom-model"}]}`))
+	}))
+	defer srv.Close()
+
+	model := &config.ModelConfig{
+		Model:   "openai/custom-model",
+		APIBase: srv.URL + "/v1",
+	}
+	model.SetAPIKey(apiKey)
+
+	if !probeLocalModelAvailability(model) {
+		t.Fatal("probeLocalModelAvailability() = false, want true when api_key is configured")
+	}
+}
diff --git a/web/backend/api/models.go b/web/backend/api/models.go
new file mode 100644
index 000000000..ce7719906
--- /dev/null
+++ b/web/backend/api/models.go
@@ -0,0 +1,348 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"sync"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// registerModelRoutes binds model list management endpoints to the ServeMux.
+func (h *Handler) registerModelRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/models", h.handleListModels)
+	mux.HandleFunc("POST /api/models", h.handleAddModel)
+	mux.HandleFunc("POST /api/models/default", h.handleSetDefaultModel)
+	mux.HandleFunc("PUT /api/models/{index}", h.handleUpdateModel)
+	mux.HandleFunc("DELETE /api/models/{index}", h.handleDeleteModel)
+}
+
+// modelResponse is the JSON structure returned for each model in the list.
+// All ModelConfig fields are included so the frontend can display and edit them.
+type modelResponse struct {
+	Index      int    `json:"index"`
+	ModelName  string `json:"model_name"`
+	Model      string `json:"model"`
+	APIBase    string `json:"api_base,omitempty"`
+	APIKey     string `json:"api_key"`
+	Proxy      string `json:"proxy,omitempty"`
+	AuthMethod string `json:"auth_method,omitempty"`
+	// Advanced fields
+	ConnectMode    string         `json:"connect_mode,omitempty"`
+	Workspace      string         `json:"workspace,omitempty"`
+	RPM            int            `json:"rpm,omitempty"`
+	MaxTokensField string         `json:"max_tokens_field,omitempty"`
+	RequestTimeout int            `json:"request_timeout,omitempty"`
+	ThinkingLevel  string         `json:"thinking_level,omitempty"`
+	ExtraBody      map[string]any `json:"extra_body,omitempty"`
+	// Meta
+	Configured bool `json:"configured"`
+	IsDefault  bool `json:"is_default"`
+	IsVirtual  bool `json:"is_virtual"`
+}
+
+// handleListModels returns all model_list entries with masked API keys.
+//
+//	GET /api/models
+func (h *Handler) handleListModels(w http.ResponseWriter, r *http.Request) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	defaultModel := cfg.Agents.Defaults.GetModelName()
+	configured := make([]bool, len(cfg.ModelList))
+
+	var wg sync.WaitGroup
+	wg.Add(len(cfg.ModelList))
+	for i, m := range cfg.ModelList {
+		go func(i int, m *config.ModelConfig) {
+			defer wg.Done()
+			configured[i] = isModelConfigured(m)
+		}(i, m)
+	}
+	wg.Wait()
+
+	models := make([]modelResponse, 0, len(cfg.ModelList))
+	for i, m := range cfg.ModelList {
+		models = append(models, modelResponse{
+			Index:          i,
+			ModelName:      m.ModelName,
+			Model:          m.Model,
+			APIBase:        m.APIBase,
+			APIKey:         maskAPIKey(m.APIKey()),
+			Proxy:          m.Proxy,
+			AuthMethod:     m.AuthMethod,
+			ConnectMode:    m.ConnectMode,
+			Workspace:      m.Workspace,
+			RPM:            m.RPM,
+			MaxTokensField: m.MaxTokensField,
+			RequestTimeout: m.RequestTimeout,
+			ThinkingLevel:  m.ThinkingLevel,
+			ExtraBody:      m.ExtraBody,
+			Configured:     configured[i],
+			IsDefault:      m.ModelName == defaultModel,
+			IsVirtual:      m.IsVirtual(),
+		})
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"models":        models,
+		"total":         len(models),
+		"default_model": defaultModel,
+	})
+}
+
+// handleAddModel appends a new model configuration entry.
+//
+//	POST /api/models
+func (h *Handler) handleAddModel(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "Failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	type custom struct {
+		config.ModelConfig
+		APIKey string `json:"api_key"`
+	}
+
+	var mc custom
+	if err = json.Unmarshal(body, &mc); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	if err = mc.Validate(); err != nil {
+		http.Error(w, fmt.Sprintf("Validation error: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	if mc.APIKey != "" {
+		mc.ModelConfig.SetAPIKey(mc.APIKey)
+	}
+
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	cfg.ModelList = append(cfg.ModelList, &mc.ModelConfig)
+
+	if err := config.SaveConfig(h.configPath, cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"status": "ok",
+		"index":  len(cfg.ModelList) - 1,
+	})
+}
+
+// handleUpdateModel replaces a model configuration entry at the given index.
+// If the request body omits api_key (or sends an empty string), the existing
+// stored key is preserved so callers can update only api_base / proxy without
+// exposing or clearing the secret.
+//
+//	PUT /api/models/{index}
+func (h *Handler) handleUpdateModel(w http.ResponseWriter, r *http.Request) {
+	idx, err := strconv.Atoi(r.PathValue("index"))
+	if err != nil {
+		http.Error(w, "Invalid index", http.StatusBadRequest)
+		return
+	}
+
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "Failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	type custom struct {
+		config.ModelConfig
+		APIKey string `json:"api_key"`
+	}
+
+	var mc custom
+	if err = json.Unmarshal(body, &mc); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	if err = mc.Validate(); err != nil {
+		http.Error(w, fmt.Sprintf("Validation error: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	if idx < 0 || idx >= len(cfg.ModelList) {
+		http.Error(w, fmt.Sprintf("Index %d out of range (0-%d)", idx, len(cfg.ModelList)-1), http.StatusNotFound)
+		return
+	}
+
+	// Preserve the existing API key when the caller omits it (empty string).
+	// This lets the UI update api_base / proxy without clearing the stored secret.
+	if mc.APIKey == "" {
+		mc.ModelConfig.SetAPIKey(cfg.ModelList[idx].APIKey())
+	} else {
+		mc.ModelConfig.SetAPIKey(mc.APIKey)
+	}
+	if mc.ExtraBody == nil {
+		mc.ExtraBody = cfg.ModelList[idx].ExtraBody
+	}
+
+	cfg.ModelList[idx] = &mc.ModelConfig
+
+	logger.Debugf("update model config: %#v", mc.ModelConfig)
+
+	if err := config.SaveConfig(h.configPath, cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+}
+
+// handleDeleteModel removes a model configuration entry at the given index.
+//
+//	DELETE /api/models/{index}
+func (h *Handler) handleDeleteModel(w http.ResponseWriter, r *http.Request) {
+	idx, err := strconv.Atoi(r.PathValue("index"))
+	if err != nil {
+		http.Error(w, "Invalid index", http.StatusBadRequest)
+		return
+	}
+
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	if idx < 0 || idx >= len(cfg.ModelList) {
+		http.Error(w, fmt.Sprintf("Index %d out of range (0-%d)", idx, len(cfg.ModelList)-1), http.StatusNotFound)
+		return
+	}
+
+	deletedModelName := cfg.ModelList[idx].ModelName
+
+	cfg.ModelList = append(cfg.ModelList[:idx], cfg.ModelList[idx+1:]...)
+
+	// If the deleted model was the default, clear it.
+	if cfg.Agents.Defaults.ModelName == deletedModelName {
+		cfg.Agents.Defaults.ModelName = ""
+	}
+
+	if err := config.SaveConfig(h.configPath, cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+}
+
+// handleSetDefaultModel sets the default model for all agents.
+//
+//	POST /api/models/default
+func (h *Handler) handleSetDefaultModel(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "Failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	var req struct {
+		ModelName string `json:"model_name"`
+	}
+	if err = json.Unmarshal(body, &req); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	if req.ModelName == "" {
+		http.Error(w, "model_name is required", http.StatusBadRequest)
+		return
+	}
+
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	// Verify the model_name exists in model_list and is not a virtual model
+	found := false
+	isVirtual := false
+	for _, m := range cfg.ModelList {
+		if m.ModelName == req.ModelName {
+			found = true
+			isVirtual = m.IsVirtual()
+			break
+		}
+	}
+	if !found {
+		http.Error(w, fmt.Sprintf("Model %q not found in model_list", req.ModelName), http.StatusNotFound)
+		return
+	}
+	if isVirtual {
+		http.Error(w, fmt.Sprintf("Cannot set virtual model %q as default", req.ModelName), http.StatusBadRequest)
+		return
+	}
+
+	cfg.Agents.Defaults.ModelName = req.ModelName
+
+	if err := config.SaveConfig(h.configPath, cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{
+		"status":        "ok",
+		"default_model": req.ModelName,
+	})
+}
+
+// maskAPIKey returns a masked version of an API key for safe display.
+// Keys longer than 12 chars show prefix + last 4 chars: "sk-****abcd".
+// Keys 9-12 chars show prefix + last 2 chars: "sk-****cd".
+// Shorter keys are fully masked as "****".
+// Empty keys return empty string.
+// Ensure at least 40% of the key will not be displayed.
+func maskAPIKey(key string) string {
+	if key == "" {
+		return ""
+	}
+
+	if len(key) <= 8 {
+		return "****"
+	}
+
+	// Show first 3 chars and last 2 chars
+	if len(key) <= 12 {
+		return key[:3] + "****" + key[len(key)-2:]
+	}
+
+	// Show first 3 chars and last 4 chars
+	return key[:3] + "****" + key[len(key)-4:]
+}
diff --git a/web/backend/api/models_test.go b/web/backend/api/models_test.go
new file mode 100644
index 000000000..c80527fe3
--- /dev/null
+++ b/web/backend/api/models_test.go
@@ -0,0 +1,468 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func resetModelProbeHooks(t *testing.T) {
+	t.Helper()
+
+	origTCPProbe := probeTCPServiceFunc
+	origOllamaProbe := probeOllamaModelFunc
+	origOpenAIProbe := probeOpenAICompatibleModelFunc
+	t.Cleanup(func() {
+		probeTCPServiceFunc = origTCPProbe
+		probeOllamaModelFunc = origOllamaProbe
+		probeOpenAICompatibleModelFunc = origOpenAIProbe
+	})
+}
+
+func TestHandleListModels_ConfiguredStatusUsesRuntimeProbesForLocalModels(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+	resetModelProbeHooks(t)
+
+	var mu sync.Mutex
+	var openAIProbes []string
+	var ollamaProbes []string
+	var tcpProbes []string
+
+	probeOpenAICompatibleModelFunc = func(apiBase, modelID, apiKey string) bool {
+		mu.Lock()
+		openAIProbes = append(openAIProbes, apiBase+"|"+modelID+"|"+apiKey)
+		mu.Unlock()
+		return apiBase == "http://127.0.0.1:8000/v1" && modelID == "custom-model" && apiKey == ""
+	}
+	probeOllamaModelFunc = func(apiBase, modelID string) bool {
+		mu.Lock()
+		ollamaProbes = append(ollamaProbes, apiBase+"|"+modelID)
+		mu.Unlock()
+		return apiBase == "http://localhost:11434/v1" && modelID == "llama3"
+	}
+	probeTCPServiceFunc = func(apiBase string) bool {
+		mu.Lock()
+		tcpProbes = append(tcpProbes, apiBase)
+		mu.Unlock()
+		return apiBase == "http://127.0.0.1:4321"
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []*config.ModelConfig{
+		{
+			ModelName:  "openai-oauth",
+			Model:      "openai/gpt-5.4",
+			AuthMethod: "oauth",
+		},
+		{
+			ModelName: "vllm-local",
+			Model:     "vllm/custom-model",
+			APIBase:   "http://127.0.0.1:8000/v1",
+		},
+		{
+			ModelName: "ollama-default",
+			Model:     "ollama/llama3",
+		},
+		{
+			ModelName: "vllm-remote",
+			Model:     "vllm/custom-model",
+			APIBase:   "https://models.example.com/v1",
+		},
+		{
+			ModelName:  "copilot-gpt-5.4",
+			Model:      "github-copilot/gpt-5.4",
+			APIBase:    "http://127.0.0.1:4321",
+			AuthMethod: "oauth",
+		},
+	}
+	cfg.WithSecurity(&config.SecurityConfig{ModelList: map[string]config.ModelSecurityEntry{
+		"vllm-remote": {
+			APIKeys: []string{"remote-key"},
+		},
+	}})
+	cfg.Agents.Defaults.ModelName = "openai-oauth"
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/models", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var resp struct {
+		Models []modelResponse `json:"models"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+
+	got := make(map[string]bool, len(resp.Models))
+	for _, model := range resp.Models {
+		got[model.ModelName] = model.Configured
+	}
+
+	if got["openai-oauth"] {
+		t.Fatalf("openai oauth model configured = true, want false without stored credential")
+	}
+	if !got["vllm-local"] {
+		t.Fatalf("vllm local model configured = false, want true when local probe succeeds")
+	}
+	if !got["ollama-default"] {
+		t.Fatalf("ollama default model configured = false, want true when default local probe succeeds")
+	}
+	if !got["vllm-remote"] {
+		t.Fatalf("remote vllm model configured = false, want true with api_key")
+	}
+	if !got["copilot-gpt-5.4"] {
+		t.Fatalf("copilot model configured = false, want true when local bridge probe succeeds")
+	}
+	if len(openAIProbes) != 1 || openAIProbes[0] != "http://127.0.0.1:8000/v1|custom-model|" {
+		t.Fatalf("openAI probes = %#v, want only local vllm probe", openAIProbes)
+	}
+	if len(ollamaProbes) != 1 || ollamaProbes[0] != "http://localhost:11434/v1|llama3" {
+		t.Fatalf("ollama probes = %#v, want default local probe", ollamaProbes)
+	}
+	if len(tcpProbes) != 1 || tcpProbes[0] != "http://127.0.0.1:4321" {
+		t.Fatalf("tcp probes = %#v, want only local copilot probe", tcpProbes)
+	}
+}
+
+func TestHandleListModels_ConfiguredStatusForOAuthModelWithCredential(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+	resetModelProbeHooks(t)
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []*config.ModelConfig{{
+		ModelName:  "claude-oauth",
+		Model:      "anthropic/claude-sonnet-4.6",
+		AuthMethod: "oauth",
+	}}
+	cfg.Agents.Defaults.ModelName = "claude-oauth"
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	if err := auth.SetCredential(oauthProviderAnthropic, &auth.AuthCredential{
+		AccessToken: "anthropic-token",
+		Provider:    oauthProviderAnthropic,
+		AuthMethod:  "oauth",
+	}); err != nil {
+		t.Fatalf("SetCredential() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/models", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var resp struct {
+		Models []modelResponse `json:"models"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if len(resp.Models) != 1 {
+		t.Fatalf("len(models) = %d, want 1", len(resp.Models))
+	}
+	if !resp.Models[0].Configured {
+		t.Fatalf("oauth model configured = false, want true with stored credential")
+	}
+}
+
+func TestHandleListModels_ProbesLocalModelsConcurrently(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+	resetModelProbeHooks(t)
+
+	started := make(chan string, 2)
+	release := make(chan struct{})
+
+	probeOpenAICompatibleModelFunc = func(apiBase, modelID, apiKey string) bool {
+		started <- apiBase + "|" + modelID
+		<-release
+		return true
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []*config.ModelConfig{
+		{
+			ModelName: "local-vllm-a",
+			Model:     "vllm/custom-a",
+			APIBase:   "http://127.0.0.1:8000/v1",
+		},
+		{
+			ModelName: "local-vllm-b",
+			Model:     "vllm/custom-b",
+			APIBase:   "http://127.0.0.1:8001/v1",
+		},
+	}
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	recCh := make(chan *httptest.ResponseRecorder, 1)
+	go func() {
+		rec := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, "/api/models", nil)
+		mux.ServeHTTP(rec, req)
+		recCh <- rec
+	}()
+
+	for i := 0; i < 2; i++ {
+		select {
+		case <-started:
+		case <-time.After(200 * time.Millisecond):
+			t.Fatal("expected both local probes to start before the first one completed")
+		}
+	}
+	close(release)
+
+	rec := <-recCh
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+}
+
+func TestHandleListModels_NormalizesWildcardLocalAPIBaseForProbe(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+	resetModelProbeHooks(t)
+
+	var gotProbe string
+	probeOpenAICompatibleModelFunc = func(apiBase, modelID, apiKey string) bool {
+		gotProbe = apiBase + "|" + modelID + "|" + apiKey
+		return apiBase == "http://127.0.0.1:8000/v1" && modelID == "custom-model" && apiKey == ""
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []*config.ModelConfig{{
+		ModelName: "vllm-local",
+		Model:     "vllm/custom-model",
+		APIBase:   "http://0.0.0.0:8000/v1",
+	}}
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/models", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var resp struct {
+		Models []modelResponse `json:"models"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if len(resp.Models) != 1 {
+		t.Fatalf("len(models) = %d, want 1", len(resp.Models))
+	}
+	if !resp.Models[0].Configured {
+		t.Fatal("wildcard-bound local model configured = false, want true after probe host normalization")
+	}
+	if gotProbe != "http://127.0.0.1:8000/v1|custom-model|" {
+		t.Fatalf("probe api base = %q, want %q", gotProbe, "http://127.0.0.1:8000/v1|custom-model|")
+	}
+}
+
+func TestHandleAddModel_PersistsAPIKey(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/models", bytes.NewBufferString(`{
+		"model_name":"new-model",
+		"model":"openai/gpt-4o-mini",
+		"api_key":"sk-new-model-key"
+	}`))
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	if len(cfg.ModelList) != 2 {
+		t.Fatalf("len(model_list) = %d, want 2", len(cfg.ModelList))
+	}
+
+	added := cfg.ModelList[1]
+	if added.ModelName != "new-model" {
+		t.Fatalf("model_name = %q, want %q", added.ModelName, "new-model")
+	}
+	if added.APIKey() != "sk-new-model-key" {
+		t.Fatalf("api_key = %q, want %q", added.APIKey(), "sk-new-model-key")
+	}
+}
+
+// TestHandleSetDefaultModel_RejectsNonexistentModel tests that setting a non-existent
+// model as default returns 404. This covers the case where virtual models (which are
+// filtered by SaveConfig) cannot be set as default.
+func TestHandleSetDefaultModel_RejectsNonexistentModel(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	// First save a valid config with a primary model
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.ModelList = []*config.ModelConfig{
+		{ModelName: "gpt-4", Model: "openai/gpt-4o"},
+	}
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	// Try to set a non-existent model (like a virtual model name) as default
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/models/default", bytes.NewBufferString(`{
+		"model_name": "gpt-4__key_1"
+	}`))
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	// Should return 404 because the virtual model doesn't exist in the persisted config
+	if rec.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusNotFound, rec.Body.String())
+	}
+	if !strings.Contains(rec.Body.String(), "not found") {
+		t.Fatalf("error message should mention 'not found', got: %s", rec.Body.String())
+	}
+}
+
+func TestMaskAPIKey(t *testing.T) {
+	tests := []struct {
+		name string
+		key  string
+		want string
+	}{
+		{
+			name: "empty key",
+			key:  "",
+			want: "",
+		},
+		{
+			name: "short key fully masked",
+			key:  "abcd",
+			want: "****",
+		},
+		{
+			name: "length 8 boundary fully masked",
+			key:  "12345678",
+			want: "****",
+		},
+		{
+			name: "length 9 boundary shows last 2",
+			key:  "123456789",
+			want: "123****89",
+		},
+		{
+			name: "length 12 boundary shows last 2",
+			key:  "abcdefghijkl",
+			want: "abc****kl",
+		},
+		{
+			name: "length 13 boundary shows last 4",
+			key:  "abcdefghijklm",
+			want: "abc****jklm",
+		},
+		{
+			name: "typical api key",
+			key:  "sk-1234567890abcd",
+			want: "sk-****abcd",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := maskAPIKey(tc.key)
+			if got != tc.want {
+				t.Fatalf("maskAPIKey(%q) = %q, want %q", tc.key, got, tc.want)
+			}
+
+			if tc.key != "" {
+				displayed := strings.Replace(tc.want, "****", "", 1)
+				if len(tc.key) <= 8 {
+					if displayed != "" {
+						t.Fatalf("maskAPIKey(%q) displayed part = %q, want empty", tc.key, displayed)
+					}
+				} else {
+					if len(displayed)*10 > len(tc.key)*6 {
+						t.Fatalf(
+							"maskAPIKey(%q) displayed length = %d, want at most 60%% of %d",
+							tc.key,
+							len(displayed),
+							len(tc.key),
+						)
+					}
+				}
+			}
+		})
+	}
+}
diff --git a/web/backend/api/oauth.go b/web/backend/api/oauth.go
new file mode 100644
index 000000000..213b53836
--- /dev/null
+++ b/web/backend/api/oauth.go
@@ -0,0 +1,833 @@
+package api
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"html"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+const (
+	oauthProviderOpenAI            = "openai"
+	oauthProviderAnthropic         = "anthropic"
+	oauthProviderGoogleAntigravity = "google-antigravity"
+
+	oauthMethodBrowser    = "browser"
+	oauthMethodDeviceCode = "device_code"
+	oauthMethodToken      = "token"
+
+	oauthFlowPending = "pending"
+	oauthFlowSuccess = "success"
+	oauthFlowError   = "error"
+	oauthFlowExpired = "expired"
+)
+
+const (
+	oauthBrowserFlowTTL    = 10 * time.Minute
+	oauthDeviceCodeFlowTTL = 15 * time.Minute
+	oauthTerminalFlowGC    = 30 * time.Minute
+)
+
+var oauthProviderOrder = []string{
+	oauthProviderOpenAI,
+	oauthProviderAnthropic,
+	oauthProviderGoogleAntigravity,
+}
+
+var oauthProviderMethods = map[string][]string{
+	oauthProviderOpenAI:            {oauthMethodBrowser, oauthMethodDeviceCode, oauthMethodToken},
+	oauthProviderAnthropic:         {oauthMethodToken},
+	oauthProviderGoogleAntigravity: {oauthMethodBrowser},
+}
+
+var oauthProviderLabels = map[string]string{
+	oauthProviderOpenAI:            "OpenAI",
+	oauthProviderAnthropic:         "Anthropic",
+	oauthProviderGoogleAntigravity: "Google Antigravity",
+}
+
+var (
+	oauthNow                      = time.Now
+	oauthGeneratePKCE             = auth.GeneratePKCE
+	oauthGenerateState            = auth.GenerateState
+	oauthBuildAuthorizeURL        = auth.BuildAuthorizeURL
+	oauthRequestDeviceCode        = auth.RequestDeviceCode
+	oauthPollDeviceCodeOnce       = auth.PollDeviceCodeOnce
+	oauthExchangeCodeForTokens    = auth.ExchangeCodeForTokens
+	oauthGetCredential            = auth.GetCredential
+	oauthSetCredential            = auth.SetCredential
+	oauthDeleteCredential         = auth.DeleteCredential
+	oauthLoadConfig               = config.LoadConfig
+	oauthSaveConfig               = config.SaveConfig
+	oauthFetchAntigravityProject  = providers.FetchAntigravityProjectID
+	oauthFetchGoogleUserEmailFunc = fetchGoogleUserEmail
+)
+
+type oauthFlow struct {
+	ID           string
+	Provider     string
+	Method       string
+	Status       string
+	CreatedAt    time.Time
+	UpdatedAt    time.Time
+	ExpiresAt    time.Time
+	Error        string
+	CodeVerifier string
+	OAuthState   string
+	RedirectURI  string
+	DeviceAuthID string
+	UserCode     string
+	VerifyURL    string
+	Interval     int
+}
+
+type oauthProviderStatus struct {
+	Provider    string   `json:"provider"`
+	DisplayName string   `json:"display_name"`
+	Methods     []string `json:"methods"`
+	LoggedIn    bool     `json:"logged_in"`
+	Status      string   `json:"status"`
+	AuthMethod  string   `json:"auth_method,omitempty"`
+	ExpiresAt   string   `json:"expires_at,omitempty"`
+	AccountID   string   `json:"account_id,omitempty"`
+	Email       string   `json:"email,omitempty"`
+	ProjectID   string   `json:"project_id,omitempty"`
+}
+
+type oauthFlowResponse struct {
+	FlowID    string `json:"flow_id"`
+	Provider  string `json:"provider"`
+	Method    string `json:"method"`
+	Status    string `json:"status"`
+	ExpiresAt string `json:"expires_at,omitempty"`
+	Error     string `json:"error,omitempty"`
+	UserCode  string `json:"user_code,omitempty"`
+	VerifyURL string `json:"verify_url,omitempty"`
+	Interval  int    `json:"interval,omitempty"`
+}
+
+// registerOAuthRoutes binds OAuth login/logout endpoints to the ServeMux.
+func (h *Handler) registerOAuthRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/oauth/providers", h.handleListOAuthProviders)
+	mux.HandleFunc("POST /api/oauth/login", h.handleOAuthLogin)
+	mux.HandleFunc("GET /api/oauth/flows/{id}", h.handleGetOAuthFlow)
+	mux.HandleFunc("POST /api/oauth/flows/{id}/poll", h.handlePollOAuthFlow)
+	mux.HandleFunc("POST /api/oauth/logout", h.handleOAuthLogout)
+	mux.HandleFunc("GET /oauth/callback", h.handleOAuthCallback)
+}
+
+func (h *Handler) handleListOAuthProviders(w http.ResponseWriter, r *http.Request) {
+	providersResp := make([]oauthProviderStatus, 0, len(oauthProviderOrder))
+
+	for _, provider := range oauthProviderOrder {
+		cred, err := oauthGetCredential(provider)
+		if err != nil {
+			http.Error(w, fmt.Sprintf("failed to load credentials: %v", err), http.StatusInternalServerError)
+			return
+		}
+
+		item := oauthProviderStatus{
+			Provider:    provider,
+			DisplayName: oauthProviderLabels[provider],
+			Methods:     oauthProviderMethods[provider],
+			Status:      "not_logged_in",
+		}
+		if cred != nil {
+			item.LoggedIn = true
+			item.AuthMethod = cred.AuthMethod
+			item.AccountID = cred.AccountID
+			item.Email = cred.Email
+			item.ProjectID = cred.ProjectID
+			if !cred.ExpiresAt.IsZero() {
+				item.ExpiresAt = cred.ExpiresAt.Format(time.RFC3339)
+			}
+			switch {
+			case cred.IsExpired():
+				item.Status = "expired"
+			case cred.NeedsRefresh():
+				item.Status = "needs_refresh"
+			default:
+				item.Status = "connected"
+			}
+		}
+
+		providersResp = append(providersResp, item)
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(map[string]any{
+		"providers": providersResp,
+	})
+}
+
+func (h *Handler) handleOAuthLogin(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	var req struct {
+		Provider string `json:"provider"`
+		Method   string `json:"method"`
+		Token    string `json:"token"`
+	}
+	if err = json.Unmarshal(body, &req); err != nil {
+		http.Error(w, fmt.Sprintf("invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	provider, err := normalizeOAuthProvider(req.Provider)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	method := strings.ToLower(strings.TrimSpace(req.Method))
+	if !isOAuthMethodSupported(provider, method) {
+		http.Error(
+			w,
+			fmt.Sprintf("unsupported login method %q for provider %q", method, provider),
+			http.StatusBadRequest,
+		)
+		return
+	}
+
+	switch method {
+	case oauthMethodToken:
+		token := strings.TrimSpace(req.Token)
+		if token == "" {
+			http.Error(w, "token is required", http.StatusBadRequest)
+			return
+		}
+
+		cred := &auth.AuthCredential{
+			AccessToken: token,
+			Provider:    provider,
+			AuthMethod:  oauthMethodToken,
+		}
+		if err := h.persistCredentialAndConfig(provider, oauthMethodToken, cred); err != nil {
+			http.Error(w, fmt.Sprintf("token login failed: %v", err), http.StatusInternalServerError)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"status":   "ok",
+			"provider": provider,
+			"method":   method,
+		})
+		return
+
+	case oauthMethodDeviceCode:
+		cfg := auth.OpenAIOAuthConfig()
+		info, err := oauthRequestDeviceCode(cfg)
+		if err != nil {
+			http.Error(w, fmt.Sprintf("failed to request device code: %v", err), http.StatusInternalServerError)
+			return
+		}
+
+		now := oauthNow()
+		flow := &oauthFlow{
+			ID:           newOAuthFlowID(),
+			Provider:     provider,
+			Method:       method,
+			Status:       oauthFlowPending,
+			CreatedAt:    now,
+			UpdatedAt:    now,
+			ExpiresAt:    now.Add(oauthDeviceCodeFlowTTL),
+			DeviceAuthID: info.DeviceAuthID,
+			UserCode:     info.UserCode,
+			VerifyURL:    info.VerifyURL,
+			Interval:     info.Interval,
+		}
+		h.storeOAuthFlow(flow)
+
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"status":     "ok",
+			"provider":   provider,
+			"method":     method,
+			"flow_id":    flow.ID,
+			"user_code":  flow.UserCode,
+			"verify_url": flow.VerifyURL,
+			"interval":   flow.Interval,
+			"expires_at": flow.ExpiresAt.Format(time.RFC3339),
+		})
+		return
+
+	case oauthMethodBrowser:
+		cfg, err := oauthConfigForProvider(provider)
+		if err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+
+		pkce, err := oauthGeneratePKCE()
+		if err != nil {
+			http.Error(w, fmt.Sprintf("failed to generate PKCE: %v", err), http.StatusInternalServerError)
+			return
+		}
+		state, err := oauthGenerateState()
+		if err != nil {
+			http.Error(w, fmt.Sprintf("failed to generate state: %v", err), http.StatusInternalServerError)
+			return
+		}
+
+		redirectURI := buildOAuthRedirectURI(r)
+		authURL := oauthBuildAuthorizeURL(cfg, pkce, state, redirectURI)
+
+		now := oauthNow()
+		flow := &oauthFlow{
+			ID:           newOAuthFlowID(),
+			Provider:     provider,
+			Method:       method,
+			Status:       oauthFlowPending,
+			CreatedAt:    now,
+			UpdatedAt:    now,
+			ExpiresAt:    now.Add(oauthBrowserFlowTTL),
+			CodeVerifier: pkce.CodeVerifier,
+			OAuthState:   state,
+			RedirectURI:  redirectURI,
+		}
+		h.storeOAuthFlow(flow)
+
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"status":     "ok",
+			"provider":   provider,
+			"method":     method,
+			"flow_id":    flow.ID,
+			"auth_url":   authURL,
+			"expires_at": flow.ExpiresAt.Format(time.RFC3339),
+		})
+		return
+	default:
+		http.Error(w, "unsupported login method", http.StatusBadRequest)
+	}
+}
+
+func (h *Handler) handleGetOAuthFlow(w http.ResponseWriter, r *http.Request) {
+	flowID := strings.TrimSpace(r.PathValue("id"))
+	if flowID == "" {
+		http.Error(w, "missing flow id", http.StatusBadRequest)
+		return
+	}
+
+	flow, ok := h.getOAuthFlow(flowID)
+	if !ok {
+		http.Error(w, "flow not found", http.StatusNotFound)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(flowToResponse(flow))
+}
+
+func (h *Handler) handlePollOAuthFlow(w http.ResponseWriter, r *http.Request) {
+	flowID := strings.TrimSpace(r.PathValue("id"))
+	if flowID == "" {
+		http.Error(w, "missing flow id", http.StatusBadRequest)
+		return
+	}
+
+	flow, ok := h.getOAuthFlow(flowID)
+	if !ok {
+		http.Error(w, "flow not found", http.StatusNotFound)
+		return
+	}
+
+	if flow.Method != oauthMethodDeviceCode {
+		http.Error(w, "flow does not support polling", http.StatusBadRequest)
+		return
+	}
+	if flow.Status != oauthFlowPending {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(flowToResponse(flow))
+		return
+	}
+
+	cfg := auth.OpenAIOAuthConfig()
+	cred, err := oauthPollDeviceCodeOnce(cfg, flow.DeviceAuthID, flow.UserCode)
+	if err != nil {
+		if strings.Contains(strings.ToLower(err.Error()), "pending") {
+			updated, _ := h.getOAuthFlow(flowID)
+			w.Header().Set("Content-Type", "application/json")
+			_ = json.NewEncoder(w).Encode(flowToResponse(updated))
+			return
+		}
+		h.setOAuthFlowError(flowID, fmt.Sprintf("device code poll failed: %v", err))
+		updated, _ := h.getOAuthFlow(flowID)
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(flowToResponse(updated))
+		return
+	}
+	if cred == nil {
+		updated, _ := h.getOAuthFlow(flowID)
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(flowToResponse(updated))
+		return
+	}
+
+	if err := h.persistCredentialAndConfig(flow.Provider, oauthMethodTokenOrOAuth(flow.Method), cred); err != nil {
+		h.setOAuthFlowError(flowID, fmt.Sprintf("failed to save credential: %v", err))
+		updated, _ := h.getOAuthFlow(flowID)
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(flowToResponse(updated))
+		return
+	}
+
+	h.setOAuthFlowSuccess(flowID)
+	updated, _ := h.getOAuthFlow(flowID)
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(flowToResponse(updated))
+}
+
+func (h *Handler) handleOAuthCallback(w http.ResponseWriter, r *http.Request) {
+	state := strings.TrimSpace(r.URL.Query().Get("state"))
+	if state == "" {
+		renderOAuthCallbackPage(w, "", oauthFlowError, "Missing state", "missing_state")
+		return
+	}
+
+	flow, ok := h.getOAuthFlowByState(state)
+	if !ok {
+		renderOAuthCallbackPage(w, "", oauthFlowError, "OAuth flow not found", "flow_not_found")
+		return
+	}
+
+	if flow.Status != oauthFlowPending {
+		renderOAuthCallbackPage(w, flow.ID, flow.Status, "Flow already completed", flow.Error)
+		return
+	}
+
+	if errMsg := strings.TrimSpace(r.URL.Query().Get("error")); errMsg != "" {
+		if desc := strings.TrimSpace(r.URL.Query().Get("error_description")); desc != "" {
+			errMsg += ": " + desc
+		}
+		h.setOAuthFlowError(flow.ID, errMsg)
+		renderOAuthCallbackPage(w, flow.ID, oauthFlowError, "Authorization failed", errMsg)
+		return
+	}
+
+	code := strings.TrimSpace(r.URL.Query().Get("code"))
+	if code == "" {
+		h.setOAuthFlowError(flow.ID, "missing authorization code")
+		renderOAuthCallbackPage(w, flow.ID, oauthFlowError, "Missing authorization code", "missing_code")
+		return
+	}
+
+	cfg, err := oauthConfigForProvider(flow.Provider)
+	if err != nil {
+		h.setOAuthFlowError(flow.ID, err.Error())
+		renderOAuthCallbackPage(w, flow.ID, oauthFlowError, "Unsupported provider", err.Error())
+		return
+	}
+
+	cred, err := oauthExchangeCodeForTokens(cfg, code, flow.CodeVerifier, flow.RedirectURI)
+	if err != nil {
+		h.setOAuthFlowError(flow.ID, fmt.Sprintf("token exchange failed: %v", err))
+		renderOAuthCallbackPage(w, flow.ID, oauthFlowError, "Token exchange failed", err.Error())
+		return
+	}
+
+	if err := h.persistCredentialAndConfig(flow.Provider, oauthMethodTokenOrOAuth(flow.Method), cred); err != nil {
+		h.setOAuthFlowError(flow.ID, fmt.Sprintf("failed to save credential: %v", err))
+		renderOAuthCallbackPage(w, flow.ID, oauthFlowError, "Failed to save credential", err.Error())
+		return
+	}
+
+	h.setOAuthFlowSuccess(flow.ID)
+	renderOAuthCallbackPage(w, flow.ID, oauthFlowSuccess, "Authentication successful", "")
+}
+
+func (h *Handler) handleOAuthLogout(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
+	if err != nil {
+		http.Error(w, "failed to read request body", http.StatusBadRequest)
+		return
+	}
+	defer r.Body.Close()
+
+	var req struct {
+		Provider string `json:"provider"`
+	}
+	if err = json.Unmarshal(body, &req); err != nil {
+		http.Error(w, fmt.Sprintf("invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	provider, err := normalizeOAuthProvider(req.Provider)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	if err := oauthDeleteCredential(provider); err != nil {
+		http.Error(w, fmt.Sprintf("failed to delete credential: %v", err), http.StatusInternalServerError)
+		return
+	}
+	if err := h.syncProviderAuthMethod(provider, ""); err != nil {
+		http.Error(w, fmt.Sprintf("failed to update config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(map[string]any{
+		"status":   "ok",
+		"provider": provider,
+	})
+}
+
+func renderOAuthCallbackPage(w http.ResponseWriter, flowID, status, title, errMsg string) {
+	payload := map[string]string{
+		"type":   "picoclaw-oauth-result",
+		"flowId": flowID,
+		"status": status,
+	}
+	if errMsg != "" {
+		payload["error"] = errMsg
+	}
+	payloadJSON, _ := json.Marshal(payload)
+
+	message := title
+	if errMsg != "" {
+		message = fmt.Sprintf("%s: %s", title, errMsg)
+	}
+
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	if status == oauthFlowSuccess {
+		w.WriteHeader(http.StatusOK)
+	} else {
+		w.WriteHeader(http.StatusBadRequest)
+	}
+
+	_, _ = fmt.Fprintf(
+		w,
+		"<!doctype html><html><head><meta charset=\"utf-8\"><title>PicoClaw OAuth</title></head><body><script>(function(){var payload=%s;var hasOpener=false;try{if(window.opener&&!window.opener.closed){window.opener.postMessage(payload,window.location.origin);hasOpener=true}}catch(e){}var target='/credentials?oauth_flow_id='+encodeURIComponent(payload.flowId||'')+'&oauth_status='+encodeURIComponent(payload.status||'');setTimeout(function(){if(hasOpener){window.close();return}window.location.replace(target)},800)})();</script><div style=\"font-family:Inter,system-ui,sans-serif;padding:24px\"><h2>%s</h2><p>%s</p><p>You can close this window.</p></div></body></html>",
+		string(payloadJSON),
+		html.EscapeString(title),
+		html.EscapeString(message),
+	)
+}
+
+func normalizeOAuthProvider(raw string) (string, error) {
+	provider := strings.ToLower(strings.TrimSpace(raw))
+	switch provider {
+	case "antigravity":
+		return oauthProviderGoogleAntigravity, nil
+	case oauthProviderOpenAI, oauthProviderAnthropic, oauthProviderGoogleAntigravity:
+		return provider, nil
+	default:
+		return "", fmt.Errorf("unsupported provider %q", raw)
+	}
+}
+
+func isOAuthMethodSupported(provider, method string) bool {
+	methods := oauthProviderMethods[provider]
+	for _, m := range methods {
+		if m == method {
+			return true
+		}
+	}
+	return false
+}
+
+func oauthConfigForProvider(provider string) (auth.OAuthProviderConfig, error) {
+	switch provider {
+	case oauthProviderOpenAI:
+		return auth.OpenAIOAuthConfig(), nil
+	case oauthProviderGoogleAntigravity:
+		return auth.GoogleAntigravityOAuthConfig(), nil
+	default:
+		return auth.OAuthProviderConfig{}, fmt.Errorf("provider %q does not support browser oauth", provider)
+	}
+}
+
+func oauthMethodTokenOrOAuth(method string) string {
+	if method == oauthMethodToken {
+		return oauthMethodToken
+	}
+	return "oauth"
+}
+
+func buildOAuthRedirectURI(r *http.Request) string {
+	scheme := "http"
+	if r.TLS != nil {
+		scheme = "https"
+	}
+	if forwarded := strings.TrimSpace(r.Header.Get("X-Forwarded-Proto")); forwarded != "" {
+		scheme = strings.Split(forwarded, ",")[0]
+	}
+	return fmt.Sprintf("%s://%s/oauth/callback", scheme, r.Host)
+}
+
+func flowToResponse(flow *oauthFlow) oauthFlowResponse {
+	resp := oauthFlowResponse{
+		FlowID:   flow.ID,
+		Provider: flow.Provider,
+		Method:   flow.Method,
+		Status:   flow.Status,
+		Error:    flow.Error,
+	}
+	if !flow.ExpiresAt.IsZero() {
+		resp.ExpiresAt = flow.ExpiresAt.Format(time.RFC3339)
+	}
+	if flow.Method == oauthMethodDeviceCode {
+		resp.UserCode = flow.UserCode
+		resp.VerifyURL = flow.VerifyURL
+		resp.Interval = flow.Interval
+	}
+	return resp
+}
+
+func newOAuthFlowID() string {
+	buf := make([]byte, 16)
+	if _, err := rand.Read(buf); err != nil {
+		return fmt.Sprintf("oauth_%d", time.Now().UnixNano())
+	}
+	return hex.EncodeToString(buf)
+}
+
+func (h *Handler) storeOAuthFlow(flow *oauthFlow) {
+	now := oauthNow()
+	h.oauthMu.Lock()
+	defer h.oauthMu.Unlock()
+
+	h.gcOAuthFlowsLocked(now)
+	h.oauthFlows[flow.ID] = flow
+	if flow.OAuthState != "" {
+		h.oauthState[flow.OAuthState] = flow.ID
+	}
+}
+
+func (h *Handler) getOAuthFlow(flowID string) (*oauthFlow, bool) {
+	now := oauthNow()
+	h.oauthMu.Lock()
+	defer h.oauthMu.Unlock()
+
+	h.gcOAuthFlowsLocked(now)
+	flow, ok := h.oauthFlows[flowID]
+	if !ok {
+		return nil, false
+	}
+	cp := *flow
+	return &cp, true
+}
+
+func (h *Handler) getOAuthFlowByState(state string) (*oauthFlow, bool) {
+	now := oauthNow()
+	h.oauthMu.Lock()
+	defer h.oauthMu.Unlock()
+
+	h.gcOAuthFlowsLocked(now)
+	flowID, ok := h.oauthState[state]
+	if !ok {
+		return nil, false
+	}
+	flow, ok := h.oauthFlows[flowID]
+	if !ok {
+		delete(h.oauthState, state)
+		return nil, false
+	}
+	cp := *flow
+	return &cp, true
+}
+
+func (h *Handler) setOAuthFlowSuccess(flowID string) {
+	now := oauthNow()
+	h.oauthMu.Lock()
+	defer h.oauthMu.Unlock()
+
+	flow, ok := h.oauthFlows[flowID]
+	if !ok {
+		return
+	}
+	flow.Status = oauthFlowSuccess
+	flow.Error = ""
+	flow.UpdatedAt = now
+	if flow.OAuthState != "" {
+		delete(h.oauthState, flow.OAuthState)
+	}
+}
+
+func (h *Handler) setOAuthFlowError(flowID, errMsg string) {
+	now := oauthNow()
+	h.oauthMu.Lock()
+	defer h.oauthMu.Unlock()
+
+	flow, ok := h.oauthFlows[flowID]
+	if !ok {
+		return
+	}
+	flow.Status = oauthFlowError
+	flow.Error = errMsg
+	flow.UpdatedAt = now
+	if flow.OAuthState != "" {
+		delete(h.oauthState, flow.OAuthState)
+	}
+}
+
+func (h *Handler) gcOAuthFlowsLocked(now time.Time) {
+	for id, flow := range h.oauthFlows {
+		if flow.Status == oauthFlowPending && !flow.ExpiresAt.IsZero() && now.After(flow.ExpiresAt) {
+			flow.Status = oauthFlowExpired
+			flow.Error = "flow expired"
+			flow.UpdatedAt = now
+			if flow.OAuthState != "" {
+				delete(h.oauthState, flow.OAuthState)
+			}
+		}
+
+		if flow.Status != oauthFlowPending && now.Sub(flow.UpdatedAt) > oauthTerminalFlowGC {
+			if flow.OAuthState != "" {
+				delete(h.oauthState, flow.OAuthState)
+			}
+			delete(h.oauthFlows, id)
+		}
+	}
+}
+
+func (h *Handler) persistCredentialAndConfig(provider, authMethod string, cred *auth.AuthCredential) error {
+	if cred == nil {
+		return fmt.Errorf("empty credential")
+	}
+
+	cp := *cred
+	cp.Provider = provider
+	if cp.AuthMethod == "" {
+		cp.AuthMethod = authMethod
+	}
+
+	if provider == oauthProviderGoogleAntigravity {
+		if cp.Email == "" {
+			email, err := oauthFetchGoogleUserEmailFunc(cp.AccessToken)
+			if err != nil {
+				logger.ErrorC("oauth", fmt.Sprintf("oauth warning: could not fetch google email: %v", err))
+			} else {
+				cp.Email = email
+			}
+		}
+		if cp.ProjectID == "" {
+			projectID, err := oauthFetchAntigravityProject(cp.AccessToken)
+			if err != nil {
+				logger.ErrorC("oauth", fmt.Sprintf("oauth warning: could not fetch antigravity project id: %v", err))
+			} else {
+				cp.ProjectID = projectID
+			}
+		}
+	}
+
+	if err := oauthSetCredential(provider, &cp); err != nil {
+		return fmt.Errorf("saving credential: %w", err)
+	}
+	if err := h.syncProviderAuthMethod(provider, authMethod); err != nil {
+		return fmt.Errorf("syncing provider auth config: %w", err)
+	}
+	return nil
+}
+
+func (h *Handler) syncProviderAuthMethod(provider, authMethod string) error {
+	cfg, err := oauthLoadConfig(h.configPath)
+	if err != nil {
+		return err
+	}
+
+	found := false
+	for i := range cfg.ModelList {
+		if modelBelongsToProvider(provider, cfg.ModelList[i].Model) {
+			cfg.ModelList[i].AuthMethod = authMethod
+			found = true
+		}
+	}
+
+	if !found && authMethod != "" {
+		cfg.ModelList = append(cfg.ModelList, defaultModelConfigForProvider(provider, authMethod))
+	}
+
+	return oauthSaveConfig(h.configPath, cfg)
+}
+
+func modelBelongsToProvider(provider, model string) bool {
+	lower := strings.ToLower(strings.TrimSpace(model))
+	switch provider {
+	case oauthProviderOpenAI:
+		return lower == "openai" || strings.HasPrefix(lower, "openai/")
+	case oauthProviderAnthropic:
+		return lower == "anthropic" || strings.HasPrefix(lower, "anthropic/")
+	case oauthProviderGoogleAntigravity:
+		return lower == "antigravity" ||
+			lower == "google-antigravity" ||
+			strings.HasPrefix(lower, "antigravity/") ||
+			strings.HasPrefix(lower, "google-antigravity/")
+	default:
+		return false
+	}
+}
+
+func defaultModelConfigForProvider(provider, authMethod string) *config.ModelConfig {
+	switch provider {
+	case oauthProviderOpenAI:
+		return &config.ModelConfig{
+			ModelName:  "gpt-5.4",
+			Model:      "openai/gpt-5.4",
+			AuthMethod: authMethod,
+		}
+	case oauthProviderAnthropic:
+		return &config.ModelConfig{
+			ModelName:  "claude-sonnet-4.6",
+			Model:      "anthropic/claude-sonnet-4.6",
+			AuthMethod: authMethod,
+		}
+	case oauthProviderGoogleAntigravity:
+		return &config.ModelConfig{
+			ModelName:  "gemini-flash",
+			Model:      "antigravity/gemini-3-flash",
+			AuthMethod: authMethod,
+		}
+	default:
+		return &config.ModelConfig{}
+	}
+}
+
+func fetchGoogleUserEmail(accessToken string) (string, error) {
+	req, err := http.NewRequest(http.MethodGet, "https://www.googleapis.com/oauth2/v2/userinfo", nil)
+	if err != nil {
+		return "", err
+	}
+	req.Header.Set("Authorization", "Bearer "+accessToken)
+
+	client := &http.Client{Timeout: 10 * time.Second}
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", err
+	}
+	defer resp.Body.Close()
+
+	body, _ := io.ReadAll(resp.Body)
+	if resp.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("userinfo request failed: %s", string(body))
+	}
+
+	var userInfo struct {
+		Email string `json:"email"`
+	}
+	if err := json.Unmarshal(body, &userInfo); err != nil {
+		return "", err
+	}
+	if userInfo.Email == "" {
+		return "", fmt.Errorf("empty email in userinfo response")
+	}
+	return userInfo.Email, nil
+}
diff --git a/web/backend/api/oauth_test.go b/web/backend/api/oauth_test.go
new file mode 100644
index 000000000..7cab79b52
--- /dev/null
+++ b/web/backend/api/oauth_test.go
@@ -0,0 +1,295 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/auth"
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestOAuthLoginRejectsUnsupportedMethod(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(
+		http.MethodPost,
+		"/api/oauth/login",
+		strings.NewReader(`{"provider":"anthropic","method":"browser"}`),
+	)
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusBadRequest, rec.Body.String())
+	}
+}
+
+func TestOAuthBrowserFlowCreatedAndQueried(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+
+	oauthGeneratePKCE = func() (auth.PKCECodes, error) {
+		return auth.PKCECodes{CodeVerifier: "verifier-1", CodeChallenge: "challenge-1"}, nil
+	}
+	oauthGenerateState = func() (string, error) { return "state-1", nil }
+	oauthBuildAuthorizeURL = func(cfg auth.OAuthProviderConfig, pkce auth.PKCECodes, state, redirectURI string) string {
+		return "https://example.com/authorize?state=" + state
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(
+		http.MethodPost,
+		"/api/oauth/login",
+		strings.NewReader(`{"provider":"openai","method":"browser"}`),
+	)
+	req.Host = "localhost:18800"
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var loginResp map[string]any
+	if err := json.Unmarshal(rec.Body.Bytes(), &loginResp); err != nil {
+		t.Fatalf("unmarshal login response: %v", err)
+	}
+	flowID, _ := loginResp["flow_id"].(string)
+	if flowID == "" {
+		t.Fatalf("flow_id is empty: %v", loginResp)
+	}
+	if loginResp["auth_url"] != "https://example.com/authorize?state=state-1" {
+		t.Fatalf("unexpected auth_url: %v", loginResp["auth_url"])
+	}
+
+	rec2 := httptest.NewRecorder()
+	req2 := httptest.NewRequest(http.MethodGet, "/api/oauth/flows/"+flowID, nil)
+	mux.ServeHTTP(rec2, req2)
+	if rec2.Code != http.StatusOK {
+		t.Fatalf("flow status code = %d, want %d, body=%s", rec2.Code, http.StatusOK, rec2.Body.String())
+	}
+	var flowResp oauthFlowResponse
+	if err := json.Unmarshal(rec2.Body.Bytes(), &flowResp); err != nil {
+		t.Fatalf("unmarshal flow response: %v", err)
+	}
+	if flowResp.Status != oauthFlowPending {
+		t.Fatalf("flow status = %q, want %q", flowResp.Status, oauthFlowPending)
+	}
+	if flowResp.Method != oauthMethodBrowser {
+		t.Fatalf("flow method = %q, want %q", flowResp.Method, oauthMethodBrowser)
+	}
+}
+
+func TestOAuthFlowExpiresWhenQueried(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+
+	now := time.Date(2026, 3, 6, 12, 0, 0, 0, time.UTC)
+	oauthNow = func() time.Time { return now }
+
+	h := NewHandler(configPath)
+	h.storeOAuthFlow(&oauthFlow{
+		ID:        "expired-flow",
+		Provider:  oauthProviderOpenAI,
+		Method:    oauthMethodBrowser,
+		Status:    oauthFlowPending,
+		CreatedAt: now.Add(-20 * time.Minute),
+		UpdatedAt: now.Add(-20 * time.Minute),
+		ExpiresAt: now.Add(-1 * time.Minute),
+	})
+
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/oauth/flows/expired-flow", nil)
+	mux.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+	var flowResp oauthFlowResponse
+	if err := json.Unmarshal(rec.Body.Bytes(), &flowResp); err != nil {
+		t.Fatalf("unmarshal flow response: %v", err)
+	}
+	if flowResp.Status != oauthFlowExpired {
+		t.Fatalf("flow status = %q, want %q", flowResp.Status, oauthFlowExpired)
+	}
+}
+
+func TestOAuthCallbackUnknownState(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/oauth/callback?state=unknown&code=abc", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusBadRequest {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusBadRequest)
+	}
+	if !strings.Contains(rec.Body.String(), "OAuth flow not found") {
+		t.Fatalf("unexpected body: %s", rec.Body.String())
+	}
+}
+
+func TestOAuthLogoutClearsCredentialAndConfig(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+	resetOAuthHooks(t)
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig error: %v", err)
+	}
+	cfg.ModelList = append(cfg.ModelList, &config.ModelConfig{
+		ModelName:  "gpt-5.4",
+		Model:      "openai/gpt-5.4",
+		AuthMethod: "oauth",
+	})
+	if err = config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig error: %v", err)
+	}
+	if err = auth.SetCredential(oauthProviderOpenAI, &auth.AuthCredential{
+		AccessToken: "token-before-logout",
+		Provider:    oauthProviderOpenAI,
+		AuthMethod:  "oauth",
+	}); err != nil {
+		t.Fatalf("SetCredential error: %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/oauth/logout", bytes.NewBufferString(`{"provider":"openai"}`))
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	cred, err := auth.GetCredential(oauthProviderOpenAI)
+	if err != nil {
+		t.Fatalf("GetCredential error: %v", err)
+	}
+	if cred != nil {
+		t.Fatalf("expected credential deleted, got %#v", cred)
+	}
+
+	updated, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig error: %v", err)
+	}
+	for _, m := range updated.ModelList {
+		if strings.HasPrefix(m.Model, "openai/") && m.AuthMethod != "" {
+			t.Fatalf("openai model auth_method = %q, want empty", m.AuthMethod)
+		}
+	}
+}
+
+func setupOAuthTestEnv(t *testing.T) (string, func()) {
+	t.Helper()
+
+	tmp := t.TempDir()
+	oldHome := os.Getenv("HOME")
+	oldPicoHome := os.Getenv("PICOCLAW_HOME")
+
+	if err := os.Setenv("HOME", tmp); err != nil {
+		t.Fatalf("set HOME: %v", err)
+	}
+	if err := os.Setenv("PICOCLAW_HOME", filepath.Join(tmp, ".picoclaw")); err != nil {
+		t.Fatalf("set PICOCLAW_HOME: %v", err)
+	}
+
+	cfg := config.DefaultConfig()
+	cfg.ModelList = []*config.ModelConfig{{
+		ModelName: "custom-default",
+		Model:     "openai/gpt-4o",
+	}}
+	cfg.Agents.Defaults.ModelName = "custom-default"
+	cfg.WithSecurity(&config.SecurityConfig{
+		ModelList: map[string]config.ModelSecurityEntry{
+			"custom-default": {
+				APIKeys: []string{"sk-default"},
+			},
+		},
+	})
+
+	configPath := filepath.Join(tmp, "config.json")
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig error: %v", err)
+	}
+
+	cleanup := func() {
+		_ = os.Setenv("HOME", oldHome)
+		if oldPicoHome == "" {
+			_ = os.Unsetenv("PICOCLAW_HOME")
+		} else {
+			_ = os.Setenv("PICOCLAW_HOME", oldPicoHome)
+		}
+	}
+	return configPath, cleanup
+}
+
+func resetOAuthHooks(t *testing.T) {
+	t.Helper()
+
+	origNow := oauthNow
+	origGeneratePKCE := oauthGeneratePKCE
+	origGenerateState := oauthGenerateState
+	origBuildAuthorizeURL := oauthBuildAuthorizeURL
+	origRequestDeviceCode := oauthRequestDeviceCode
+	origPollDeviceCodeOnce := oauthPollDeviceCodeOnce
+	origExchangeCodeForTokens := oauthExchangeCodeForTokens
+	origGetCredential := oauthGetCredential
+	origSetCredential := oauthSetCredential
+	origDeleteCredential := oauthDeleteCredential
+	origLoadConfig := oauthLoadConfig
+	origSaveConfig := oauthSaveConfig
+	origFetchProject := oauthFetchAntigravityProject
+	origFetchGoogleEmail := oauthFetchGoogleUserEmailFunc
+
+	t.Cleanup(func() {
+		oauthNow = origNow
+		oauthGeneratePKCE = origGeneratePKCE
+		oauthGenerateState = origGenerateState
+		oauthBuildAuthorizeURL = origBuildAuthorizeURL
+		oauthRequestDeviceCode = origRequestDeviceCode
+		oauthPollDeviceCodeOnce = origPollDeviceCodeOnce
+		oauthExchangeCodeForTokens = origExchangeCodeForTokens
+		oauthGetCredential = origGetCredential
+		oauthSetCredential = origSetCredential
+		oauthDeleteCredential = origDeleteCredential
+		oauthLoadConfig = origLoadConfig
+		oauthSaveConfig = origSaveConfig
+		oauthFetchAntigravityProject = origFetchProject
+		oauthFetchGoogleUserEmailFunc = origFetchGoogleEmail
+	})
+}
diff --git a/web/backend/api/pico.go b/web/backend/api/pico.go
new file mode 100644
index 000000000..4faafc2ae
--- /dev/null
+++ b/web/backend/api/pico.go
@@ -0,0 +1,168 @@
+package api
+
+import (
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httputil"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// registerPicoRoutes binds Pico Channel management endpoints to the ServeMux.
+func (h *Handler) registerPicoRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/pico/token", h.handleGetPicoToken)
+	mux.HandleFunc("POST /api/pico/token", h.handleRegenPicoToken)
+	mux.HandleFunc("POST /api/pico/setup", h.handlePicoSetup)
+
+	// WebSocket proxy: forward /pico/ws to gateway
+	// This allows the frontend to connect via the same port as the web UI,
+	// avoiding the need to expose extra ports for WebSocket communication.
+	mux.HandleFunc("GET /pico/ws", h.handleWebSocketProxy())
+}
+
+// createWsProxy creates a reverse proxy to the current gateway WebSocket endpoint.
+// The gateway bind host and port are resolved from the latest configuration.
+func (h *Handler) createWsProxy() *httputil.ReverseProxy {
+	wsProxy := httputil.NewSingleHostReverseProxy(h.gatewayProxyURL())
+	wsProxy.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
+		http.Error(w, "Gateway unavailable: "+err.Error(), http.StatusBadGateway)
+	}
+	return wsProxy
+}
+
+// handleWebSocketProxy wraps a reverse proxy to handle WebSocket connections.
+// The reverse proxy forwards the incoming upgrade handshake as-is.
+func (h *Handler) handleWebSocketProxy() http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		proxy := h.createWsProxy()
+		proxy.ServeHTTP(w, r)
+	}
+}
+
+// handleGetPicoToken returns the current WS token and URL for the frontend.
+//
+//	GET /api/pico/token
+func (h *Handler) handleGetPicoToken(w http.ResponseWriter, r *http.Request) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	wsURL := h.buildWsURL(r, cfg)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"token":   cfg.Channels.Pico.Token(),
+		"ws_url":  wsURL,
+		"enabled": cfg.Channels.Pico.Enabled,
+	})
+}
+
+// handleRegenPicoToken generates a new Pico WebSocket token and saves it.
+//
+//	POST /api/pico/token
+func (h *Handler) handleRegenPicoToken(w http.ResponseWriter, r *http.Request) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	token := generateSecureToken()
+	cfg.Channels.Pico.SetToken(token)
+
+	if err := config.SaveConfig(h.configPath, cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	wsURL := h.buildWsURL(r, cfg)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"token":  token,
+		"ws_url": wsURL,
+	})
+}
+
+// EnsurePicoChannel enables the Pico channel with sane defaults if it isn't
+// already configured. Returns true when the config was modified.
+//
+// callerOrigin is the Origin header from the setup request. If non-empty and
+// no origins are configured yet, it's written as the allowed origin so the
+// WebSocket handshake works for whatever host the caller is on (LAN, custom
+// port, etc.). Pass "" when there's no request context.
+func (h *Handler) EnsurePicoChannel(callerOrigin string) (bool, error) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		return false, fmt.Errorf("failed to load config: %w", err)
+	}
+
+	changed := false
+
+	if !cfg.Channels.Pico.Enabled {
+		cfg.Channels.Pico.Enabled = true
+		changed = true
+	}
+
+	if cfg.Channels.Pico.Token() == "" {
+		cfg.Channels.Pico.SetToken(generateSecureToken())
+		changed = true
+	}
+
+	// Seed origins from the request instead of hardcoding ports.
+	if len(cfg.Channels.Pico.AllowOrigins) == 0 && callerOrigin != "" {
+		cfg.Channels.Pico.AllowOrigins = []string{callerOrigin}
+		changed = true
+	}
+
+	if changed {
+		if err := config.SaveConfig(h.configPath, cfg); err != nil {
+			return false, fmt.Errorf("failed to save config: %w", err)
+		}
+	}
+
+	return changed, nil
+}
+
+// handlePicoSetup automatically configures everything needed for the Pico Channel to work.
+//
+//	POST /api/pico/setup
+func (h *Handler) handlePicoSetup(w http.ResponseWriter, r *http.Request) {
+	changed, err := h.EnsurePicoChannel(r.Header.Get("Origin"))
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusInternalServerError)
+		return
+	}
+
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	wsURL := h.buildWsURL(r, cfg)
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"token":   cfg.Channels.Pico.Token(),
+		"ws_url":  wsURL,
+		"enabled": true,
+		"changed": changed,
+	})
+}
+
+// generateSecureToken creates a random 32-character hex string.
+func generateSecureToken() string {
+	b := make([]byte, 16)
+	if _, err := rand.Read(b); err != nil {
+		// Fallback to something pseudo-random if crypto/rand fails
+		return fmt.Sprintf("pico_%x", time.Now().UnixNano())
+	}
+	return hex.EncodeToString(b)
+}
diff --git a/web/backend/api/pico_test.go b/web/backend/api/pico_test.go
new file mode 100644
index 000000000..051e356cf
--- /dev/null
+++ b/web/backend/api/pico_test.go
@@ -0,0 +1,380 @@
+package api
+
+import (
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestEnsurePicoChannel_FreshConfig(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	changed, err := h.EnsurePicoChannel("")
+	if err != nil {
+		t.Fatalf("EnsurePicoChannel() error = %v", err)
+	}
+	if !changed {
+		t.Fatal("EnsurePicoChannel() should report changed on a fresh config")
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	if !cfg.Channels.Pico.Enabled {
+		t.Error("expected Pico to be enabled after setup")
+	}
+	if cfg.Channels.Pico.Token() == "" {
+		t.Error("expected a non-empty token after setup")
+	}
+}
+
+func TestEnsurePicoChannel_DoesNotEnableTokenQuery(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	if _, err := h.EnsurePicoChannel(""); err != nil {
+		t.Fatalf("EnsurePicoChannel() error = %v", err)
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	if cfg.Channels.Pico.AllowTokenQuery {
+		t.Error("setup must not enable allow_token_query by default")
+	}
+}
+
+func TestEnsurePicoChannel_DoesNotSetWildcardOrigins(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	if _, err := h.EnsurePicoChannel("http://localhost:18800"); err != nil {
+		t.Fatalf("EnsurePicoChannel() error = %v", err)
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	for _, origin := range cfg.Channels.Pico.AllowOrigins {
+		if origin == "*" {
+			t.Error("setup must not set wildcard origin '*'")
+		}
+	}
+}
+
+func TestEnsurePicoChannel_NoOriginWithoutCaller(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	if _, err := h.EnsurePicoChannel(""); err != nil {
+		t.Fatalf("EnsurePicoChannel() error = %v", err)
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	// Without a caller origin, allow_origins stays empty (CheckOrigin
+	// allows all when the list is empty, so the channel still works).
+	if len(cfg.Channels.Pico.AllowOrigins) != 0 {
+		t.Errorf("allow_origins = %v, want empty when no caller origin", cfg.Channels.Pico.AllowOrigins)
+	}
+}
+
+func TestEnsurePicoChannel_SetsCallerOrigin(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	lanOrigin := "http://192.168.1.9:18800"
+	if _, err := h.EnsurePicoChannel(lanOrigin); err != nil {
+		t.Fatalf("EnsurePicoChannel() error = %v", err)
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	if len(cfg.Channels.Pico.AllowOrigins) != 1 || cfg.Channels.Pico.AllowOrigins[0] != lanOrigin {
+		t.Errorf("allow_origins = %v, want [%s]", cfg.Channels.Pico.AllowOrigins, lanOrigin)
+	}
+}
+
+func TestEnsurePicoChannel_PreservesUserSettings(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+
+	// Pre-configure with custom user settings
+	cfg := config.DefaultConfig()
+	cfg.Channels.Pico.Enabled = true
+	cfg.Channels.Pico.SetToken("user-custom-token")
+	cfg.Channels.Pico.AllowTokenQuery = true
+	cfg.Channels.Pico.AllowOrigins = []string{"https://myapp.example.com"}
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+
+	changed, err := h.EnsurePicoChannel("")
+	if err != nil {
+		t.Fatalf("EnsurePicoChannel() error = %v", err)
+	}
+	if changed {
+		t.Error("EnsurePicoChannel() should not change a fully configured config")
+	}
+
+	cfg, err = config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	if cfg.Channels.Pico.Token() != "user-custom-token" {
+		t.Errorf("token = %q, want %q", cfg.Channels.Pico.Token(), "user-custom-token")
+	}
+	if !cfg.Channels.Pico.AllowTokenQuery {
+		t.Error("user's allow_token_query=true must be preserved")
+	}
+	if len(cfg.Channels.Pico.AllowOrigins) != 1 || cfg.Channels.Pico.AllowOrigins[0] != "https://myapp.example.com" {
+		t.Errorf("allow_origins = %v, want [https://myapp.example.com]", cfg.Channels.Pico.AllowOrigins)
+	}
+}
+
+func TestEnsurePicoChannel_ExistingConfigWithoutSecurityFile(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+
+	cfg := config.DefaultConfig()
+	raw, err := json.Marshal(cfg)
+	if err != nil {
+		t.Fatalf("Marshal() error = %v", err)
+	}
+	if err = os.WriteFile(configPath, raw, 0o600); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+
+	changed, err := h.EnsurePicoChannel("")
+	if err != nil {
+		t.Fatalf("EnsurePicoChannel() error = %v", err)
+	}
+	if !changed {
+		t.Fatal("EnsurePicoChannel() should report changed when pico is missing")
+	}
+
+	cfg, err = config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	if !cfg.Channels.Pico.Enabled {
+		t.Error("expected Pico to be enabled after setup")
+	}
+	if cfg.Channels.Pico.Token() == "" {
+		t.Error("expected a non-empty token after setup")
+	}
+	if _, err := os.Stat(filepath.Join(filepath.Dir(configPath), config.SecurityConfigFile)); err != nil {
+		t.Fatalf("expected .security.yml to be created: %v", err)
+	}
+}
+
+func TestEnsurePicoChannel_ConfiguresPicoWithoutGateway(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+
+	cfg := config.DefaultConfig()
+	cfg.Agents.Defaults.ModelName = ""
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	if _, err := h.EnsurePicoChannel(""); err != nil {
+		t.Fatalf("EnsurePicoChannel() error = %v", err)
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	if !cfg.Channels.Pico.Enabled {
+		t.Error("expected Pico to be enabled after launcher startup setup")
+	}
+	if cfg.Channels.Pico.Token() == "" {
+		t.Error("expected a non-empty token after launcher startup setup")
+	}
+}
+
+func TestEnsurePicoChannel_Idempotent(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	origin := "http://localhost:18800"
+
+	// First call sets things up
+	if _, err := h.EnsurePicoChannel(origin); err != nil {
+		t.Fatalf("first EnsurePicoChannel() error = %v", err)
+	}
+
+	cfg1, _ := config.LoadConfig(configPath)
+	token1 := cfg1.Channels.Pico.Token()
+
+	// Second call should be a no-op
+	changed, err := h.EnsurePicoChannel(origin)
+	if err != nil {
+		t.Fatalf("second EnsurePicoChannel() error = %v", err)
+	}
+	if changed {
+		t.Error("second EnsurePicoChannel() should not report changed")
+	}
+
+	cfg2, _ := config.LoadConfig(configPath)
+	if cfg2.Channels.Pico.Token() != token1 {
+		t.Error("token should not change on subsequent calls")
+	}
+}
+
+func TestHandlePicoSetup_IncludesRequestOrigin(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	req := httptest.NewRequest("POST", "/api/pico/setup", nil)
+	req.Header.Set("Origin", "http://10.0.0.5:3000")
+	rec := httptest.NewRecorder()
+
+	h.handlePicoSetup(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	if len(cfg.Channels.Pico.AllowOrigins) != 1 || cfg.Channels.Pico.AllowOrigins[0] != "http://10.0.0.5:3000" {
+		t.Errorf("allow_origins = %v, want [http://10.0.0.5:3000]", cfg.Channels.Pico.AllowOrigins)
+	}
+}
+
+func TestHandlePicoSetup_Response(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	req := httptest.NewRequest("POST", "/api/pico/setup", nil)
+	rec := httptest.NewRecorder()
+
+	h.handlePicoSetup(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+
+	var resp map[string]any
+	if err := json.NewDecoder(rec.Body).Decode(&resp); err != nil {
+		t.Fatalf("failed to decode response: %v", err)
+	}
+
+	if resp["token"] == nil || resp["token"] == "" {
+		t.Error("response should contain a non-empty token")
+	}
+	if resp["ws_url"] == nil || resp["ws_url"] == "" {
+		t.Error("response should contain ws_url")
+	}
+	if resp["enabled"] != true {
+		t.Error("response should have enabled=true")
+	}
+	if resp["changed"] != true {
+		t.Error("response should have changed=true on first setup")
+	}
+}
+
+func TestHandleWebSocketProxyReloadsGatewayTargetFromConfig(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+	handler := h.handleWebSocketProxy()
+
+	server1 := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/pico/ws" {
+			t.Fatalf("server1 path = %q, want %q", r.URL.Path, "/pico/ws")
+		}
+		w.WriteHeader(http.StatusOK)
+		_, _ = io.WriteString(w, "server1")
+	}))
+	defer server1.Close()
+
+	server2 := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/pico/ws" {
+			t.Fatalf("server2 path = %q, want %q", r.URL.Path, "/pico/ws")
+		}
+		w.WriteHeader(http.StatusOK)
+		_, _ = io.WriteString(w, "server2")
+	}))
+	defer server2.Close()
+
+	cfg := config.DefaultConfig()
+	cfg.Gateway.Host = "127.0.0.1"
+	cfg.Gateway.Port = mustGatewayTestPort(t, server1.URL)
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	req1 := httptest.NewRequest(http.MethodGet, "/pico/ws", nil)
+	rec1 := httptest.NewRecorder()
+	handler(rec1, req1)
+
+	if rec1.Code != http.StatusOK {
+		t.Fatalf("first status = %d, want %d", rec1.Code, http.StatusOK)
+	}
+	if body := rec1.Body.String(); body != "server1" {
+		t.Fatalf("first body = %q, want %q", body, "server1")
+	}
+
+	cfg.Gateway.Port = mustGatewayTestPort(t, server2.URL)
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	req2 := httptest.NewRequest(http.MethodGet, "/pico/ws", nil)
+	rec2 := httptest.NewRecorder()
+	handler(rec2, req2)
+
+	if rec2.Code != http.StatusOK {
+		t.Fatalf("second status = %d, want %d", rec2.Code, http.StatusOK)
+	}
+	if body := rec2.Body.String(); body != "server2" {
+		t.Fatalf("second body = %q, want %q", body, "server2")
+	}
+}
+
+func mustGatewayTestPort(t *testing.T, rawURL string) int {
+	t.Helper()
+
+	parsed, err := url.Parse(rawURL)
+	if err != nil {
+		t.Fatalf("url.Parse() error = %v", err)
+	}
+
+	port, err := strconv.Atoi(parsed.Port())
+	if err != nil {
+		t.Fatalf("Atoi(%q) error = %v", parsed.Port(), err)
+	}
+
+	return port
+}
diff --git a/web/backend/api/router.go b/web/backend/api/router.go
new file mode 100644
index 000000000..d09f68eac
--- /dev/null
+++ b/web/backend/api/router.go
@@ -0,0 +1,83 @@
+package api
+
+import (
+	"net/http"
+	"sync"
+
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+)
+
+// Handler serves HTTP API requests.
+type Handler struct {
+	configPath           string
+	serverPort           int
+	serverPublic         bool
+	serverPublicExplicit bool
+	serverCIDRs          []string
+	oauthMu              sync.Mutex
+	oauthFlows           map[string]*oauthFlow
+	oauthState           map[string]string
+	weixinMu             sync.Mutex
+	weixinFlows          map[string]*weixinFlow
+}
+
+// NewHandler creates an instance of the API handler.
+func NewHandler(configPath string) *Handler {
+	return &Handler{
+		configPath:  configPath,
+		serverPort:  launcherconfig.DefaultPort,
+		oauthFlows:  make(map[string]*oauthFlow),
+		oauthState:  make(map[string]string),
+		weixinFlows: make(map[string]*weixinFlow),
+	}
+}
+
+// SetServerOptions stores current backend listen options for fallback behavior.
+func (h *Handler) SetServerOptions(port int, public bool, publicExplicit bool, allowedCIDRs []string) {
+	h.serverPort = port
+	h.serverPublic = public
+	h.serverPublicExplicit = publicExplicit
+	h.serverCIDRs = append([]string(nil), allowedCIDRs...)
+}
+
+// RegisterRoutes binds all API endpoint handlers to the ServeMux.
+func (h *Handler) RegisterRoutes(mux *http.ServeMux) {
+	// Config CRUD
+	h.registerConfigRoutes(mux)
+
+	// Pico Channel (WebSocket chat)
+	h.registerPicoRoutes(mux)
+
+	// Gateway process lifecycle
+	h.registerGatewayRoutes(mux)
+
+	// Session history
+	h.registerSessionRoutes(mux)
+
+	// OAuth login and credential management
+	h.registerOAuthRoutes(mux)
+
+	// Model list management
+	h.registerModelRoutes(mux)
+
+	// Channel catalog (for frontend navigation/config pages)
+	h.registerChannelRoutes(mux)
+
+	// Skills and tools support/actions
+	h.registerSkillRoutes(mux)
+	h.registerToolRoutes(mux)
+
+	// OS startup / launch-at-login
+	h.registerStartupRoutes(mux)
+
+	// Launcher service parameters (port/public)
+	h.registerLauncherConfigRoutes(mux)
+
+	// WeChat QR login flow
+	h.registerWeixinRoutes(mux)
+}
+
+// Shutdown gracefully shuts down the handler, stopping the gateway if it was started by this handler.
+func (h *Handler) Shutdown() {
+	h.StopGateway()
+}
diff --git a/web/backend/api/session.go b/web/backend/api/session.go
new file mode 100644
index 000000000..42d451a05
--- /dev/null
+++ b/web/backend/api/session.go
@@ -0,0 +1,506 @@
+package api
+
+import (
+	"bufio"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"os"
+	"path/filepath"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/providers"
+)
+
+// registerSessionRoutes binds session list and detail endpoints to the ServeMux.
+func (h *Handler) registerSessionRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/sessions", h.handleListSessions)
+	mux.HandleFunc("GET /api/sessions/{id}", h.handleGetSession)
+	mux.HandleFunc("DELETE /api/sessions/{id}", h.handleDeleteSession)
+}
+
+// sessionFile mirrors the on-disk session JSON structure from pkg/session.
+type sessionFile struct {
+	Key      string              `json:"key"`
+	Messages []providers.Message `json:"messages"`
+	Summary  string              `json:"summary,omitempty"`
+	Created  time.Time           `json:"created"`
+	Updated  time.Time           `json:"updated"`
+}
+
+// sessionListItem is a lightweight summary returned by GET /api/sessions.
+type sessionListItem struct {
+	ID           string `json:"id"`
+	Title        string `json:"title"`
+	Preview      string `json:"preview"`
+	MessageCount int    `json:"message_count"`
+	Created      string `json:"created"`
+	Updated      string `json:"updated"`
+}
+
+type sessionMetaFile struct {
+	Key       string    `json:"key"`
+	Summary   string    `json:"summary"`
+	Skip      int       `json:"skip"`
+	Count     int       `json:"count"`
+	CreatedAt time.Time `json:"created_at"`
+	UpdatedAt time.Time `json:"updated_at"`
+}
+
+// picoSessionPrefix is the key prefix used by the gateway's routing for Pico
+// channel sessions. The full key format is:
+//
+//	agent:main:pico:direct:pico:<session-uuid>
+//
+// The sanitized filename replaces ':' with '_', so on disk it becomes:
+//
+//	agent_main_pico_direct_pico_<session-uuid>.json
+const (
+	picoSessionPrefix          = "agent:main:pico:direct:pico:"
+	sanitizedPicoSessionPrefix = "agent_main_pico_direct_pico_"
+	maxSessionJSONLLineSize    = 10 * 1024 * 1024 // 10 MB
+	maxSessionTitleRunes       = 60
+)
+
+// extractPicoSessionID extracts the session UUID from a full session key.
+// Returns the UUID and true if the key matches the Pico session pattern.
+func extractPicoSessionID(key string) (string, bool) {
+	if strings.HasPrefix(key, picoSessionPrefix) {
+		return strings.TrimPrefix(key, picoSessionPrefix), true
+	}
+	return "", false
+}
+
+func extractPicoSessionIDFromSanitizedKey(key string) (string, bool) {
+	if strings.HasPrefix(key, sanitizedPicoSessionPrefix) {
+		return strings.TrimPrefix(key, sanitizedPicoSessionPrefix), true
+	}
+	return "", false
+}
+
+func sanitizeSessionKey(key string) string {
+	return strings.ReplaceAll(key, ":", "_")
+}
+
+func (h *Handler) readLegacySession(dir, sessionID string) (sessionFile, error) {
+	path := filepath.Join(dir, sanitizeSessionKey(picoSessionPrefix+sessionID)+".json")
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return sessionFile{}, err
+	}
+
+	var sess sessionFile
+	if err := json.Unmarshal(data, &sess); err != nil {
+		return sessionFile{}, err
+	}
+	return sess, nil
+}
+
+func (h *Handler) readSessionMeta(path, sessionKey string) (sessionMetaFile, error) {
+	data, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return sessionMetaFile{Key: sessionKey}, nil
+	}
+	if err != nil {
+		return sessionMetaFile{}, err
+	}
+
+	var meta sessionMetaFile
+	if err := json.Unmarshal(data, &meta); err != nil {
+		return sessionMetaFile{}, err
+	}
+	if meta.Key == "" {
+		meta.Key = sessionKey
+	}
+	return meta, nil
+}
+
+func (h *Handler) readSessionMessages(path string, skip int) ([]providers.Message, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+
+	msgs := make([]providers.Message, 0)
+	scanner := bufio.NewScanner(f)
+	scanner.Buffer(make([]byte, 0, 64*1024), maxSessionJSONLLineSize)
+
+	seen := 0
+	for scanner.Scan() {
+		line := scanner.Bytes()
+		if len(line) == 0 {
+			continue
+		}
+
+		seen++
+		if seen <= skip {
+			continue
+		}
+
+		var msg providers.Message
+		if err := json.Unmarshal(line, &msg); err != nil {
+			continue
+		}
+		msgs = append(msgs, msg)
+	}
+	if err := scanner.Err(); err != nil {
+		return nil, err
+	}
+	return msgs, nil
+}
+
+func (h *Handler) readJSONLSession(dir, sessionID string) (sessionFile, error) {
+	sessionKey := picoSessionPrefix + sessionID
+	base := filepath.Join(dir, sanitizeSessionKey(sessionKey))
+	jsonlPath := base + ".jsonl"
+	metaPath := base + ".meta.json"
+
+	meta, err := h.readSessionMeta(metaPath, sessionKey)
+	if err != nil {
+		return sessionFile{}, err
+	}
+
+	messages, err := h.readSessionMessages(jsonlPath, meta.Skip)
+	if err != nil {
+		return sessionFile{}, err
+	}
+
+	updated := meta.UpdatedAt
+	created := meta.CreatedAt
+	if created.IsZero() || updated.IsZero() {
+		if info, statErr := os.Stat(jsonlPath); statErr == nil {
+			if created.IsZero() {
+				created = info.ModTime()
+			}
+			if updated.IsZero() {
+				updated = info.ModTime()
+			}
+		}
+	}
+
+	return sessionFile{
+		Key:      meta.Key,
+		Messages: messages,
+		Summary:  meta.Summary,
+		Created:  created,
+		Updated:  updated,
+	}, nil
+}
+
+func buildSessionListItem(sessionID string, sess sessionFile) sessionListItem {
+	preview := ""
+	for _, msg := range sess.Messages {
+		if msg.Role == "user" && strings.TrimSpace(msg.Content) != "" {
+			preview = msg.Content
+			break
+		}
+	}
+	title := strings.TrimSpace(sess.Summary)
+	if title == "" {
+		title = preview
+	}
+
+	title = truncateRunes(title, maxSessionTitleRunes)
+	preview = truncateRunes(preview, maxSessionTitleRunes)
+
+	if preview == "" {
+		preview = "(empty)"
+	}
+	if title == "" {
+		title = preview
+	}
+
+	validMessageCount := 0
+	for _, msg := range sess.Messages {
+		if (msg.Role == "user" || msg.Role == "assistant") && strings.TrimSpace(msg.Content) != "" {
+			validMessageCount++
+		}
+	}
+
+	return sessionListItem{
+		ID:           sessionID,
+		Title:        title,
+		Preview:      preview,
+		MessageCount: validMessageCount,
+		Created:      sess.Created.Format(time.RFC3339),
+		Updated:      sess.Updated.Format(time.RFC3339),
+	}
+}
+
+func isEmptySession(sess sessionFile) bool {
+	return len(sess.Messages) == 0 && strings.TrimSpace(sess.Summary) == ""
+}
+
+func truncateRunes(s string, maxLen int) string {
+	if maxLen <= 0 {
+		return ""
+	}
+	runes := []rune(strings.TrimSpace(s))
+	if len(runes) <= maxLen {
+		return string(runes)
+	}
+	return string(runes[:maxLen]) + "..."
+}
+
+// sessionsDir resolves the path to the gateway's session storage directory.
+// It reads the workspace from config, falling back to ~/.picoclaw/workspace.
+func (h *Handler) sessionsDir() (string, error) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		return "", err
+	}
+
+	workspace := cfg.Agents.Defaults.Workspace
+	if workspace == "" {
+		home, _ := os.UserHomeDir()
+		workspace = filepath.Join(home, ".picoclaw", "workspace")
+	}
+
+	// Expand ~ prefix
+	if len(workspace) > 0 && workspace[0] == '~' {
+		home, _ := os.UserHomeDir()
+		if len(workspace) > 1 && workspace[1] == '/' {
+			workspace = home + workspace[1:]
+		} else {
+			workspace = home
+		}
+	}
+
+	return filepath.Join(workspace, "sessions"), nil
+}
+
+// handleListSessions returns a list of Pico session summaries.
+//
+//	GET /api/sessions
+func (h *Handler) handleListSessions(w http.ResponseWriter, r *http.Request) {
+	dir, err := h.sessionsDir()
+	if err != nil {
+		http.Error(w, "failed to resolve sessions directory", http.StatusInternalServerError)
+		return
+	}
+
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		// Directory doesn't exist yet = no sessions
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode([]sessionListItem{})
+		return
+	}
+
+	items := []sessionListItem{}
+	seen := make(map[string]struct{})
+
+	for _, entry := range entries {
+		if entry.IsDir() {
+			continue
+		}
+
+		name := entry.Name()
+		var (
+			sessionID string
+			sess      sessionFile
+			loadErr   error
+			ok        bool
+		)
+
+		switch {
+		case strings.HasSuffix(name, ".jsonl"):
+			sessionID, ok = extractPicoSessionIDFromSanitizedKey(strings.TrimSuffix(name, ".jsonl"))
+			if !ok {
+				continue
+			}
+			sess, loadErr = h.readJSONLSession(dir, sessionID)
+			if loadErr == nil && isEmptySession(sess) {
+				continue
+			}
+		case strings.HasSuffix(name, ".meta.json"):
+			continue
+		case filepath.Ext(name) == ".json":
+			base := strings.TrimSuffix(name, ".json")
+			if _, statErr := os.Stat(filepath.Join(dir, base+".jsonl")); statErr == nil {
+				if jsonlSessionID, found := extractPicoSessionIDFromSanitizedKey(base); found {
+					if jsonlSess, jsonlErr := h.readJSONLSession(
+						dir,
+						jsonlSessionID,
+					); jsonlErr == nil &&
+						!isEmptySession(jsonlSess) {
+						continue
+					}
+				}
+			}
+			data, err := os.ReadFile(filepath.Join(dir, name))
+			if err != nil {
+				continue
+			}
+			if err := json.Unmarshal(data, &sess); err != nil {
+				continue
+			}
+			if isEmptySession(sess) {
+				continue
+			}
+			sessionID, ok = extractPicoSessionID(sess.Key)
+			if !ok {
+				continue
+			}
+			if _, exists := seen[sessionID]; exists {
+				continue
+			}
+		default:
+			continue
+		}
+
+		if loadErr != nil {
+			continue
+		}
+		if _, exists := seen[sessionID]; exists {
+			continue
+		}
+
+		seen[sessionID] = struct{}{}
+		items = append(items, buildSessionListItem(sessionID, sess))
+	}
+
+	// Sort by updated descending (most recent first)
+	sort.Slice(items, func(i, j int) bool {
+		return items[i].Updated > items[j].Updated
+	})
+
+	// Pagination parameters
+	offsetStr := r.URL.Query().Get("offset")
+	limitStr := r.URL.Query().Get("limit")
+
+	offset := 0
+	limit := 20 // Default limit
+
+	if val, err := strconv.Atoi(offsetStr); err == nil && val >= 0 {
+		offset = val
+	}
+	if val, err := strconv.Atoi(limitStr); err == nil && val > 0 {
+		limit = val
+	}
+
+	totalItems := len(items)
+
+	end := offset + limit
+	if offset >= totalItems {
+		items = []sessionListItem{} // Out of bounds, return empty
+	} else {
+		if end > totalItems {
+			end = totalItems
+		}
+		items = items[offset:end]
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(items)
+}
+
+// handleGetSession returns the full message history for a specific session.
+//
+//	GET /api/sessions/{id}
+func (h *Handler) handleGetSession(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	if sessionID == "" {
+		http.Error(w, "missing session id", http.StatusBadRequest)
+		return
+	}
+
+	dir, err := h.sessionsDir()
+	if err != nil {
+		http.Error(w, "failed to resolve sessions directory", http.StatusInternalServerError)
+		return
+	}
+
+	sess, err := h.readJSONLSession(dir, sessionID)
+	if err == nil && isEmptySession(sess) {
+		err = os.ErrNotExist
+	}
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			sess, err = h.readLegacySession(dir, sessionID)
+			if err == nil && isEmptySession(sess) {
+				err = os.ErrNotExist
+			}
+		}
+		if err != nil {
+			if errors.Is(err, os.ErrNotExist) {
+				http.Error(w, "session not found", http.StatusNotFound)
+			} else {
+				http.Error(w, "failed to parse session", http.StatusInternalServerError)
+			}
+			return
+		}
+	}
+
+	// Convert to a simpler format for the frontend
+	type chatMessage struct {
+		Role    string `json:"role"`
+		Content string `json:"content"`
+	}
+
+	messages := make([]chatMessage, 0, len(sess.Messages))
+	for _, msg := range sess.Messages {
+		// Only include user and assistant messages that have actual content
+		if (msg.Role == "user" || msg.Role == "assistant") && strings.TrimSpace(msg.Content) != "" {
+			messages = append(messages, chatMessage{
+				Role:    msg.Role,
+				Content: msg.Content,
+			})
+		}
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]any{
+		"id":       sessionID,
+		"messages": messages,
+		"summary":  sess.Summary,
+		"created":  sess.Created.Format(time.RFC3339),
+		"updated":  sess.Updated.Format(time.RFC3339),
+	})
+}
+
+// handleDeleteSession deletes a specific session.
+//
+//	DELETE /api/sessions/{id}
+func (h *Handler) handleDeleteSession(w http.ResponseWriter, r *http.Request) {
+	sessionID := r.PathValue("id")
+	if sessionID == "" {
+		http.Error(w, "missing session id", http.StatusBadRequest)
+		return
+	}
+
+	dir, err := h.sessionsDir()
+	if err != nil {
+		http.Error(w, "failed to resolve sessions directory", http.StatusInternalServerError)
+		return
+	}
+
+	base := filepath.Join(dir, sanitizeSessionKey(picoSessionPrefix+sessionID))
+	jsonlPath := base + ".jsonl"
+	metaPath := base + ".meta.json"
+	legacyPath := base + ".json"
+
+	removed := false
+	for _, path := range []string{jsonlPath, metaPath, legacyPath} {
+		if err := os.Remove(path); err != nil {
+			if os.IsNotExist(err) {
+				continue
+			}
+			http.Error(w, "failed to delete session", http.StatusInternalServerError)
+			return
+		}
+		removed = true
+	}
+
+	if !removed {
+		http.Error(w, "session not found", http.StatusNotFound)
+		return
+	}
+
+	w.WriteHeader(http.StatusNoContent)
+}
diff --git a/web/backend/api/session_test.go b/web/backend/api/session_test.go
new file mode 100644
index 000000000..21ef5b5b8
--- /dev/null
+++ b/web/backend/api/session_test.go
@@ -0,0 +1,322 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/memory"
+	"github.com/sipeed/picoclaw/pkg/providers"
+	"github.com/sipeed/picoclaw/pkg/session"
+)
+
+func sessionsTestDir(t *testing.T, configPath string) string {
+	t.Helper()
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	dir := filepath.Join(cfg.Agents.Defaults.Workspace, "sessions")
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatalf("MkdirAll() error = %v", err)
+	}
+	return dir
+}
+
+func TestHandleListSessions_JSONLStorage(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	dir := sessionsTestDir(t, configPath)
+	store, err := memory.NewJSONLStore(dir)
+	if err != nil {
+		t.Fatalf("NewJSONLStore() error = %v", err)
+	}
+
+	sessionKey := picoSessionPrefix + "history-jsonl"
+	if err := store.AddFullMessage(nil, sessionKey, providers.Message{
+		Role:    "user",
+		Content: "Explain why the history API is empty after migration.",
+	}); err != nil {
+		t.Fatalf("AddFullMessage(user) error = %v", err)
+	}
+	if err := store.AddFullMessage(nil, sessionKey, providers.Message{
+		Role:    "assistant",
+		Content: "Because the API still reads only legacy JSON session files.",
+	}); err != nil {
+		t.Fatalf("AddFullMessage(assistant) error = %v", err)
+	}
+	if err := store.AddFullMessage(nil, sessionKey, providers.Message{
+		Role:    "tool",
+		Content: "ignored",
+	}); err != nil {
+		t.Fatalf("AddFullMessage(tool) error = %v", err)
+	}
+	if err := store.SetSummary(nil, sessionKey, "JSONL-backed session"); err != nil {
+		t.Fatalf("SetSummary() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/sessions", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var items []sessionListItem
+	if err := json.Unmarshal(rec.Body.Bytes(), &items); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if len(items) != 1 {
+		t.Fatalf("len(items) = %d, want 1", len(items))
+	}
+	if items[0].ID != "history-jsonl" {
+		t.Fatalf("items[0].ID = %q, want %q", items[0].ID, "history-jsonl")
+	}
+	if items[0].MessageCount != 2 {
+		t.Fatalf("items[0].MessageCount = %d, want 2", items[0].MessageCount)
+	}
+	if items[0].Title != "JSONL-backed session" {
+		t.Fatalf("items[0].Title = %q, want %q", items[0].Title, "JSONL-backed session")
+	}
+	if items[0].Preview != "Explain why the history API is empty after migration." {
+		t.Fatalf("items[0].Preview = %q", items[0].Preview)
+	}
+}
+
+func TestHandleListSessions_TitleUsesTrimmedSummary(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	dir := sessionsTestDir(t, configPath)
+	store, err := memory.NewJSONLStore(dir)
+	if err != nil {
+		t.Fatalf("NewJSONLStore() error = %v", err)
+	}
+
+	sessionKey := picoSessionPrefix + "summary-title"
+	if err := store.AddFullMessage(nil, sessionKey, providers.Message{
+		Role:    "user",
+		Content: "fallback preview",
+	}); err != nil {
+		t.Fatalf("AddFullMessage() error = %v", err)
+	}
+	if err := store.SetSummary(
+		nil,
+		sessionKey,
+		"  This summary is intentionally longer than sixty characters so it must be truncated in the history menu.  ",
+	); err != nil {
+		t.Fatalf("SetSummary() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/sessions", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var items []sessionListItem
+	if err := json.Unmarshal(rec.Body.Bytes(), &items); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if len(items) != 1 {
+		t.Fatalf("len(items) = %d, want 1", len(items))
+	}
+	expectedTitle := truncateRunes(
+		"This summary is intentionally longer than sixty characters so it must be truncated in the history menu.",
+		maxSessionTitleRunes,
+	)
+	if items[0].Title != expectedTitle {
+		t.Fatalf("items[0].Title = %q", items[0].Title)
+	}
+	if items[0].Preview != "fallback preview" {
+		t.Fatalf("items[0].Preview = %q, want %q", items[0].Preview, "fallback preview")
+	}
+}
+
+func TestHandleGetSession_JSONLStorage(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	dir := sessionsTestDir(t, configPath)
+	store, err := memory.NewJSONLStore(dir)
+	if err != nil {
+		t.Fatalf("NewJSONLStore() error = %v", err)
+	}
+
+	sessionKey := picoSessionPrefix + "detail-jsonl"
+	for _, msg := range []providers.Message{
+		{Role: "user", Content: "first"},
+		{Role: "assistant", Content: "second"},
+		{Role: "tool", Content: "ignored"},
+	} {
+		if err := store.AddFullMessage(nil, sessionKey, msg); err != nil {
+			t.Fatalf("AddFullMessage() error = %v", err)
+		}
+	}
+	if err := store.SetSummary(nil, sessionKey, "detail summary"); err != nil {
+		t.Fatalf("SetSummary() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/sessions/detail-jsonl", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var resp struct {
+		ID       string `json:"id"`
+		Summary  string `json:"summary"`
+		Messages []struct {
+			Role    string `json:"role"`
+			Content string `json:"content"`
+		} `json:"messages"`
+	}
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if resp.ID != "detail-jsonl" {
+		t.Fatalf("resp.ID = %q, want %q", resp.ID, "detail-jsonl")
+	}
+	if resp.Summary != "detail summary" {
+		t.Fatalf("resp.Summary = %q, want %q", resp.Summary, "detail summary")
+	}
+	if len(resp.Messages) != 2 {
+		t.Fatalf("len(resp.Messages) = %d, want 2", len(resp.Messages))
+	}
+	if resp.Messages[0].Role != "user" || resp.Messages[0].Content != "first" {
+		t.Fatalf("first message = %#v, want user/first", resp.Messages[0])
+	}
+	if resp.Messages[1].Role != "assistant" || resp.Messages[1].Content != "second" {
+		t.Fatalf("second message = %#v, want assistant/second", resp.Messages[1])
+	}
+}
+
+func TestHandleDeleteSession_JSONLStorage(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	dir := sessionsTestDir(t, configPath)
+	store, err := memory.NewJSONLStore(dir)
+	if err != nil {
+		t.Fatalf("NewJSONLStore() error = %v", err)
+	}
+
+	sessionKey := picoSessionPrefix + "delete-jsonl"
+	if err := store.AddFullMessage(nil, sessionKey, providers.Message{
+		Role:    "user",
+		Content: "delete me",
+	}); err != nil {
+		t.Fatalf("AddFullMessage() error = %v", err)
+	}
+	if err := store.SetSummary(nil, sessionKey, "delete summary"); err != nil {
+		t.Fatalf("SetSummary() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodDelete, "/api/sessions/delete-jsonl", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusNoContent {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusNoContent, rec.Body.String())
+	}
+
+	base := filepath.Join(dir, sanitizeSessionKey(sessionKey))
+	for _, path := range []string{base + ".jsonl", base + ".meta.json"} {
+		if _, err := os.Stat(path); !os.IsNotExist(err) {
+			t.Fatalf("expected %s to be removed, stat err = %v", path, err)
+		}
+	}
+}
+
+func TestHandleGetSession_LegacyJSONFallback(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	dir := sessionsTestDir(t, configPath)
+	manager := session.NewSessionManager(dir)
+	sessionKey := picoSessionPrefix + "legacy-json"
+	manager.AddMessage(sessionKey, "user", "legacy user")
+	manager.AddMessage(sessionKey, "assistant", "legacy assistant")
+	if err := manager.Save(sessionKey); err != nil {
+		t.Fatalf("Save() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/sessions/legacy-json", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+}
+
+func TestHandleSessions_FiltersEmptyJSONLFiles(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	dir := sessionsTestDir(t, configPath)
+	base := filepath.Join(dir, sanitizeSessionKey(picoSessionPrefix+"empty-jsonl"))
+	if err := os.WriteFile(base+".jsonl", []byte{}, 0o644); err != nil {
+		t.Fatalf("WriteFile(jsonl) error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	listRec := httptest.NewRecorder()
+	listReq := httptest.NewRequest(http.MethodGet, "/api/sessions", nil)
+	mux.ServeHTTP(listRec, listReq)
+
+	if listRec.Code != http.StatusOK {
+		t.Fatalf("list status = %d, want %d, body=%s", listRec.Code, http.StatusOK, listRec.Body.String())
+	}
+
+	var items []sessionListItem
+	if err := json.Unmarshal(listRec.Body.Bytes(), &items); err != nil {
+		t.Fatalf("Unmarshal(list) error = %v", err)
+	}
+	if len(items) != 0 {
+		t.Fatalf("len(items) = %d, want 0", len(items))
+	}
+
+	detailRec := httptest.NewRecorder()
+	detailReq := httptest.NewRequest(http.MethodGet, "/api/sessions/empty-jsonl", nil)
+	mux.ServeHTTP(detailRec, detailReq)
+
+	if detailRec.Code != http.StatusNotFound {
+		t.Fatalf("detail status = %d, want %d, body=%s", detailRec.Code, http.StatusNotFound, detailRec.Body.String())
+	}
+}
diff --git a/web/backend/api/skills.go b/web/backend/api/skills.go
new file mode 100644
index 000000000..3c2fb57dd
--- /dev/null
+++ b/web/backend/api/skills.go
@@ -0,0 +1,331 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/skills"
+)
+
+type skillSupportResponse struct {
+	Skills []skills.SkillInfo `json:"skills"`
+}
+
+type skillDetailResponse struct {
+	Name        string `json:"name"`
+	Path        string `json:"path"`
+	Source      string `json:"source"`
+	Description string `json:"description"`
+	Content     string `json:"content"`
+}
+
+var (
+	skillNameSanitizer       = regexp.MustCompile(`[^a-z0-9-]+`)
+	importedSkillFrontmatter = regexp.MustCompile(`(?s)^---(?:\r\n|\n|\r)(.*?)(?:\r\n|\n|\r)---(?:\r\n|\n|\r)*`)
+	skillFrontmatterStripper = regexp.MustCompile(`(?s)^---(?:\r\n|\n|\r)(.*?)(?:\r\n|\n|\r)---(?:\r\n|\n|\r)*`)
+)
+
+func (h *Handler) registerSkillRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/skills", h.handleListSkills)
+	mux.HandleFunc("GET /api/skills/{name}", h.handleGetSkill)
+	mux.HandleFunc("POST /api/skills/import", h.handleImportSkill)
+	mux.HandleFunc("DELETE /api/skills/{name}", h.handleDeleteSkill)
+}
+
+func (h *Handler) handleListSkills(w http.ResponseWriter, r *http.Request) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	loader := newSkillsLoader(cfg.WorkspacePath())
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(skillSupportResponse{
+		Skills: loader.ListSkills(),
+	})
+}
+
+func (h *Handler) handleGetSkill(w http.ResponseWriter, r *http.Request) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	loader := newSkillsLoader(cfg.WorkspacePath())
+	name := r.PathValue("name")
+	allSkills := loader.ListSkills()
+
+	for _, skill := range allSkills {
+		if skill.Name != name {
+			continue
+		}
+
+		content, err := loadSkillContent(skill.Path)
+		if err != nil {
+			http.Error(w, "Skill content not found", http.StatusNotFound)
+			return
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(skillDetailResponse{
+			Name:        skill.Name,
+			Path:        skill.Path,
+			Source:      skill.Source,
+			Description: skill.Description,
+			Content:     content,
+		})
+		return
+	}
+
+	http.Error(w, "Skill not found", http.StatusNotFound)
+}
+
+func (h *Handler) handleImportSkill(w http.ResponseWriter, r *http.Request) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	err = r.ParseMultipartForm(2 << 20)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Invalid multipart form: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	uploadedFile, fileHeader, err := r.FormFile("file")
+	if err != nil {
+		http.Error(w, "file is required", http.StatusBadRequest)
+		return
+	}
+	defer uploadedFile.Close()
+
+	content, err := io.ReadAll(io.LimitReader(uploadedFile, (1<<20)+1))
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to read file: %v", err), http.StatusBadRequest)
+		return
+	}
+	if len(content) > 1<<20 {
+		http.Error(w, "file exceeds 1MB limit", http.StatusBadRequest)
+		return
+	}
+
+	skillName, err := normalizeImportedSkillName(fileHeader.Filename, content)
+	if err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+	content = normalizeImportedSkillContent(content, skillName)
+
+	workspace := cfg.WorkspacePath()
+	skillDir := filepath.Join(workspace, "skills", skillName)
+	skillFile := filepath.Join(skillDir, "SKILL.md")
+	if _, err := os.Stat(skillDir); err == nil {
+		http.Error(w, "skill already exists", http.StatusConflict)
+		return
+	}
+
+	if err := os.MkdirAll(skillDir, 0o755); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to create skill directory: %v", err), http.StatusInternalServerError)
+		return
+	}
+	if err := os.WriteFile(skillFile, content, 0o644); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save skill: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	loader := newSkillsLoader(workspace)
+	for _, skill := range loader.ListSkills() {
+		if skill.Path == skillFile || (skill.Name == skillName && skill.Source == "workspace") {
+			w.Header().Set("Content-Type", "application/json")
+			json.NewEncoder(w).Encode(skill)
+			return
+		}
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{
+		"name": skillName,
+		"path": skillFile,
+	})
+}
+
+func (h *Handler) handleDeleteSkill(w http.ResponseWriter, r *http.Request) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	loader := newSkillsLoader(cfg.WorkspacePath())
+	name := r.PathValue("name")
+	for _, skill := range loader.ListSkills() {
+		if skill.Name != name {
+			continue
+		}
+		if skill.Source != "workspace" {
+			http.Error(w, "only workspace skills can be deleted", http.StatusBadRequest)
+			return
+		}
+		if err := os.RemoveAll(filepath.Dir(skill.Path)); err != nil {
+			http.Error(w, fmt.Sprintf("Failed to delete skill: %v", err), http.StatusInternalServerError)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+		return
+	}
+
+	http.Error(w, "Skill not found", http.StatusNotFound)
+}
+
+func newSkillsLoader(workspace string) *skills.SkillsLoader {
+	return skills.NewSkillsLoader(
+		workspace,
+		filepath.Join(globalConfigDir(), "skills"),
+		builtinSkillsDir(),
+	)
+}
+
+func normalizeImportedSkillName(filename string, content []byte) (string, error) {
+	rawContent := strings.ReplaceAll(string(content), "\r\n", "\n")
+	rawContent = strings.ReplaceAll(rawContent, "\r", "\n")
+	metadata, _ := extractImportedSkillMetadata(rawContent)
+
+	raw := strings.TrimSpace(metadata["name"])
+	if raw == "" {
+		raw = strings.TrimSpace(strings.TrimSuffix(filepath.Base(filename), filepath.Ext(filename)))
+	}
+	raw = strings.ToLower(raw)
+	raw = strings.ReplaceAll(raw, "_", "-")
+	raw = strings.ReplaceAll(raw, " ", "-")
+	raw = skillNameSanitizer.ReplaceAllString(raw, "-")
+	raw = strings.Trim(raw, "-")
+	raw = strings.Join(strings.FieldsFunc(raw, func(r rune) bool { return r == '-' }), "-")
+
+	if raw == "" {
+		return "", fmt.Errorf("skill name is required in frontmatter or filename")
+	}
+	if len(raw) > 64 {
+		return "", fmt.Errorf("skill name exceeds 64 characters")
+	}
+	matched, err := regexp.MatchString(`^[a-z0-9]+(-[a-z0-9]+)*$`, raw)
+	if err != nil || !matched {
+		return "", fmt.Errorf("skill name must be alphanumeric with hyphens")
+	}
+	return raw, nil
+}
+
+func normalizeImportedSkillContent(content []byte, skillName string) []byte {
+	raw := strings.ReplaceAll(string(content), "\r\n", "\n")
+	raw = strings.ReplaceAll(raw, "\r", "\n")
+
+	metadata, body := extractImportedSkillMetadata(raw)
+	description := strings.TrimSpace(metadata["description"])
+	if description == "" {
+		description = inferImportedSkillDescription(body)
+	}
+	if description == "" {
+		description = "Imported skill"
+	}
+	if len(description) > 1024 {
+		description = strings.TrimSpace(description[:1024])
+	}
+
+	body = strings.TrimLeft(body, "\n")
+	var builder strings.Builder
+	builder.WriteString("---\n")
+	builder.WriteString("name: ")
+	builder.WriteString(skillName)
+	builder.WriteString("\n")
+	builder.WriteString("description: ")
+	builder.WriteString(description)
+	builder.WriteString("\n")
+	builder.WriteString("---\n\n")
+	builder.WriteString(body)
+	if !strings.HasSuffix(builder.String(), "\n") {
+		builder.WriteString("\n")
+	}
+	return []byte(builder.String())
+}
+
+func extractImportedSkillMetadata(raw string) (map[string]string, string) {
+	matches := importedSkillFrontmatter.FindStringSubmatch(raw)
+	if len(matches) != 2 {
+		return map[string]string{}, raw
+	}
+	meta := parseImportedSkillYAML(matches[1])
+	body := importedSkillFrontmatter.ReplaceAllString(raw, "")
+	return meta, body
+}
+
+func parseImportedSkillYAML(frontmatter string) map[string]string {
+	result := make(map[string]string)
+	for _, line := range strings.Split(frontmatter, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		key, value, ok := strings.Cut(line, ":")
+		if !ok {
+			continue
+		}
+		result[strings.TrimSpace(key)] = strings.Trim(strings.TrimSpace(value), `"'`)
+	}
+	return result
+}
+
+func inferImportedSkillDescription(body string) string {
+	for _, line := range strings.Split(body, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" {
+			continue
+		}
+		line = strings.TrimLeft(line, "#-*0123456789. ")
+		line = strings.TrimSpace(line)
+		if line != "" {
+			return line
+		}
+	}
+	return ""
+}
+
+func loadSkillContent(path string) (string, error) {
+	content, err := os.ReadFile(path)
+	if err != nil {
+		return "", err
+	}
+	return skillFrontmatterStripper.ReplaceAllString(string(content), ""), nil
+}
+
+func globalConfigDir() string {
+	if home := os.Getenv(config.EnvHome); home != "" {
+		return home
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return ""
+	}
+	return filepath.Join(home, ".picoclaw")
+}
+
+func builtinSkillsDir() string {
+	if path := os.Getenv(config.EnvBuiltinSkills); path != "" {
+		return path
+	}
+	wd, err := os.Getwd()
+	if err != nil {
+		return ""
+	}
+	return filepath.Join(wd, "skills")
+}
diff --git a/web/backend/api/skills_test.go b/web/backend/api/skills_test.go
new file mode 100644
index 000000000..3289d5b33
--- /dev/null
+++ b/web/backend/api/skills_test.go
@@ -0,0 +1,336 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestHandleListSkills(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	workspace := filepath.Join(t.TempDir(), "workspace")
+	cfg.Agents.Defaults.Workspace = workspace
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	if err := os.MkdirAll(filepath.Join(workspace, "skills", "workspace-skill"), 0o755); err != nil {
+		t.Fatalf("MkdirAll(workspace skill) error = %v", err)
+	}
+	if err := os.WriteFile(
+		filepath.Join(workspace, "skills", "workspace-skill", "SKILL.md"),
+		[]byte("---\nname: workspace-skill\ndescription: Workspace skill\n---\n"),
+		0o644,
+	); err != nil {
+		t.Fatalf("WriteFile(workspace skill) error = %v", err)
+	}
+
+	globalSkillDir := filepath.Join(globalConfigDir(), "skills", "global-skill")
+	if err := os.MkdirAll(globalSkillDir, 0o755); err != nil {
+		t.Fatalf("MkdirAll(global skill) error = %v", err)
+	}
+	if err := os.WriteFile(
+		filepath.Join(globalSkillDir, "SKILL.md"),
+		[]byte("---\nname: global-skill\ndescription: Global skill\n---\n"),
+		0o644,
+	); err != nil {
+		t.Fatalf("WriteFile(global skill) error = %v", err)
+	}
+
+	builtinRoot := filepath.Join(t.TempDir(), "builtin-skills")
+	oldBuiltin := os.Getenv("PICOCLAW_BUILTIN_SKILLS")
+	if err := os.Setenv("PICOCLAW_BUILTIN_SKILLS", builtinRoot); err != nil {
+		t.Fatalf("Setenv(PICOCLAW_BUILTIN_SKILLS) error = %v", err)
+	}
+	defer func() {
+		if oldBuiltin == "" {
+			_ = os.Unsetenv("PICOCLAW_BUILTIN_SKILLS")
+		} else {
+			_ = os.Setenv("PICOCLAW_BUILTIN_SKILLS", oldBuiltin)
+		}
+	}()
+
+	builtinSkillDir := filepath.Join(builtinRoot, "builtin-skill")
+	if err := os.MkdirAll(builtinSkillDir, 0o755); err != nil {
+		t.Fatalf("MkdirAll(builtin skill) error = %v", err)
+	}
+	if err := os.WriteFile(
+		filepath.Join(builtinSkillDir, "SKILL.md"),
+		[]byte("---\nname: builtin-skill\ndescription: Builtin skill\n---\n"),
+		0o644,
+	); err != nil {
+		t.Fatalf("WriteFile(builtin skill) error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/skills", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var resp skillSupportResponse
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if len(resp.Skills) != 3 {
+		t.Fatalf("skills count = %d, want 3", len(resp.Skills))
+	}
+
+	gotSkills := make(map[string]string, len(resp.Skills))
+	for _, skill := range resp.Skills {
+		gotSkills[skill.Name] = skill.Source
+	}
+	if gotSkills["workspace-skill"] != "workspace" {
+		t.Fatalf("workspace-skill source = %q, want workspace", gotSkills["workspace-skill"])
+	}
+	if gotSkills["global-skill"] != "global" {
+		t.Fatalf("global-skill source = %q, want global", gotSkills["global-skill"])
+	}
+	if gotSkills["builtin-skill"] != "builtin" {
+		t.Fatalf("builtin-skill source = %q, want builtin", gotSkills["builtin-skill"])
+	}
+}
+
+func TestHandleGetSkill(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	workspace := filepath.Join(t.TempDir(), "workspace")
+	cfg.Agents.Defaults.Workspace = workspace
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	skillDir := filepath.Join(workspace, "skills", "viewer-skill")
+	if err := os.MkdirAll(skillDir, 0o755); err != nil {
+		t.Fatalf("MkdirAll() error = %v", err)
+	}
+	if err := os.WriteFile(
+		filepath.Join(skillDir, "SKILL.md"),
+		[]byte(
+			"---\nname: viewer-skill\ndescription: Viewable skill\n---\n# Viewer Skill\n\nThis is visible content.\n",
+		),
+		0o644,
+	); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/skills/viewer-skill", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var resp skillDetailResponse
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if resp.Name != "viewer-skill" || resp.Source != "workspace" || resp.Description != "Viewable skill" {
+		t.Fatalf("unexpected response: %#v", resp)
+	}
+	if resp.Content != "# Viewer Skill\n\nThis is visible content.\n" {
+		t.Fatalf("content = %q", resp.Content)
+	}
+}
+
+func TestHandleGetSkillUsesResolvedPath(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+
+	workspace := filepath.Join(t.TempDir(), "workspace")
+	cfg.Agents.Defaults.Workspace = workspace
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	skillDir := filepath.Join(workspace, "skills", "folder-name")
+	if err := os.MkdirAll(skillDir, 0o755); err != nil {
+		t.Fatalf("MkdirAll() error = %v", err)
+	}
+	if err := os.WriteFile(
+		filepath.Join(skillDir, "SKILL.md"),
+		[]byte("---\nname: display-name\ndescription: Mismatched path skill\n---\n# Display Name\n"),
+		0o644,
+	); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/skills/display-name", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var resp skillDetailResponse
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	if resp.Name != "display-name" {
+		t.Fatalf("resp.Name = %q, want display-name", resp.Name)
+	}
+	if resp.Content != "# Display Name\n" {
+		t.Fatalf("content = %q", resp.Content)
+	}
+}
+
+func TestHandleImportSkill(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	workspace := filepath.Join(t.TempDir(), "workspace")
+	cfg.Agents.Defaults.Workspace = workspace
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	var body bytes.Buffer
+	writer := multipart.NewWriter(&body)
+	part, err := writer.CreateFormFile("file", "Plain Skill.md")
+	if err != nil {
+		t.Fatalf("CreateFormFile() error = %v", err)
+	}
+	_, err = io.WriteString(part, "# Plain Skill\n\nUse this skill to test imports.\n")
+	if err != nil {
+		t.Fatalf("WriteString() error = %v", err)
+	}
+	err = writer.Close()
+	if err != nil {
+		t.Fatalf("Close() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPost, "/api/skills/import", &body)
+	req.Header.Set("Content-Type", writer.FormDataContentType())
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	skillFile := filepath.Join(workspace, "skills", "plain-skill", "SKILL.md")
+	content, err := os.ReadFile(skillFile)
+	if err != nil {
+		t.Fatalf("ReadFile() error = %v", err)
+	}
+	expected := "---\nname: plain-skill\ndescription: Plain Skill\n---\n\n# Plain Skill\n\nUse this skill to test imports.\n"
+	if string(content) != expected {
+		t.Fatalf("saved skill content mismatch:\n%s", string(content))
+	}
+
+	rec2 := httptest.NewRecorder()
+	req2 := httptest.NewRequest(http.MethodGet, "/api/skills", nil)
+	mux.ServeHTTP(rec2, req2)
+	if rec2.Code != http.StatusOK {
+		t.Fatalf("list status = %d, want %d, body=%s", rec2.Code, http.StatusOK, rec2.Body.String())
+	}
+	var listResp skillSupportResponse
+	if err := json.Unmarshal(rec2.Body.Bytes(), &listResp); err != nil {
+		t.Fatalf("Unmarshal list response error = %v", err)
+	}
+	found := false
+	for _, skill := range listResp.Skills {
+		if skill.Name == "plain-skill" && skill.Source == "workspace" && skill.Description == "Plain Skill" {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("plain-skill should be listed after import, got %#v", listResp.Skills)
+	}
+}
+
+func TestHandleDeleteSkill(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	workspace := filepath.Join(t.TempDir(), "workspace")
+	cfg.Agents.Defaults.Workspace = workspace
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	skillDir := filepath.Join(workspace, "skills", "delete-me")
+	if err := os.MkdirAll(skillDir, 0o755); err != nil {
+		t.Fatalf("MkdirAll() error = %v", err)
+	}
+	if err := os.WriteFile(
+		filepath.Join(skillDir, "SKILL.md"),
+		[]byte("---\nname: delete-me\ndescription: delete me\n---\n"),
+		0o644,
+	); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodDelete, "/api/skills/delete-me", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+	if _, err := os.Stat(skillDir); !os.IsNotExist(err) {
+		t.Fatalf("skill directory should be removed, stat err=%v", err)
+	}
+}
diff --git a/web/backend/api/startup.go b/web/backend/api/startup.go
new file mode 100644
index 000000000..1c685bc90
--- /dev/null
+++ b/web/backend/api/startup.go
@@ -0,0 +1,305 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+)
+
+const (
+	autoStartEntryName = "PicoClawLauncher"
+	launchAgentLabel   = "io.picoclaw.launcher"
+)
+
+type autoStartRequest struct {
+	Enabled bool `json:"enabled"`
+}
+
+type autoStartResponse struct {
+	Enabled   bool   `json:"enabled"`
+	Supported bool   `json:"supported"`
+	Platform  string `json:"platform"`
+	Message   string `json:"message,omitempty"`
+}
+
+var errAutoStartUnsupported = errors.New("autostart is not supported on this platform")
+
+func (h *Handler) registerStartupRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/system/autostart", h.handleGetAutoStart)
+	mux.HandleFunc("PUT /api/system/autostart", h.handleSetAutoStart)
+}
+
+func (h *Handler) handleGetAutoStart(w http.ResponseWriter, r *http.Request) {
+	enabled, supported, message, err := h.getAutoStartStatus()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to read startup setting: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(autoStartResponse{
+		Enabled:   enabled,
+		Supported: supported,
+		Platform:  runtime.GOOS,
+		Message:   message,
+	})
+}
+
+func (h *Handler) handleSetAutoStart(w http.ResponseWriter, r *http.Request) {
+	var req autoStartRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	if err := h.setAutoStart(req.Enabled); err != nil {
+		if errors.Is(err, errAutoStartUnsupported) {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		http.Error(w, fmt.Sprintf("Failed to update startup setting: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	enabled, supported, message, err := h.getAutoStartStatus()
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to verify startup setting: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(autoStartResponse{
+		Enabled:   enabled,
+		Supported: supported,
+		Platform:  runtime.GOOS,
+		Message:   message,
+	})
+}
+
+func (h *Handler) resolveLaunchCommand() (string, []string, error) {
+	exePath, err := os.Executable()
+	if err != nil {
+		return "", nil, err
+	}
+
+	args := []string{"-no-browser"}
+	if h.configPath != "" {
+		args = append(args, h.configPath)
+	}
+
+	return exePath, args, nil
+}
+
+func (h *Handler) getAutoStartStatus() (enabled bool, supported bool, message string, err error) {
+	switch runtime.GOOS {
+	case "darwin":
+		exists, err := fileExists(macLaunchAgentPath())
+		return exists, true, "Changes apply on next login.", err
+	case "linux":
+		exists, err := fileExists(linuxAutoStartPath())
+		return exists, true, "Changes apply on next login.", err
+	case "windows":
+		exists, err := windowsRunKeyExists()
+		return exists, true, "Changes apply on next login.", err
+	default:
+		return false, false, "Current platform does not support launch at login.", nil
+	}
+}
+
+func (h *Handler) setAutoStart(enabled bool) error {
+	exePath, args, err := h.resolveLaunchCommand()
+	if err != nil {
+		return err
+	}
+
+	switch runtime.GOOS {
+	case "darwin":
+		return setDarwinAutoStart(enabled, exePath, args)
+	case "linux":
+		return setLinuxAutoStart(enabled, exePath, args)
+	case "windows":
+		return setWindowsAutoStart(enabled, exePath, args)
+	default:
+		return errAutoStartUnsupported
+	}
+}
+
+func fileExists(path string) (bool, error) {
+	_, err := os.Stat(path)
+	if err == nil {
+		return true, nil
+	}
+	if os.IsNotExist(err) {
+		return false, nil
+	}
+	return false, err
+}
+
+func macLaunchAgentPath() string {
+	home, _ := os.UserHomeDir()
+	return filepath.Join(home, "Library", "LaunchAgents", launchAgentLabel+".plist")
+}
+
+func setDarwinAutoStart(enabled bool, exePath string, args []string) error {
+	plistPath := macLaunchAgentPath()
+	if enabled {
+		if err := os.MkdirAll(filepath.Dir(plistPath), 0o755); err != nil {
+			return err
+		}
+		content := buildDarwinPlist(exePath, args)
+		return os.WriteFile(plistPath, []byte(content), 0o644)
+	}
+
+	if err := os.Remove(plistPath); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+func xmlEscape(s string) string {
+	var b bytes.Buffer
+	for _, r := range s {
+		switch r {
+		case '&':
+			b.WriteString("&amp;")
+		case '<':
+			b.WriteString("&lt;")
+		case '>':
+			b.WriteString("&gt;")
+		case '"':
+			b.WriteString("&quot;")
+		case '\'':
+			b.WriteString("&apos;")
+		default:
+			b.WriteRune(r)
+		}
+	}
+	return b.String()
+}
+
+func buildDarwinPlist(exePath string, args []string) string {
+	programArgs := make([]string, 0, len(args)+1)
+	programArgs = append(programArgs, exePath)
+	programArgs = append(programArgs, args...)
+
+	var b strings.Builder
+	b.WriteString(`<?xml version="1.0" encoding="UTF-8"?>` + "\n")
+	b.WriteString(
+		`<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">` + "\n",
+	)
+	b.WriteString(`<plist version="1.0">` + "\n")
+	b.WriteString(`<dict>` + "\n")
+	b.WriteString(`  <key>Label</key>` + "\n")
+	b.WriteString(`  <string>` + launchAgentLabel + `</string>` + "\n")
+	b.WriteString(`  <key>ProgramArguments</key>` + "\n")
+	b.WriteString(`  <array>` + "\n")
+	for _, arg := range programArgs {
+		b.WriteString(`    <string>` + xmlEscape(arg) + `</string>` + "\n")
+	}
+	b.WriteString(`  </array>` + "\n")
+	b.WriteString(`  <key>RunAtLoad</key>` + "\n")
+	b.WriteString(`  <true/>` + "\n")
+	b.WriteString(`  <key>ProcessType</key>` + "\n")
+	b.WriteString(`  <string>Background</string>` + "\n")
+	b.WriteString(`</dict>` + "\n")
+	b.WriteString(`</plist>` + "\n")
+	return b.String()
+}
+
+func linuxAutoStartPath() string {
+	home, _ := os.UserHomeDir()
+	return filepath.Join(home, ".config", "autostart", "picoclaw-web.desktop")
+}
+
+func shellQuote(s string) string {
+	if s == "" {
+		return "''"
+	}
+	if !strings.ContainsAny(s, " \t\n'\"\\$`") {
+		return s
+	}
+	return "'" + strings.ReplaceAll(s, "'", "'\"'\"'") + "'"
+}
+
+func buildLinuxExecLine(exePath string, args []string) string {
+	parts := make([]string, 0, len(args)+1)
+	parts = append(parts, shellQuote(exePath))
+	for _, arg := range args {
+		parts = append(parts, shellQuote(arg))
+	}
+	return strings.Join(parts, " ")
+}
+
+func setLinuxAutoStart(enabled bool, exePath string, args []string) error {
+	desktopPath := linuxAutoStartPath()
+	if enabled {
+		if err := os.MkdirAll(filepath.Dir(desktopPath), 0o755); err != nil {
+			return err
+		}
+		content := strings.Join([]string{
+			"[Desktop Entry]",
+			"Type=Application",
+			"Version=1.0",
+			"Name=PicoClaw Web",
+			"Comment=Start PicoClaw Web on login",
+			"Exec=" + buildLinuxExecLine(exePath, args),
+			"Terminal=false",
+			"X-GNOME-Autostart-enabled=true",
+			"NoDisplay=true",
+			"",
+		}, "\n")
+		return os.WriteFile(desktopPath, []byte(content), 0o644)
+	}
+
+	if err := os.Remove(desktopPath); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+func windowsCommandLine(exePath string, args []string) string {
+	parts := make([]string, 0, len(args)+1)
+	parts = append(parts, fmt.Sprintf("%q", exePath))
+	for _, arg := range args {
+		parts = append(parts, fmt.Sprintf("%q", arg))
+	}
+	return strings.Join(parts, " ")
+}
+
+func windowsRunKeyExists() (bool, error) {
+	cmd := exec.Command("reg", "query", `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`, "/v", autoStartEntryName)
+	if err := cmd.Run(); err != nil {
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) {
+			return false, nil
+		}
+		return false, err
+	}
+	return true, nil
+}
+
+func setWindowsAutoStart(enabled bool, exePath string, args []string) error {
+	key := `HKCU\Software\Microsoft\Windows\CurrentVersion\Run`
+	if enabled {
+		commandLine := windowsCommandLine(exePath, args)
+		cmd := exec.Command("reg", "add", key, "/v", autoStartEntryName, "/t", "REG_SZ", "/d", commandLine, "/f")
+		return cmd.Run()
+	}
+
+	cmd := exec.Command("reg", "delete", key, "/v", autoStartEntryName, "/f")
+	if err := cmd.Run(); err != nil {
+		var exitErr *exec.ExitError
+		if errors.As(err, &exitErr) {
+			return nil
+		}
+		return err
+	}
+	return nil
+}
diff --git a/web/backend/api/startup_test.go b/web/backend/api/startup_test.go
new file mode 100644
index 000000000..cfa9b4c53
--- /dev/null
+++ b/web/backend/api/startup_test.go
@@ -0,0 +1,56 @@
+package api
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+)
+
+func TestResolveLaunchCommandUsesConfigFileDefaults(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	h := NewHandler(configPath)
+
+	// Persist non-default launcher options to ensure resolveLaunchCommand does not
+	// pin them into autostart args.
+	launcherPath := launcherconfig.PathForAppConfig(configPath)
+	if err := launcherconfig.Save(launcherPath, launcherconfig.Config{
+		Port:   19999,
+		Public: true,
+	}); err != nil {
+		t.Fatalf("launcherconfig.Save() error = %v", err)
+	}
+
+	exePath, args, err := h.resolveLaunchCommand()
+	if err != nil {
+		t.Fatalf("resolveLaunchCommand() error = %v", err)
+	}
+	if exePath == "" {
+		t.Fatal("resolveLaunchCommand() returned empty executable path")
+	}
+	if len(args) != 2 {
+		t.Fatalf("args len = %d, want 2 (got %v)", len(args), args)
+	}
+	if args[0] != "-no-browser" {
+		t.Fatalf("args[0] = %q, want %q", args[0], "-no-browser")
+	}
+	if args[1] != configPath {
+		t.Fatalf("args[1] = %q, want %q", args[1], configPath)
+	}
+	for _, arg := range args {
+		if arg == "-port" || arg == "-public" {
+			t.Fatalf("autostart args should not pin network flags, got %v", args)
+		}
+	}
+}
+
+func TestBuildDarwinPlistIncludesRunAtLoad(t *testing.T) {
+	plist := buildDarwinPlist("/tmp/picoclaw-web", []string{"-no-browser", "/tmp/config.json"})
+	if !strings.Contains(plist, "<key>RunAtLoad</key>") {
+		t.Fatalf("plist missing RunAtLoad key:\n%s", plist)
+	}
+	if !strings.Contains(plist, "<true/>") {
+		t.Fatalf("plist missing RunAtLoad true value:\n%s", plist)
+	}
+}
diff --git a/web/backend/api/tools.go b/web/backend/api/tools.go
new file mode 100644
index 000000000..9df4a7091
--- /dev/null
+++ b/web/backend/api/tools.go
@@ -0,0 +1,335 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"runtime"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+type toolCatalogEntry struct {
+	Name        string
+	Description string
+	Category    string
+	ConfigKey   string
+}
+
+type toolSupportItem struct {
+	Name        string `json:"name"`
+	Description string `json:"description"`
+	Category    string `json:"category"`
+	ConfigKey   string `json:"config_key"`
+	Status      string `json:"status"`
+	ReasonCode  string `json:"reason_code,omitempty"`
+}
+
+type toolSupportResponse struct {
+	Tools []toolSupportItem `json:"tools"`
+}
+
+type toolStateRequest struct {
+	Enabled bool `json:"enabled"`
+}
+
+var toolCatalog = []toolCatalogEntry{
+	{
+		Name:        "read_file",
+		Description: "Read file content from the workspace or explicitly allowed paths.",
+		Category:    "filesystem",
+		ConfigKey:   "read_file",
+	},
+	{
+		Name:        "write_file",
+		Description: "Create or overwrite files within the writable workspace scope.",
+		Category:    "filesystem",
+		ConfigKey:   "write_file",
+	},
+	{
+		Name:        "list_dir",
+		Description: "Inspect directories and enumerate files available to the agent.",
+		Category:    "filesystem",
+		ConfigKey:   "list_dir",
+	},
+	{
+		Name:        "edit_file",
+		Description: "Apply targeted edits to existing files without rewriting everything.",
+		Category:    "filesystem",
+		ConfigKey:   "edit_file",
+	},
+	{
+		Name:        "append_file",
+		Description: "Append content to the end of an existing file.",
+		Category:    "filesystem",
+		ConfigKey:   "append_file",
+	},
+	{
+		Name:        "exec",
+		Description: "Run shell commands inside the configured workspace sandbox.",
+		Category:    "filesystem",
+		ConfigKey:   "exec",
+	},
+	{
+		Name:        "cron",
+		Description: "Schedule one-time or recurring reminders, jobs, and shell commands.",
+		Category:    "automation",
+		ConfigKey:   "cron",
+	},
+	{
+		Name:        "web_search",
+		Description: "Search the web using the configured providers.",
+		Category:    "web",
+		ConfigKey:   "web",
+	},
+	{
+		Name:        "web_fetch",
+		Description: "Fetch and summarize the contents of a webpage.",
+		Category:    "web",
+		ConfigKey:   "web_fetch",
+	},
+	{
+		Name:        "message",
+		Description: "Send a follow-up message back to the active user or chat.",
+		Category:    "communication",
+		ConfigKey:   "message",
+	},
+	{
+		Name:        "send_file",
+		Description: "Send an outbound file or media attachment to the active chat.",
+		Category:    "communication",
+		ConfigKey:   "send_file",
+	},
+	{
+		Name:        "find_skills",
+		Description: "Search external skill registries for installable skills.",
+		Category:    "skills",
+		ConfigKey:   "find_skills",
+	},
+	{
+		Name:        "install_skill",
+		Description: "Install a skill into the current workspace from a registry.",
+		Category:    "skills",
+		ConfigKey:   "install_skill",
+	},
+	{
+		Name:        "spawn",
+		Description: "Launch a background subagent for long-running or delegated work.",
+		Category:    "agents",
+		ConfigKey:   "spawn",
+	},
+	{
+		Name:        "spawn_status",
+		Description: "Query the status of spawned subagents.",
+		Category:    "agents",
+		ConfigKey:   "spawn_status",
+	},
+	{
+		Name:        "i2c",
+		Description: "Interact with I2C hardware devices exposed on the host.",
+		Category:    "hardware",
+		ConfigKey:   "i2c",
+	},
+	{
+		Name:        "spi",
+		Description: "Interact with SPI hardware devices exposed on the host.",
+		Category:    "hardware",
+		ConfigKey:   "spi",
+	},
+	{
+		Name:        "tool_search_tool_regex",
+		Description: "Discover hidden MCP tools by regex search when tool discovery is enabled.",
+		Category:    "discovery",
+		ConfigKey:   "mcp.discovery.use_regex",
+	},
+	{
+		Name:        "tool_search_tool_bm25",
+		Description: "Discover hidden MCP tools by semantic ranking when tool discovery is enabled.",
+		Category:    "discovery",
+		ConfigKey:   "mcp.discovery.use_bm25",
+	},
+}
+
+func (h *Handler) registerToolRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("GET /api/tools", h.handleListTools)
+	mux.HandleFunc("PUT /api/tools/{name}/state", h.handleUpdateToolState)
+}
+
+func (h *Handler) handleListTools(w http.ResponseWriter, r *http.Request) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(toolSupportResponse{
+		Tools: buildToolSupport(cfg),
+	})
+}
+
+func (h *Handler) handleUpdateToolState(w http.ResponseWriter, r *http.Request) {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("Failed to load config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	var req toolStateRequest
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		http.Error(w, fmt.Sprintf("Invalid JSON: %v", err), http.StatusBadRequest)
+		return
+	}
+
+	if err := applyToolState(cfg, r.PathValue("name"), req.Enabled); err != nil {
+		http.Error(w, err.Error(), http.StatusBadRequest)
+		return
+	}
+
+	if err := config.SaveConfig(h.configPath, cfg); err != nil {
+		http.Error(w, fmt.Sprintf("Failed to save config: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
+}
+
+func buildToolSupport(cfg *config.Config) []toolSupportItem {
+	items := make([]toolSupportItem, 0, len(toolCatalog))
+	for _, entry := range toolCatalog {
+		status := "disabled"
+		reasonCode := ""
+
+		switch entry.Name {
+		case "find_skills", "install_skill":
+			if cfg.Tools.IsToolEnabled(entry.ConfigKey) {
+				if cfg.Tools.IsToolEnabled("skills") {
+					status = "enabled"
+				} else {
+					status = "blocked"
+					reasonCode = "requires_skills"
+				}
+			}
+		case "spawn", "spawn_status":
+			if cfg.Tools.IsToolEnabled(entry.ConfigKey) {
+				if cfg.Tools.IsToolEnabled("subagent") {
+					status = "enabled"
+				} else {
+					status = "blocked"
+					reasonCode = "requires_subagent"
+				}
+			}
+		case "tool_search_tool_regex":
+			status, reasonCode = resolveDiscoveryToolSupport(cfg, cfg.Tools.MCP.Discovery.UseRegex)
+		case "tool_search_tool_bm25":
+			status, reasonCode = resolveDiscoveryToolSupport(cfg, cfg.Tools.MCP.Discovery.UseBM25)
+		case "i2c", "spi":
+			status, reasonCode = resolveHardwareToolSupport(cfg.Tools.IsToolEnabled(entry.ConfigKey))
+		default:
+			if cfg.Tools.IsToolEnabled(entry.ConfigKey) {
+				status = "enabled"
+			}
+		}
+
+		items = append(items, toolSupportItem{
+			Name:        entry.Name,
+			Description: entry.Description,
+			Category:    entry.Category,
+			ConfigKey:   entry.ConfigKey,
+			Status:      status,
+			ReasonCode:  reasonCode,
+		})
+	}
+	return items
+}
+
+func resolveHardwareToolSupport(enabled bool) (string, string) {
+	if !enabled {
+		return "disabled", ""
+	}
+	if runtime.GOOS != "linux" {
+		return "blocked", "requires_linux"
+	}
+	return "enabled", ""
+}
+
+func resolveDiscoveryToolSupport(cfg *config.Config, methodEnabled bool) (string, string) {
+	if !cfg.Tools.IsToolEnabled("mcp") {
+		return "disabled", ""
+	}
+	if !cfg.Tools.MCP.Discovery.Enabled {
+		return "blocked", "requires_mcp_discovery"
+	}
+	if !methodEnabled {
+		return "disabled", ""
+	}
+	return "enabled", ""
+}
+
+func applyToolState(cfg *config.Config, toolName string, enabled bool) error {
+	switch toolName {
+	case "read_file":
+		cfg.Tools.ReadFile.Enabled = enabled
+	case "write_file":
+		cfg.Tools.WriteFile.Enabled = enabled
+	case "list_dir":
+		cfg.Tools.ListDir.Enabled = enabled
+	case "edit_file":
+		cfg.Tools.EditFile.Enabled = enabled
+	case "append_file":
+		cfg.Tools.AppendFile.Enabled = enabled
+	case "exec":
+		cfg.Tools.Exec.Enabled = enabled
+	case "cron":
+		cfg.Tools.Cron.Enabled = enabled
+	case "web_search":
+		cfg.Tools.Web.Enabled = enabled
+	case "web_fetch":
+		cfg.Tools.WebFetch.Enabled = enabled
+	case "message":
+		cfg.Tools.Message.Enabled = enabled
+	case "send_file":
+		cfg.Tools.SendFile.Enabled = enabled
+	case "find_skills":
+		cfg.Tools.FindSkills.Enabled = enabled
+		if enabled {
+			cfg.Tools.Skills.Enabled = true
+		}
+	case "install_skill":
+		cfg.Tools.InstallSkill.Enabled = enabled
+		if enabled {
+			cfg.Tools.Skills.Enabled = true
+		}
+	case "spawn":
+		cfg.Tools.Spawn.Enabled = enabled
+		if enabled {
+			cfg.Tools.Subagent.Enabled = true
+		}
+	case "spawn_status":
+		cfg.Tools.SpawnStatus.Enabled = enabled
+		if enabled {
+			cfg.Tools.Spawn.Enabled = true
+			cfg.Tools.Subagent.Enabled = true
+		}
+	case "i2c":
+		cfg.Tools.I2C.Enabled = enabled
+	case "spi":
+		cfg.Tools.SPI.Enabled = enabled
+	case "tool_search_tool_regex":
+		cfg.Tools.MCP.Discovery.UseRegex = enabled
+		if enabled {
+			cfg.Tools.MCP.Enabled = true
+			cfg.Tools.MCP.Discovery.Enabled = true
+		}
+	case "tool_search_tool_bm25":
+		cfg.Tools.MCP.Discovery.UseBM25 = enabled
+		if enabled {
+			cfg.Tools.MCP.Enabled = true
+			cfg.Tools.MCP.Discovery.Enabled = true
+		}
+	default:
+		return fmt.Errorf("tool %q cannot be updated", toolName)
+	}
+	return nil
+}
diff --git a/web/backend/api/tools_test.go b/web/backend/api/tools_test.go
new file mode 100644
index 000000000..646cefbe2
--- /dev/null
+++ b/web/backend/api/tools_test.go
@@ -0,0 +1,198 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"runtime"
+	"testing"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestHandleListTools(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.Tools.ReadFile.Enabled = true
+	cfg.Tools.WriteFile.Enabled = false
+	cfg.Tools.Cron.Enabled = true
+	cfg.Tools.FindSkills.Enabled = true
+	cfg.Tools.Skills.Enabled = true
+	cfg.Tools.Spawn.Enabled = true
+	cfg.Tools.Subagent.Enabled = false
+	cfg.Tools.MCP.Enabled = true
+	cfg.Tools.MCP.Discovery.Enabled = true
+	cfg.Tools.MCP.Discovery.UseRegex = true
+	cfg.Tools.MCP.Discovery.UseBM25 = false
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/tools", nil)
+	mux.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	var resp toolSupportResponse
+	if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("Unmarshal() error = %v", err)
+	}
+	gotTools := make(map[string]toolSupportItem, len(resp.Tools))
+	for _, tool := range resp.Tools {
+		gotTools[tool.Name] = tool
+	}
+	if gotTools["read_file"].Status != "enabled" {
+		t.Fatalf("read_file status = %q, want enabled", gotTools["read_file"].Status)
+	}
+	if gotTools["write_file"].Status != "disabled" {
+		t.Fatalf("write_file status = %q, want disabled", gotTools["write_file"].Status)
+	}
+	if gotTools["cron"].Status != "enabled" {
+		t.Fatalf("cron status = %q, want enabled", gotTools["cron"].Status)
+	}
+	if gotTools["spawn"].Status != "blocked" || gotTools["spawn"].ReasonCode != "requires_subagent" {
+		t.Fatalf("spawn = %#v, want blocked/requires_subagent", gotTools["spawn"])
+	}
+	if gotTools["find_skills"].Status != "enabled" {
+		t.Fatalf("find_skills status = %q, want enabled", gotTools["find_skills"].Status)
+	}
+	if gotTools["tool_search_tool_regex"].Status != "enabled" {
+		t.Fatalf("tool_search_tool_regex status = %q, want enabled", gotTools["tool_search_tool_regex"].Status)
+	}
+	if gotTools["tool_search_tool_regex"].ConfigKey != "mcp.discovery.use_regex" {
+		t.Fatalf(
+			"tool_search_tool_regex config_key = %q, want mcp.discovery.use_regex",
+			gotTools["tool_search_tool_regex"].ConfigKey,
+		)
+	}
+	if gotTools["tool_search_tool_bm25"].Status != "disabled" {
+		t.Fatalf("tool_search_tool_bm25 status = %q, want disabled", gotTools["tool_search_tool_bm25"].Status)
+	}
+	if gotTools["tool_search_tool_bm25"].ConfigKey != "mcp.discovery.use_bm25" {
+		t.Fatalf(
+			"tool_search_tool_bm25 config_key = %q, want mcp.discovery.use_bm25",
+			gotTools["tool_search_tool_bm25"].ConfigKey,
+		)
+	}
+	if runtime.GOOS == "linux" {
+		if gotTools["i2c"].Status != "disabled" {
+			t.Fatalf("i2c status = %q, want disabled on linux when config is off", gotTools["i2c"].Status)
+		}
+	} else {
+		cfg.Tools.I2C.Enabled = true
+		cfg.Tools.SPI.Enabled = true
+		if err := config.SaveConfig(configPath, cfg); err != nil {
+			t.Fatalf("SaveConfig() error = %v", err)
+		}
+
+		rec = httptest.NewRecorder()
+		req = httptest.NewRequest(http.MethodGet, "/api/tools", nil)
+		mux.ServeHTTP(rec, req)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+		}
+
+		if err := json.Unmarshal(rec.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("Unmarshal() error = %v", err)
+		}
+		gotTools = make(map[string]toolSupportItem, len(resp.Tools))
+		for _, tool := range resp.Tools {
+			gotTools[tool.Name] = tool
+		}
+
+		if gotTools["i2c"].Status != "blocked" || gotTools["i2c"].ReasonCode != "requires_linux" {
+			t.Fatalf("i2c = %#v, want blocked/requires_linux", gotTools["i2c"])
+		}
+		if gotTools["spi"].Status != "blocked" || gotTools["spi"].ReasonCode != "requires_linux" {
+			t.Fatalf("spi = %#v, want blocked/requires_linux", gotTools["spi"])
+		}
+	}
+}
+
+func TestHandleUpdateToolState(t *testing.T) {
+	configPath, cleanup := setupOAuthTestEnv(t)
+	defer cleanup()
+
+	cfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	cfg.Tools.Spawn.Enabled = false
+	cfg.Tools.Subagent.Enabled = false
+	cfg.Tools.Cron.Enabled = false
+	cfg.Tools.MCP.Enabled = false
+	cfg.Tools.MCP.Discovery.Enabled = false
+	cfg.Tools.MCP.Discovery.UseRegex = false
+	err = config.SaveConfig(configPath, cfg)
+	if err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	h := NewHandler(configPath)
+	mux := http.NewServeMux()
+	h.RegisterRoutes(mux)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(
+		http.MethodPut,
+		"/api/tools/spawn/state",
+		bytes.NewBufferString(`{"enabled":true}`),
+	)
+	req.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec, req)
+	if rec.Code != http.StatusOK {
+		t.Fatalf("spawn status = %d, want %d, body=%s", rec.Code, http.StatusOK, rec.Body.String())
+	}
+
+	rec2 := httptest.NewRecorder()
+	req2 := httptest.NewRequest(
+		http.MethodPut,
+		"/api/tools/tool_search_tool_regex/state",
+		bytes.NewBufferString(`{"enabled":true}`),
+	)
+	req2.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec2, req2)
+	if rec2.Code != http.StatusOK {
+		t.Fatalf("regex status = %d, want %d, body=%s", rec2.Code, http.StatusOK, rec2.Body.String())
+	}
+
+	rec3 := httptest.NewRecorder()
+	req3 := httptest.NewRequest(
+		http.MethodPut,
+		"/api/tools/cron/state",
+		bytes.NewBufferString(`{"enabled":true}`),
+	)
+	req3.Header.Set("Content-Type", "application/json")
+	mux.ServeHTTP(rec3, req3)
+	if rec3.Code != http.StatusOK {
+		t.Fatalf("cron status = %d, want %d, body=%s", rec3.Code, http.StatusOK, rec3.Body.String())
+	}
+
+	updated, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig(updated) error = %v", err)
+	}
+	if !updated.Tools.Spawn.Enabled || !updated.Tools.Subagent.Enabled {
+		t.Fatalf("spawn/subagent should both be enabled: %#v", updated.Tools)
+	}
+	if !updated.Tools.MCP.Enabled || !updated.Tools.MCP.Discovery.Enabled || !updated.Tools.MCP.Discovery.UseRegex {
+		t.Fatalf("mcp regex discovery should be enabled: %#v", updated.Tools.MCP)
+	}
+	if !updated.Tools.Cron.Enabled {
+		t.Fatalf("cron should be enabled: %#v", updated.Tools.Cron)
+	}
+}
diff --git a/web/backend/api/weixin.go b/web/backend/api/weixin.go
new file mode 100644
index 000000000..808b88c41
--- /dev/null
+++ b/web/backend/api/weixin.go
@@ -0,0 +1,317 @@
+package api
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"rsc.io/qr"
+
+	"github.com/sipeed/picoclaw/pkg/channels/weixin"
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+const (
+	weixinFlowTTL   = 5 * time.Minute
+	weixinFlowGCAge = 30 * time.Minute
+	weixinBaseURL   = "https://ilinkai.weixin.qq.com/"
+	weixinBotType   = "3"
+)
+
+const (
+	weixinStatusWait      = "wait"
+	weixinStatusScanned   = "scaned"
+	weixinStatusConfirmed = "confirmed"
+	weixinStatusExpired   = "expired"
+	weixinStatusError     = "error"
+)
+
+type weixinFlow struct {
+	ID        string
+	Qrcode    string // qrcode token from WeChat API (used for status polling)
+	QRDataURI string // base64 PNG data URI for display
+	AccountID string // IlinkBotID returned on confirmed
+	Status    string // wait / scaned / confirmed / expired / error
+	Error     string
+	CreatedAt time.Time
+	UpdatedAt time.Time
+	ExpiresAt time.Time
+}
+
+type weixinFlowResponse struct {
+	FlowID    string `json:"flow_id"`
+	Status    string `json:"status"`
+	QRDataURI string `json:"qr_data_uri,omitempty"`
+	AccountID string `json:"account_id,omitempty"`
+	Error     string `json:"error,omitempty"`
+}
+
+// registerWeixinRoutes binds WeChat QR login endpoints to the ServeMux.
+func (h *Handler) registerWeixinRoutes(mux *http.ServeMux) {
+	mux.HandleFunc("POST /api/weixin/flows", h.handleStartWeixinFlow)
+	mux.HandleFunc("GET /api/weixin/flows/{id}", h.handlePollWeixinFlow)
+}
+
+// handleStartWeixinFlow starts a new WeChat QR login flow.
+//
+//	POST /api/weixin/flows
+func (h *Handler) handleStartWeixinFlow(w http.ResponseWriter, r *http.Request) {
+	ctx, cancel := context.WithTimeout(r.Context(), 15*time.Second)
+	defer cancel()
+
+	api, err := weixin.NewApiClient(weixinBaseURL, "", "")
+	if err != nil {
+		http.Error(w, fmt.Sprintf("failed to create weixin client: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	qrResp, err := api.GetQRCode(ctx, weixinBotType)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("failed to get QR code: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	dataURI, err := generateQRDataURI(qrResp.QrcodeImgContent)
+	if err != nil {
+		http.Error(w, fmt.Sprintf("failed to generate QR image: %v", err), http.StatusInternalServerError)
+		return
+	}
+
+	now := time.Now()
+	flow := &weixinFlow{
+		ID:        newWeixinFlowID(),
+		Qrcode:    qrResp.Qrcode,
+		QRDataURI: dataURI,
+		Status:    weixinStatusWait,
+		CreatedAt: now,
+		UpdatedAt: now,
+		ExpiresAt: now.Add(weixinFlowTTL),
+	}
+	h.storeWeixinFlow(flow)
+
+	logger.InfoCF("weixin", "QR flow started", map[string]any{"flow_id": flow.ID})
+
+	w.Header().Set("Content-Type", "application/json")
+	_ = json.NewEncoder(w).Encode(weixinFlowResponse{
+		FlowID:    flow.ID,
+		Status:    flow.Status,
+		QRDataURI: flow.QRDataURI,
+	})
+}
+
+// handlePollWeixinFlow polls the WeChat API for QR code status and updates the flow.
+//
+//	GET /api/weixin/flows/{id}
+func (h *Handler) handlePollWeixinFlow(w http.ResponseWriter, r *http.Request) {
+	flowID := strings.TrimSpace(r.PathValue("id"))
+	if flowID == "" {
+		http.Error(w, "missing flow id", http.StatusBadRequest)
+		return
+	}
+
+	flow, ok := h.getWeixinFlow(flowID)
+	if !ok {
+		http.Error(w, "flow not found", http.StatusNotFound)
+		return
+	}
+
+	// Return terminal states directly without polling WeChat again
+	if flow.Status == weixinStatusConfirmed ||
+		flow.Status == weixinStatusExpired ||
+		flow.Status == weixinStatusError {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(weixinFlowResponse{
+			FlowID: flow.ID,
+			Status: flow.Status,
+			Error:  flow.Error,
+		})
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(r.Context(), 10*time.Second)
+	defer cancel()
+
+	api, err := weixin.NewApiClient(weixinBaseURL, "", "")
+	if err != nil {
+		h.setWeixinFlowError(flowID, fmt.Sprintf("client error: %v", err))
+		flow, _ = h.getWeixinFlow(flowID)
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(weixinFlowResponse{FlowID: flow.ID, Status: flow.Status, Error: flow.Error})
+		return
+	}
+
+	statusResp, err := api.GetQRCodeStatus(ctx, flow.Qrcode)
+	if err != nil {
+		// Transient error — keep current status, return it
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(weixinFlowResponse{
+			FlowID:    flow.ID,
+			Status:    flow.Status,
+			QRDataURI: flow.QRDataURI,
+		})
+		return
+	}
+
+	switch statusResp.Status {
+	case weixinStatusWait:
+		// no change
+
+	case weixinStatusScanned:
+		h.updateWeixinFlowStatus(flowID, weixinStatusScanned)
+
+	case weixinStatusConfirmed:
+		if statusResp.BotToken == "" {
+			h.setWeixinFlowError(flowID, "login confirmed but missing bot_token")
+			break
+		}
+		if saveErr := h.saveWeixinBinding(statusResp.BotToken, statusResp.IlinkBotID); saveErr != nil {
+			h.setWeixinFlowError(flowID, fmt.Sprintf("failed to save token: %v", saveErr))
+			logger.ErrorCF("weixin", "failed to save token", map[string]any{"error": saveErr.Error()})
+			break
+		}
+		h.setWeixinFlowConfirmed(flowID, statusResp.IlinkBotID)
+		logger.InfoCF("weixin", "QR login confirmed, token saved", map[string]any{
+			"flow_id":    flowID,
+			"account_id": statusResp.IlinkBotID,
+		})
+
+	case weixinStatusExpired:
+		h.updateWeixinFlowStatus(flowID, weixinStatusExpired)
+
+	default:
+		// unknown status, keep as-is
+	}
+
+	flow, _ = h.getWeixinFlow(flowID)
+	w.Header().Set("Content-Type", "application/json")
+	resp := weixinFlowResponse{
+		FlowID:    flow.ID,
+		Status:    flow.Status,
+		AccountID: flow.AccountID,
+		Error:     flow.Error,
+	}
+	if flow.Status == weixinStatusWait || flow.Status == weixinStatusScanned {
+		resp.QRDataURI = flow.QRDataURI
+	}
+	_ = json.NewEncoder(w).Encode(resp)
+}
+
+// saveWeixinBinding writes the token/account ID, enables the Weixin channel,
+// and best-effort restarts the gateway when it is currently running.
+func (h *Handler) saveWeixinBinding(token, accountID string) error {
+	cfg, err := config.LoadConfig(h.configPath)
+	if err != nil {
+		return fmt.Errorf("load config: %w", err)
+	}
+	cfg.Channels.Weixin.SetToken(token)
+	cfg.Channels.Weixin.Enabled = true
+	if accountID != "" {
+		cfg.Channels.Weixin.AccountID = accountID
+	}
+	if err := config.SaveConfig(h.configPath, cfg); err != nil {
+		return err
+	}
+
+	status := h.gatewayStatusData()
+	gatewayStatus, _ := status["gateway_status"].(string)
+	if gatewayStatus != "running" {
+		return nil
+	}
+
+	if _, err := h.RestartGateway(); err != nil {
+		logger.ErrorCF("weixin", "failed to restart gateway after saving binding", map[string]any{
+			"error": err.Error(),
+		})
+	}
+	return nil
+}
+
+// generateQRDataURI encodes content as a QR code PNG and returns a data URI.
+func generateQRDataURI(content string) (string, error) {
+	code, err := qr.Encode(content, qr.L)
+	if err != nil {
+		return "", fmt.Errorf("qr encode: %w", err)
+	}
+	pngBytes := code.PNG()
+	encoded := base64.StdEncoding.EncodeToString(pngBytes)
+	return "data:image/png;base64," + encoded, nil
+}
+
+func newWeixinFlowID() string {
+	buf := make([]byte, 12)
+	if _, err := rand.Read(buf); err != nil {
+		return fmt.Sprintf("wx_%d", time.Now().UnixNano())
+	}
+	return "wx_" + hex.EncodeToString(buf)
+}
+
+func (h *Handler) storeWeixinFlow(flow *weixinFlow) {
+	h.weixinMu.Lock()
+	defer h.weixinMu.Unlock()
+	h.gcWeixinFlowsLocked(time.Now())
+	h.weixinFlows[flow.ID] = flow
+}
+
+func (h *Handler) getWeixinFlow(flowID string) (*weixinFlow, bool) {
+	h.weixinMu.Lock()
+	defer h.weixinMu.Unlock()
+	h.gcWeixinFlowsLocked(time.Now())
+	flow, ok := h.weixinFlows[flowID]
+	if !ok {
+		return nil, false
+	}
+	cp := *flow
+	return &cp, true
+}
+
+func (h *Handler) updateWeixinFlowStatus(flowID, status string) {
+	h.weixinMu.Lock()
+	defer h.weixinMu.Unlock()
+	if flow, ok := h.weixinFlows[flowID]; ok {
+		flow.Status = status
+		flow.UpdatedAt = time.Now()
+	}
+}
+
+func (h *Handler) setWeixinFlowConfirmed(flowID, accountID string) {
+	h.weixinMu.Lock()
+	defer h.weixinMu.Unlock()
+	if flow, ok := h.weixinFlows[flowID]; ok {
+		flow.Status = weixinStatusConfirmed
+		flow.AccountID = accountID
+		flow.UpdatedAt = time.Now()
+	}
+}
+
+func (h *Handler) setWeixinFlowError(flowID, errMsg string) {
+	h.weixinMu.Lock()
+	defer h.weixinMu.Unlock()
+	if flow, ok := h.weixinFlows[flowID]; ok {
+		flow.Status = weixinStatusError
+		flow.Error = errMsg
+		flow.UpdatedAt = time.Now()
+	}
+}
+
+func (h *Handler) gcWeixinFlowsLocked(now time.Time) {
+	for id, flow := range h.weixinFlows {
+		if flow.Status == weixinStatusWait || flow.Status == weixinStatusScanned {
+			if !flow.ExpiresAt.IsZero() && now.After(flow.ExpiresAt) {
+				flow.Status = weixinStatusExpired
+				flow.UpdatedAt = now
+			}
+		}
+		if flow.Status != weixinStatusWait &&
+			flow.Status != weixinStatusScanned &&
+			now.Sub(flow.UpdatedAt) > weixinFlowGCAge {
+			delete(h.weixinFlows, id)
+		}
+	}
+}
diff --git a/web/backend/api/weixin_test.go b/web/backend/api/weixin_test.go
new file mode 100644
index 000000000..03342b72b
--- /dev/null
+++ b/web/backend/api/weixin_test.go
@@ -0,0 +1,56 @@
+package api
+
+import (
+	"io"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+func TestSaveWeixinBindingReturnsSuccessWhenRestartFails(t *testing.T) {
+	resetGatewayTestState(t)
+
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	cfg := config.DefaultConfig()
+	if err := config.SaveConfig(configPath, cfg); err != nil {
+		t.Fatalf("SaveConfig() error = %v", err)
+	}
+
+	originalHealthGet := gatewayHealthGet
+	gatewayHealthGet = func(url string, timeout time.Duration) (*http.Response, error) {
+		return &http.Response{
+			StatusCode: http.StatusOK,
+			Body: io.NopCloser(strings.NewReader(
+				`{"status":"ok","uptime":"1s","pid":` + strconv.Itoa(os.Getpid()) + `}`,
+			)),
+		}, nil
+	}
+	t.Cleanup(func() {
+		gatewayHealthGet = originalHealthGet
+	})
+
+	h := NewHandler(configPath)
+	if err := h.saveWeixinBinding("bot-token", "bot-account"); err != nil {
+		t.Fatalf("saveWeixinBinding() error = %v, want nil after config save succeeds", err)
+	}
+
+	savedCfg, err := config.LoadConfig(configPath)
+	if err != nil {
+		t.Fatalf("LoadConfig() error = %v", err)
+	}
+	if got := savedCfg.Channels.Weixin.Token(); got != "bot-token" {
+		t.Fatalf("Weixin.Token() = %q, want %q", got, "bot-token")
+	}
+	if got := savedCfg.Channels.Weixin.AccountID; got != "bot-account" {
+		t.Fatalf("Weixin.AccountID = %q, want %q", got, "bot-account")
+	}
+	if !savedCfg.Channels.Weixin.Enabled {
+		t.Fatalf("Weixin.Enabled = false, want true")
+	}
+}
diff --git a/web/backend/app_runtime.go b/web/backend/app_runtime.go
new file mode 100644
index 000000000..e3a9ec64f
--- /dev/null
+++ b/web/backend/app_runtime.go
@@ -0,0 +1,62 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/web/backend/utils"
+)
+
+const (
+	browserDelay    = 500 * time.Millisecond
+	shutdownTimeout = 15 * time.Second
+)
+
+// shutdownApp gracefully shuts down all server components and resources.
+// It performs the following shutdown sequence:
+//   - Shuts down the API handler to close all active SSE (Server-Sent Events) connections
+//   - Disables HTTP keep-alive to prevent new connections during shutdown
+//   - Attempts graceful HTTP server shutdown with timeout
+//   - Logs shutdown status at appropriate log levels
+//
+// The function handles timeout errors gracefully by logging them at info level
+// since context.DeadlineExceeded is expected when there are active long-running
+// connections (such as SSE streams).
+//
+// This function should be called during application termination to ensure
+// clean resource cleanup and proper connection closure.
+func shutdownApp() {
+	// First, shutdown API handler to close all SSE connections
+	if apiHandler != nil {
+		apiHandler.Shutdown()
+	}
+
+	if server != nil {
+		// Disable keep-alive to allow graceful shutdown
+		server.SetKeepAlivesEnabled(false)
+
+		ctx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
+		defer cancel()
+		if err := server.Shutdown(ctx); err != nil {
+			// Context deadline exceeded is expected if there are active connections
+			// This is not necessarily an error, so log it at info level
+			if errors.Is(err, context.DeadlineExceeded) {
+				logger.Infof("Server shutdown timeout after %v, forcing close", shutdownTimeout)
+			} else {
+				logger.Errorf("Server shutdown error: %v", err)
+			}
+		} else {
+			logger.Infof("Server shutdown completed successfully")
+		}
+	}
+}
+
+func openBrowser() error {
+	if serverAddr == "" {
+		return fmt.Errorf("server address not set")
+	}
+	return utils.OpenBrowser(serverAddr)
+}
diff --git a/web/backend/dist/.gitkeep b/web/backend/dist/.gitkeep
new file mode 100644
index 000000000..4b533f03a
--- /dev/null
+++ b/web/backend/dist/.gitkeep
@@ -0,0 +1 @@
+# Keep the embedded web backend dist directory in version control.
diff --git a/web/backend/embed.go b/web/backend/embed.go
new file mode 100644
index 000000000..cf0c76bce
--- /dev/null
+++ b/web/backend/embed.go
@@ -0,0 +1,79 @@
+package main
+
+import (
+	"embed"
+	"fmt"
+	"io/fs"
+	"mime"
+	"net/http"
+	"path"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+//go:embed all:dist
+var frontendFS embed.FS
+
+// registerEmbedRoutes sets up the HTTP handler to serve the embedded frontend files
+func registerEmbedRoutes(mux *http.ServeMux) {
+	// Register correct MIME type for SVG files
+	// Go's built-in mime.TypeByExtension returns "image/svg" which is incorrect
+	// The correct MIME type per RFC 6838 is "image/svg+xml"
+	if err := mime.AddExtensionType(".svg", "image/svg+xml"); err != nil {
+		logger.ErrorC("web", fmt.Sprintf("Warning: failed to register SVG MIME type: %v", err))
+	}
+
+	// Attempt to get the subdirectory 'dist' where Vite usually builds
+	subFS, err := fs.Sub(frontendFS, "dist")
+	if err != nil {
+		// Log a warning if dist doesn't exist yet (e.g., during development before a frontend build)
+		logger.WarnC("web",
+			"Warning: no 'dist' folder found in embedded frontend. "+
+				"Ensure you run `pnpm build:backend` in the frontend directory "+
+				"before building the Go backend.",
+		)
+		return
+	}
+
+	fileServer := http.FileServer(http.FS(subFS))
+
+	// Serve static assets and fallback to index.html for SPA routes.
+	mux.Handle(
+		"/",
+		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+			if r.Method != http.MethodGet && r.Method != http.MethodHead {
+				http.NotFound(w, r)
+				return
+			}
+
+			// Keep unknown API paths as 404 instead of falling back to SPA entry.
+			if r.URL.Path == "/api" || strings.HasPrefix(r.URL.Path, "/api/") {
+				http.NotFound(w, r)
+				return
+			}
+
+			cleanPath := path.Clean(strings.TrimPrefix(r.URL.Path, "/"))
+			if cleanPath == "." {
+				cleanPath = ""
+			}
+
+			// Existing static files/directories should be served directly.
+			if cleanPath != "" {
+				if _, statErr := fs.Stat(subFS, cleanPath); statErr == nil {
+					fileServer.ServeHTTP(w, r)
+					return
+				}
+				// Missing asset-like paths should remain 404.
+				if strings.Contains(path.Base(cleanPath), ".") {
+					fileServer.ServeHTTP(w, r)
+					return
+				}
+			}
+
+			indexReq := r.Clone(r.Context())
+			indexReq.URL.Path = "/"
+			fileServer.ServeHTTP(w, indexReq)
+		}),
+	)
+}
diff --git a/web/backend/embed_test.go b/web/backend/embed_test.go
new file mode 100644
index 000000000..c0365488e
--- /dev/null
+++ b/web/backend/embed_test.go
@@ -0,0 +1,33 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestUnknownAPIPathStays404(t *testing.T) {
+	mux := http.NewServeMux()
+	registerEmbedRoutes(mux)
+
+	req := httptest.NewRequest(http.MethodGet, "/api/not-found", nil)
+	rr := httptest.NewRecorder()
+	mux.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want %d", rr.Code, http.StatusNotFound)
+	}
+}
+
+func TestMissingAssetStays404(t *testing.T) {
+	mux := http.NewServeMux()
+	registerEmbedRoutes(mux)
+
+	req := httptest.NewRequest(http.MethodGet, "/assets/not-found.js", nil)
+	rr := httptest.NewRecorder()
+	mux.ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want %d", rr.Code, http.StatusNotFound)
+	}
+}
diff --git a/web/backend/i18n.go b/web/backend/i18n.go
new file mode 100644
index 000000000..9cda9e5d5
--- /dev/null
+++ b/web/backend/i18n.go
@@ -0,0 +1,120 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"strings"
+)
+
+// Language represents the supported languages
+type Language string
+
+const (
+	LanguageEnglish Language = "en"
+	LanguageChinese Language = "zh"
+)
+
+// current language (default: English)
+var currentLang Language = LanguageEnglish
+
+// TranslationKey represents a translation key used for i18n
+type TranslationKey string
+
+const (
+	AppTooltip         TranslationKey = "AppTooltip"
+	MenuOpen           TranslationKey = "MenuOpen"
+	MenuOpenTooltip    TranslationKey = "MenuOpenTooltip"
+	MenuAbout          TranslationKey = "MenuAbout"
+	MenuAboutTooltip   TranslationKey = "MenuAboutTooltip"
+	MenuVersion        TranslationKey = "MenuVersion"
+	MenuVersionTooltip TranslationKey = "MenuVersionTooltip"
+	MenuGitHub         TranslationKey = "MenuGitHub"
+	MenuDocs           TranslationKey = "MenuDocs"
+	MenuRestart        TranslationKey = "MenuRestart"
+	MenuRestartTooltip TranslationKey = "MenuRestartTooltip"
+	MenuQuit           TranslationKey = "MenuQuit"
+	MenuQuitTooltip    TranslationKey = "MenuQuitTooltip"
+	Exiting            TranslationKey = "Exiting"
+	DocUrl             TranslationKey = "DocUrl"
+)
+
+// Translation tables
+// Chinese translations intentionally contain Han script
+//
+//nolint:gosmopolitan
+var translations = map[Language]map[TranslationKey]string{
+	LanguageEnglish: {
+		AppTooltip:         "%s - Web Console",
+		MenuOpen:           "Open Console",
+		MenuOpenTooltip:    "Open PicoClaw console in browser",
+		MenuAbout:          "About",
+		MenuAboutTooltip:   "About PicoClaw",
+		MenuVersion:        "Version: %s",
+		MenuVersionTooltip: "Current version number",
+		MenuGitHub:         "GitHub",
+		MenuDocs:           "Documentation",
+		MenuRestart:        "Restart Service",
+		MenuRestartTooltip: "Restart Gateway service",
+		MenuQuit:           "Quit",
+		MenuQuitTooltip:    "Exit PicoClaw",
+		Exiting:            "Exiting PicoClaw...",
+		DocUrl:             "https://docs.picoclaw.io/docs/",
+	},
+	LanguageChinese: {
+		AppTooltip:         "%s - Web Console",
+		MenuOpen:           "打开控制台",
+		MenuOpenTooltip:    "在浏览器中打开 PicoClaw 控制台",
+		MenuAbout:          "关于",
+		MenuAboutTooltip:   "关于 PicoClaw",
+		MenuVersion:        "版本: %s",
+		MenuVersionTooltip: "当前版本号",
+		MenuGitHub:         "GitHub",
+		MenuDocs:           "文档",
+		MenuRestart:        "重启服务",
+		MenuRestartTooltip: "重启核心服务",
+		MenuQuit:           "退出",
+		MenuQuitTooltip:    "退出 PicoClaw",
+		Exiting:            "正在退出 PicoClaw...",
+		DocUrl:             "https://docs.picoclaw.io/zh-Hans/docs/",
+	},
+}
+
+// SetLanguage sets the current language
+func SetLanguage(lang string) {
+	lang = strings.ToLower(strings.TrimSpace(lang))
+
+	// Extract language code before first underscore or dot
+	// e.g., "en_US.UTF-8" -> "en", "zh_CN" -> "zh"
+	if idx := strings.IndexAny(lang, "_."); idx > 0 {
+		lang = lang[:idx]
+	}
+
+	if lang == "zh" || lang == "zh-cn" || lang == "chinese" {
+		currentLang = LanguageChinese
+	} else {
+		currentLang = LanguageEnglish
+	}
+}
+
+// GetLanguage returns the current language
+func GetLanguage() Language {
+	return currentLang
+}
+
+// T translates a key to the current language
+func T(key TranslationKey, args ...any) string {
+	if trans, ok := translations[currentLang][key]; ok {
+		if len(args) > 0 {
+			return fmt.Sprintf(trans, args...)
+		}
+		return trans
+	}
+	return string(key)
+}
+
+// Initialize i18n from environment variable
+func init() {
+	if lang := os.Getenv("LANG"); lang != "" {
+		SetLanguage(lang)
+	}
+}
diff --git a/cmd/picoclaw-launcher/icon.ico b/web/backend/icon.ico
similarity index 100%
rename from cmd/picoclaw-launcher/icon.ico
rename to web/backend/icon.ico
diff --git a/web/backend/icon.png b/web/backend/icon.png
new file mode 100644
index 000000000..e0b4aab9c
Binary files /dev/null and b/web/backend/icon.png differ
diff --git a/web/backend/launcherconfig/config.go b/web/backend/launcherconfig/config.go
new file mode 100644
index 000000000..4dca45b0e
--- /dev/null
+++ b/web/backend/launcherconfig/config.go
@@ -0,0 +1,113 @@
+package launcherconfig
+
+import (
+	"encoding/json"
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+const (
+	// FileName is the launcher-specific settings file name.
+	FileName = "launcher-config.json"
+	// DefaultPort is the default port for the web launcher.
+	DefaultPort = 18800
+)
+
+// Config stores launch parameters for the web backend service.
+type Config struct {
+	Port         int      `json:"port"`
+	Public       bool     `json:"public"`
+	AllowedCIDRs []string `json:"allowed_cidrs,omitempty"`
+}
+
+// Default returns default launcher settings.
+func Default() Config {
+	return Config{Port: DefaultPort, Public: false}
+}
+
+// Validate checks if launcher settings are valid.
+func Validate(cfg Config) error {
+	if cfg.Port < 1 || cfg.Port > 65535 {
+		return fmt.Errorf("port %d is out of range (1-65535)", cfg.Port)
+	}
+	for _, cidr := range cfg.AllowedCIDRs {
+		if _, _, err := net.ParseCIDR(cidr); err != nil {
+			return fmt.Errorf("invalid CIDR %q", cidr)
+		}
+	}
+	return nil
+}
+
+// NormalizeCIDRs trims entries, removes empty values, and deduplicates CIDRs.
+func NormalizeCIDRs(cidrs []string) []string {
+	if len(cidrs) == 0 {
+		return nil
+	}
+	out := make([]string, 0, len(cidrs))
+	seen := make(map[string]struct{}, len(cidrs))
+	for _, raw := range cidrs {
+		trimmed := strings.TrimSpace(raw)
+		if trimmed == "" {
+			continue
+		}
+		if _, ok := seen[trimmed]; ok {
+			continue
+		}
+		seen[trimmed] = struct{}{}
+		out = append(out, trimmed)
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+// PathForAppConfig returns launcher-config path near the app config file.
+func PathForAppConfig(appConfigPath string) string {
+	dir := filepath.Dir(appConfigPath)
+	if dir == "" || dir == "." {
+		dir = "."
+	}
+	return filepath.Join(dir, FileName)
+}
+
+// Load reads launcher settings; fallback is returned when file does not exist.
+func Load(path string, fallback Config) (Config, error) {
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return fallback, nil
+		}
+		return Config{}, err
+	}
+
+	cfg := fallback
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return Config{}, err
+	}
+	cfg.AllowedCIDRs = NormalizeCIDRs(cfg.AllowedCIDRs)
+	if err := Validate(cfg); err != nil {
+		return Config{}, err
+	}
+	return cfg, nil
+}
+
+// Save writes launcher settings to disk.
+func Save(path string, cfg Config) error {
+	cfg.AllowedCIDRs = NormalizeCIDRs(cfg.AllowedCIDRs)
+	if err := Validate(cfg); err != nil {
+		return err
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return err
+	}
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		return err
+	}
+	data = append(data, '\n')
+	return os.WriteFile(path, data, 0o600)
+}
diff --git a/web/backend/launcherconfig/config_test.go b/web/backend/launcherconfig/config_test.go
new file mode 100644
index 000000000..c63bee09a
--- /dev/null
+++ b/web/backend/launcherconfig/config_test.go
@@ -0,0 +1,89 @@
+package launcherconfig
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestLoadReturnsFallbackWhenMissing(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "launcher-config.json")
+	fallback := Config{Port: 19999, Public: true}
+
+	got, err := Load(path, fallback)
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if got.Port != fallback.Port || got.Public != fallback.Public {
+		t.Fatalf("Load() = %+v, want %+v", got, fallback)
+	}
+}
+
+func TestSaveAndLoadRoundTrip(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "launcher-config.json")
+	want := Config{
+		Port:         18080,
+		Public:       true,
+		AllowedCIDRs: []string{"192.168.1.0/24", "10.0.0.0/8"},
+	}
+
+	if err := Save(path, want); err != nil {
+		t.Fatalf("Save() error = %v", err)
+	}
+	got, err := Load(path, Default())
+	if err != nil {
+		t.Fatalf("Load() error = %v", err)
+	}
+	if got.Port != want.Port || got.Public != want.Public {
+		t.Fatalf("Load() = %+v, want %+v", got, want)
+	}
+	if len(got.AllowedCIDRs) != len(want.AllowedCIDRs) {
+		t.Fatalf("allowed_cidrs len = %d, want %d", len(got.AllowedCIDRs), len(want.AllowedCIDRs))
+	}
+	for i := range want.AllowedCIDRs {
+		if got.AllowedCIDRs[i] != want.AllowedCIDRs[i] {
+			t.Fatalf("allowed_cidrs[%d] = %q, want %q", i, got.AllowedCIDRs[i], want.AllowedCIDRs[i])
+		}
+	}
+
+	stat, err := os.Stat(path)
+	if err != nil {
+		t.Fatalf("Stat() error = %v", err)
+	}
+	if perm := stat.Mode().Perm(); perm != 0o600 {
+		t.Fatalf("file perm = %o, want 600", perm)
+	}
+}
+
+func TestValidateRejectsInvalidPort(t *testing.T) {
+	if err := Validate(Config{Port: 0, Public: false}); err == nil {
+		t.Fatal("Validate() expected error for port 0")
+	}
+	if err := Validate(Config{Port: 65536, Public: false}); err == nil {
+		t.Fatal("Validate() expected error for port 65536")
+	}
+}
+
+func TestValidateRejectsInvalidCIDR(t *testing.T) {
+	err := Validate(Config{
+		Port:         18800,
+		AllowedCIDRs: []string{"192.168.1.0/24", "not-a-cidr"},
+	})
+	if err == nil {
+		t.Fatal("Validate() expected error for invalid CIDR")
+	}
+}
+
+func TestNormalizeCIDRs(t *testing.T) {
+	got := NormalizeCIDRs([]string{" 192.168.1.0/24 ", "", "10.0.0.0/8", "192.168.1.0/24"})
+	want := []string{"192.168.1.0/24", "10.0.0.0/8"}
+	if len(got) != len(want) {
+		t.Fatalf("len(got) = %d, want %d", len(got), len(want))
+	}
+	for i := range want {
+		if got[i] != want[i] {
+			t.Fatalf("got[%d] = %q, want %q", i, got[i], want[i])
+		}
+	}
+}
diff --git a/web/backend/main.go b/web/backend/main.go
new file mode 100644
index 000000000..2f181603e
--- /dev/null
+++ b/web/backend/main.go
@@ -0,0 +1,264 @@
+// PicoClaw Web Console - Web-based chat and management interface
+//
+// Provides a web UI for chatting with PicoClaw via the Pico Channel WebSocket,
+// with configuration management and gateway process control.
+//
+// Usage:
+//
+//	go build -o picoclaw-web ./web/backend/
+//	./picoclaw-web [config.json]
+//	./picoclaw-web -public config.json
+
+package main
+
+import (
+	"errors"
+	"flag"
+	"fmt"
+	"net/http"
+	"os"
+	"os/signal"
+	"path/filepath"
+	"strconv"
+	"syscall"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/web/backend/api"
+	"github.com/sipeed/picoclaw/web/backend/launcherconfig"
+	"github.com/sipeed/picoclaw/web/backend/middleware"
+	"github.com/sipeed/picoclaw/web/backend/utils"
+)
+
+const (
+	appName = "PicoClaw"
+
+	logPath   = "logs"
+	panicFile = "launcher_panic.log"
+	logFile   = "launcher.log"
+)
+
+var (
+	appVersion = config.Version
+
+	server     *http.Server
+	serverAddr string
+	apiHandler *api.Handler
+
+	noBrowser *bool
+)
+
+func main() {
+	port := flag.String("port", "18800", "Port to listen on")
+	public := flag.Bool("public", false, "Listen on all interfaces (0.0.0.0) instead of localhost only")
+	noBrowser = flag.Bool("no-browser", false, "Do not auto-open browser on startup")
+	lang := flag.String("lang", "", "Language: en (English) or zh (Chinese). Default: auto-detect from system locale")
+	console := flag.Bool("console", false, "Console mode, no GUI")
+
+	flag.Usage = func() {
+		fmt.Fprintf(os.Stderr, "PicoClaw Launcher - A web-based configuration editor\n\n")
+		fmt.Fprintf(os.Stderr, "Usage: %s [options] [config.json]\n\n", os.Args[0])
+		fmt.Fprintf(os.Stderr, "Arguments:\n")
+		fmt.Fprintf(os.Stderr, "  config.json    Path to the configuration file (default: ~/.picoclaw/config.json)\n\n")
+		fmt.Fprintf(os.Stderr, "Options:\n")
+		flag.PrintDefaults()
+		fmt.Fprintf(os.Stderr, "\nExamples:\n")
+		fmt.Fprintf(os.Stderr, "  %s                          Use default config path\n", os.Args[0])
+		fmt.Fprintf(os.Stderr, "  %s ./config.json             Specify a config file\n", os.Args[0])
+		fmt.Fprintf(
+			os.Stderr,
+			"  %s -public ./config.json     Allow access from other devices on the network\n",
+			os.Args[0],
+		)
+	}
+	flag.Parse()
+
+	// Initialize logger
+	picoHome := utils.GetPicoclawHome()
+
+	f := filepath.Join(picoHome, logPath, panicFile)
+	panicFunc, err := logger.InitPanic(f)
+	if err != nil {
+		panic(fmt.Sprintf("error initializing panic log: %v", err))
+	}
+	defer panicFunc()
+
+	// By default, detect terminal to decide console log behavior
+	// If -console-logs flag is explicitly set, it overrides the detection
+	enableConsole := *console
+	if !enableConsole {
+		// Disable console logging by setting level to Fatal (no output)
+		logger.SetConsoleLevel(logger.FATAL)
+
+		f := filepath.Join(picoHome, logPath, logFile)
+		if err = logger.EnableFileLogging(f); err != nil {
+			panic(fmt.Sprintf("error enabling file logging: %v", err))
+		}
+		defer logger.DisableFileLogging()
+	}
+
+	logger.InfoC("web", "PicoClaw Launcher starting...")
+	logger.InfoC("web", fmt.Sprintf("PicoClaw Home: %s", picoHome))
+
+	// Set language from command line or auto-detect
+	if *lang != "" {
+		SetLanguage(*lang)
+	}
+
+	// Resolve config path
+	configPath := utils.GetDefaultConfigPath()
+	if flag.NArg() > 0 {
+		configPath = flag.Arg(0)
+	}
+
+	absPath, err := filepath.Abs(configPath)
+	if err != nil {
+		logger.Fatalf("Failed to resolve config path: %v", err)
+	}
+	err = utils.EnsureOnboarded(absPath)
+	if err != nil {
+		logger.Errorf("Warning: Failed to initialize PicoClaw config automatically: %v", err)
+	}
+
+	var explicitPort bool
+	var explicitPublic bool
+	flag.Visit(func(f *flag.Flag) {
+		switch f.Name {
+		case "port":
+			explicitPort = true
+		case "public":
+			explicitPublic = true
+		}
+	})
+
+	launcherPath := launcherconfig.PathForAppConfig(absPath)
+	launcherCfg, err := launcherconfig.Load(launcherPath, launcherconfig.Default())
+	if err != nil {
+		logger.ErrorC("web", fmt.Sprintf("Warning: Failed to load %s: %v", launcherPath, err))
+		launcherCfg = launcherconfig.Default()
+	}
+
+	effectivePort := *port
+	effectivePublic := *public
+	if !explicitPort {
+		effectivePort = strconv.Itoa(launcherCfg.Port)
+	}
+	if !explicitPublic {
+		effectivePublic = launcherCfg.Public
+	}
+
+	portNum, err := strconv.Atoi(effectivePort)
+	if err != nil || portNum < 1 || portNum > 65535 {
+		if err == nil {
+			err = errors.New("must be in range 1-65535")
+		}
+		logger.Fatalf("Invalid port %q: %v", effectivePort, err)
+	}
+
+	// Determine listen address
+	var addr string
+	if effectivePublic {
+		addr = "0.0.0.0:" + effectivePort
+	} else {
+		addr = "127.0.0.1:" + effectivePort
+	}
+
+	// Initialize Server components
+	mux := http.NewServeMux()
+
+	// API Routes (e.g. /api/status)
+	apiHandler = api.NewHandler(absPath)
+	if _, err = apiHandler.EnsurePicoChannel(""); err != nil {
+		logger.ErrorC("web", fmt.Sprintf("Warning: failed to ensure pico channel on startup: %v", err))
+	}
+	apiHandler.SetServerOptions(portNum, effectivePublic, explicitPublic, launcherCfg.AllowedCIDRs)
+	apiHandler.RegisterRoutes(mux)
+
+	// Frontend Embedded Assets
+	registerEmbedRoutes(mux)
+
+	accessControlledMux, err := middleware.IPAllowlist(launcherCfg.AllowedCIDRs, mux)
+	if err != nil {
+		logger.Fatalf("Invalid allowed CIDR configuration: %v", err)
+	}
+
+	// Apply middleware stack
+	handler := middleware.Recoverer(
+		middleware.Logger(
+			middleware.JSONContentType(accessControlledMux),
+		),
+	)
+
+	// Print startup banner (only in console mode)
+	if enableConsole {
+		fmt.Print(utils.Banner)
+		fmt.Println()
+		fmt.Println("  Open the following URL in your browser:")
+		fmt.Println()
+		fmt.Printf("    >> http://localhost:%s <<\n", effectivePort)
+		if effectivePublic {
+			if ip := utils.GetLocalIP(); ip != "" {
+				fmt.Printf("    >> http://%s:%s <<\n", ip, effectivePort)
+			}
+		}
+		fmt.Println()
+	}
+
+	// Log startup info to file
+	logger.InfoC("web", fmt.Sprintf("Server will listen on http://localhost:%s", effectivePort))
+	if effectivePublic {
+		if ip := utils.GetLocalIP(); ip != "" {
+			logger.InfoC("web", fmt.Sprintf("Public access enabled at http://%s:%s", ip, effectivePort))
+		}
+	}
+
+	// Share the local URL with the launcher runtime.
+	serverAddr = fmt.Sprintf("http://localhost:%s", effectivePort)
+
+	// Auto-open browser will be handled by the launcher runtime.
+
+	// Auto-start gateway after backend starts listening.
+	go func() {
+		time.Sleep(1 * time.Second)
+		apiHandler.TryAutoStartGateway()
+	}()
+
+	// Start the Server in a goroutine
+	server = &http.Server{Addr: addr, Handler: handler}
+	go func() {
+		logger.InfoC("web", fmt.Sprintf("Server listening on %s", addr))
+		if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+			logger.Fatalf("Server failed to start: %v", err)
+		}
+	}()
+
+	defer shutdownApp()
+
+	// Start system tray or run in console mode
+	if enableConsole {
+		if !*noBrowser {
+			// Auto-open browser after systray is ready (if not disabled)
+			// Check no-browser flag via environment or pass as parameter if needed
+			if err := openBrowser(); err != nil {
+				logger.Errorf("Warning: Failed to auto-open browser: %v", err)
+			}
+		}
+
+		sigChan := make(chan os.Signal, 1)
+		signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
+
+		// Main event loop - wait for signals or config changes
+		for {
+			select {
+			case <-sigChan:
+				logger.Info("Shutting down...")
+
+				return
+			}
+		}
+	} else {
+		// GUI mode: start system tray
+		runTray()
+	}
+}
diff --git a/web/backend/middleware/access_control.go b/web/backend/middleware/access_control.go
new file mode 100644
index 000000000..159d60c3e
--- /dev/null
+++ b/web/backend/middleware/access_control.go
@@ -0,0 +1,64 @@
+package middleware
+
+import (
+	"fmt"
+	"net"
+	"net/http"
+	"strings"
+)
+
+// IPAllowlist restricts access to requests from configured CIDR ranges.
+// Loopback addresses are always allowed for local administration.
+// Empty CIDR list means no restriction.
+func IPAllowlist(allowedCIDRs []string, next http.Handler) (http.Handler, error) {
+	if len(allowedCIDRs) == 0 {
+		return next, nil
+	}
+
+	nets := make([]*net.IPNet, 0, len(allowedCIDRs))
+	for _, cidr := range allowedCIDRs {
+		_, ipNet, err := net.ParseCIDR(cidr)
+		if err != nil {
+			return nil, fmt.Errorf("invalid CIDR %q: %w", cidr, err)
+		}
+		nets = append(nets, ipNet)
+	}
+
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		ip := clientIPFromRemoteAddr(r.RemoteAddr)
+		if ip == nil {
+			rejectByPolicy(w, r)
+			return
+		}
+		if ip.IsLoopback() {
+			next.ServeHTTP(w, r)
+			return
+		}
+		for _, ipNet := range nets {
+			if ipNet.Contains(ip) {
+				next.ServeHTTP(w, r)
+				return
+			}
+		}
+
+		rejectByPolicy(w, r)
+	}), nil
+}
+
+func clientIPFromRemoteAddr(remoteAddr string) net.IP {
+	host := remoteAddr
+	if h, _, err := net.SplitHostPort(remoteAddr); err == nil {
+		host = h
+	}
+	return net.ParseIP(host)
+}
+
+func rejectByPolicy(w http.ResponseWriter, r *http.Request) {
+	if strings.HasPrefix(r.URL.Path, "/api/") {
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(http.StatusForbidden)
+		_, _ = w.Write([]byte(`{"error":"access denied by network policy"}`))
+		return
+	}
+	http.Error(w, "Forbidden", http.StatusForbidden)
+}
diff --git a/web/backend/middleware/access_control_test.go b/web/backend/middleware/access_control_test.go
new file mode 100644
index 000000000..259fd4a4c
--- /dev/null
+++ b/web/backend/middleware/access_control_test.go
@@ -0,0 +1,86 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestIPAllowlist_EmptyCIDRsAllowsAll(t *testing.T) {
+	h, err := IPAllowlist(nil, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	if err != nil {
+		t.Fatalf("IPAllowlist() error = %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.RemoteAddr = "203.0.113.5:1234"
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}
+
+func TestIPAllowlist_RejectsOutsideCIDR(t *testing.T) {
+	h, err := IPAllowlist([]string{"192.168.1.0/24"}, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	if err != nil {
+		t.Fatalf("IPAllowlist() error = %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/api/config", nil)
+	req.RemoteAddr = "10.0.0.8:1234"
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusForbidden)
+	}
+}
+
+func TestIPAllowlist_AllowsInsideCIDR(t *testing.T) {
+	h, err := IPAllowlist([]string{"192.168.1.0/24"}, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	if err != nil {
+		t.Fatalf("IPAllowlist() error = %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.RemoteAddr = "192.168.1.88:1234"
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}
+
+func TestIPAllowlist_AlwaysAllowsLoopback(t *testing.T) {
+	h, err := IPAllowlist([]string{"192.168.1.0/24"}, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+	if err != nil {
+		t.Fatalf("IPAllowlist() error = %v", err)
+	}
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/", nil)
+	req.RemoteAddr = "127.0.0.1:1234"
+	h.ServeHTTP(rec, req)
+
+	if rec.Code != http.StatusOK {
+		t.Fatalf("status = %d, want %d", rec.Code, http.StatusOK)
+	}
+}
+
+func TestIPAllowlist_InvalidCIDR(t *testing.T) {
+	_, err := IPAllowlist([]string{"bad-cidr"}, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {}))
+	if err == nil {
+		t.Fatal("IPAllowlist() expected error for invalid CIDR")
+	}
+}
diff --git a/web/backend/middleware/middleware.go b/web/backend/middleware/middleware.go
new file mode 100644
index 000000000..5e0dfeb90
--- /dev/null
+++ b/web/backend/middleware/middleware.go
@@ -0,0 +1,69 @@
+package middleware
+
+import (
+	"fmt"
+	"net/http"
+	"runtime/debug"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+// JSONContentType sets the Content-Type header to application/json for
+// API requests handled by the wrapped handler.
+func JSONContentType(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if len(r.URL.Path) >= 5 && r.URL.Path[:5] == "/api/" {
+			w.Header().Set("Content-Type", "application/json")
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// responseRecorder wraps http.ResponseWriter to capture the status code.
+type responseRecorder struct {
+	http.ResponseWriter
+	statusCode int
+}
+
+func (rr *responseRecorder) WriteHeader(code int) {
+	rr.statusCode = code
+	rr.ResponseWriter.WriteHeader(code)
+}
+
+// Flush delegates to the underlying ResponseWriter if it implements http.Flusher.
+func (rr *responseRecorder) Flush() {
+	if f, ok := rr.ResponseWriter.(http.Flusher); ok {
+		f.Flush()
+	}
+}
+
+// Unwrap returns the underlying ResponseWriter so that http.ResponseController
+// and interface checks (like http.Flusher) can see through the wrapper.
+func (rr *responseRecorder) Unwrap() http.ResponseWriter {
+	return rr.ResponseWriter
+}
+
+// Logger logs each HTTP request with method, path, status code, and duration.
+func Logger(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		start := time.Now()
+		rec := &responseRecorder{ResponseWriter: w, statusCode: http.StatusOK}
+		next.ServeHTTP(rec, r)
+		logger.DebugC("http", fmt.Sprintf("%s %s %d %s", r.Method, r.URL.Path, rec.statusCode, time.Since(start)))
+	})
+}
+
+// Recoverer recovers from panics in downstream handlers and returns a 500
+// Internal Server Error response.
+func Recoverer(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		defer func() {
+			if err := recover(); err != nil {
+				logger.ErrorC("http", fmt.Sprintf("panic recovered: %v\n%s", err, debug.Stack()))
+				http.Error(w, `{"error":"internal server error"}`, http.StatusInternalServerError)
+			}
+		}()
+		next.ServeHTTP(w, r)
+	})
+}
diff --git a/web/backend/model/status.go b/web/backend/model/status.go
new file mode 100644
index 000000000..325981502
--- /dev/null
+++ b/web/backend/model/status.go
@@ -0,0 +1,8 @@
+package model
+
+// StatusResponse represents the response payload for the GET /api/status endpoint.
+type StatusResponse struct {
+	Status  string `json:"status"`
+	Version string `json:"version"`
+	Uptime  string `json:"uptime"`
+}
diff --git a/web/backend/systray.go b/web/backend/systray.go
new file mode 100644
index 000000000..fde2e115e
--- /dev/null
+++ b/web/backend/systray.go
@@ -0,0 +1,100 @@
+//go:build (!darwin && !freebsd) || cgo
+
+package main
+
+import (
+	_ "embed"
+	"fmt"
+
+	"fyne.io/systray"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+	"github.com/sipeed/picoclaw/web/backend/utils"
+)
+
+func runTray() {
+	systray.Run(onReady, onExit)
+}
+
+// onReady is called when the system tray is ready
+func onReady() {
+	// Set icon and tooltip
+	systray.SetIcon(getIcon())
+	systray.SetTooltip(fmt.Sprintf(T(AppTooltip), appName))
+
+	// Create menu items
+	mOpen := systray.AddMenuItem(T(MenuOpen), T(MenuOpenTooltip))
+	mAbout := systray.AddMenuItem(T(MenuAbout), T(MenuAboutTooltip))
+
+	// Add version info under About menu
+	mVersion := mAbout.AddSubMenuItem(fmt.Sprintf(T(MenuVersion), appVersion), T(MenuVersionTooltip))
+	mVersion.Disable()
+	mRepo := mAbout.AddSubMenuItem(T(MenuGitHub), "")
+	mDocs := mAbout.AddSubMenuItem(T(MenuDocs), "")
+
+	systray.AddSeparator()
+
+	// Add restart option
+	mRestart := systray.AddMenuItem(T(MenuRestart), T(MenuRestartTooltip))
+
+	systray.AddSeparator()
+
+	// Quit option
+	mQuit := systray.AddMenuItem(T(MenuQuit), T(MenuQuitTooltip))
+
+	// Handle menu clicks
+	go func() {
+		for {
+			select {
+			case <-mOpen.ClickedCh:
+				if err := openBrowser(); err != nil {
+					logger.Errorf("Failed to open browser: %v", err)
+				}
+
+			case <-mVersion.ClickedCh:
+				// Version info - do nothing, just shows current version
+
+			case <-mRepo.ClickedCh:
+				if err := utils.OpenBrowser("https://github.com/sipeed/picoclaw"); err != nil {
+					logger.Errorf("Failed to open GitHub: %v", err)
+				}
+
+			case <-mDocs.ClickedCh:
+				if err := utils.OpenBrowser(T(DocUrl)); err != nil {
+					logger.Errorf("Failed to open docs: %v", err)
+				}
+
+			case <-mRestart.ClickedCh:
+				fmt.Println("Restart request received...")
+				if apiHandler != nil {
+					if pid, err := apiHandler.RestartGateway(); err != nil {
+						logger.Errorf("Failed to restart gateway: %v", err)
+					} else {
+						logger.Infof("Gateway restarted (PID: %d)", pid)
+					}
+				}
+
+			case <-mQuit.ClickedCh:
+				systray.Quit()
+			}
+		}
+	}()
+
+	if !*noBrowser {
+		// Auto-open browser after systray is ready (if not disabled)
+		// Check no-browser flag via environment or pass as parameter if needed
+		if err := openBrowser(); err != nil {
+			logger.Errorf("Warning: Failed to auto-open browser: %v", err)
+		}
+	}
+}
+
+// onExit is called when the system tray is exiting
+func onExit() {
+	logger.Info(T(Exiting))
+}
+
+// getIcon returns the system tray icon
+func getIcon() []byte {
+	return iconData
+}
diff --git a/web/backend/systray_unix.go b/web/backend/systray_unix.go
new file mode 100644
index 000000000..0f9d2bb51
--- /dev/null
+++ b/web/backend/systray_unix.go
@@ -0,0 +1,8 @@
+//go:build !windows
+
+package main
+
+import _ "embed"
+
+//go:embed icon.png
+var iconData []byte
diff --git a/web/backend/systray_windows.go b/web/backend/systray_windows.go
new file mode 100644
index 000000000..cc1885155
--- /dev/null
+++ b/web/backend/systray_windows.go
@@ -0,0 +1,8 @@
+//go:build windows
+
+package main
+
+import _ "embed"
+
+//go:embed icon.ico
+var iconData []byte
diff --git a/web/backend/tray_stub_nocgo.go b/web/backend/tray_stub_nocgo.go
new file mode 100644
index 000000000..13ecfd2cb
--- /dev/null
+++ b/web/backend/tray_stub_nocgo.go
@@ -0,0 +1,33 @@
+//go:build (darwin || freebsd) && !cgo
+
+package main
+
+import (
+	"context"
+	"os"
+	"os/signal"
+	"runtime"
+	"syscall"
+	"time"
+
+	"github.com/sipeed/picoclaw/pkg/logger"
+)
+
+func runTray() {
+	logger.Infof("System tray is unavailable in %s builds without cgo; running without tray", runtime.GOOS)
+
+	if !*noBrowser {
+		go func() {
+			time.Sleep(browserDelay)
+			if err := openBrowser(); err != nil {
+				logger.Errorf("Warning: Failed to auto-open browser: %v", err)
+			}
+		}()
+	}
+
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	<-ctx.Done()
+	shutdownApp()
+}
diff --git a/web/backend/utils/banner.go b/web/backend/utils/banner.go
new file mode 100644
index 000000000..a64ea6390
--- /dev/null
+++ b/web/backend/utils/banner.go
@@ -0,0 +1,15 @@
+package utils
+
+const (
+	colorBlue  = "\x1b[38;2;62;93;185m"
+	colorRed   = "\x1b[38;2;213;70;70m"
+	colorReset = "\x1b[0m"
+	Banner     = "\r\n" +
+		colorBlue + "██████╗ ██╗ ██████╗ ██████╗ " + colorRed + " ██████╗██╗      █████╗ ██╗    ██╗\n" +
+		colorBlue + "██╔══██╗██║██╔════╝██╔═══██╗" + colorRed + "██╔════╝██║     ██╔══██╗██║    ██║\n" +
+		colorBlue + "██████╔╝██║██║     ██║   ██║" + colorRed + "██║     ██║     ███████║██║ █╗ ██║\n" +
+		colorBlue + "██╔═══╝ ██║██║     ██║   ██║" + colorRed + "██║     ██║     ██╔══██║██║███╗██║\n" +
+		colorBlue + "██║     ██║╚██████╗╚██████╔╝" + colorRed + "╚██████╗███████╗██║  ██║╚███╔███╔╝\n" +
+		colorBlue + "╚═╝     ╚═╝ ╚═════╝ ╚═════╝ " + colorRed + " ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝\n" +
+		colorReset
+)
diff --git a/web/backend/utils/onboard.go b/web/backend/utils/onboard.go
new file mode 100644
index 000000000..81475ac80
--- /dev/null
+++ b/web/backend/utils/onboard.go
@@ -0,0 +1,44 @@
+package utils
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"strings"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+var execCommand = exec.Command
+
+func EnsureOnboarded(configPath string) error {
+	_, err := os.Stat(configPath)
+	if err == nil {
+		return nil
+	}
+	if !os.IsNotExist(err) {
+		return fmt.Errorf("stat config: %w", err)
+	}
+
+	cmd := execCommand(FindPicoclawBinary(), "onboard")
+	cmd.Env = append(os.Environ(), config.EnvConfig+"="+configPath)
+	cmd.Stdin = strings.NewReader("n\n")
+
+	output, err := cmd.CombinedOutput()
+	if err != nil {
+		trimmed := strings.TrimSpace(string(output))
+		if trimmed == "" {
+			return fmt.Errorf("run onboard: %w", err)
+		}
+		return fmt.Errorf("run onboard: %w: %s", err, trimmed)
+	}
+
+	if _, err := os.Stat(configPath); err != nil {
+		if os.IsNotExist(err) {
+			return fmt.Errorf("onboard completed but did not create config %s", configPath)
+		}
+		return fmt.Errorf("verify config after onboard: %w", err)
+	}
+
+	return nil
+}
diff --git a/web/backend/utils/onboard_test.go b/web/backend/utils/onboard_test.go
new file mode 100644
index 000000000..06f967e76
--- /dev/null
+++ b/web/backend/utils/onboard_test.go
@@ -0,0 +1,101 @@
+package utils
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestEnsureOnboardedSkipsWhenConfigExists(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	if err := os.WriteFile(configPath, []byte(`{}`), 0o644); err != nil {
+		t.Fatalf("WriteFile() error = %v", err)
+	}
+
+	origExecCommand := execCommand
+	defer func() { execCommand = origExecCommand }()
+
+	called := false
+	execCommand = func(name string, args ...string) *exec.Cmd {
+		called = true
+		return exec.Command("sh", "-c", "exit 1")
+	}
+
+	if err := EnsureOnboarded(configPath); err != nil {
+		t.Fatalf("EnsureOnboarded() error = %v", err)
+	}
+	if called {
+		t.Fatal("expected onboard command not to run when config already exists")
+	}
+}
+
+func TestEnsureOnboardedRunsOnboardWhenConfigMissing(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+	t.Setenv("EXPECTED_CONFIG_PATH", configPath)
+
+	origExecCommand := execCommand
+	defer func() { execCommand = origExecCommand }()
+
+	var gotName string
+	var gotArgs []string
+	execCommand = func(name string, args ...string) *exec.Cmd {
+		gotName = name
+		gotArgs = append([]string(nil), args...)
+		return exec.Command(
+			"sh",
+			"-c",
+			`test "$PICOCLAW_CONFIG" = "$EXPECTED_CONFIG_PATH" &&
+mkdir -p "$(dirname "$PICOCLAW_CONFIG")" &&
+printf '{}' > "$PICOCLAW_CONFIG"`,
+		)
+	}
+
+	if err := EnsureOnboarded(configPath); err != nil {
+		t.Fatalf("EnsureOnboarded() error = %v", err)
+	}
+	if gotName == "" {
+		t.Fatal("expected onboard command to run")
+	}
+	if len(gotArgs) != 1 || gotArgs[0] != "onboard" {
+		t.Fatalf("command args = %#v, want []string{\"onboard\"}", gotArgs)
+	}
+	if _, err := os.Stat(configPath); err != nil {
+		t.Fatalf("expected config to be created: %v", err)
+	}
+}
+
+func TestEnsureOnboardedFailsWhenOnboardDoesNotCreateConfig(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+
+	origExecCommand := execCommand
+	defer func() { execCommand = origExecCommand }()
+
+	execCommand = func(name string, args ...string) *exec.Cmd {
+		return exec.Command("sh", "-c", "exit 0")
+	}
+
+	if err := EnsureOnboarded(configPath); err == nil {
+		t.Fatal("EnsureOnboarded() error = nil, want failure when onboard does not create config")
+	}
+}
+
+func TestEnsureOnboardedIncludesOnboardOutputOnFailure(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "config.json")
+
+	origExecCommand := execCommand
+	defer func() { execCommand = origExecCommand }()
+
+	execCommand = func(name string, args ...string) *exec.Cmd {
+		return exec.Command("sh", "-c", "echo onboarding failed >&2; exit 2")
+	}
+
+	err := EnsureOnboarded(configPath)
+	if err == nil {
+		t.Fatal("EnsureOnboarded() error = nil, want failure")
+	}
+	if !strings.Contains(err.Error(), "onboarding failed") {
+		t.Fatalf("error = %q, want onboard output included", err)
+	}
+}
diff --git a/web/backend/utils/runtime.go b/web/backend/utils/runtime.go
new file mode 100644
index 000000000..772cd7ec0
--- /dev/null
+++ b/web/backend/utils/runtime.go
@@ -0,0 +1,85 @@
+package utils
+
+import (
+	"fmt"
+	"net"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+
+	"github.com/sipeed/picoclaw/pkg/config"
+)
+
+// GetPicoclawHome returns the picoclaw home directory.
+// Priority: $PICOCLAW_HOME > ~/.picoclaw
+func GetPicoclawHome() string {
+	if home := os.Getenv(config.EnvHome); home != "" {
+		return home
+	}
+	home, _ := os.UserHomeDir()
+	return filepath.Join(home, ".picoclaw")
+}
+
+// GetDefaultConfigPath returns the default path to the picoclaw config file.
+func GetDefaultConfigPath() string {
+	if configPath := os.Getenv(config.EnvConfig); configPath != "" {
+		return configPath
+	}
+	return filepath.Join(GetPicoclawHome(), "config.json")
+}
+
+// FindPicoclawBinary locates the picoclaw executable.
+// Search order:
+//  1. PICOCLAW_BINARY environment variable (explicit override)
+//  2. Same directory as the current executable
+//  3. Falls back to "picoclaw" and relies on $PATH
+func FindPicoclawBinary() string {
+	binaryName := "picoclaw"
+	if runtime.GOOS == "windows" {
+		binaryName = "picoclaw.exe"
+	}
+
+	if p := os.Getenv(config.EnvBinary); p != "" {
+		if info, _ := os.Stat(p); info != nil && !info.IsDir() {
+			return p
+		}
+	}
+
+	if exe, err := os.Executable(); err == nil {
+		candidate := filepath.Join(filepath.Dir(exe), binaryName)
+		if info, err := os.Stat(candidate); err == nil && !info.IsDir() {
+			return candidate
+		}
+	}
+
+	return "picoclaw"
+}
+
+// GetLocalIP returns the local IP address of the machine.
+func GetLocalIP() string {
+	addrs, err := net.InterfaceAddrs()
+	if err != nil {
+		return ""
+	}
+	for _, a := range addrs {
+		if ipnet, ok := a.(*net.IPNet); ok && !ipnet.IP.IsLoopback() && ipnet.IP.To4() != nil {
+			return ipnet.IP.String()
+		}
+	}
+	return ""
+}
+
+// OpenBrowser automatically opens the given URL in the default browser.
+func OpenBrowser(url string) error {
+	switch runtime.GOOS {
+	case "linux":
+		return exec.Command("xdg-open", url).Start()
+	case "windows":
+		return exec.Command("rundll32", "url.dll,FileProtocolHandler", url).Start()
+	case "darwin":
+		return exec.Command("open", url).Start()
+	default:
+		return fmt.Errorf("unsupported platform")
+	}
+}
diff --git a/cmd/picoclaw-launcher/winres/winres.json b/web/backend/winres/winres.json
similarity index 100%
rename from cmd/picoclaw-launcher/winres/winres.json
rename to web/backend/winres/winres.json
diff --git a/web/frontend/.editorconfig b/web/frontend/.editorconfig
new file mode 100644
index 000000000..a8c0f1ecf
--- /dev/null
+++ b/web/frontend/.editorconfig
@@ -0,0 +1,7 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+end_of_line = lf
\ No newline at end of file
diff --git a/web/frontend/.gitignore b/web/frontend/.gitignore
new file mode 100644
index 000000000..72e68ffba
--- /dev/null
+++ b/web/frontend/.gitignore
@@ -0,0 +1,25 @@
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+.tanstack
diff --git a/web/frontend/.prettierignore b/web/frontend/.prettierignore
new file mode 100644
index 000000000..7040bf59e
--- /dev/null
+++ b/web/frontend/.prettierignore
@@ -0,0 +1,5 @@
+package-lock.json
+pnpm-lock.yaml
+yarn.lock
+routeTree.gen.ts
+src/components/ui
\ No newline at end of file
diff --git a/web/frontend/components.json b/web/frontend/components.json
new file mode 100644
index 000000000..9d5329694
--- /dev/null
+++ b/web/frontend/components.json
@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "radix-vega",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "tabler",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}
diff --git a/web/frontend/eslint.config.js b/web/frontend/eslint.config.js
new file mode 100644
index 000000000..bc9c64344
--- /dev/null
+++ b/web/frontend/eslint.config.js
@@ -0,0 +1,31 @@
+import js from "@eslint/js"
+import eslintConfigPrettier from "eslint-config-prettier"
+import reactHooks from "eslint-plugin-react-hooks"
+import reactRefresh from "eslint-plugin-react-refresh"
+import { defineConfig, globalIgnores } from "eslint/config"
+import globals from "globals"
+import tseslint from "typescript-eslint"
+
+export default defineConfig([
+  globalIgnores(["dist", "src/components/ui", "src/routeTree.gen.ts"]),
+  {
+    files: ["**/*.{ts,tsx}"],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+      eslintConfigPrettier,
+    ],
+    languageOptions: {
+      ecmaVersion: "latest",
+      globals: globals.browser,
+    },
+    rules: {
+      "react-refresh/only-export-components": [
+        "warn",
+        { allowConstantExport: true },
+      ],
+    },
+  },
+])
diff --git a/web/frontend/index.html b/web/frontend/index.html
new file mode 100644
index 000000000..d3bdd90f8
--- /dev/null
+++ b/web/frontend/index.html
@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="shortcut icon" href="/favicon.ico" />
+    <link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
+    <link rel="manifest" href="/site.webmanifest" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>PicoClaw</title>
+  </head>
+
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>
diff --git a/web/frontend/package.json b/web/frontend/package.json
new file mode 100644
index 000000000..8053d1f2a
--- /dev/null
+++ b/web/frontend/package.json
@@ -0,0 +1,65 @@
+{
+  "name": "picoclaw-web",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "build:backend": "tsc -b && vite build --outDir ../backend/dist --emptyOutDir && node ./scripts/ensure-backend-gitkeep.cjs",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "format": "prettier --check .",
+    "check": "prettier --write . && eslint --fix"
+  },
+  "dependencies": {
+    "@fontsource-variable/inter": "^5.2.8",
+    "@tabler/icons-react": "^3.40.0",
+    "@tailwindcss/vite": "^4.2.2",
+    "@tanstack/react-query": "^5.90.21",
+    "@tanstack/react-router": "^1.167.0",
+    "@tanstack/react-router-devtools": "^1.163.3",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "dayjs": "^1.11.20",
+    "i18next": "^25.8.14",
+    "i18next-browser-languagedetector": "^8.2.1",
+    "jotai": "^2.18.1",
+    "radix-ui": "^1.4.3",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-i18next": "^16.5.8",
+    "react-markdown": "^10.1.0",
+    "react-textarea-autosize": "^8.5.9",
+    "rehype-raw": "^7.0.0",
+    "rehype-sanitize": "^6.0.0",
+    "remark-gfm": "^4.0.1",
+    "shadcn": "^4.1.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.5.0",
+    "tailwindcss": "^4.2.2",
+    "tw-animate-css": "^1.4.0",
+    "wrap-ansi": "^10.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@tailwindcss/typography": "^0.5.19",
+    "@tanstack/router-plugin": "^1.164.0",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/node": "^25.5.0",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.57.1",
+    "@vitejs/plugin-react": "^5.2.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.26",
+    "globals": "^16.5.0",
+    "prettier": "^3.8.1",
+    "prettier-plugin-tailwindcss": "^0.7.2",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.57.1",
+    "vite": "^7.3.1"
+  }
+}
diff --git a/web/frontend/pnpm-lock.yaml b/web/frontend/pnpm-lock.yaml
new file mode 100644
index 000000000..edaf49ccc
--- /dev/null
+++ b/web/frontend/pnpm-lock.yaml
@@ -0,0 +1,8090 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    dependencies:
+      '@fontsource-variable/inter':
+        specifier: ^5.2.8
+        version: 5.2.8
+      '@tabler/icons-react':
+        specifier: ^3.40.0
+        version: 3.40.0(react@19.2.4)
+      '@tailwindcss/vite':
+        specifier: ^4.2.2
+        version: 4.2.2(vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0))
+      '@tanstack/react-query':
+        specifier: ^5.90.21
+        version: 5.91.2(react@19.2.4)
+      '@tanstack/react-router':
+        specifier: ^1.167.0
+        version: 1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@tanstack/react-router-devtools':
+        specifier: ^1.163.3
+        version: 1.166.9(@tanstack/react-router@1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@tanstack/router-core@1.167.5)(csstype@3.2.3)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      class-variance-authority:
+        specifier: ^0.7.1
+        version: 0.7.1
+      clsx:
+        specifier: ^2.1.1
+        version: 2.1.1
+      dayjs:
+        specifier: ^1.11.20
+        version: 1.11.20
+      i18next:
+        specifier: ^25.8.14
+        version: 25.8.20(typescript@5.9.3)
+      i18next-browser-languagedetector:
+        specifier: ^8.2.1
+        version: 8.2.1
+      jotai:
+        specifier: ^2.18.1
+        version: 2.18.1(@babel/core@7.29.0)(@babel/template@7.28.6)(@types/react@19.2.14)(react@19.2.4)
+      radix-ui:
+        specifier: ^1.4.3
+        version: 1.4.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react:
+        specifier: ^19.2.0
+        version: 19.2.4
+      react-dom:
+        specifier: ^19.2.0
+        version: 19.2.4(react@19.2.4)
+      react-i18next:
+        specifier: ^16.5.8
+        version: 16.5.8(i18next@25.8.20(typescript@5.9.3))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3)
+      react-markdown:
+        specifier: ^10.1.0
+        version: 10.1.0(@types/react@19.2.14)(react@19.2.4)
+      react-textarea-autosize:
+        specifier: ^8.5.9
+        version: 8.5.9(@types/react@19.2.14)(react@19.2.4)
+      rehype-raw:
+        specifier: ^7.0.0
+        version: 7.0.0
+      rehype-sanitize:
+        specifier: ^6.0.0
+        version: 6.0.0
+      remark-gfm:
+        specifier: ^4.0.1
+        version: 4.0.1
+      shadcn:
+        specifier: ^4.1.0
+        version: 4.1.0(@types/node@25.5.0)(typescript@5.9.3)
+      sonner:
+        specifier: ^2.0.7
+        version: 2.0.7(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      tailwind-merge:
+        specifier: ^3.5.0
+        version: 3.5.0
+      tailwindcss:
+        specifier: ^4.2.2
+        version: 4.2.2
+      tw-animate-css:
+        specifier: ^1.4.0
+        version: 1.4.0
+      wrap-ansi:
+        specifier: ^10.0.0
+        version: 10.0.0
+    devDependencies:
+      '@eslint/js':
+        specifier: ^9.39.4
+        version: 9.39.4
+      '@tailwindcss/typography':
+        specifier: ^0.5.19
+        version: 0.5.19(tailwindcss@4.2.2)
+      '@tanstack/router-plugin':
+        specifier: ^1.164.0
+        version: 1.166.14(@tanstack/react-router@1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0))
+      '@trivago/prettier-plugin-sort-imports':
+        specifier: ^6.0.2
+        version: 6.0.2(prettier@3.8.1)
+      '@types/node':
+        specifier: ^25.5.0
+        version: 25.5.0
+      '@types/react':
+        specifier: ^19.2.7
+        version: 19.2.14
+      '@types/react-dom':
+        specifier: ^19.2.3
+        version: 19.2.3(@types/react@19.2.14)
+      '@typescript-eslint/eslint-plugin':
+        specifier: ^8.57.1
+        version: 8.57.1(@typescript-eslint/parser@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+      '@vitejs/plugin-react':
+        specifier: ^5.2.0
+        version: 5.2.0(vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0))
+      eslint:
+        specifier: ^9.39.4
+        version: 9.39.4(jiti@2.6.1)
+      eslint-config-prettier:
+        specifier: ^10.1.8
+        version: 10.1.8(eslint@9.39.4(jiti@2.6.1))
+      eslint-plugin-react-hooks:
+        specifier: ^7.0.1
+        version: 7.0.1(eslint@9.39.4(jiti@2.6.1))
+      eslint-plugin-react-refresh:
+        specifier: ^0.4.26
+        version: 0.4.26(eslint@9.39.4(jiti@2.6.1))
+      globals:
+        specifier: ^16.5.0
+        version: 16.5.0
+      prettier:
+        specifier: ^3.8.1
+        version: 3.8.1
+      prettier-plugin-tailwindcss:
+        specifier: ^0.7.2
+        version: 0.7.2(@trivago/prettier-plugin-sort-imports@6.0.2(prettier@3.8.1))(prettier@3.8.1)
+      typescript:
+        specifier: ~5.9.3
+        version: 5.9.3
+      typescript-eslint:
+        specifier: ^8.57.1
+        version: 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+      vite:
+        specifier: ^7.3.1
+        version: 7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)
+
+packages:
+
+  '@babel/code-frame@7.29.0':
+    resolution: {integrity: sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/compat-data@7.29.0':
+    resolution: {integrity: sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/core@7.29.0':
+    resolution: {integrity: sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/generator@7.29.1':
+    resolution: {integrity: sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-annotate-as-pure@7.27.3':
+    resolution: {integrity: sha512-fXSwMQqitTGeHLBC08Eq5yXz2m37E4pJX1qAU1+2cNedz/ifv/bVXft90VeSav5nFO61EcNgwr0aJxbyPaWBPg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-compilation-targets@7.28.6':
+    resolution: {integrity: sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-create-class-features-plugin@7.28.6':
+    resolution: {integrity: sha512-dTOdvsjnG3xNT9Y0AUg1wAl38y+4Rl4sf9caSQZOXdNqVn+H+HbbJ4IyyHaIqNR6SW9oJpA/RuRjsjCw2IdIow==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-globals@7.28.0':
+    resolution: {integrity: sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-member-expression-to-functions@7.28.5':
+    resolution: {integrity: sha512-cwM7SBRZcPCLgl8a7cY0soT1SptSzAlMH39vwiRpOQkJlh53r5hdHwLSCZpQdVLT39sZt+CRpNwYG4Y2v77atg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-imports@7.28.6':
+    resolution: {integrity: sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-transforms@7.28.6':
+    resolution: {integrity: sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-optimise-call-expression@7.27.1':
+    resolution: {integrity: sha512-URMGH08NzYFhubNSGJrpUEphGKQwMQYBySzat5cAByY1/YgIRkULnIy3tAMeszlL/so2HbeilYloUmSpd7GdVw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-plugin-utils@7.28.6':
+    resolution: {integrity: sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-replace-supers@7.28.6':
+    resolution: {integrity: sha512-mq8e+laIk94/yFec3DxSjCRD2Z0TAjhVbEJY3UQrlwVo15Lmt7C2wAUbK4bjnTs4APkwsYLTahXRraQXhb1WCg==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-skip-transparent-expression-wrappers@7.27.1':
+    resolution: {integrity: sha512-Tub4ZKEXqbPjXgWLl2+3JpQAYBJ8+ikpQ2Ocj/q/r0LwE3UhENh7EUabyHjz2kCEsrRY83ew2DQdHluuiDQFzg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-string-parser@7.27.1':
+    resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-identifier@7.28.5':
+    resolution: {integrity: sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-option@7.27.1':
+    resolution: {integrity: sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helpers@7.29.2':
+    resolution: {integrity: sha512-HoGuUs4sCZNezVEKdVcwqmZN8GoHirLUcLaYVNBK2J0DadGtdcqgr3BCbvH8+XUo4NGjNl3VOtSjEKNzqfFgKw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/parser@7.29.2':
+    resolution: {integrity: sha512-4GgRzy/+fsBa72/RZVJmGKPmZu9Byn8o4MoLpmNe1m8ZfYnz5emHLQz3U4gLud6Zwl0RZIcgiLD7Uq7ySFuDLA==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  '@babel/plugin-syntax-jsx@7.28.6':
+    resolution: {integrity: sha512-wgEmr06G6sIpqr8YDwA2dSRTE3bJ+V0IfpzfSY3Lfgd7YWOaAdlykvJi13ZKBt8cZHfgH1IXN+CL656W3uUa4w==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-syntax-typescript@7.28.6':
+    resolution: {integrity: sha512-+nDNmQye7nlnuuHDboPbGm00Vqg3oO8niRRL27/4LYHUsHYh0zJ1xWOz0uRwNFmM1Avzk8wZbc6rdiYhomzv/A==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-modules-commonjs@7.28.6':
+    resolution: {integrity: sha512-jppVbf8IV9iWWwWTQIxJMAJCWBuuKx71475wHwYytrRGQ2CWiDvYlADQno3tcYpS/T2UUWFQp3nVtYfK/YBQrA==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-react-jsx-self@7.27.1':
+    resolution: {integrity: sha512-6UzkCs+ejGdZ5mFFC/OCUrv028ab2fp1znZmCZjAOBKiBK2jXD1O+BPSfX8X2qjJ75fZBMSnQn3Rq2mrBJK2mw==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-react-jsx-source@7.27.1':
+    resolution: {integrity: sha512-zbwoTsBruTeKB9hSq73ha66iFeJHuaFkUbwvqElnygoNbj/jHRsSeokowZFN3CZ64IvEqcmmkVe89OPXc7ldAw==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/plugin-transform-typescript@7.28.6':
+    resolution: {integrity: sha512-0YWL2RFxOqEm9Efk5PvreamxPME8OyY0wM5wh5lHjF+VtVhdneCWGzZeSqzOfiobVqQaNCd2z0tQvnI9DaPWPw==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/preset-typescript@7.28.5':
+    resolution: {integrity: sha512-+bQy5WOI2V6LJZpPVxY+yp66XdZ2yifu0Mc1aP5CQKgjn4QM5IN2i5fAZ4xKop47pr8rpVhiAeu+nDQa12C8+g==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0-0
+
+  '@babel/runtime@7.29.2':
+    resolution: {integrity: sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/template@7.28.6':
+    resolution: {integrity: sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/traverse@7.29.0':
+    resolution: {integrity: sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/types@7.29.0':
+    resolution: {integrity: sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==}
+    engines: {node: '>=6.9.0'}
+
+  '@dotenvx/dotenvx@1.57.0':
+    resolution: {integrity: sha512-WsTEcqfHzKmLFZh3jLGd7o4iCkrIupp+qFH2FJUJtQXUh2GcOnLXD00DcrhlO4H8QSmaKnW9lugOEbrdpu25kA==}
+    hasBin: true
+
+  '@ecies/ciphers@0.2.5':
+    resolution: {integrity: sha512-GalEZH4JgOMHYYcYmVqnFirFsjZHeoGMDt9IxEnM9F7GRUUyUksJ7Ou53L83WHJq3RWKD3AcBpo0iQh0oMpf8A==}
+    engines: {bun: '>=1', deno: '>=2', node: '>=16'}
+    peerDependencies:
+      '@noble/ciphers': ^1.0.0
+
+  '@esbuild/aix-ppc64@0.27.4':
+    resolution: {integrity: sha512-cQPwL2mp2nSmHHJlCyoXgHGhbEPMrEEU5xhkcy3Hs/O7nGZqEpZ2sUtLaL9MORLtDfRvVl2/3PAuEkYZH0Ty8Q==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.27.4':
+    resolution: {integrity: sha512-gdLscB7v75wRfu7QSm/zg6Rx29VLdy9eTr2t44sfTW7CxwAtQghZ4ZnqHk3/ogz7xao0QAgrkradbBzcqFPasw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.27.4':
+    resolution: {integrity: sha512-X9bUgvxiC8CHAGKYufLIHGXPJWnr0OCdR0anD2e21vdvgCI8lIfqFbnoeOz7lBjdrAGUhqLZLcQo6MLhTO2DKQ==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.27.4':
+    resolution: {integrity: sha512-PzPFnBNVF292sfpfhiyiXCGSn9HZg5BcAz+ivBuSsl6Rk4ga1oEXAamhOXRFyMcjwr2DVtm40G65N3GLeH1Lvw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.27.4':
+    resolution: {integrity: sha512-b7xaGIwdJlht8ZFCvMkpDN6uiSmnxxK56N2GDTMYPr2/gzvfdQN8rTfBsvVKmIVY/X7EM+/hJKEIbbHs9oA4tQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.27.4':
+    resolution: {integrity: sha512-sR+OiKLwd15nmCdqpXMnuJ9W2kpy0KigzqScqHI3Hqwr7IXxBp3Yva+yJwoqh7rE8V77tdoheRYataNKL4QrPw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.27.4':
+    resolution: {integrity: sha512-jnfpKe+p79tCnm4GVav68A7tUFeKQwQyLgESwEAUzyxk/TJr4QdGog9sqWNcUbr/bZt/O/HXouspuQDd9JxFSw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.27.4':
+    resolution: {integrity: sha512-2kb4ceA/CpfUrIcTUl1wrP/9ad9Atrp5J94Lq69w7UwOMolPIGrfLSvAKJp0RTvkPPyn6CIWrNy13kyLikZRZQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.27.4':
+    resolution: {integrity: sha512-7nQOttdzVGth1iz57kxg9uCz57dxQLHWxopL6mYuYthohPKEK0vU0C3O21CcBK6KDlkYVcnDXY099HcCDXd9dA==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.27.4':
+    resolution: {integrity: sha512-aBYgcIxX/wd5n2ys0yESGeYMGF+pv6g0DhZr3G1ZG4jMfruU9Tl1i2Z+Wnj9/KjGz1lTLCcorqE2viePZqj4Eg==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.27.4':
+    resolution: {integrity: sha512-oPtixtAIzgvzYcKBQM/qZ3R+9TEUd1aNJQu0HhGyqtx6oS7qTpvjheIWBbes4+qu1bNlo2V4cbkISr8q6gRBFA==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.27.4':
+    resolution: {integrity: sha512-8mL/vh8qeCoRcFH2nM8wm5uJP+ZcVYGGayMavi8GmRJjuI3g1v6Z7Ni0JJKAJW+m0EtUuARb6Lmp4hMjzCBWzA==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.27.4':
+    resolution: {integrity: sha512-1RdrWFFiiLIW7LQq9Q2NES+HiD4NyT8Itj9AUeCl0IVCA459WnPhREKgwrpaIfTOe+/2rdntisegiPWn/r/aAw==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.27.4':
+    resolution: {integrity: sha512-tLCwNG47l3sd9lpfyx9LAGEGItCUeRCWeAx6x2Jmbav65nAwoPXfewtAdtbtit/pJFLUWOhpv0FpS6GQAmPrHA==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.27.4':
+    resolution: {integrity: sha512-BnASypppbUWyqjd1KIpU4AUBiIhVr6YlHx/cnPgqEkNoVOhHg+YiSVxM1RLfiy4t9cAulbRGTNCKOcqHrEQLIw==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.27.4':
+    resolution: {integrity: sha512-+eUqgb/Z7vxVLezG8bVB9SfBie89gMueS+I0xYh2tJdw3vqA/0ImZJ2ROeWwVJN59ihBeZ7Tu92dF/5dy5FttA==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.27.4':
+    resolution: {integrity: sha512-S5qOXrKV8BQEzJPVxAwnryi2+Iq5pB40gTEIT69BQONqR7JH1EPIcQ/Uiv9mCnn05jff9umq/5nqzxlqTOg9NA==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.27.4':
+    resolution: {integrity: sha512-xHT8X4sb0GS8qTqiwzHqpY00C95DPAq7nAwX35Ie/s+LO9830hrMd3oX0ZMKLvy7vsonee73x0lmcdOVXFzd6Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.27.4':
+    resolution: {integrity: sha512-RugOvOdXfdyi5Tyv40kgQnI0byv66BFgAqjdgtAKqHoZTbTF2QqfQrFwa7cHEORJf6X2ht+l9ABLMP0dnKYsgg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.27.4':
+    resolution: {integrity: sha512-2MyL3IAaTX+1/qP0O1SwskwcwCoOI4kV2IBX1xYnDDqthmq5ArrW94qSIKCAuRraMgPOmG0RDTA74mzYNQA9ow==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.27.4':
+    resolution: {integrity: sha512-u8fg/jQ5aQDfsnIV6+KwLOf1CmJnfu1ShpwqdwC0uA7ZPwFws55Ngc12vBdeUdnuWoQYx/SOQLGDcdlfXhYmXQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.27.4':
+    resolution: {integrity: sha512-JkTZrl6VbyO8lDQO3yv26nNr2RM2yZzNrNHEsj9bm6dOwwu9OYN28CjzZkH57bh4w0I2F7IodpQvUAEd1mbWXg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.27.4':
+    resolution: {integrity: sha512-/gOzgaewZJfeJTlsWhvUEmUG4tWEY2Spp5M20INYRg2ZKl9QPO3QEEgPeRtLjEWSW8FilRNacPOg8R1uaYkA6g==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.27.4':
+    resolution: {integrity: sha512-Z9SExBg2y32smoDQdf1HRwHRt6vAHLXcxD2uGgO/v2jK7Y718Ix4ndsbNMU/+1Qiem9OiOdaqitioZwxivhXYg==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.27.4':
+    resolution: {integrity: sha512-DAyGLS0Jz5G5iixEbMHi5KdiApqHBWMGzTtMiJ72ZOLhbu/bzxgAe8Ue8CTS3n3HbIUHQz/L51yMdGMeoxXNJw==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.27.4':
+    resolution: {integrity: sha512-+knoa0BDoeXgkNvvV1vvbZX4+hizelrkwmGJBdT17t8FNPwG2lKemmuMZlmaNQ3ws3DKKCxpb4zRZEIp3UxFCg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@eslint-community/eslint-utils@4.9.1':
+    resolution: {integrity: sha512-phrYmNiYppR7znFEdqgfWHXR6NCkZEK7hwWDHZUjit/2/U0r6XvkDl0SYnoM51Hq7FhCGdLDT6zxCCOY1hexsQ==}
+    engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+    peerDependencies:
+      eslint: ^6.0.0 || ^7.0.0 || >=8.0.0
+
+  '@eslint-community/regexpp@4.12.2':
+    resolution: {integrity: sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==}
+    engines: {node: ^12.0.0 || ^14.0.0 || >=16.0.0}
+
+  '@eslint/config-array@0.21.2':
+    resolution: {integrity: sha512-nJl2KGTlrf9GjLimgIru+V/mzgSK0ABCDQRvxw5BjURL7WfH5uoWmizbH7QB6MmnMBd8cIC9uceWnezL1VZWWw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/config-helpers@0.4.2':
+    resolution: {integrity: sha512-gBrxN88gOIf3R7ja5K9slwNayVcZgK6SOUORm2uBzTeIEfeVaIhOpCtTox3P6R7o2jLFwLFTLnC7kU/RGcYEgw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/core@0.17.0':
+    resolution: {integrity: sha512-yL/sLrpmtDaFEiUj1osRP4TI2MDz1AddJL+jZ7KSqvBuliN4xqYY54IfdN8qD8Toa6g1iloph1fxQNkjOxrrpQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/eslintrc@3.3.5':
+    resolution: {integrity: sha512-4IlJx0X0qftVsN5E+/vGujTRIFtwuLbNsVUe7TO6zYPDR1O6nFwvwhIKEKSrl6dZchmYBITazxKoUYOjdtjlRg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/js@9.39.4':
+    resolution: {integrity: sha512-nE7DEIchvtiFTwBw4Lfbu59PG+kCofhjsKaCWzxTpt4lfRjRMqG6uMBzKXuEcyXhOHoUp9riAm7/aWYGhXZ9cw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/object-schema@2.1.7':
+    resolution: {integrity: sha512-VtAOaymWVfZcmZbp6E2mympDIHvyjXs/12LqWYjVw6qjrfF+VK+fyG33kChz3nnK+SU5/NeHOqrTEHS8sXO3OA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/plugin-kit@0.4.1':
+    resolution: {integrity: sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@floating-ui/core@1.7.5':
+    resolution: {integrity: sha512-1Ih4WTWyw0+lKyFMcBHGbb5U5FtuHJuujoyyr5zTaWS5EYMeT6Jb2AuDeftsCsEuchO+mM2ij5+q9crhydzLhQ==}
+
+  '@floating-ui/dom@1.7.6':
+    resolution: {integrity: sha512-9gZSAI5XM36880PPMm//9dfiEngYoC6Am2izES1FF406YFsjvyBMmeJ2g4SAju3xWwtuynNRFL2s9hgxpLI5SQ==}
+
+  '@floating-ui/react-dom@2.1.8':
+    resolution: {integrity: sha512-cC52bHwM/n/CxS87FH0yWdngEZrjdtLW/qVruo68qg+prK7ZQ4YGdut2GyDVpoGeAYe/h899rVeOVm6Oi40k2A==}
+    peerDependencies:
+      react: '>=16.8.0'
+      react-dom: '>=16.8.0'
+
+  '@floating-ui/utils@0.2.11':
+    resolution: {integrity: sha512-RiB/yIh78pcIxl6lLMG0CgBXAZ2Y0eVHqMPYugu+9U0AeT6YBeiJpf7lbdJNIugFP5SIjwNRgo4DhR1Qxi26Gg==}
+
+  '@fontsource-variable/inter@5.2.8':
+    resolution: {integrity: sha512-kOfP2D+ykbcX/P3IFnokOhVRNoTozo5/JxhAIVYLpea/UBmCQ/YWPBfWIDuBImXX/15KH+eKh4xpEUyS2sQQGQ==}
+
+  '@hono/node-server@1.19.11':
+    resolution: {integrity: sha512-dr8/3zEaB+p0D2n/IUrlPF1HZm586qgJNXK1a9fhg/PzdtkK7Ksd5l312tJX2yBuALqDYBlG20QEbayqPyxn+g==}
+    engines: {node: '>=18.14.1'}
+    peerDependencies:
+      hono: ^4
+
+  '@humanfs/core@0.19.1':
+    resolution: {integrity: sha512-5DyQ4+1JEUzejeK1JGICcideyfUbGixgS9jNgex5nqkW+cY7WZhxBigmieN5Qnw9ZosSNVC9KQKyb+GUaGyKUA==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanfs/node@0.16.7':
+    resolution: {integrity: sha512-/zUx+yOsIrG4Y43Eh2peDeKCxlRt/gET6aHfaKpuq267qXdYDFViVHfMaLyygZOnl0kGWxFIgsBy8QFuTLUXEQ==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanwhocodes/module-importer@1.0.1':
+    resolution: {integrity: sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==}
+    engines: {node: '>=12.22'}
+
+  '@humanwhocodes/retry@0.4.3':
+    resolution: {integrity: sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==}
+    engines: {node: '>=18.18'}
+
+  '@inquirer/ansi@1.0.2':
+    resolution: {integrity: sha512-S8qNSZiYzFd0wAcyG5AXCvUHC5Sr7xpZ9wZ2py9XR88jUz8wooStVx5M6dRzczbBWjic9NP7+rY0Xi7qqK/aMQ==}
+    engines: {node: '>=18'}
+
+  '@inquirer/confirm@5.1.21':
+    resolution: {integrity: sha512-KR8edRkIsUayMXV+o3Gv+q4jlhENF9nMYUZs9PA2HzrXeHI8M5uDag70U7RJn9yyiMZSbtF5/UexBtAVtZGSbQ==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/core@10.3.2':
+    resolution: {integrity: sha512-43RTuEbfP8MbKzedNqBrlhhNKVwoK//vUFNW3Q3vZ88BLcrs4kYpGg+B2mm5p2K/HfygoCxuKwJJiv8PbGmE0A==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@inquirer/figures@1.0.15':
+    resolution: {integrity: sha512-t2IEY+unGHOzAaVM5Xx6DEWKeXlDDcNPeDyUpsRc6CUhBfU3VQOEl+Vssh7VNp1dR8MdUJBWhuObjXCsVpjN5g==}
+    engines: {node: '>=18'}
+
+  '@inquirer/type@3.0.10':
+    resolution: {integrity: sha512-BvziSRxfz5Ov8ch0z/n3oijRSEcEsHnhggm4xFZe93DHcUCTlutlq9Ox4SVENAfcRD22UQq7T/atg9Wr3k09eA==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@types/node': '>=18'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@jridgewell/gen-mapping@0.3.13':
+    resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
+
+  '@jridgewell/remapping@2.3.5':
+    resolution: {integrity: sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==}
+
+  '@jridgewell/resolve-uri@3.1.2':
+    resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
+    engines: {node: '>=6.0.0'}
+
+  '@jridgewell/sourcemap-codec@1.5.5':
+    resolution: {integrity: sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
+
+  '@modelcontextprotocol/sdk@1.27.1':
+    resolution: {integrity: sha512-sr6GbP+4edBwFndLbM60gf07z0FQ79gaExpnsjMGePXqFcSSb7t6iscpjk9DhFhwd+mTEQrzNafGP8/iGGFYaA==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      '@cfworker/json-schema': ^4.1.1
+      zod: ^3.25 || ^4.0
+    peerDependenciesMeta:
+      '@cfworker/json-schema':
+        optional: true
+
+  '@mswjs/interceptors@0.41.3':
+    resolution: {integrity: sha512-cXu86tF4VQVfwz8W1SPbhoRyHJkti6mjH/XJIxp40jhO4j2k1m4KYrEykxqWPkFF3vrK4rgQppBh//AwyGSXPA==}
+    engines: {node: '>=18'}
+
+  '@noble/ciphers@1.3.0':
+    resolution: {integrity: sha512-2I0gnIVPtfnMw9ee9h1dJG7tp81+8Ob3OJb3Mv37rx5L40/b0i7djjCVvGOVqc9AEIQyvyu1i6ypKdFw8R8gQw==}
+    engines: {node: ^14.21.3 || >=16}
+
+  '@noble/curves@1.9.7':
+    resolution: {integrity: sha512-gbKGcRUYIjA3/zCCNaWDciTMFI0dCkvou3TL8Zmy5Nc7sJ47a0jtOeZoTaMxkuqRo9cRhjOdZJXegxYE5FN/xw==}
+    engines: {node: ^14.21.3 || >=16}
+
+  '@noble/hashes@1.8.0':
+    resolution: {integrity: sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==}
+    engines: {node: ^14.21.3 || >=16}
+
+  '@nodelib/fs.scandir@2.1.5':
+    resolution: {integrity: sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.stat@2.0.5':
+    resolution: {integrity: sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==}
+    engines: {node: '>= 8'}
+
+  '@nodelib/fs.walk@1.2.8':
+    resolution: {integrity: sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==}
+    engines: {node: '>= 8'}
+
+  '@open-draft/deferred-promise@2.2.0':
+    resolution: {integrity: sha512-CecwLWx3rhxVQF6V4bAgPS5t+So2sTbPgAzafKkVizyi7tlwpcFpdFqq+wqF2OwNBmqFuu6tOyouTuxgpMfzmA==}
+
+  '@open-draft/logger@0.3.0':
+    resolution: {integrity: sha512-X2g45fzhxH238HKO4xbSr7+wBS8Fvw6ixhTDuvLd5mqh6bJJCFAPwU9mPDxbcrRtfxv4u5IHCEH77BmxvXmmxQ==}
+
+  '@open-draft/until@2.1.0':
+    resolution: {integrity: sha512-U69T3ItWHvLwGg5eJ0n3I62nWuE6ilHlmz7zM0npLBRvPRd7e6NYmg54vvRtP5mZG7kZqZCFVdsTWo7BPtBujg==}
+
+  '@radix-ui/number@1.1.1':
+    resolution: {integrity: sha512-MkKCwxlXTgz6CFoJx3pCwn07GKp36+aZyu/u2Ln2VrA5DcdyCZkASEDBTd8x5whTQQL5CiYf4prXKLcgQdv29g==}
+
+  '@radix-ui/primitive@1.1.3':
+    resolution: {integrity: sha512-JTF99U/6XIjCBo0wqkU5sK10glYe27MRRsfwoiq5zzOEZLHU3A3KCMa5X/azekYRCJ0HlwI0crAXS/5dEHTzDg==}
+
+  '@radix-ui/react-accessible-icon@1.1.7':
+    resolution: {integrity: sha512-XM+E4WXl0OqUJFovy6GjmxxFyx9opfCAIUku4dlKRd5YEPqt4kALOkQOp0Of6reHuUkJuiPBEc5k0o4z4lTC8A==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-accordion@1.2.12':
+    resolution: {integrity: sha512-T4nygeh9YE9dLRPhAHSeOZi7HBXo+0kYIPJXayZfvWOWA0+n3dESrZbjfDPUABkUNym6Hd+f2IR113To8D2GPA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-alert-dialog@1.1.15':
+    resolution: {integrity: sha512-oTVLkEw5GpdRe29BqJ0LSDFWI3qu0vR1M0mUkOQWDIUnY/QIkLpgDMWuKxP94c2NAC2LGcgVhG1ImF3jkZ5wXw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-arrow@1.1.7':
+    resolution: {integrity: sha512-F+M1tLhO+mlQaOWspE8Wstg+z6PwxwRd8oQ8IXceWz92kfAmalTRf0EjrouQeo7QssEPfCn05B4Ihs1K9WQ/7w==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-aspect-ratio@1.1.7':
+    resolution: {integrity: sha512-Yq6lvO9HQyPwev1onK1daHCHqXVLzPhSVjmsNjCa2Zcxy2f7uJD2itDtxknv6FzAKCwD1qQkeVDmX/cev13n/g==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-avatar@1.1.10':
+    resolution: {integrity: sha512-V8piFfWapM5OmNCXTzVQY+E1rDa53zY+MQ4Y7356v4fFz6vqCyUtIz2rUD44ZEdwg78/jKmMJHj07+C/Z/rcog==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-checkbox@1.3.3':
+    resolution: {integrity: sha512-wBbpv+NQftHDdG86Qc0pIyXk5IR3tM8Vd0nWLKDcX8nNn4nXFOFwsKuqw2okA/1D/mpaAkmuyndrPJTYDNZtFw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-collapsible@1.1.12':
+    resolution: {integrity: sha512-Uu+mSh4agx2ib1uIGPP4/CKNULyajb3p92LsVXmH2EHVMTfZWpll88XJ0j4W0z3f8NK1eYl1+Mf/szHPmcHzyA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-collection@1.1.7':
+    resolution: {integrity: sha512-Fh9rGN0MoI4ZFUNyfFVNU4y9LUz93u9/0K+yLgA2bwRojxM8JU1DyvvMBabnZPBgMWREAJvU2jjVzq+LrFUglw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-compose-refs@1.1.2':
+    resolution: {integrity: sha512-z4eqJvfiNnFMHIIvXP3CY57y2WJs5g2v3X0zm9mEJkrkNv4rDxu+sg9Jh8EkXyeqBkB7SOcboo9dMVqhyrACIg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-context-menu@2.2.16':
+    resolution: {integrity: sha512-O8morBEW+HsVG28gYDZPTrT9UUovQUlJue5YO836tiTJhuIWBm/zQHc7j388sHWtdH/xUZurK9olD2+pcqx5ww==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-context@1.1.2':
+    resolution: {integrity: sha512-jCi/QKUM2r1Ju5a3J64TH2A5SpKAgh0LpknyqdQ4m6DCV0xJ2HG1xARRwNGPQfi1SLdLWZ1OJz6F4OMBBNiGJA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-dialog@1.1.15':
+    resolution: {integrity: sha512-TCglVRtzlffRNxRMEyR36DGBLJpeusFcgMVD9PZEzAKnUs1lKCgX5u9BmC2Yg+LL9MgZDugFFs1Vl+Jp4t/PGw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-direction@1.1.1':
+    resolution: {integrity: sha512-1UEWRX6jnOA2y4H5WczZ44gOOjTEmlqv1uNW4GAJEO5+bauCBhv8snY65Iw5/VOS/ghKN9gr2KjnLKxrsvoMVw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-dismissable-layer@1.1.11':
+    resolution: {integrity: sha512-Nqcp+t5cTB8BinFkZgXiMJniQH0PsUt2k51FUhbdfeKvc4ACcG2uQniY/8+h1Yv6Kza4Q7lD7PQV0z0oicE0Mg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-dropdown-menu@2.1.16':
+    resolution: {integrity: sha512-1PLGQEynI/3OX/ftV54COn+3Sud/Mn8vALg2rWnBLnRaGtJDduNW/22XjlGgPdpcIbiQxjKtb7BkcjP00nqfJw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-focus-guards@1.1.3':
+    resolution: {integrity: sha512-0rFg/Rj2Q62NCm62jZw0QX7a3sz6QCQU0LpZdNrJX8byRGaGVTqbrW9jAoIAHyMQqsNpeZ81YgSizOt5WXq0Pw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-focus-scope@1.1.7':
+    resolution: {integrity: sha512-t2ODlkXBQyn7jkl6TNaw/MtVEVvIGelJDCG41Okq/KwUsJBwQ4XVZsHAVUkK4mBv3ewiAS3PGuUWuY2BoK4ZUw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-form@0.1.8':
+    resolution: {integrity: sha512-QM70k4Zwjttifr5a4sZFts9fn8FzHYvQ5PiB19O2HsYibaHSVt9fH9rzB0XZo/YcM+b7t/p7lYCT/F5eOeF5yQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-hover-card@1.1.15':
+    resolution: {integrity: sha512-qgTkjNT1CfKMoP0rcasmlH2r1DAiYicWsDsufxl940sT2wHNEWWv6FMWIQXWhVdmC1d/HYfbhQx60KYyAtKxjg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-id@1.1.1':
+    resolution: {integrity: sha512-kGkGegYIdQsOb4XjsfM97rXsiHaBwco+hFI66oO4s9LU+PLAC5oJ7khdOVFxkhsmlbpUqDAvXw11CluXP+jkHg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-label@2.1.7':
+    resolution: {integrity: sha512-YT1GqPSL8kJn20djelMX7/cTRp/Y9w5IZHvfxQTVHrOqa2yMl7i/UfMqKRU5V7mEyKTrUVgJXhNQPVCG8PBLoQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-menu@2.1.16':
+    resolution: {integrity: sha512-72F2T+PLlphrqLcAotYPp0uJMr5SjP5SL01wfEspJbru5Zs5vQaSHb4VB3ZMJPimgHHCHG7gMOeOB9H3Hdmtxg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-menubar@1.1.16':
+    resolution: {integrity: sha512-EB1FktTz5xRRi2Er974AUQZWg2yVBb1yjip38/lgwtCVRd3a+maUoGHN/xs9Yv8SY8QwbSEb+YrxGadVWbEutA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-navigation-menu@1.2.14':
+    resolution: {integrity: sha512-YB9mTFQvCOAQMHU+C/jVl96WmuWeltyUEpRJJky51huhds5W2FQr1J8D/16sQlf0ozxkPK8uF3niQMdUwZPv5w==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-one-time-password-field@0.1.8':
+    resolution: {integrity: sha512-ycS4rbwURavDPVjCb5iS3aG4lURFDILi6sKI/WITUMZ13gMmn/xGjpLoqBAalhJaDk8I3UbCM5GzKHrnzwHbvg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-password-toggle-field@0.1.3':
+    resolution: {integrity: sha512-/UuCrDBWravcaMix4TdT+qlNdVwOM1Nck9kWx/vafXsdfj1ChfhOdfi3cy9SGBpWgTXwYCuboT/oYpJy3clqfw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-popover@1.1.15':
+    resolution: {integrity: sha512-kr0X2+6Yy/vJzLYJUPCZEc8SfQcf+1COFoAqauJm74umQhta9M7lNJHP7QQS3vkvcGLQUbWpMzwrXYwrYztHKA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-popper@1.2.8':
+    resolution: {integrity: sha512-0NJQ4LFFUuWkE7Oxf0htBKS6zLkkjBH+hM1uk7Ng705ReR8m/uelduy1DBo0PyBXPKVnBA6YBlU94MBGXrSBCw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-portal@1.1.9':
+    resolution: {integrity: sha512-bpIxvq03if6UNwXZ+HTK71JLh4APvnXntDc6XOX8UVq4XQOVl7lwok0AvIl+b8zgCw3fSaVTZMpAPPagXbKmHQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-presence@1.1.5':
+    resolution: {integrity: sha512-/jfEwNDdQVBCNvjkGit4h6pMOzq8bHkopq458dPt2lMjx+eBQUohZNG9A7DtO/O5ukSbxuaNGXMjHicgwy6rQQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-primitive@2.1.3':
+    resolution: {integrity: sha512-m9gTwRkhy2lvCPe6QJp4d3G1TYEUHn/FzJUtq9MjH46an1wJU+GdoGC5VLof8RX8Ft/DlpshApkhswDLZzHIcQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-progress@1.1.7':
+    resolution: {integrity: sha512-vPdg/tF6YC/ynuBIJlk1mm7Le0VgW6ub6J2UWnTQ7/D23KXcPI1qy+0vBkgKgd38RCMJavBXpB83HPNFMTb0Fg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-radio-group@1.3.8':
+    resolution: {integrity: sha512-VBKYIYImA5zsxACdisNQ3BjCBfmbGH3kQlnFVqlWU4tXwjy7cGX8ta80BcrO+WJXIn5iBylEH3K6ZTlee//lgQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-roving-focus@1.1.11':
+    resolution: {integrity: sha512-7A6S9jSgm/S+7MdtNDSb+IU859vQqJ/QAtcYQcfFC6W8RS4IxIZDldLR0xqCFZ6DCyrQLjLPsxtTNch5jVA4lA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-scroll-area@1.2.10':
+    resolution: {integrity: sha512-tAXIa1g3sM5CGpVT0uIbUx/U3Gs5N8T52IICuCtObaos1S8fzsrPXG5WObkQN3S6NVl6wKgPhAIiBGbWnvc97A==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-select@2.2.6':
+    resolution: {integrity: sha512-I30RydO+bnn2PQztvo25tswPH+wFBjehVGtmagkU78yMdwTwVf12wnAOF+AeP8S2N8xD+5UPbGhkUfPyvT+mwQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-separator@1.1.7':
+    resolution: {integrity: sha512-0HEb8R9E8A+jZjvmFCy/J4xhbXy3TV+9XSnGJ3KvTtjlIUy/YQ/p6UYZvi7YbeoeXdyU9+Y3scizK6hkY37baA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-slider@1.3.6':
+    resolution: {integrity: sha512-JPYb1GuM1bxfjMRlNLE+BcmBC8onfCi60Blk7OBqi2MLTFdS+8401U4uFjnwkOr49BLmXxLC6JHkvAsx5OJvHw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-slot@1.2.3':
+    resolution: {integrity: sha512-aeNmHnBxbi2St0au6VBVC7JXFlhLlOnvIIlePNniyUNAClzmtAUEY8/pBiK3iHjufOlwA+c20/8jngo7xcrg8A==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-switch@1.2.6':
+    resolution: {integrity: sha512-bByzr1+ep1zk4VubeEVViV592vu2lHE2BZY5OnzehZqOOgogN80+mNtCqPkhn2gklJqOpxWgPoYTSnhBCqpOXQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-tabs@1.1.13':
+    resolution: {integrity: sha512-7xdcatg7/U+7+Udyoj2zodtI9H/IIopqo+YOIcZOq1nJwXWBZ9p8xiu5llXlekDbZkca79a/fozEYQXIA4sW6A==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-toast@1.2.15':
+    resolution: {integrity: sha512-3OSz3TacUWy4WtOXV38DggwxoqJK4+eDkNMl5Z/MJZaoUPaP4/9lf81xXMe1I2ReTAptverZUpbPY4wWwWyL5g==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-toggle-group@1.1.11':
+    resolution: {integrity: sha512-5umnS0T8JQzQT6HbPyO7Hh9dgd82NmS36DQr+X/YJ9ctFNCiiQd6IJAYYZ33LUwm8M+taCz5t2ui29fHZc4Y6Q==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-toggle@1.1.10':
+    resolution: {integrity: sha512-lS1odchhFTeZv3xwHH31YPObmJn8gOg7Lq12inrr0+BH/l3Tsq32VfjqH1oh80ARM3mlkfMic15n0kg4sD1poQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-toolbar@1.1.11':
+    resolution: {integrity: sha512-4ol06/1bLoFu1nwUqzdD4Y5RZ9oDdKeiHIsntug54Hcr1pgaHiPqHFEaXI1IFP/EsOfROQZ8Mig9VTIRza6Tjg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-tooltip@1.2.8':
+    resolution: {integrity: sha512-tY7sVt1yL9ozIxvmbtN5qtmH2krXcBCfjEiCgKGLqunJHvgvZG2Pcl2oQ3kbcZARb1BGEHdkLzcYGO8ynVlieg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-use-callback-ref@1.1.1':
+    resolution: {integrity: sha512-FkBMwD+qbGQeMu1cOHnuGB6x4yzPjho8ap5WtbEJ26umhgqVXbhekKUQO+hZEL1vU92a3wHwdp0HAcqAUF5iDg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-controllable-state@1.2.2':
+    resolution: {integrity: sha512-BjasUjixPFdS+NKkypcyyN5Pmg83Olst0+c6vGov0diwTEo6mgdqVR6hxcEgFuh4QrAs7Rc+9KuGJ9TVCj0Zzg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-effect-event@0.0.2':
+    resolution: {integrity: sha512-Qp8WbZOBe+blgpuUT+lw2xheLP8q0oatc9UpmiemEICxGvFLYmHm9QowVZGHtJlGbS6A6yJ3iViad/2cVjnOiA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-escape-keydown@1.1.1':
+    resolution: {integrity: sha512-Il0+boE7w/XebUHyBjroE+DbByORGR9KKmITzbR7MyQ4akpORYP/ZmbhAr0DG7RmmBqoOnZdy2QlvajJ2QA59g==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-is-hydrated@0.1.0':
+    resolution: {integrity: sha512-U+UORVEq+cTnRIaostJv9AGdV3G6Y+zbVd+12e18jQ5A3c0xL03IhnHuiU4UV69wolOQp5GfR58NW/EgdQhwOA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-layout-effect@1.1.1':
+    resolution: {integrity: sha512-RbJRS4UWQFkzHTTwVymMTUv8EqYhOp8dOOviLj2ugtTiXRaRQS7GLGxZTLL1jWhMeoSCf5zmcZkqTl9IiYfXcQ==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-previous@1.1.1':
+    resolution: {integrity: sha512-2dHfToCj/pzca2Ck724OZ5L0EVrr3eHRNsG/b3xQJLA2hZpVCS99bLAX+hm1IHXDEnzU6by5z/5MIY794/a8NQ==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-rect@1.1.1':
+    resolution: {integrity: sha512-QTYuDesS0VtuHNNvMh+CjlKJ4LJickCMUAqjlE3+j8w+RlRpwyX3apEQKGFzbZGdo7XNG1tXa+bQqIE7HIXT2w==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-size@1.1.1':
+    resolution: {integrity: sha512-ewrXRDTAqAXlkl6t/fkXWNAhFX9I+CkKlw6zjEwk86RSPKwZr3xpBRso655aqYafwtnbpHLj6toFzmd6xdVptQ==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-visually-hidden@1.2.3':
+    resolution: {integrity: sha512-pzJq12tEaaIhqjbzpCuv/OypJY/BPavOofm+dbab+MHLajy277+1lLm6JFcGgF5eskJ6mquGirhXY2GD/8u8Ug==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/rect@1.1.1':
+    resolution: {integrity: sha512-HPwpGIzkl28mWyZqG52jiqDJ12waP11Pa1lGoiyUkIEuMLBP0oeK/C89esbXrxsky5we7dfd8U58nm0SgAWpVw==}
+
+  '@rolldown/pluginutils@1.0.0-rc.3':
+    resolution: {integrity: sha512-eybk3TjzzzV97Dlj5c+XrBFW57eTNhzod66y9HrBlzJ6NsCrWCp/2kaPS3K9wJmurBC0Tdw4yPjXKZqlznim3Q==}
+
+  '@rollup/rollup-android-arm-eabi@4.59.0':
+    resolution: {integrity: sha512-upnNBkA6ZH2VKGcBj9Fyl9IGNPULcjXRlg0LLeaioQWueH30p6IXtJEbKAgvyv+mJaMxSm1l6xwDXYjpEMiLMg==}
+    cpu: [arm]
+    os: [android]
+
+  '@rollup/rollup-android-arm64@4.59.0':
+    resolution: {integrity: sha512-hZ+Zxj3SySm4A/DylsDKZAeVg0mvi++0PYVceVyX7hemkw7OreKdCvW2oQ3T1FMZvCaQXqOTHb8qmBShoqk69Q==}
+    cpu: [arm64]
+    os: [android]
+
+  '@rollup/rollup-darwin-arm64@4.59.0':
+    resolution: {integrity: sha512-W2Psnbh1J8ZJw0xKAd8zdNgF9HRLkdWwwdWqubSVk0pUuQkoHnv7rx4GiF9rT4t5DIZGAsConRE3AxCdJ4m8rg==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rollup/rollup-darwin-x64@4.59.0':
+    resolution: {integrity: sha512-ZW2KkwlS4lwTv7ZVsYDiARfFCnSGhzYPdiOU4IM2fDbL+QGlyAbjgSFuqNRbSthybLbIJ915UtZBtmuLrQAT/w==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rollup/rollup-freebsd-arm64@4.59.0':
+    resolution: {integrity: sha512-EsKaJ5ytAu9jI3lonzn3BgG8iRBjV4LxZexygcQbpiU0wU0ATxhNVEpXKfUa0pS05gTcSDMKpn3Sx+QB9RlTTA==}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@rollup/rollup-freebsd-x64@4.59.0':
+    resolution: {integrity: sha512-d3DuZi2KzTMjImrxoHIAODUZYoUUMsuUiY4SRRcJy6NJoZ6iIqWnJu9IScV9jXysyGMVuW+KNzZvBLOcpdl3Vg==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rollup/rollup-linux-arm-gnueabihf@4.59.0':
+    resolution: {integrity: sha512-t4ONHboXi/3E0rT6OZl1pKbl2Vgxf9vJfWgmUoCEVQVxhW6Cw/c8I6hbbu7DAvgp82RKiH7TpLwxnJeKv2pbsw==}
+    cpu: [arm]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm-musleabihf@4.59.0':
+    resolution: {integrity: sha512-CikFT7aYPA2ufMD086cVORBYGHffBo4K8MQ4uPS/ZnY54GKj36i196u8U+aDVT2LX4eSMbyHtyOh7D7Zvk2VvA==}
+    cpu: [arm]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm64-gnu@4.59.0':
+    resolution: {integrity: sha512-jYgUGk5aLd1nUb1CtQ8E+t5JhLc9x5WdBKew9ZgAXg7DBk0ZHErLHdXM24rfX+bKrFe+Xp5YuJo54I5HFjGDAA==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm64-musl@4.59.0':
+    resolution: {integrity: sha512-peZRVEdnFWZ5Bh2KeumKG9ty7aCXzzEsHShOZEFiCQlDEepP1dpUl/SrUNXNg13UmZl+gzVDPsiCwnV1uI0RUA==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rollup/rollup-linux-loong64-gnu@4.59.0':
+    resolution: {integrity: sha512-gbUSW/97f7+r4gHy3Jlup8zDG190AuodsWnNiXErp9mT90iCy9NKKU0Xwx5k8VlRAIV2uU9CsMnEFg/xXaOfXg==}
+    cpu: [loong64]
+    os: [linux]
+
+  '@rollup/rollup-linux-loong64-musl@4.59.0':
+    resolution: {integrity: sha512-yTRONe79E+o0FWFijasoTjtzG9EBedFXJMl888NBEDCDV9I2wGbFFfJQQe63OijbFCUZqxpHz1GzpbtSFikJ4Q==}
+    cpu: [loong64]
+    os: [linux]
+
+  '@rollup/rollup-linux-ppc64-gnu@4.59.0':
+    resolution: {integrity: sha512-sw1o3tfyk12k3OEpRddF68a1unZ5VCN7zoTNtSn2KndUE+ea3m3ROOKRCZxEpmT9nsGnogpFP9x6mnLTCaoLkA==}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rollup/rollup-linux-ppc64-musl@4.59.0':
+    resolution: {integrity: sha512-+2kLtQ4xT3AiIxkzFVFXfsmlZiG5FXYW7ZyIIvGA7Bdeuh9Z0aN4hVyXS/G1E9bTP/vqszNIN/pUKCk/BTHsKA==}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rollup/rollup-linux-riscv64-gnu@4.59.0':
+    resolution: {integrity: sha512-NDYMpsXYJJaj+I7UdwIuHHNxXZ/b/N2hR15NyH3m2qAtb/hHPA4g4SuuvrdxetTdndfj9b1WOmy73kcPRoERUg==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@rollup/rollup-linux-riscv64-musl@4.59.0':
+    resolution: {integrity: sha512-nLckB8WOqHIf1bhymk+oHxvM9D3tyPndZH8i8+35p/1YiVoVswPid2yLzgX7ZJP0KQvnkhM4H6QZ5m0LzbyIAg==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@rollup/rollup-linux-s390x-gnu@4.59.0':
+    resolution: {integrity: sha512-oF87Ie3uAIvORFBpwnCvUzdeYUqi2wY6jRFWJAy1qus/udHFYIkplYRW+wo+GRUP4sKzYdmE1Y3+rY5Gc4ZO+w==}
+    cpu: [s390x]
+    os: [linux]
+
+  '@rollup/rollup-linux-x64-gnu@4.59.0':
+    resolution: {integrity: sha512-3AHmtQq/ppNuUspKAlvA8HtLybkDflkMuLK4DPo77DfthRb71V84/c4MlWJXixZz4uruIH4uaa07IqoAkG64fg==}
+    cpu: [x64]
+    os: [linux]
+
+  '@rollup/rollup-linux-x64-musl@4.59.0':
+    resolution: {integrity: sha512-2UdiwS/9cTAx7qIUZB/fWtToJwvt0Vbo0zmnYt7ED35KPg13Q0ym1g442THLC7VyI6JfYTP4PiSOWyoMdV2/xg==}
+    cpu: [x64]
+    os: [linux]
+
+  '@rollup/rollup-openbsd-x64@4.59.0':
+    resolution: {integrity: sha512-M3bLRAVk6GOwFlPTIxVBSYKUaqfLrn8l0psKinkCFxl4lQvOSz8ZrKDz2gxcBwHFpci0B6rttydI4IpS4IS/jQ==}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@rollup/rollup-openharmony-arm64@4.59.0':
+    resolution: {integrity: sha512-tt9KBJqaqp5i5HUZzoafHZX8b5Q2Fe7UjYERADll83O4fGqJ49O1FsL6LpdzVFQcpwvnyd0i+K/VSwu/o/nWlA==}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rollup/rollup-win32-arm64-msvc@4.59.0':
+    resolution: {integrity: sha512-V5B6mG7OrGTwnxaNUzZTDTjDS7F75PO1ae6MJYdiMu60sq0CqN5CVeVsbhPxalupvTX8gXVSU9gq+Rx1/hvu6A==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rollup/rollup-win32-ia32-msvc@4.59.0':
+    resolution: {integrity: sha512-UKFMHPuM9R0iBegwzKF4y0C4J9u8C6MEJgFuXTBerMk7EJ92GFVFYBfOZaSGLu6COf7FxpQNqhNS4c4icUPqxA==}
+    cpu: [ia32]
+    os: [win32]
+
+  '@rollup/rollup-win32-x64-gnu@4.59.0':
+    resolution: {integrity: sha512-laBkYlSS1n2L8fSo1thDNGrCTQMmxjYY5G0WFWjFFYZkKPjsMBsgJfGf4TLxXrF6RyhI60L8TMOjBMvXiTcxeA==}
+    cpu: [x64]
+    os: [win32]
+
+  '@rollup/rollup-win32-x64-msvc@4.59.0':
+    resolution: {integrity: sha512-2HRCml6OztYXyJXAvdDXPKcawukWY2GpR5/nxKp4iBgiO3wcoEGkAaqctIbZcNB6KlUQBIqt8VYkNSj2397EfA==}
+    cpu: [x64]
+    os: [win32]
+
+  '@sec-ant/readable-stream@0.4.1':
+    resolution: {integrity: sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==}
+
+  '@sindresorhus/merge-streams@4.0.0':
+    resolution: {integrity: sha512-tlqY9xq5ukxTUZBmoOp+m61cqwQD5pHJtFY3Mn8CA8ps6yghLH/Hw8UPdqg4OLmFW3IFlcXnQNmo/dh8HzXYIQ==}
+    engines: {node: '>=18'}
+
+  '@tabler/icons-react@3.40.0':
+    resolution: {integrity: sha512-oO5+6QCnna4a//mYubx4euZfECtzQZFDGsDMIdzZUhbdyBCT+3bRVFBPueGIcemWld4Vb/0UQ39C/cmGfGylAg==}
+    peerDependencies:
+      react: '>= 16'
+
+  '@tabler/icons@3.40.0':
+    resolution: {integrity: sha512-V/Q4VgNPKubRTiLdmWjV/zscYcj5IIk+euicUtaVVqF6luSC9rDngYWgST5/yh3Mrg/mYUwRv1YVTk71Jp0twQ==}
+
+  '@tailwindcss/node@4.2.2':
+    resolution: {integrity: sha512-pXS+wJ2gZpVXqFaUEjojq7jzMpTGf8rU6ipJz5ovJV6PUGmlJ+jvIwGrzdHdQ80Sg+wmQxUFuoW1UAAwHNEdFA==}
+
+  '@tailwindcss/oxide-android-arm64@4.2.2':
+    resolution: {integrity: sha512-dXGR1n+P3B6748jZO/SvHZq7qBOqqzQ+yFrXpoOWWALWndF9MoSKAT3Q0fYgAzYzGhxNYOoysRvYlpixRBBoDg==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [android]
+
+  '@tailwindcss/oxide-darwin-arm64@4.2.2':
+    resolution: {integrity: sha512-iq9Qjr6knfMpZHj55/37ouZeykwbDqF21gPFtfnhCCKGDcPI/21FKC9XdMO/XyBM7qKORx6UIhGgg6jLl7BZlg==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-darwin-x64@4.2.2':
+    resolution: {integrity: sha512-BlR+2c3nzc8f2G639LpL89YY4bdcIdUmiOOkv2GQv4/4M0vJlpXEa0JXNHhCHU7VWOKWT/CjqHdTP8aUuDJkuw==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-freebsd-x64@4.2.2':
+    resolution: {integrity: sha512-YUqUgrGMSu2CDO82hzlQ5qSb5xmx3RUrke/QgnoEx7KvmRJHQuZHZmZTLSuuHwFf0DJPybFMXMYf+WJdxHy/nQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.2.2':
+    resolution: {integrity: sha512-FPdhvsW6g06T9BWT0qTwiVZYE2WIFo2dY5aCSpjG/S/u1tby+wXoslXS0kl3/KXnULlLr1E3NPRRw0g7t2kgaQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.2.2':
+    resolution: {integrity: sha512-4og1V+ftEPXGttOO7eCmW7VICmzzJWgMx+QXAJRAhjrSjumCwWqMfkDrNu1LXEQzNAwz28NCUpucgQPrR4S2yw==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.2.2':
+    resolution: {integrity: sha512-oCfG/mS+/+XRlwNjnsNLVwnMWYH7tn/kYPsNPh+JSOMlnt93mYNCKHYzylRhI51X+TbR+ufNhhKKzm6QkqX8ag==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.2.2':
+    resolution: {integrity: sha512-rTAGAkDgqbXHNp/xW0iugLVmX62wOp2PoE39BTCGKjv3Iocf6AFbRP/wZT/kuCxC9QBh9Pu8XPkv/zCZB2mcMg==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-x64-musl@4.2.2':
+    resolution: {integrity: sha512-XW3t3qwbIwiSyRCggeO2zxe3KWaEbM0/kW9e8+0XpBgyKU4ATYzcVSMKteZJ1iukJ3HgHBjbg9P5YPRCVUxlnQ==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+
+  '@tailwindcss/oxide-wasm32-wasi@4.2.2':
+    resolution: {integrity: sha512-eKSztKsmEsn1O5lJ4ZAfyn41NfG7vzCg496YiGtMDV86jz1q/irhms5O0VrY6ZwTUkFy/EKG3RfWgxSI3VbZ8Q==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+    bundledDependencies:
+      - '@napi-rs/wasm-runtime'
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - '@tybys/wasm-util'
+      - '@emnapi/wasi-threads'
+      - tslib
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.2.2':
+    resolution: {integrity: sha512-qPmaQM4iKu5mxpsrWZMOZRgZv1tOZpUm+zdhhQP0VhJfyGGO3aUKdbh3gDZc/dPLQwW4eSqWGrrcWNBZWUWaXQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.2.2':
+    resolution: {integrity: sha512-1T/37VvI7WyH66b+vqHj/cLwnCxt7Qt3WFu5Q8hk65aOvlwAhs7rAp1VkulBJw/N4tMirXjVnylTR72uI0HGcA==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [win32]
+
+  '@tailwindcss/oxide@4.2.2':
+    resolution: {integrity: sha512-qEUA07+E5kehxYp9BVMpq9E8vnJuBHfJEC0vPC5e7iL/hw7HR61aDKoVoKzrG+QKp56vhNZe4qwkRmMC0zDLvg==}
+    engines: {node: '>= 20'}
+
+  '@tailwindcss/typography@0.5.19':
+    resolution: {integrity: sha512-w31dd8HOx3k9vPtcQh5QHP9GwKcgbMp87j58qi6xgiBnFFtKEAgCWnDw4qUT8aHwkCp8bKvb/KGKWWHedP0AAg==}
+    peerDependencies:
+      tailwindcss: '>=3.0.0 || insiders || >=4.0.0-alpha.20 || >=4.0.0-beta.1'
+
+  '@tailwindcss/vite@4.2.2':
+    resolution: {integrity: sha512-mEiF5HO1QqCLXoNEfXVA1Tzo+cYsrqV7w9Juj2wdUFyW07JRenqMG225MvPwr3ZD9N1bFQj46X7r33iHxLUW0w==}
+    peerDependencies:
+      vite: ^5.2.0 || ^6 || ^7 || ^8
+
+  '@tanstack/history@1.161.6':
+    resolution: {integrity: sha512-NaOGLRrddszbQj9upGat6HG/4TKvXLvu+osAIgfxPYA+eIvYKv8GKDJOrY2D3/U9MRnKfMWD7bU4jeD4xmqyIg==}
+    engines: {node: '>=20.19'}
+
+  '@tanstack/query-core@5.91.2':
+    resolution: {integrity: sha512-Uz2pTgPC1mhqrrSGg18RKCWT/pkduAYtxbcyIyKBhw7dTWjXZIzqmpzO2lBkyWr4hlImQgpu1m1pei3UnkFRWw==}
+
+  '@tanstack/react-query@5.91.2':
+    resolution: {integrity: sha512-GClLPzbM57iFXv+FlvOUL56XVe00PxuTaVEyj1zAObhRiKF008J5vedmaq7O6ehs+VmPHe8+PUQhMuEyv8d9wQ==}
+    peerDependencies:
+      react: ^18 || ^19
+
+  '@tanstack/react-router-devtools@1.166.9':
+    resolution: {integrity: sha512-O49eZmaeEKB5YnKH/qd61AbxV/lW8ICm4stfZ4GNQNpzQQ6rhPIB0p3PMZDIgX+6DoMivdNvLRmXAOOpzpIpDg==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      '@tanstack/react-router': ^1.167.2
+      '@tanstack/router-core': ^1.167.2
+      react: '>=18.0.0 || >=19.0.0'
+      react-dom: '>=18.0.0 || >=19.0.0'
+    peerDependenciesMeta:
+      '@tanstack/router-core':
+        optional: true
+
+  '@tanstack/react-router@1.167.5':
+    resolution: {integrity: sha512-s1nP6l/7BYZfSwhoNbB7/rUmZ07q/AvkmhBoiDQl3tgy5dpb9Q1qjtIapYdvCOrao1aA/QCaWqxcbGc2Ct1bvQ==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      react: '>=18.0.0 || >=19.0.0'
+      react-dom: '>=18.0.0 || >=19.0.0'
+
+  '@tanstack/react-store@0.9.2':
+    resolution: {integrity: sha512-Vt5usJE5sHG/cMechQfmwvwne6ktGCELe89Lmvoxe3LKRoFrhPa8OCKWs0NliG8HTJElEIj7PLtaBQIcux5pAQ==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@tanstack/router-core@1.167.5':
+    resolution: {integrity: sha512-8fRgJ0zNJf77R4grCaJQ5Imatjyc4YT5v8rlsPkYYYeUlcFNLbuFRhLlAMdND9gRUMznpnbRDXngpTPgx2K7HQ==}
+    engines: {node: '>=20.19'}
+    hasBin: true
+
+  '@tanstack/router-devtools-core@1.166.9':
+    resolution: {integrity: sha512-PNlA7GmOUX9wY7LUG709Pk3Lg33dfHBztQwzjzrOiOsuf4ggp2R6bwarF8nYGNjG79z/MaB5PN+5yvkCVk8jGw==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      '@tanstack/router-core': ^1.167.2
+      csstype: ^3.0.10
+    peerDependenciesMeta:
+      csstype:
+        optional: true
+
+  '@tanstack/router-generator@1.166.13':
+    resolution: {integrity: sha512-ALxSs6OzimiSgpOuIm+AXmc7eUx/oGPwSPpdQbpZ/kX7WHRh6qM7lv8DAN0K3jWcBpzF8eeOIdryWryX8gH+Yg==}
+    engines: {node: '>=20.19'}
+
+  '@tanstack/router-plugin@1.166.14':
+    resolution: {integrity: sha512-hypyj0qlsAbJf60/glmVYqSVwnRB4hKRrMCUsSXjrPdO2g6gs3z6xHmcWsHQ831C4G9+bSFEK9Uy5EjO3A4THQ==}
+    engines: {node: '>=20.19'}
+    hasBin: true
+    peerDependencies:
+      '@rsbuild/core': '>=1.0.2'
+      '@tanstack/react-router': ^1.167.5
+      vite: '>=5.0.0 || >=6.0.0 || >=7.0.0'
+      vite-plugin-solid: ^2.11.10
+      webpack: '>=5.92.0'
+    peerDependenciesMeta:
+      '@rsbuild/core':
+        optional: true
+      '@tanstack/react-router':
+        optional: true
+      vite:
+        optional: true
+      vite-plugin-solid:
+        optional: true
+      webpack:
+        optional: true
+
+  '@tanstack/router-utils@1.161.6':
+    resolution: {integrity: sha512-nRcYw+w2OEgK6VfjirYvGyPLOK+tZQz1jkYcmH5AjMamQ9PycnlxZF2aEZtPpNoUsaceX2bHptn6Ub5hGXqNvw==}
+    engines: {node: '>=20.19'}
+
+  '@tanstack/store@0.9.2':
+    resolution: {integrity: sha512-K013lUJEFJK2ofFQ/hZKJUmCnpcV00ebLyOyFOWQvyQHUOZp/iYO84BM6aOGiV81JzwbX0APTVmW8YI7yiG5oA==}
+
+  '@tanstack/virtual-file-routes@1.161.7':
+    resolution: {integrity: sha512-olW33+Cn+bsCsZKPwEGhlkqS6w3M2slFv11JIobdnCFKMLG97oAI2kWKdx5/zsywTL8flpnoIgaZZPlQTFYhdQ==}
+    engines: {node: '>=20.19'}
+    hasBin: true
+
+  '@trivago/prettier-plugin-sort-imports@6.0.2':
+    resolution: {integrity: sha512-3DgfkukFyC/sE/VuYjaUUWoFfuVjPK55vOFDsxD56XXynFMCZDYFogH2l/hDfOsQAm1myoU/1xByJ3tWqtulXA==}
+    engines: {node: '>= 20'}
+    peerDependencies:
+      '@vue/compiler-sfc': 3.x
+      prettier: 2.x - 3.x
+      prettier-plugin-ember-template-tag: '>= 2.0.0'
+      prettier-plugin-svelte: 3.x
+      svelte: 4.x || 5.x
+    peerDependenciesMeta:
+      '@vue/compiler-sfc':
+        optional: true
+      prettier-plugin-ember-template-tag:
+        optional: true
+      prettier-plugin-svelte:
+        optional: true
+      svelte:
+        optional: true
+
+  '@ts-morph/common@0.27.0':
+    resolution: {integrity: sha512-Wf29UqxWDpc+i61k3oIOzcUfQt79PIT9y/MWfAGlrkjg6lBC1hwDECLXPVJAhWjiGbfBCxZd65F/LIZF3+jeJQ==}
+
+  '@types/babel__core@7.20.5':
+    resolution: {integrity: sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==}
+
+  '@types/babel__generator@7.27.0':
+    resolution: {integrity: sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg==}
+
+  '@types/babel__template@7.4.4':
+    resolution: {integrity: sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A==}
+
+  '@types/babel__traverse@7.28.0':
+    resolution: {integrity: sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==}
+
+  '@types/debug@4.1.13':
+    resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
+
+  '@types/estree-jsx@1.0.5':
+    resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==}
+
+  '@types/estree@1.0.8':
+    resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
+
+  '@types/hast@3.0.4':
+    resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==}
+
+  '@types/json-schema@7.0.15':
+    resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}
+
+  '@types/mdast@4.0.4':
+    resolution: {integrity: sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==}
+
+  '@types/ms@2.1.0':
+    resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
+
+  '@types/node@25.5.0':
+    resolution: {integrity: sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw==}
+
+  '@types/react-dom@19.2.3':
+    resolution: {integrity: sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==}
+    peerDependencies:
+      '@types/react': ^19.2.0
+
+  '@types/react@19.2.14':
+    resolution: {integrity: sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w==}
+
+  '@types/statuses@2.0.6':
+    resolution: {integrity: sha512-xMAgYwceFhRA2zY+XbEA7mxYbA093wdiW8Vu6gZPGWy9cmOyU9XesH1tNcEWsKFd5Vzrqx5T3D38PWx1FIIXkA==}
+
+  '@types/unist@2.0.11':
+    resolution: {integrity: sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==}
+
+  '@types/unist@3.0.3':
+    resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==}
+
+  '@types/validate-npm-package-name@4.0.2':
+    resolution: {integrity: sha512-lrpDziQipxCEeK5kWxvljWYhUvOiB2A9izZd9B2AFarYAkqZshb4lPbRs7zKEic6eGtH8V/2qJW+dPp9OtF6bw==}
+
+  '@typescript-eslint/eslint-plugin@8.57.1':
+    resolution: {integrity: sha512-Gn3aqnvNl4NGc6x3/Bqk1AOn0thyTU9bqDRhiRnUWezgvr2OnhYCWCgC8zXXRVqBsIL1pSDt7T9nJUe0oM0kDQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      '@typescript-eslint/parser': ^8.57.1
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/parser@8.57.1':
+    resolution: {integrity: sha512-k4eNDan0EIMTT/dUKc/g+rsJ6wcHYhNPdY19VoX/EOtaAG8DLtKCykhrUnuHPYvinn5jhAPgD2Qw9hXBwrahsw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/project-service@8.57.1':
+    resolution: {integrity: sha512-vx1F37BRO1OftsYlmG9xay1TqnjNVlqALymwWVuYTdo18XuKxtBpCj1QlzNIEHlvlB27osvXFWptYiEWsVdYsg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/scope-manager@8.57.1':
+    resolution: {integrity: sha512-hs/QcpCwlwT2L5S+3fT6gp0PabyGk4Q0Rv2doJXA0435/OpnSR3VRgvrp8Xdoc3UAYSg9cyUjTeFXZEPg/3OKg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/tsconfig-utils@8.57.1':
+    resolution: {integrity: sha512-0lgOZB8cl19fHO4eI46YUx2EceQqhgkPSuCGLlGi79L2jwYY1cxeYc1Nae8Aw1xjgW3PKVDLlr3YJ6Bxx8HkWg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/type-utils@8.57.1':
+    resolution: {integrity: sha512-+Bwwm0ScukFdyoJsh2u6pp4S9ktegF98pYUU0hkphOOqdMB+1sNQhIz8y5E9+4pOioZijrkfNO/HUJVAFFfPKA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/types@8.57.1':
+    resolution: {integrity: sha512-S29BOBPJSFUiblEl6RzPPjJt6w25A6XsBqRVDt53tA/tlL8q7ceQNZHTjPeONt/3S7KRI4quk+yP9jK2WjBiPQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/typescript-estree@8.57.1':
+    resolution: {integrity: sha512-ybe2hS9G6pXpqGtPli9Gx9quNV0TWLOmh58ADlmZe9DguLq0tiAKVjirSbtM1szG6+QH6rVXyU6GTLQbWnMY+g==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/utils@8.57.1':
+    resolution: {integrity: sha512-XUNSJ/lEVFttPMMoDVA2r2bwrl8/oPx8cURtczkSEswY5T3AeLmCy+EKWQNdL4u0MmAHOjcWrqJp2cdvgjn8dQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.0.0'
+
+  '@typescript-eslint/visitor-keys@8.57.1':
+    resolution: {integrity: sha512-YWnmJkXbofiz9KbnbbwuA2rpGkFPLbAIetcCNO6mJ8gdhdZ/v7WDXsoGFAJuM6ikUFKTlSQnjWnVO4ux+UzS6A==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@ungap/structured-clone@1.3.0':
+    resolution: {integrity: sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==}
+
+  '@vitejs/plugin-react@5.2.0':
+    resolution: {integrity: sha512-YmKkfhOAi3wsB1PhJq5Scj3GXMn3WvtQ/JC0xoopuHoXSdmtdStOpFrYaT1kie2YgFBcIe64ROzMYRjCrYOdYw==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    peerDependencies:
+      vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0
+
+  accepts@2.0.0:
+    resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
+    engines: {node: '>= 0.6'}
+
+  acorn-jsx@5.3.2:
+    resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
+    peerDependencies:
+      acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
+
+  acorn@8.16.0:
+    resolution: {integrity: sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==}
+    engines: {node: '>=0.4.0'}
+    hasBin: true
+
+  agent-base@7.1.4:
+    resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
+    engines: {node: '>= 14'}
+
+  ajv-formats@3.0.1:
+    resolution: {integrity: sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==}
+    peerDependencies:
+      ajv: ^8.0.0
+    peerDependenciesMeta:
+      ajv:
+        optional: true
+
+  ajv@6.14.0:
+    resolution: {integrity: sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==}
+
+  ajv@8.18.0:
+    resolution: {integrity: sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==}
+
+  ansi-regex@5.0.1:
+    resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
+    engines: {node: '>=8'}
+
+  ansi-regex@6.2.2:
+    resolution: {integrity: sha512-Bq3SmSpyFHaWjPk8If9yc6svM8c56dB5BAtW4Qbw5jHTwwXXcTLoRMkpDJp6VL0XzlWaCHTXrkFURMYmD0sLqg==}
+    engines: {node: '>=12'}
+
+  ansi-styles@4.3.0:
+    resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
+    engines: {node: '>=8'}
+
+  ansi-styles@6.2.3:
+    resolution: {integrity: sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==}
+    engines: {node: '>=12'}
+
+  ansis@4.2.0:
+    resolution: {integrity: sha512-HqZ5rWlFjGiV0tDm3UxxgNRqsOTniqoKZu0pIAfh7TZQMGuZK+hH0drySty0si0QXj1ieop4+SkSfPZBPPkHig==}
+    engines: {node: '>=14'}
+
+  anymatch@3.1.3:
+    resolution: {integrity: sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==}
+    engines: {node: '>= 8'}
+
+  argparse@2.0.1:
+    resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
+
+  aria-hidden@1.2.6:
+    resolution: {integrity: sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA==}
+    engines: {node: '>=10'}
+
+  ast-types@0.16.1:
+    resolution: {integrity: sha512-6t10qk83GOG8p0vKmaCr8eiilZwO171AvbROMtvvNiwrTly62t+7XkA8RdIIVbpMhCASAsxgAzdRSwh6nw/5Dg==}
+    engines: {node: '>=4'}
+
+  babel-dead-code-elimination@1.0.12:
+    resolution: {integrity: sha512-GERT7L2TiYcYDtYk1IpD+ASAYXjKbLTDPhBtYj7X1NuRMDTMtAx9kyBenub1Ev41lo91OHCKdmP+egTDmfQ7Ig==}
+
+  bail@2.0.2:
+    resolution: {integrity: sha512-0xO6mYd7JB2YesxDKplafRpsiOzPt9V02ddPCLbY1xYGPOX24NTyN50qnUxgCPcSoYMhKpAuBTjQoRZCAkUDRw==}
+
+  balanced-match@1.0.2:
+    resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==}
+
+  balanced-match@4.0.4:
+    resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
+    engines: {node: 18 || 20 || >=22}
+
+  baseline-browser-mapping@2.10.9:
+    resolution: {integrity: sha512-OZd0e2mU11ClX8+IdXe3r0dbqMEznRiT4TfbhYIbcRPZkqJ7Qwer8ij3GZAmLsRKa+II9V1v5czCkvmHH3XZBg==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  binary-extensions@2.3.0:
+    resolution: {integrity: sha512-Ceh+7ox5qe7LJuLHoY0feh3pHuUDHAcRUeyL2VYghZwfpkNIy/+8Ocg0a3UuSoYzavmylwuLWQOf3hl0jjMMIw==}
+    engines: {node: '>=8'}
+
+  body-parser@2.2.2:
+    resolution: {integrity: sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA==}
+    engines: {node: '>=18'}
+
+  brace-expansion@1.1.12:
+    resolution: {integrity: sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==}
+
+  brace-expansion@2.0.2:
+    resolution: {integrity: sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==}
+
+  brace-expansion@5.0.4:
+    resolution: {integrity: sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg==}
+    engines: {node: 18 || 20 || >=22}
+
+  braces@3.0.3:
+    resolution: {integrity: sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==}
+    engines: {node: '>=8'}
+
+  browserslist@4.28.1:
+    resolution: {integrity: sha512-ZC5Bd0LgJXgwGqUknZY/vkUQ04r8NXnJZ3yYi4vDmSiZmC/pdSN0NbNRPxZpbtO4uAfDUAFffO8IZoM3Gj8IkA==}
+    engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
+    hasBin: true
+
+  bundle-name@4.1.0:
+    resolution: {integrity: sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==}
+    engines: {node: '>=18'}
+
+  bytes@3.1.2:
+    resolution: {integrity: sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==}
+    engines: {node: '>= 0.8'}
+
+  call-bind-apply-helpers@1.0.2:
+    resolution: {integrity: sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==}
+    engines: {node: '>= 0.4'}
+
+  call-bound@1.0.4:
+    resolution: {integrity: sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==}
+    engines: {node: '>= 0.4'}
+
+  callsites@3.1.0:
+    resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==}
+    engines: {node: '>=6'}
+
+  caniuse-lite@1.0.30001780:
+    resolution: {integrity: sha512-llngX0E7nQci5BPJDqoZSbuZ5Bcs9F5db7EtgfwBerX9XGtkkiO4NwfDDIRzHTTwcYC8vC7bmeUEPGrKlR/TkQ==}
+
+  ccount@2.0.1:
+    resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
+
+  chalk@4.1.2:
+    resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
+    engines: {node: '>=10'}
+
+  chalk@5.6.2:
+    resolution: {integrity: sha512-7NzBL0rN6fMUW+f7A6Io4h40qQlG+xGmtMxfbnH/K7TAtt8JQWVQK+6g0UXKMeVJoyV5EkkNsErQ8pVD3bLHbA==}
+    engines: {node: ^12.17.0 || ^14.13 || >=16.0.0}
+
+  character-entities-html4@2.1.0:
+    resolution: {integrity: sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==}
+
+  character-entities-legacy@3.0.0:
+    resolution: {integrity: sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==}
+
+  character-entities@2.0.2:
+    resolution: {integrity: sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==}
+
+  character-reference-invalid@2.0.1:
+    resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==}
+
+  chokidar@3.6.0:
+    resolution: {integrity: sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==}
+    engines: {node: '>= 8.10.0'}
+
+  class-variance-authority@0.7.1:
+    resolution: {integrity: sha512-Ka+9Trutv7G8M6WT6SeiRWz792K5qEqIGEGzXKhAE6xOWAY6pPH8U+9IY3oCMv6kqTmLsv7Xh/2w2RigkePMsg==}
+
+  cli-cursor@5.0.0:
+    resolution: {integrity: sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==}
+    engines: {node: '>=18'}
+
+  cli-spinners@2.9.2:
+    resolution: {integrity: sha512-ywqV+5MmyL4E7ybXgKys4DugZbX0FC6LnwrhjuykIjnK9k8OQacQ7axGKnjDXWNhns0xot3bZI5h55H8yo9cJg==}
+    engines: {node: '>=6'}
+
+  cli-width@4.1.0:
+    resolution: {integrity: sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==}
+    engines: {node: '>= 12'}
+
+  cliui@8.0.1:
+    resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==}
+    engines: {node: '>=12'}
+
+  clsx@2.1.1:
+    resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==}
+    engines: {node: '>=6'}
+
+  code-block-writer@13.0.3:
+    resolution: {integrity: sha512-Oofo0pq3IKnsFtuHqSF7TqBfr71aeyZDVJ0HpmqB7FBM2qEigL0iPONSCZSO9pE9dZTAxANe5XHG9Uy0YMv8cg==}
+
+  color-convert@2.0.1:
+    resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
+    engines: {node: '>=7.0.0'}
+
+  color-name@1.1.4:
+    resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
+
+  comma-separated-tokens@2.0.3:
+    resolution: {integrity: sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==}
+
+  commander@11.1.0:
+    resolution: {integrity: sha512-yPVavfyCcRhmorC7rWlkHn15b4wDVgVmBA7kV4QVBsF7kv/9TKJAbAXVTxvTnwP8HHKjRCJDClKbciiYS7p0DQ==}
+    engines: {node: '>=16'}
+
+  commander@14.0.3:
+    resolution: {integrity: sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==}
+    engines: {node: '>=20'}
+
+  concat-map@0.0.1:
+    resolution: {integrity: sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==}
+
+  content-disposition@1.0.1:
+    resolution: {integrity: sha512-oIXISMynqSqm241k6kcQ5UwttDILMK4BiurCfGEREw6+X9jkkpEe5T9FZaApyLGGOnFuyMWZpdolTXMtvEJ08Q==}
+    engines: {node: '>=18'}
+
+  content-type@1.0.5:
+    resolution: {integrity: sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==}
+    engines: {node: '>= 0.6'}
+
+  convert-source-map@2.0.0:
+    resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==}
+
+  cookie-es@2.0.0:
+    resolution: {integrity: sha512-RAj4E421UYRgqokKUmotqAwuplYw15qtdXfY+hGzgCJ/MBjCVZcSoHK/kH9kocfjRjcDME7IiDWR/1WX1TM2Pg==}
+
+  cookie-signature@1.2.2:
+    resolution: {integrity: sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==}
+    engines: {node: '>=6.6.0'}
+
+  cookie@0.7.2:
+    resolution: {integrity: sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==}
+    engines: {node: '>= 0.6'}
+
+  cookie@1.1.1:
+    resolution: {integrity: sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==}
+    engines: {node: '>=18'}
+
+  cors@2.8.6:
+    resolution: {integrity: sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==}
+    engines: {node: '>= 0.10'}
+
+  cosmiconfig@9.0.1:
+    resolution: {integrity: sha512-hr4ihw+DBqcvrsEDioRO31Z17x71pUYoNe/4h6Z0wB72p7MU7/9gH8Q3s12NFhHPfYBBOV3qyfUxmr/Yn3shnQ==}
+    engines: {node: '>=14'}
+    peerDependencies:
+      typescript: '>=4.9.5'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  cross-spawn@7.0.6:
+    resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
+    engines: {node: '>= 8'}
+
+  cssesc@3.0.0:
+    resolution: {integrity: sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg==}
+    engines: {node: '>=4'}
+    hasBin: true
+
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
+
+  data-uri-to-buffer@4.0.1:
+    resolution: {integrity: sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==}
+    engines: {node: '>= 12'}
+
+  dayjs@1.11.20:
+    resolution: {integrity: sha512-YbwwqR/uYpeoP4pu043q+LTDLFBLApUP6VxRihdfNTqu4ubqMlGDLd6ErXhEgsyvY0K6nCs7nggYumAN+9uEuQ==}
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  decode-named-character-reference@1.3.0:
+    resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==}
+
+  dedent@1.7.2:
+    resolution: {integrity: sha512-WzMx3mW98SN+zn3hgemf4OzdmyNhhhKz5Ay0pUfQiMQ3e1g+xmTJWp/pKdwKVXhdSkAEGIIzqeuWrL3mV/AXbA==}
+    peerDependencies:
+      babel-plugin-macros: ^3.1.0
+    peerDependenciesMeta:
+      babel-plugin-macros:
+        optional: true
+
+  deep-is@0.1.4:
+    resolution: {integrity: sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==}
+
+  deepmerge@4.3.1:
+    resolution: {integrity: sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==}
+    engines: {node: '>=0.10.0'}
+
+  default-browser-id@5.0.1:
+    resolution: {integrity: sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q==}
+    engines: {node: '>=18'}
+
+  default-browser@5.5.0:
+    resolution: {integrity: sha512-H9LMLr5zwIbSxrmvikGuI/5KGhZ8E2zH3stkMgM5LpOWDutGM2JZaj460Udnf1a+946zc7YBgrqEWwbk7zHvGw==}
+    engines: {node: '>=18'}
+
+  define-lazy-prop@3.0.0:
+    resolution: {integrity: sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==}
+    engines: {node: '>=12'}
+
+  depd@2.0.0:
+    resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==}
+    engines: {node: '>= 0.8'}
+
+  dequal@2.0.3:
+    resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
+    engines: {node: '>=6'}
+
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
+  detect-node-es@1.1.0:
+    resolution: {integrity: sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==}
+
+  devlop@1.1.0:
+    resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==}
+
+  diff@8.0.3:
+    resolution: {integrity: sha512-qejHi7bcSD4hQAZE0tNAawRK1ZtafHDmMTMkrrIGgSLl7hTnQHmKCeB45xAcbfTqK2zowkM3j3bHt/4b/ARbYQ==}
+    engines: {node: '>=0.3.1'}
+
+  dotenv@17.3.1:
+    resolution: {integrity: sha512-IO8C/dzEb6O3F9/twg6ZLXz164a2fhTnEWb95H23Dm4OuN+92NmEAlTrupP9VW6Jm3sO26tQlqyvyi4CsnY9GA==}
+    engines: {node: '>=12'}
+
+  dunder-proto@1.0.1:
+    resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
+    engines: {node: '>= 0.4'}
+
+  eciesjs@0.4.18:
+    resolution: {integrity: sha512-wG99Zcfcys9fZux7Cft8BAX/YrOJLJSZ3jyYPfhZHqN2E+Ffx+QXBDsv3gubEgPtV6dTzJMSQUwk1H98/t/0wQ==}
+    engines: {bun: '>=1', deno: '>=2', node: '>=16'}
+
+  ee-first@1.1.1:
+    resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
+
+  electron-to-chromium@1.5.321:
+    resolution: {integrity: sha512-L2C7Q279W2D/J4PLZLk7sebOILDSWos7bMsMNN06rK482umHUrh/3lM8G7IlHFOYip2oAg5nha1rCMxr/rs6ZQ==}
+
+  emoji-regex@10.6.0:
+    resolution: {integrity: sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==}
+
+  emoji-regex@8.0.0:
+    resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
+
+  encodeurl@2.0.0:
+    resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
+    engines: {node: '>= 0.8'}
+
+  enhanced-resolve@5.20.1:
+    resolution: {integrity: sha512-Qohcme7V1inbAfvjItgw0EaxVX5q2rdVEZHRBrEQdRZTssLDGsL8Lwrznl8oQ/6kuTJONLaDcGjkNP247XEhcA==}
+    engines: {node: '>=10.13.0'}
+
+  entities@6.0.1:
+    resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}
+    engines: {node: '>=0.12'}
+
+  env-paths@2.2.1:
+    resolution: {integrity: sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==}
+    engines: {node: '>=6'}
+
+  error-ex@1.3.4:
+    resolution: {integrity: sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==}
+
+  es-define-property@1.0.1:
+    resolution: {integrity: sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==}
+    engines: {node: '>= 0.4'}
+
+  es-errors@1.3.0:
+    resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==}
+    engines: {node: '>= 0.4'}
+
+  es-object-atoms@1.1.1:
+    resolution: {integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==}
+    engines: {node: '>= 0.4'}
+
+  esbuild@0.27.4:
+    resolution: {integrity: sha512-Rq4vbHnYkK5fws5NF7MYTU68FPRE1ajX7heQ/8QXXWqNgqqJ/GkmmyxIzUnf2Sr/bakf8l54716CcMGHYhMrrQ==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  escalade@3.2.0:
+    resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
+    engines: {node: '>=6'}
+
+  escape-html@1.0.3:
+    resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==}
+
+  escape-string-regexp@4.0.0:
+    resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
+    engines: {node: '>=10'}
+
+  escape-string-regexp@5.0.0:
+    resolution: {integrity: sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw==}
+    engines: {node: '>=12'}
+
+  eslint-config-prettier@10.1.8:
+    resolution: {integrity: sha512-82GZUjRS0p/jganf6q1rEO25VSoHH0hKPCTrgillPjdI/3bgBhAE1QzHrHTizjpRvy6pGAvKjDJtk2pF9NDq8w==}
+    hasBin: true
+    peerDependencies:
+      eslint: '>=7.0.0'
+
+  eslint-plugin-react-hooks@7.0.1:
+    resolution: {integrity: sha512-O0d0m04evaNzEPoSW+59Mezf8Qt0InfgGIBJnpC0h3NH/WjUAR7BIKUfysC6todmtiZ/A0oUVS8Gce0WhBrHsA==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      eslint: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0 || ^9.0.0
+
+  eslint-plugin-react-refresh@0.4.26:
+    resolution: {integrity: sha512-1RETEylht2O6FM/MvgnyvT+8K21wLqDNg4qD51Zj3guhjt433XbnnkVttHMyaVyAFD03QSV4LPS5iE3VQmO7XQ==}
+    peerDependencies:
+      eslint: '>=8.40'
+
+  eslint-scope@8.4.0:
+    resolution: {integrity: sha512-sNXOfKCn74rt8RICKMvJS7XKV/Xk9kA7DyJr8mJik3S7Cwgy3qlkkmyS2uQB3jiJg6VNdZd/pDBJu0nvG2NlTg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  eslint-visitor-keys@3.4.3:
+    resolution: {integrity: sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==}
+    engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+
+  eslint-visitor-keys@4.2.1:
+    resolution: {integrity: sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  eslint-visitor-keys@5.0.1:
+    resolution: {integrity: sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  eslint@9.39.4:
+    resolution: {integrity: sha512-XoMjdBOwe/esVgEvLmNsD3IRHkm7fbKIUGvrleloJXUZgDHig2IPWNniv+GwjyJXzuNqVjlr5+4yVUZjycJwfQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    hasBin: true
+    peerDependencies:
+      jiti: '*'
+    peerDependenciesMeta:
+      jiti:
+        optional: true
+
+  espree@10.4.0:
+    resolution: {integrity: sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  esprima@4.0.1:
+    resolution: {integrity: sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==}
+    engines: {node: '>=4'}
+    hasBin: true
+
+  esquery@1.7.0:
+    resolution: {integrity: sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g==}
+    engines: {node: '>=0.10'}
+
+  esrecurse@4.3.0:
+    resolution: {integrity: sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==}
+    engines: {node: '>=4.0'}
+
+  estraverse@5.3.0:
+    resolution: {integrity: sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==}
+    engines: {node: '>=4.0'}
+
+  estree-util-is-identifier-name@3.0.0:
+    resolution: {integrity: sha512-hFtqIDZTIUZ9BXLb8y4pYGyk6+wekIivNVTcmvk8NoOh+VeRn5y6cEHzbURrWbfp1fIqdVipilzj+lfaadNZmg==}
+
+  esutils@2.0.3:
+    resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==}
+    engines: {node: '>=0.10.0'}
+
+  etag@1.8.1:
+    resolution: {integrity: sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==}
+    engines: {node: '>= 0.6'}
+
+  eventsource-parser@3.0.6:
+    resolution: {integrity: sha512-Vo1ab+QXPzZ4tCa8SwIHJFaSzy4R6SHf7BY79rFBDf0idraZWAkYrDjDj8uWaSm3S2TK+hJ7/t1CEmZ7jXw+pg==}
+    engines: {node: '>=18.0.0'}
+
+  eventsource@3.0.7:
+    resolution: {integrity: sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==}
+    engines: {node: '>=18.0.0'}
+
+  execa@5.1.1:
+    resolution: {integrity: sha512-8uSpZZocAZRBAPIEINJj3Lo9HyGitllczc27Eh5YYojjMFMn8yHMDMaUHE2Jqfq05D/wucwI4JGURyXt1vchyg==}
+    engines: {node: '>=10'}
+
+  execa@9.6.1:
+    resolution: {integrity: sha512-9Be3ZoN4LmYR90tUoVu2te2BsbzHfhJyfEiAVfz7N5/zv+jduIfLrV2xdQXOHbaD6KgpGdO9PRPM1Y4Q9QkPkA==}
+    engines: {node: ^18.19.0 || >=20.5.0}
+
+  express-rate-limit@8.3.1:
+    resolution: {integrity: sha512-D1dKN+cmyPWuvB+G2SREQDzPY1agpBIcTa9sJxOPMCNeH3gwzhqJRDWCXW3gg0y//+LQ/8j52JbMROWyrKdMdw==}
+    engines: {node: '>= 16'}
+    peerDependencies:
+      express: '>= 4.11'
+
+  express@5.2.1:
+    resolution: {integrity: sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==}
+    engines: {node: '>= 18'}
+
+  extend@3.0.2:
+    resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==}
+
+  fast-deep-equal@3.1.3:
+    resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
+
+  fast-glob@3.3.3:
+    resolution: {integrity: sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==}
+    engines: {node: '>=8.6.0'}
+
+  fast-json-stable-stringify@2.1.0:
+    resolution: {integrity: sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==}
+
+  fast-levenshtein@2.0.6:
+    resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==}
+
+  fast-uri@3.1.0:
+    resolution: {integrity: sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==}
+
+  fastq@1.20.1:
+    resolution: {integrity: sha512-GGToxJ/w1x32s/D2EKND7kTil4n8OVk/9mycTc4VDza13lOvpUZTGX3mFSCtV9ksdGBVzvsyAVLM6mHFThxXxw==}
+
+  fdir@6.5.0:
+    resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
+    engines: {node: '>=12.0.0'}
+    peerDependencies:
+      picomatch: ^3 || ^4
+    peerDependenciesMeta:
+      picomatch:
+        optional: true
+
+  fetch-blob@3.2.0:
+    resolution: {integrity: sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==}
+    engines: {node: ^12.20 || >= 14.13}
+
+  figures@6.1.0:
+    resolution: {integrity: sha512-d+l3qxjSesT4V7v2fh+QnmFnUWv9lSpjarhShNTgBOfA0ttejbQUAlHLitbjkoRiDulW0OPoQPYIGhIC8ohejg==}
+    engines: {node: '>=18'}
+
+  file-entry-cache@8.0.0:
+    resolution: {integrity: sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==}
+    engines: {node: '>=16.0.0'}
+
+  fill-range@7.1.1:
+    resolution: {integrity: sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==}
+    engines: {node: '>=8'}
+
+  finalhandler@2.1.1:
+    resolution: {integrity: sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==}
+    engines: {node: '>= 18.0.0'}
+
+  find-up@5.0.0:
+    resolution: {integrity: sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==}
+    engines: {node: '>=10'}
+
+  flat-cache@4.0.1:
+    resolution: {integrity: sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==}
+    engines: {node: '>=16'}
+
+  flatted@3.4.2:
+    resolution: {integrity: sha512-PjDse7RzhcPkIJwy5t7KPWQSZ9cAbzQXcafsetQoD7sOJRQlGikNbx7yZp2OotDnJyrDcbyRq3Ttb18iYOqkxA==}
+
+  formdata-polyfill@4.0.10:
+    resolution: {integrity: sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==}
+    engines: {node: '>=12.20.0'}
+
+  forwarded@0.2.0:
+    resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==}
+    engines: {node: '>= 0.6'}
+
+  fresh@2.0.0:
+    resolution: {integrity: sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==}
+    engines: {node: '>= 0.8'}
+
+  fs-extra@11.3.4:
+    resolution: {integrity: sha512-CTXd6rk/M3/ULNQj8FBqBWHYBVYybQ3VPBw0xGKFe3tuH7ytT6ACnvzpIQ3UZtB8yvUKC2cXn1a+x+5EVQLovA==}
+    engines: {node: '>=14.14'}
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  function-bind@1.1.2:
+    resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
+
+  fuzzysort@3.1.0:
+    resolution: {integrity: sha512-sR9BNCjBg6LNgwvxlBd0sBABvQitkLzoVY9MYYROQVX/FvfJ4Mai9LsGhDgd8qYdds0bY77VzYd5iuB+v5rwQQ==}
+
+  gensync@1.0.0-beta.2:
+    resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==}
+    engines: {node: '>=6.9.0'}
+
+  get-caller-file@2.0.5:
+    resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
+    engines: {node: 6.* || 8.* || >= 10.*}
+
+  get-east-asian-width@1.5.0:
+    resolution: {integrity: sha512-CQ+bEO+Tva/qlmw24dCejulK5pMzVnUOFOijVogd3KQs07HnRIgp8TGipvCCRT06xeYEbpbgwaCxglFyiuIcmA==}
+    engines: {node: '>=18'}
+
+  get-intrinsic@1.3.0:
+    resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==}
+    engines: {node: '>= 0.4'}
+
+  get-nonce@1.0.1:
+    resolution: {integrity: sha512-FJhYRoDaiatfEkUK8HKlicmu/3SGFD51q3itKDGoSTysQJBnfOcxU5GxnhE1E6soB76MbT0MBtnKJuXyAx+96Q==}
+    engines: {node: '>=6'}
+
+  get-own-enumerable-keys@1.0.0:
+    resolution: {integrity: sha512-PKsK2FSrQCyxcGHsGrLDcK0lx+0Ke+6e8KFFozA9/fIQLhQzPaRvJFdcz7+Axg3jUH/Mq+NI4xa5u/UT2tQskA==}
+    engines: {node: '>=14.16'}
+
+  get-proto@1.0.1:
+    resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==}
+    engines: {node: '>= 0.4'}
+
+  get-stream@6.0.1:
+    resolution: {integrity: sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==}
+    engines: {node: '>=10'}
+
+  get-stream@9.0.1:
+    resolution: {integrity: sha512-kVCxPF3vQM/N0B1PmoqVUqgHP+EeVjmZSQn+1oCRPxd2P21P2F19lIgbR3HBosbB1PUhOAoctJnfEn2GbN2eZA==}
+    engines: {node: '>=18'}
+
+  get-tsconfig@4.13.6:
+    resolution: {integrity: sha512-shZT/QMiSHc/YBLxxOkMtgSid5HFoauqCE3/exfsEcwg1WkeqjG+V40yBbBrsD+jW2HDXcs28xOfcbm2jI8Ddw==}
+
+  glob-parent@5.1.2:
+    resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}
+    engines: {node: '>= 6'}
+
+  glob-parent@6.0.2:
+    resolution: {integrity: sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==}
+    engines: {node: '>=10.13.0'}
+
+  globals@14.0.0:
+    resolution: {integrity: sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ==}
+    engines: {node: '>=18'}
+
+  globals@16.5.0:
+    resolution: {integrity: sha512-c/c15i26VrJ4IRt5Z89DnIzCGDn9EcebibhAOjw5ibqEHsE1wLUgkPn9RDmNcUKyU87GeaL633nyJ+pplFR2ZQ==}
+    engines: {node: '>=18'}
+
+  goober@2.1.18:
+    resolution: {integrity: sha512-2vFqsaDVIT9Gz7N6kAL++pLpp41l3PfDuusHcjnGLfR6+huZkl6ziX+zgVC3ZxpqWhzH6pyDdGrCeDhMIvwaxw==}
+    peerDependencies:
+      csstype: ^3.0.10
+
+  gopd@1.2.0:
+    resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==}
+    engines: {node: '>= 0.4'}
+
+  graceful-fs@4.2.11:
+    resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
+
+  graphql@16.13.1:
+    resolution: {integrity: sha512-gGgrVCoDKlIZ8fIqXBBb0pPKqDgki0Z/FSKNiQzSGj2uEYHr1tq5wmBegGwJx6QB5S5cM0khSBpi/JFHMCvsmQ==}
+    engines: {node: ^12.22.0 || ^14.16.0 || ^16.0.0 || >=17.0.0}
+
+  has-flag@4.0.0:
+    resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
+    engines: {node: '>=8'}
+
+  has-symbols@1.1.0:
+    resolution: {integrity: sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==}
+    engines: {node: '>= 0.4'}
+
+  hasown@2.0.2:
+    resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==}
+    engines: {node: '>= 0.4'}
+
+  hast-util-from-parse5@8.0.3:
+    resolution: {integrity: sha512-3kxEVkEKt0zvcZ3hCRYI8rqrgwtlIOFMWkbclACvjlDw8Li9S2hk/d51OI0nr/gIpdMHNepwgOKqZ/sy0Clpyg==}
+
+  hast-util-parse-selector@4.0.0:
+    resolution: {integrity: sha512-wkQCkSYoOGCRKERFWcxMVMOcYE2K1AaNLU8DXS9arxnLOUEWbOXKXiJUNzEpqZ3JOKpnha3jkFrumEjVliDe7A==}
+
+  hast-util-raw@9.1.0:
+    resolution: {integrity: sha512-Y8/SBAHkZGoNkpzqqfCldijcuUKh7/su31kEBp67cFY09Wy0mTRgtsLYsiIxMJxlu0f6AA5SUTbDR8K0rxnbUw==}
+
+  hast-util-sanitize@5.0.2:
+    resolution: {integrity: sha512-3yTWghByc50aGS7JlGhk61SPenfE/p1oaFeNwkOOyrscaOkMGrcW9+Cy/QAIOBpZxP1yqDIzFMR0+Np0i0+usg==}
+
+  hast-util-to-jsx-runtime@2.3.6:
+    resolution: {integrity: sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg==}
+
+  hast-util-to-parse5@8.0.1:
+    resolution: {integrity: sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA==}
+
+  hast-util-whitespace@3.0.0:
+    resolution: {integrity: sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==}
+
+  hastscript@9.0.1:
+    resolution: {integrity: sha512-g7df9rMFX/SPi34tyGCyUBREQoKkapwdY/T04Qn9TDWfHhAYt4/I0gMVirzK5wEzeUqIjEB+LXC/ypb7Aqno5w==}
+
+  headers-polyfill@4.0.3:
+    resolution: {integrity: sha512-IScLbePpkvO846sIwOtOTDjutRMWdXdJmXdMvk6gCBHxFO8d+QKOQedyZSxFTTFYRSmlgSTDtXqqq4pcenBXLQ==}
+
+  hermes-estree@0.25.1:
+    resolution: {integrity: sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw==}
+
+  hermes-parser@0.25.1:
+    resolution: {integrity: sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA==}
+
+  hono@4.12.8:
+    resolution: {integrity: sha512-VJCEvtrezO1IAR+kqEYnxUOoStaQPGrCmX3j4wDTNOcD1uRPFpGlwQUIW8niPuvHXaTUxeOUl5MMDGrl+tmO9A==}
+    engines: {node: '>=16.9.0'}
+
+  html-parse-stringify@3.0.1:
+    resolution: {integrity: sha512-KknJ50kTInJ7qIScF3jeaFRpMpE8/lfiTdzf/twXyPBLAGrLRTmkz3AdTnKeh40X8k9L2fdYwEp/42WGXIRGcg==}
+
+  html-url-attributes@3.0.1:
+    resolution: {integrity: sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ==}
+
+  html-void-elements@3.0.0:
+    resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==}
+
+  http-errors@2.0.1:
+    resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
+    engines: {node: '>= 0.8'}
+
+  https-proxy-agent@7.0.6:
+    resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==}
+    engines: {node: '>= 14'}
+
+  human-signals@2.1.0:
+    resolution: {integrity: sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw==}
+    engines: {node: '>=10.17.0'}
+
+  human-signals@8.0.1:
+    resolution: {integrity: sha512-eKCa6bwnJhvxj14kZk5NCPc6Hb6BdsU9DZcOnmQKSnO1VKrfV0zCvtttPZUsBvjmNDn8rpcJfpwSYnHBjc95MQ==}
+    engines: {node: '>=18.18.0'}
+
+  i18next-browser-languagedetector@8.2.1:
+    resolution: {integrity: sha512-bZg8+4bdmaOiApD7N7BPT9W8MLZG+nPTOFlLiJiT8uzKXFjhxw4v2ierCXOwB5sFDMtuA5G4kgYZ0AznZxQ/cw==}
+
+  i18next@25.8.20:
+    resolution: {integrity: sha512-xjo9+lbX/P1tQt3xpO2rfJiBppNfUnNIPKgCvNsTKsvTOCro1Qr/geXVg1N47j5ScOSaXAPq8ET93raK3Rr06A==}
+    peerDependencies:
+      typescript: ^5
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  iconv-lite@0.7.2:
+    resolution: {integrity: sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==}
+    engines: {node: '>=0.10.0'}
+
+  ignore@5.3.2:
+    resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
+    engines: {node: '>= 4'}
+
+  ignore@7.0.5:
+    resolution: {integrity: sha512-Hs59xBNfUIunMFgWAbGX5cq6893IbWg4KnrjbYwX3tx0ztorVgTDA6B2sxf8ejHJ4wz8BqGUMYlnzNBer5NvGg==}
+    engines: {node: '>= 4'}
+
+  import-fresh@3.3.1:
+    resolution: {integrity: sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==}
+    engines: {node: '>=6'}
+
+  imurmurhash@0.1.4:
+    resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
+    engines: {node: '>=0.8.19'}
+
+  inherits@2.0.4:
+    resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
+
+  inline-style-parser@0.2.7:
+    resolution: {integrity: sha512-Nb2ctOyNR8DqQoR0OwRG95uNWIC0C1lCgf5Naz5H6Ji72KZ8OcFZLz2P5sNgwlyoJ8Yif11oMuYs5pBQa86csA==}
+
+  ip-address@10.1.0:
+    resolution: {integrity: sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==}
+    engines: {node: '>= 12'}
+
+  ipaddr.js@1.9.1:
+    resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
+    engines: {node: '>= 0.10'}
+
+  is-alphabetical@2.0.1:
+    resolution: {integrity: sha512-FWyyY60MeTNyeSRpkM2Iry0G9hpr7/9kD40mD/cGQEuilcZYS4okz8SN2Q6rLCJ8gbCt6fN+rC+6tMGS99LaxQ==}
+
+  is-alphanumerical@2.0.1:
+    resolution: {integrity: sha512-hmbYhX/9MUMF5uh7tOXyK/n0ZvWpad5caBA17GsC6vyuCqaWliRG5K1qS9inmUhEMaOBIW7/whAnSwveW/LtZw==}
+
+  is-arrayish@0.2.1:
+    resolution: {integrity: sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==}
+
+  is-binary-path@2.1.0:
+    resolution: {integrity: sha512-ZMERYes6pDydyuGidse7OsHxtbI7WVeUEozgR/g7rd0xUimYNlvZRE/K2MgZTjWy725IfelLeVcEM97mmtRGXw==}
+    engines: {node: '>=8'}
+
+  is-decimal@2.0.1:
+    resolution: {integrity: sha512-AAB9hiomQs5DXWcRB1rqsxGUstbRroFOPPVAomNk/3XHR5JyEZChOyTWe2oayKnsSsr/kcGqF+z6yuH6HHpN0A==}
+
+  is-docker@3.0.0:
+    resolution: {integrity: sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+    hasBin: true
+
+  is-extglob@2.1.1:
+    resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==}
+    engines: {node: '>=0.10.0'}
+
+  is-fullwidth-code-point@3.0.0:
+    resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==}
+    engines: {node: '>=8'}
+
+  is-glob@4.0.3:
+    resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
+    engines: {node: '>=0.10.0'}
+
+  is-hexadecimal@2.0.1:
+    resolution: {integrity: sha512-DgZQp241c8oO6cA1SbTEWiXeoxV42vlcJxgH+B3hi1AiqqKruZR3ZGF8In3fj4+/y/7rHvlOZLZtgJ/4ttYGZg==}
+
+  is-in-ssh@1.0.0:
+    resolution: {integrity: sha512-jYa6Q9rH90kR1vKB6NM7qqd1mge3Fx4Dhw5TVlK1MUBqhEOuCagrEHMevNuCcbECmXZ0ThXkRm+Ymr51HwEPAw==}
+    engines: {node: '>=20'}
+
+  is-inside-container@1.0.0:
+    resolution: {integrity: sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==}
+    engines: {node: '>=14.16'}
+    hasBin: true
+
+  is-interactive@2.0.0:
+    resolution: {integrity: sha512-qP1vozQRI+BMOPcjFzrjXuQvdak2pHNUMZoeG2eRbiSqyvbEf/wQtEOTOX1guk6E3t36RkaqiSt8A/6YElNxLQ==}
+    engines: {node: '>=12'}
+
+  is-node-process@1.2.0:
+    resolution: {integrity: sha512-Vg4o6/fqPxIjtxgUH5QLJhwZ7gW5diGCVlXpuUfELC62CuxM1iHcRe51f2W1FDy04Ai4KJkagKjx3XaqyfRKXw==}
+
+  is-number@7.0.0:
+    resolution: {integrity: sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==}
+    engines: {node: '>=0.12.0'}
+
+  is-obj@3.0.0:
+    resolution: {integrity: sha512-IlsXEHOjtKhpN8r/tRFj2nDyTmHvcfNeu/nrRIcXE17ROeatXchkojffa1SpdqW4cr/Fj6QkEf/Gn4zf6KKvEQ==}
+    engines: {node: '>=12'}
+
+  is-plain-obj@4.1.0:
+    resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==}
+    engines: {node: '>=12'}
+
+  is-promise@4.0.0:
+    resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==}
+
+  is-regexp@3.1.0:
+    resolution: {integrity: sha512-rbku49cWloU5bSMI+zaRaXdQHXnthP6DZ/vLnfdSKyL4zUzuWnomtOEiZZOd+ioQ+avFo/qau3KPTc7Fjy1uPA==}
+    engines: {node: '>=12'}
+
+  is-stream@2.0.1:
+    resolution: {integrity: sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==}
+    engines: {node: '>=8'}
+
+  is-stream@4.0.1:
+    resolution: {integrity: sha512-Dnz92NInDqYckGEUJv689RbRiTSEHCQ7wOVeALbkOz999YpqT46yMRIGtSNl2iCL1waAZSx40+h59NV/EwzV/A==}
+    engines: {node: '>=18'}
+
+  is-unicode-supported@1.3.0:
+    resolution: {integrity: sha512-43r2mRvz+8JRIKnWJ+3j8JtjRKZ6GmjzfaE/qiBJnikNnYv/6bagRJ1kUhNk8R5EX/GkobD+r+sfxCPJsiKBLQ==}
+    engines: {node: '>=12'}
+
+  is-unicode-supported@2.1.0:
+    resolution: {integrity: sha512-mE00Gnza5EEB3Ds0HfMyllZzbBrmLOX3vfWoj9A9PEnTfratQ/BcaJOuMhnkhjXvb2+FkY3VuHqtAGpTPmglFQ==}
+    engines: {node: '>=18'}
+
+  is-wsl@3.1.1:
+    resolution: {integrity: sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==}
+    engines: {node: '>=16'}
+
+  isbot@5.1.36:
+    resolution: {integrity: sha512-C/ZtXyJqDPZ7G7JPr06ApWyYoHjYexQbS6hPYD4WYCzpv2Qes6Z+CCEfTX4Owzf+1EJ933PoI2p+B9v7wpGZBQ==}
+    engines: {node: '>=18'}
+
+  isexe@2.0.0:
+    resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
+
+  isexe@3.1.5:
+    resolution: {integrity: sha512-6B3tLtFqtQS4ekarvLVMZ+X+VlvQekbe4taUkf/rhVO3d/h0M2rfARm/pXLcPEsjjMsFgrFgSrhQIxcSVrBz8w==}
+    engines: {node: '>=18'}
+
+  javascript-natural-sort@0.7.1:
+    resolution: {integrity: sha512-nO6jcEfZWQXDhOiBtG2KvKyEptz7RVbpGP4vTD2hLBdmNQSsCiicO2Ioinv6UI4y9ukqnBpy+XZ9H6uLNgJTlw==}
+
+  jiti@2.6.1:
+    resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==}
+    hasBin: true
+
+  jose@6.2.2:
+    resolution: {integrity: sha512-d7kPDd34KO/YnzaDOlikGpOurfF0ByC2sEV4cANCtdqLlTfBlw2p14O/5d/zv40gJPbIQxfES3nSx1/oYNyuZQ==}
+
+  jotai@2.18.1:
+    resolution: {integrity: sha512-e0NOzK+yRFwHo7DOp0DS0Ycq74KMEAObDWFGmfEL28PD9nLqBTt3/Ug7jf9ca72x0gC9LQZG9zH+0ISICmy3iA==}
+    engines: {node: '>=12.20.0'}
+    peerDependencies:
+      '@babel/core': '>=7.0.0'
+      '@babel/template': '>=7.0.0'
+      '@types/react': '>=17.0.0'
+      react: '>=17.0.0'
+    peerDependenciesMeta:
+      '@babel/core':
+        optional: true
+      '@babel/template':
+        optional: true
+      '@types/react':
+        optional: true
+      react:
+        optional: true
+
+  js-tokens@4.0.0:
+    resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
+
+  js-yaml@4.1.1:
+    resolution: {integrity: sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==}
+    hasBin: true
+
+  jsesc@3.1.0:
+    resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  json-buffer@3.0.1:
+    resolution: {integrity: sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==}
+
+  json-parse-even-better-errors@2.3.1:
+    resolution: {integrity: sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==}
+
+  json-schema-traverse@0.4.1:
+    resolution: {integrity: sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==}
+
+  json-schema-traverse@1.0.0:
+    resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
+
+  json-schema-typed@8.0.2:
+    resolution: {integrity: sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==}
+
+  json-stable-stringify-without-jsonify@1.0.1:
+    resolution: {integrity: sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==}
+
+  json5@2.2.3:
+    resolution: {integrity: sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  jsonfile@6.2.0:
+    resolution: {integrity: sha512-FGuPw30AdOIUTRMC2OMRtQV+jkVj2cfPqSeWXv1NEAJ1qZ5zb1X6z1mFhbfOB/iy3ssJCD+3KuZ8r8C3uVFlAg==}
+
+  keyv@4.5.4:
+    resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==}
+
+  kleur@3.0.3:
+    resolution: {integrity: sha512-eTIzlVOSUR+JxdDFepEYcBMtZ9Qqdef+rnzWdRZuMbOywu5tO2w2N7rqjoANZ5k9vywhL6Br1VRjUIgTQx4E8w==}
+    engines: {node: '>=6'}
+
+  kleur@4.1.5:
+    resolution: {integrity: sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==}
+    engines: {node: '>=6'}
+
+  levn@0.4.1:
+    resolution: {integrity: sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==}
+    engines: {node: '>= 0.8.0'}
+
+  lightningcss-android-arm64@1.32.0:
+    resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.32.0:
+    resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.32.0:
+    resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.32.0:
+    resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  lightningcss-linux-x64-musl@1.32.0:
+    resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss@1.32.0:
+    resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==}
+    engines: {node: '>= 12.0.0'}
+
+  lines-and-columns@1.2.4:
+    resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==}
+
+  locate-path@6.0.0:
+    resolution: {integrity: sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==}
+    engines: {node: '>=10'}
+
+  lodash-es@4.17.23:
+    resolution: {integrity: sha512-kVI48u3PZr38HdYz98UmfPnXl2DXrpdctLrFLCd3kOx1xUkOmpFPx7gCWWM5MPkL/fD8zb+Ph0QzjGFs4+hHWg==}
+
+  lodash.merge@4.6.2:
+    resolution: {integrity: sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==}
+
+  log-symbols@6.0.0:
+    resolution: {integrity: sha512-i24m8rpwhmPIS4zscNzK6MSEhk0DUWa/8iYQWxhffV8jkI4Phvs3F+quL5xvS0gdQR0FyTCMMH33Y78dDTzzIw==}
+    engines: {node: '>=18'}
+
+  longest-streak@3.1.0:
+    resolution: {integrity: sha512-9Ri+o0JYgehTaVBBDoMqIl8GXtbWg711O3srftcHhZ0dqnETqLaoIK0x17fUw9rFSlK/0NlsKe0Ahhyl5pXE2g==}
+
+  lru-cache@5.1.1:
+    resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
+
+  magic-string@0.30.21:
+    resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
+
+  markdown-table@3.0.4:
+    resolution: {integrity: sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==}
+
+  math-intrinsics@1.1.0:
+    resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
+    engines: {node: '>= 0.4'}
+
+  mdast-util-find-and-replace@3.0.2:
+    resolution: {integrity: sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==}
+
+  mdast-util-from-markdown@2.0.3:
+    resolution: {integrity: sha512-W4mAWTvSlKvf8L6J+VN9yLSqQ9AOAAvHuoDAmPkz4dHf553m5gVj2ejadHJhoJmcmxEnOv6Pa8XJhpxE93kb8Q==}
+
+  mdast-util-gfm-autolink-literal@2.0.1:
+    resolution: {integrity: sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==}
+
+  mdast-util-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==}
+
+  mdast-util-gfm-strikethrough@2.0.0:
+    resolution: {integrity: sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==}
+
+  mdast-util-gfm-table@2.0.0:
+    resolution: {integrity: sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==}
+
+  mdast-util-gfm-task-list-item@2.0.0:
+    resolution: {integrity: sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==}
+
+  mdast-util-gfm@3.1.0:
+    resolution: {integrity: sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==}
+
+  mdast-util-mdx-expression@2.0.1:
+    resolution: {integrity: sha512-J6f+9hUp+ldTZqKRSg7Vw5V6MqjATc+3E4gf3CFNcuZNWD8XdyI6zQ8GqH7f8169MM6P7hMBRDVGnn7oHB9kXQ==}
+
+  mdast-util-mdx-jsx@3.2.0:
+    resolution: {integrity: sha512-lj/z8v0r6ZtsN/cGNNtemmmfoLAFZnjMbNyLzBafjzikOM+glrjNHPlf6lQDOTccj9n5b0PPihEBbhneMyGs1Q==}
+
+  mdast-util-mdxjs-esm@2.0.1:
+    resolution: {integrity: sha512-EcmOpxsZ96CvlP03NghtH1EsLtr0n9Tm4lPUJUBccV9RwUOneqSycg19n5HGzCf+10LozMRSObtVr3ee1WoHtg==}
+
+  mdast-util-phrasing@4.1.0:
+    resolution: {integrity: sha512-TqICwyvJJpBwvGAMZjj4J2n0X8QWp21b9l0o7eXyVJ25YNWYbJDVIyD1bZXE6WtV6RmKJVYmQAKWa0zWOABz2w==}
+
+  mdast-util-to-hast@13.2.1:
+    resolution: {integrity: sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==}
+
+  mdast-util-to-markdown@2.1.2:
+    resolution: {integrity: sha512-xj68wMTvGXVOKonmog6LwyJKrYXZPvlwabaryTjLh9LuvovB/KAH+kvi8Gjj+7rJjsFi23nkUxRQv1KqSroMqA==}
+
+  mdast-util-to-string@4.0.0:
+    resolution: {integrity: sha512-0H44vDimn51F0YwvxSJSm0eCDOJTRlmN0R1yBh4HLj9wiV1Dn0QoXGbvFAWj2hSItVTlCmBF1hqKlIyUBVFLPg==}
+
+  media-typer@1.1.0:
+    resolution: {integrity: sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==}
+    engines: {node: '>= 0.8'}
+
+  merge-descriptors@2.0.0:
+    resolution: {integrity: sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==}
+    engines: {node: '>=18'}
+
+  merge-stream@2.0.0:
+    resolution: {integrity: sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==}
+
+  merge2@1.4.1:
+    resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
+    engines: {node: '>= 8'}
+
+  micromark-core-commonmark@2.0.3:
+    resolution: {integrity: sha512-RDBrHEMSxVFLg6xvnXmb1Ayr2WzLAWjeSATAoxwKYJV94TeNavgoIdA0a9ytzDSVzBy2YKFK+emCPOEibLeCrg==}
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    resolution: {integrity: sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==}
+
+  micromark-extension-gfm-footnote@2.1.0:
+    resolution: {integrity: sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==}
+
+  micromark-extension-gfm-strikethrough@2.1.0:
+    resolution: {integrity: sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==}
+
+  micromark-extension-gfm-table@2.1.1:
+    resolution: {integrity: sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==}
+
+  micromark-extension-gfm-tagfilter@2.0.0:
+    resolution: {integrity: sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==}
+
+  micromark-extension-gfm-task-list-item@2.1.0:
+    resolution: {integrity: sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==}
+
+  micromark-extension-gfm@3.0.0:
+    resolution: {integrity: sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==}
+
+  micromark-factory-destination@2.0.1:
+    resolution: {integrity: sha512-Xe6rDdJlkmbFRExpTOmRj9N3MaWmbAgdpSrBQvCFqhezUn4AHqJHbaEnfbVYYiexVSs//tqOdY/DxhjdCiJnIA==}
+
+  micromark-factory-label@2.0.1:
+    resolution: {integrity: sha512-VFMekyQExqIW7xIChcXn4ok29YE3rnuyveW3wZQWWqF4Nv9Wk5rgJ99KzPvHjkmPXF93FXIbBp6YdW3t71/7Vg==}
+
+  micromark-factory-space@2.0.1:
+    resolution: {integrity: sha512-zRkxjtBxxLd2Sc0d+fbnEunsTj46SWXgXciZmHq0kDYGnck/ZSGj9/wULTV95uoeYiK5hRXP2mJ98Uo4cq/LQg==}
+
+  micromark-factory-title@2.0.1:
+    resolution: {integrity: sha512-5bZ+3CjhAd9eChYTHsjy6TGxpOFSKgKKJPJxr293jTbfry2KDoWkhBb6TcPVB4NmzaPhMs1Frm9AZH7OD4Cjzw==}
+
+  micromark-factory-whitespace@2.0.1:
+    resolution: {integrity: sha512-Ob0nuZ3PKt/n0hORHyvoD9uZhr+Za8sFoP+OnMcnWK5lngSzALgQYKMr9RJVOWLqQYuyn6ulqGWSXdwf6F80lQ==}
+
+  micromark-util-character@2.1.1:
+    resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==}
+
+  micromark-util-chunked@2.0.1:
+    resolution: {integrity: sha512-QUNFEOPELfmvv+4xiNg2sRYeS/P84pTW0TCgP5zc9FpXetHY0ab7SxKyAQCNCc1eK0459uoLI1y5oO5Vc1dbhA==}
+
+  micromark-util-classify-character@2.0.1:
+    resolution: {integrity: sha512-K0kHzM6afW/MbeWYWLjoHQv1sgg2Q9EccHEDzSkxiP/EaagNzCm7T/WMKZ3rjMbvIpvBiZgwR3dKMygtA4mG1Q==}
+
+  micromark-util-combine-extensions@2.0.1:
+    resolution: {integrity: sha512-OnAnH8Ujmy59JcyZw8JSbK9cGpdVY44NKgSM7E9Eh7DiLS2E9RNQf0dONaGDzEG9yjEl5hcqeIsj4hfRkLH/Bg==}
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    resolution: {integrity: sha512-ccUbYk6CwVdkmCQMyr64dXz42EfHGkPQlBj5p7YVGzq8I7CtjXZJrubAYezf7Rp+bjPseiROqe7G6foFd+lEuw==}
+
+  micromark-util-decode-string@2.0.1:
+    resolution: {integrity: sha512-nDV/77Fj6eH1ynwscYTOsbK7rR//Uj0bZXBwJZRfaLEJ1iGBR6kIfNmlNqaqJf649EP0F3NWNdeJi03elllNUQ==}
+
+  micromark-util-encode@2.0.1:
+    resolution: {integrity: sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==}
+
+  micromark-util-html-tag-name@2.0.1:
+    resolution: {integrity: sha512-2cNEiYDhCWKI+Gs9T0Tiysk136SnR13hhO8yW6BGNyhOC4qYFnwF1nKfD3HFAIXA5c45RrIG1ub11GiXeYd1xA==}
+
+  micromark-util-normalize-identifier@2.0.1:
+    resolution: {integrity: sha512-sxPqmo70LyARJs0w2UclACPUUEqltCkJ6PhKdMIDuJ3gSf/Q+/GIe3WKl0Ijb/GyH9lOpUkRAO2wp0GVkLvS9Q==}
+
+  micromark-util-resolve-all@2.0.1:
+    resolution: {integrity: sha512-VdQyxFWFT2/FGJgwQnJYbe1jjQoNTS4RjglmSjTUlpUMa95Htx9NHeYW4rGDJzbjvCsl9eLjMQwGeElsqmzcHg==}
+
+  micromark-util-sanitize-uri@2.0.1:
+    resolution: {integrity: sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==}
+
+  micromark-util-subtokenize@2.1.0:
+    resolution: {integrity: sha512-XQLu552iSctvnEcgXw6+Sx75GflAPNED1qx7eBJ+wydBb2KCbRZe+NwvIEEMM83uml1+2WSXpBAcp9IUCgCYWA==}
+
+  micromark-util-symbol@2.0.1:
+    resolution: {integrity: sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==}
+
+  micromark-util-types@2.0.2:
+    resolution: {integrity: sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==}
+
+  micromark@4.0.2:
+    resolution: {integrity: sha512-zpe98Q6kvavpCr1NPVSCMebCKfD7CA2NqZ+rykeNhONIJBpc1tFKt9hucLGwha3jNTNI8lHpctWJWoimVF4PfA==}
+
+  micromatch@4.0.8:
+    resolution: {integrity: sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==}
+    engines: {node: '>=8.6'}
+
+  mime-db@1.54.0:
+    resolution: {integrity: sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==}
+    engines: {node: '>= 0.6'}
+
+  mime-types@3.0.2:
+    resolution: {integrity: sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==}
+    engines: {node: '>=18'}
+
+  mimic-fn@2.1.0:
+    resolution: {integrity: sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==}
+    engines: {node: '>=6'}
+
+  mimic-function@5.0.1:
+    resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
+    engines: {node: '>=18'}
+
+  minimatch@10.2.4:
+    resolution: {integrity: sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg==}
+    engines: {node: 18 || 20 || >=22}
+
+  minimatch@3.1.5:
+    resolution: {integrity: sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==}
+
+  minimatch@9.0.9:
+    resolution: {integrity: sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==}
+    engines: {node: '>=16 || 14 >=14.17'}
+
+  minimist@1.2.8:
+    resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
+  msw@2.12.13:
+    resolution: {integrity: sha512-9CV2mXT9+z0J26MQDfEZZkj/psJ5Er/w0w+t95FWdaGH/DTlhNZBx8vBO5jSYv8AZEnl3ouX+AaTT68KXdAIag==}
+    engines: {node: '>=18'}
+    hasBin: true
+    peerDependencies:
+      typescript: '>= 4.8.x'
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
+  mute-stream@2.0.0:
+    resolution: {integrity: sha512-WWdIxpyjEn+FhQJQQv9aQAYlHoNVdzIzUySNV1gHUPDSdZJ3yZn7pAAbQcV7B56Mvu881q9FZV+0Vx2xC44VWA==}
+    engines: {node: ^18.17.0 || >=20.5.0}
+
+  nanoid@3.3.11:
+    resolution: {integrity: sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  natural-compare@1.4.0:
+    resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==}
+
+  negotiator@1.0.0:
+    resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
+    engines: {node: '>= 0.6'}
+
+  node-domexception@1.0.0:
+    resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==}
+    engines: {node: '>=10.5.0'}
+    deprecated: Use your platform's native DOMException instead
+
+  node-fetch@3.3.2:
+    resolution: {integrity: sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
+  node-releases@2.0.36:
+    resolution: {integrity: sha512-TdC8FSgHz8Mwtw9g5L4gR/Sh9XhSP/0DEkQxfEFXOpiul5IiHgHan2VhYYb6agDSfp4KuvltmGApc8HMgUrIkA==}
+
+  normalize-path@3.0.0:
+    resolution: {integrity: sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==}
+    engines: {node: '>=0.10.0'}
+
+  npm-run-path@4.0.1:
+    resolution: {integrity: sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw==}
+    engines: {node: '>=8'}
+
+  npm-run-path@6.0.0:
+    resolution: {integrity: sha512-9qny7Z9DsQU8Ou39ERsPU4OZQlSTP47ShQzuKZ6PRXpYLtIFgl/DEBYEXKlvcEa+9tHVcK8CF81Y2V72qaZhWA==}
+    engines: {node: '>=18'}
+
+  object-assign@4.1.1:
+    resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
+    engines: {node: '>=0.10.0'}
+
+  object-inspect@1.13.4:
+    resolution: {integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==}
+    engines: {node: '>= 0.4'}
+
+  object-treeify@1.1.33:
+    resolution: {integrity: sha512-EFVjAYfzWqWsBMRHPMAXLCDIJnpMhdWAqR7xG6M6a2cs6PMFpl/+Z20w9zDW4vkxOFfddegBKq9Rehd0bxWE7A==}
+    engines: {node: '>= 10'}
+
+  on-finished@2.4.1:
+    resolution: {integrity: sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==}
+    engines: {node: '>= 0.8'}
+
+  once@1.4.0:
+    resolution: {integrity: sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==}
+
+  onetime@5.1.2:
+    resolution: {integrity: sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==}
+    engines: {node: '>=6'}
+
+  onetime@7.0.0:
+    resolution: {integrity: sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==}
+    engines: {node: '>=18'}
+
+  open@11.0.0:
+    resolution: {integrity: sha512-smsWv2LzFjP03xmvFoJ331ss6h+jixfA4UUV/Bsiyuu4YJPfN+FIQGOIiv4w9/+MoHkfkJ22UIaQWRVFRfH6Vw==}
+    engines: {node: '>=20'}
+
+  optionator@0.9.4:
+    resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
+    engines: {node: '>= 0.8.0'}
+
+  ora@8.2.0:
+    resolution: {integrity: sha512-weP+BZ8MVNnlCm8c0Qdc1WSWq4Qn7I+9CJGm7Qali6g44e/PUzbjNqJX5NJ9ljlNMosfJvg1fKEGILklK9cwnw==}
+    engines: {node: '>=18'}
+
+  outvariant@1.4.3:
+    resolution: {integrity: sha512-+Sl2UErvtsoajRDKCE5/dBz4DIvHXQQnAxtQTF04OJxY0+DyZXSo5P5Bb7XYWOh81syohlYL24hbDwxedPUJCA==}
+
+  p-limit@3.1.0:
+    resolution: {integrity: sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==}
+    engines: {node: '>=10'}
+
+  p-locate@5.0.0:
+    resolution: {integrity: sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==}
+    engines: {node: '>=10'}
+
+  parent-module@1.0.1:
+    resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
+    engines: {node: '>=6'}
+
+  parse-entities@4.0.2:
+    resolution: {integrity: sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw==}
+
+  parse-imports-exports@0.2.4:
+    resolution: {integrity: sha512-4s6vd6dx1AotCx/RCI2m7t7GCh5bDRUtGNvRfHSP2wbBQdMi67pPe7mtzmgwcaQ8VKK/6IB7Glfyu3qdZJPybQ==}
+
+  parse-json@5.2.0:
+    resolution: {integrity: sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==}
+    engines: {node: '>=8'}
+
+  parse-ms@4.0.0:
+    resolution: {integrity: sha512-TXfryirbmq34y8QBwgqCVLi+8oA3oWx2eAnSn62ITyEhEYaWRlVZ2DvMM9eZbMs/RfxPu/PK/aBLyGj4IrqMHw==}
+    engines: {node: '>=18'}
+
+  parse-statements@1.0.11:
+    resolution: {integrity: sha512-HlsyYdMBnbPQ9Jr/VgJ1YF4scnldvJpJxCVx6KgqPL4dxppsWrJHCIIxQXMJrqGnsRkNPATbeMJ8Yxu7JMsYcA==}
+
+  parse5@7.3.0:
+    resolution: {integrity: sha512-IInvU7fabl34qmi9gY8XOVxhYyMyuH2xUNpb2q8/Y+7552KlejkRvqvD19nMoUW/uQGGbqNpA6Tufu5FL5BZgw==}
+
+  parseurl@1.3.3:
+    resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==}
+    engines: {node: '>= 0.8'}
+
+  path-browserify@1.0.1:
+    resolution: {integrity: sha512-b7uo2UCUOYZcnF/3ID0lulOJi/bafxa1xPe7ZPsammBSpjSWQkjNxlt635YGS2MiR9GjvuXCtz2emr3jbsz98g==}
+
+  path-exists@4.0.0:
+    resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==}
+    engines: {node: '>=8'}
+
+  path-key@3.1.1:
+    resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==}
+    engines: {node: '>=8'}
+
+  path-key@4.0.0:
+    resolution: {integrity: sha512-haREypq7xkM7ErfgIyA0z+Bj4AGKlMSdlQE2jvJo6huWD1EdkKYV+G/T4nq0YEF2vgTT8kqMFKo1uHn950r4SQ==}
+    engines: {node: '>=12'}
+
+  path-to-regexp@6.3.0:
+    resolution: {integrity: sha512-Yhpw4T9C6hPpgPeA28us07OJeqZ5EzQTkbfwuhsUg0c237RomFoETJgmp2sa3F/41gfLE6G5cqcYwznmeEeOlQ==}
+
+  path-to-regexp@8.3.0:
+    resolution: {integrity: sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA==}
+
+  pathe@2.0.3:
+    resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  picomatch@2.3.1:
+    resolution: {integrity: sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==}
+    engines: {node: '>=8.6'}
+
+  picomatch@4.0.3:
+    resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==}
+    engines: {node: '>=12'}
+
+  pkce-challenge@5.0.1:
+    resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==}
+    engines: {node: '>=16.20.0'}
+
+  postcss-selector-parser@6.0.10:
+    resolution: {integrity: sha512-IQ7TZdoaqbT+LCpShg46jnZVlhWD2w6iQYAcYXfHARZ7X1t/UGhhceQDs5X0cGqKvYlHNOuv7Oa1xmb0oQuA3w==}
+    engines: {node: '>=4'}
+
+  postcss-selector-parser@7.1.1:
+    resolution: {integrity: sha512-orRsuYpJVw8LdAwqqLykBj9ecS5/cRHlI5+nvTo8LcCKmzDmqVORXtOIYEEQuL9D4BxtA1lm5isAqzQZCoQ6Eg==}
+    engines: {node: '>=4'}
+
+  postcss@8.5.8:
+    resolution: {integrity: sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  powershell-utils@0.1.0:
+    resolution: {integrity: sha512-dM0jVuXJPsDN6DvRpea484tCUaMiXWjuCn++HGTqUWzGDjv5tZkEZldAJ/UMlqRYGFrD/etByo4/xOuC/snX2A==}
+    engines: {node: '>=20'}
+
+  prelude-ls@1.2.1:
+    resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==}
+    engines: {node: '>= 0.8.0'}
+
+  prettier-plugin-tailwindcss@0.7.2:
+    resolution: {integrity: sha512-LkphyK3Fw+q2HdMOoiEHWf93fNtYJwfamoKPl7UwtjFQdei/iIBoX11G6j706FzN3ymX9mPVi97qIY8328vdnA==}
+    engines: {node: '>=20.19'}
+    peerDependencies:
+      '@ianvs/prettier-plugin-sort-imports': '*'
+      '@prettier/plugin-hermes': '*'
+      '@prettier/plugin-oxc': '*'
+      '@prettier/plugin-pug': '*'
+      '@shopify/prettier-plugin-liquid': '*'
+      '@trivago/prettier-plugin-sort-imports': '*'
+      '@zackad/prettier-plugin-twig': '*'
+      prettier: ^3.0
+      prettier-plugin-astro: '*'
+      prettier-plugin-css-order: '*'
+      prettier-plugin-jsdoc: '*'
+      prettier-plugin-marko: '*'
+      prettier-plugin-multiline-arrays: '*'
+      prettier-plugin-organize-attributes: '*'
+      prettier-plugin-organize-imports: '*'
+      prettier-plugin-sort-imports: '*'
+      prettier-plugin-svelte: '*'
+    peerDependenciesMeta:
+      '@ianvs/prettier-plugin-sort-imports':
+        optional: true
+      '@prettier/plugin-hermes':
+        optional: true
+      '@prettier/plugin-oxc':
+        optional: true
+      '@prettier/plugin-pug':
+        optional: true
+      '@shopify/prettier-plugin-liquid':
+        optional: true
+      '@trivago/prettier-plugin-sort-imports':
+        optional: true
+      '@zackad/prettier-plugin-twig':
+        optional: true
+      prettier-plugin-astro:
+        optional: true
+      prettier-plugin-css-order:
+        optional: true
+      prettier-plugin-jsdoc:
+        optional: true
+      prettier-plugin-marko:
+        optional: true
+      prettier-plugin-multiline-arrays:
+        optional: true
+      prettier-plugin-organize-attributes:
+        optional: true
+      prettier-plugin-organize-imports:
+        optional: true
+      prettier-plugin-sort-imports:
+        optional: true
+      prettier-plugin-svelte:
+        optional: true
+
+  prettier@3.8.1:
+    resolution: {integrity: sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==}
+    engines: {node: '>=14'}
+    hasBin: true
+
+  pretty-ms@9.3.0:
+    resolution: {integrity: sha512-gjVS5hOP+M3wMm5nmNOucbIrqudzs9v/57bWRHQWLYklXqoXKrVfYW2W9+glfGsqtPgpiz5WwyEEB+ksXIx3gQ==}
+    engines: {node: '>=18'}
+
+  prompts@2.4.2:
+    resolution: {integrity: sha512-NxNv/kLguCA7p3jE8oL2aEBsrJWgAakBpgmgK6lpPWV+WuOmY6r2/zbAVnP+T8bQlA0nzHXSJSJW0Hq7ylaD2Q==}
+    engines: {node: '>= 6'}
+
+  property-information@7.1.0:
+    resolution: {integrity: sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==}
+
+  proxy-addr@2.0.7:
+    resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==}
+    engines: {node: '>= 0.10'}
+
+  punycode@2.3.1:
+    resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
+    engines: {node: '>=6'}
+
+  qs@6.15.0:
+    resolution: {integrity: sha512-mAZTtNCeetKMH+pSjrb76NAM8V9a05I9aBZOHztWy/UqcJdQYNsf59vrRKWnojAT9Y+GbIvoTBC++CPHqpDBhQ==}
+    engines: {node: '>=0.6'}
+
+  queue-microtask@1.2.3:
+    resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==}
+
+  radix-ui@1.4.3:
+    resolution: {integrity: sha512-aWizCQiyeAenIdUbqEpXgRA1ya65P13NKn/W8rWkcN0OPkRDxdBVLWnIEDsS2RpwCK2nobI7oMUSmexzTDyAmA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  range-parser@1.2.1:
+    resolution: {integrity: sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==}
+    engines: {node: '>= 0.6'}
+
+  raw-body@3.0.2:
+    resolution: {integrity: sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==}
+    engines: {node: '>= 0.10'}
+
+  react-dom@19.2.4:
+    resolution: {integrity: sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ==}
+    peerDependencies:
+      react: ^19.2.4
+
+  react-i18next@16.5.8:
+    resolution: {integrity: sha512-2ABeHHlakxVY+LSirD+OiERxFL6+zip0PaHo979bgwzeHg27Sqc82xxXWIrSFmfWX0ZkrvXMHwhsi/NGUf5VQg==}
+    peerDependencies:
+      i18next: '>= 25.6.2'
+      react: '>= 16.8.0'
+      react-dom: '*'
+      react-native: '*'
+      typescript: ^5
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+      react-native:
+        optional: true
+      typescript:
+        optional: true
+
+  react-markdown@10.1.0:
+    resolution: {integrity: sha512-qKxVopLT/TyA6BX3Ue5NwabOsAzm0Q7kAPwq6L+wWDwisYs7R8vZ0nRXqq6rkueboxpkjvLGU9fWifiX/ZZFxQ==}
+    peerDependencies:
+      '@types/react': '>=18'
+      react: '>=18'
+
+  react-refresh@0.18.0:
+    resolution: {integrity: sha512-QgT5//D3jfjJb6Gsjxv0Slpj23ip+HtOpnNgnb2S5zU3CB26G/IDPGoy4RJB42wzFE46DRsstbW6tKHoKbhAxw==}
+    engines: {node: '>=0.10.0'}
+
+  react-remove-scroll-bar@2.3.8:
+    resolution: {integrity: sha512-9r+yi9+mgU33AKcj6IbT9oRCO78WriSj6t/cF8DWBZJ9aOGPOTEDvdUDz1FwKim7QXWwmHqtdHnRJfhAxEG46Q==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-remove-scroll@2.7.2:
+    resolution: {integrity: sha512-Iqb9NjCCTt6Hf+vOdNIZGdTiH1QSqr27H/Ek9sv/a97gfueI/5h1s3yRi1nngzMUaOOToin5dI1dXKdXiF+u0Q==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-style-singleton@2.2.3:
+    resolution: {integrity: sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-textarea-autosize@8.5.9:
+    resolution: {integrity: sha512-U1DGlIQN5AwgjTyOEnI1oCcMuEr1pv1qOtklB2l4nyMGbHzWrI0eFsYK0zos2YWqAolJyG0IWJaqWmWj5ETh0A==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  react@19.2.4:
+    resolution: {integrity: sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==}
+    engines: {node: '>=0.10.0'}
+
+  readdirp@3.6.0:
+    resolution: {integrity: sha512-hOS089on8RduqdbhvQ5Z37A0ESjsqz6qnRcffsMU3495FuTdqSm+7bhJ29JvIOsBDEEnan5DPu9t3To9VRlMzA==}
+    engines: {node: '>=8.10.0'}
+
+  recast@0.23.11:
+    resolution: {integrity: sha512-YTUo+Flmw4ZXiWfQKGcwwc11KnoRAYgzAE2E7mXKCjSviTKShtxBsN6YUUBB2gtaBzKzeKunxhUwNHQuRryhWA==}
+    engines: {node: '>= 4'}
+
+  rehype-raw@7.0.0:
+    resolution: {integrity: sha512-/aE8hCfKlQeA8LmyeyQvQF3eBiLRGNlfBJEvWH7ivp9sBqs7TNqBL5X3v157rM4IFETqDnIOO+z5M/biZbo9Ww==}
+
+  rehype-sanitize@6.0.0:
+    resolution: {integrity: sha512-CsnhKNsyI8Tub6L4sm5ZFsme4puGfc6pYylvXo1AeqaGbjOYyzNv3qZPwvs0oMJ39eryyeOdmxwUIo94IpEhqg==}
+
+  remark-gfm@4.0.1:
+    resolution: {integrity: sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==}
+
+  remark-parse@11.0.0:
+    resolution: {integrity: sha512-FCxlKLNGknS5ba/1lmpYijMUzX2esxW5xQqjWxw2eHFfS2MSdaHVINFmhjo+qN1WhZhNimq0dZATN9pH0IDrpA==}
+
+  remark-rehype@11.1.2:
+    resolution: {integrity: sha512-Dh7l57ianaEoIpzbp0PC9UKAdCSVklD8E5Rpw7ETfbTl3FqcOOgq5q2LVDhgGCkaBv7p24JXikPdvhhmHvKMsw==}
+
+  remark-stringify@11.0.0:
+    resolution: {integrity: sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==}
+
+  require-directory@2.1.1:
+    resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
+    engines: {node: '>=0.10.0'}
+
+  require-from-string@2.0.2:
+    resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
+    engines: {node: '>=0.10.0'}
+
+  resolve-from@4.0.0:
+    resolution: {integrity: sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==}
+    engines: {node: '>=4'}
+
+  resolve-pkg-maps@1.0.0:
+    resolution: {integrity: sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==}
+
+  restore-cursor@5.1.0:
+    resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
+    engines: {node: '>=18'}
+
+  rettime@0.10.1:
+    resolution: {integrity: sha512-uyDrIlUEH37cinabq0AX4QbgV4HbFZ/gqoiunWQ1UqBtRvTTytwhNYjE++pO/MjPTZL5KQCf2bEoJ/BJNVQ5Kw==}
+
+  reusify@1.1.0:
+    resolution: {integrity: sha512-g6QUff04oZpHs0eG5p83rFLhHeV00ug/Yf9nZM6fLeUrPguBTkTQOdpAWWspMh55TZfVQDPaN3NQJfbVRAxdIw==}
+    engines: {iojs: '>=1.0.0', node: '>=0.10.0'}
+
+  rollup@4.59.0:
+    resolution: {integrity: sha512-2oMpl67a3zCH9H79LeMcbDhXW/UmWG/y2zuqnF2jQq5uq9TbM9TVyXvA4+t+ne2IIkBdrLpAaRQAvo7YI/Yyeg==}
+    engines: {node: '>=18.0.0', npm: '>=8.0.0'}
+    hasBin: true
+
+  router@2.2.0:
+    resolution: {integrity: sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==}
+    engines: {node: '>= 18'}
+
+  run-applescript@7.1.0:
+    resolution: {integrity: sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==}
+    engines: {node: '>=18'}
+
+  run-parallel@1.2.0:
+    resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
+
+  safer-buffer@2.1.2:
+    resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
+
+  scheduler@0.27.0:
+    resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
+
+  semver@6.3.1:
+    resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
+    hasBin: true
+
+  semver@7.7.4:
+    resolution: {integrity: sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==}
+    engines: {node: '>=10'}
+    hasBin: true
+
+  send@1.2.1:
+    resolution: {integrity: sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==}
+    engines: {node: '>= 18'}
+
+  seroval-plugins@1.5.1:
+    resolution: {integrity: sha512-4FbuZ/TMl02sqv0RTFexu0SP6V+ywaIe5bAWCCEik0fk17BhALgwvUDVF7e3Uvf9pxmwCEJsRPmlkUE6HdzLAw==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      seroval: ^1.0
+
+  seroval@1.5.1:
+    resolution: {integrity: sha512-OwrZRZAfhHww0WEnKHDY8OM0U/Qs8OTfIDWhUD4BLpNJUfXK4cGmjiagGze086m+mhI+V2nD0gfbHEnJjb9STA==}
+    engines: {node: '>=10'}
+
+  serve-static@2.2.1:
+    resolution: {integrity: sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==}
+    engines: {node: '>= 18'}
+
+  setprototypeof@1.2.0:
+    resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==}
+
+  shadcn@4.1.0:
+    resolution: {integrity: sha512-3zETJ+0Ezj69FS6RL0HOkLKKAR5yXisXx1iISJdfLQfrUqj/VIQlanQi1Ukk+9OE+XHZVj4FQNTBSfbr2CyCYg==}
+    hasBin: true
+
+  shebang-command@2.0.0:
+    resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
+    engines: {node: '>=8'}
+
+  shebang-regex@3.0.0:
+    resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
+    engines: {node: '>=8'}
+
+  side-channel-list@1.0.0:
+    resolution: {integrity: sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-map@1.0.1:
+    resolution: {integrity: sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-weakmap@1.0.2:
+    resolution: {integrity: sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==}
+    engines: {node: '>= 0.4'}
+
+  side-channel@1.1.0:
+    resolution: {integrity: sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==}
+    engines: {node: '>= 0.4'}
+
+  signal-exit@3.0.7:
+    resolution: {integrity: sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==}
+
+  signal-exit@4.1.0:
+    resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
+    engines: {node: '>=14'}
+
+  sisteransi@1.0.5:
+    resolution: {integrity: sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==}
+
+  sonner@2.0.7:
+    resolution: {integrity: sha512-W6ZN4p58k8aDKA4XPcx2hpIQXBRAgyiWVkYhT7CvK6D3iAu7xjvVyhQHg2/iaKJZ1XVJ4r7XuwGL+WGEK37i9w==}
+    peerDependencies:
+      react: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+      react-dom: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+
+  source-map-js@1.2.1:
+    resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
+    engines: {node: '>=0.10.0'}
+
+  source-map@0.6.1:
+    resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==}
+    engines: {node: '>=0.10.0'}
+
+  source-map@0.7.6:
+    resolution: {integrity: sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==}
+    engines: {node: '>= 12'}
+
+  space-separated-tokens@2.0.2:
+    resolution: {integrity: sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==}
+
+  statuses@2.0.2:
+    resolution: {integrity: sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==}
+    engines: {node: '>= 0.8'}
+
+  stdin-discarder@0.2.2:
+    resolution: {integrity: sha512-UhDfHmA92YAlNnCfhmq0VeNL5bDbiZGg7sZ2IvPsXubGkiNa9EC+tUTsjBRsYUAz87btI6/1wf4XoVvQ3uRnmQ==}
+    engines: {node: '>=18'}
+
+  strict-event-emitter@0.5.1:
+    resolution: {integrity: sha512-vMgjE/GGEPEFnhFub6pa4FmJBRBVOLpIII2hvCZ8Kzb7K0hlHo7mQv6xYrBvCL2LtAIBwFUK8wvuJgTVSQ5MFQ==}
+
+  string-width@4.2.3:
+    resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
+    engines: {node: '>=8'}
+
+  string-width@7.2.0:
+    resolution: {integrity: sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==}
+    engines: {node: '>=18'}
+
+  string-width@8.2.0:
+    resolution: {integrity: sha512-6hJPQ8N0V0P3SNmP6h2J99RLuzrWz2gvT7VnK5tKvrNqJoyS9W4/Fb8mo31UiPvy00z7DQXkP2hnKBVav76thw==}
+    engines: {node: '>=20'}
+
+  stringify-entities@4.0.4:
+    resolution: {integrity: sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==}
+
+  stringify-object@5.0.0:
+    resolution: {integrity: sha512-zaJYxz2FtcMb4f+g60KsRNFOpVMUyuJgA51Zi5Z1DOTC3S59+OQiVOzE9GZt0x72uBGWKsQIuBKeF9iusmKFsg==}
+    engines: {node: '>=14.16'}
+
+  strip-ansi@6.0.1:
+    resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==}
+    engines: {node: '>=8'}
+
+  strip-ansi@7.2.0:
+    resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
+    engines: {node: '>=12'}
+
+  strip-bom@3.0.0:
+    resolution: {integrity: sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==}
+    engines: {node: '>=4'}
+
+  strip-final-newline@2.0.0:
+    resolution: {integrity: sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA==}
+    engines: {node: '>=6'}
+
+  strip-final-newline@4.0.0:
+    resolution: {integrity: sha512-aulFJcD6YK8V1G7iRB5tigAP4TsHBZZrOV8pjV++zdUwmeV8uzbY7yn6h9MswN62adStNZFuCIx4haBnRuMDaw==}
+    engines: {node: '>=18'}
+
+  strip-json-comments@3.1.1:
+    resolution: {integrity: sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==}
+    engines: {node: '>=8'}
+
+  style-to-js@1.1.21:
+    resolution: {integrity: sha512-RjQetxJrrUJLQPHbLku6U/ocGtzyjbJMP9lCNK7Ag0CNh690nSH8woqWH9u16nMjYBAok+i7JO1NP2pOy8IsPQ==}
+
+  style-to-object@1.0.14:
+    resolution: {integrity: sha512-LIN7rULI0jBscWQYaSswptyderlarFkjQ+t79nzty8tcIAceVomEVlLzH5VP4Cmsv6MtKhs7qaAiwlcp+Mgaxw==}
+
+  supports-color@7.2.0:
+    resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
+    engines: {node: '>=8'}
+
+  tagged-tag@1.0.0:
+    resolution: {integrity: sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==}
+    engines: {node: '>=20'}
+
+  tailwind-merge@3.5.0:
+    resolution: {integrity: sha512-I8K9wewnVDkL1NTGoqWmVEIlUcB9gFriAEkXkfCjX5ib8ezGxtR3xD7iZIxrfArjEsH7F1CHD4RFUtxefdqV/A==}
+
+  tailwindcss@4.2.2:
+    resolution: {integrity: sha512-KWBIxs1Xb6NoLdMVqhbhgwZf2PGBpPEiwOqgI4pFIYbNTfBXiKYyWoTsXgBQ9WFg/OlhnvHaY+AEpW7wSmFo2Q==}
+
+  tapable@2.3.0:
+    resolution: {integrity: sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg==}
+    engines: {node: '>=6'}
+
+  tiny-invariant@1.3.3:
+    resolution: {integrity: sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg==}
+
+  tiny-warning@1.0.3:
+    resolution: {integrity: sha512-lBN9zLN/oAf68o3zNXYrdCt1kP8WsiGW8Oo2ka41b2IM5JL/S1CTyX1rW0mb/zSuJun0ZUrDxx4sqvYS2FWzPA==}
+
+  tinyglobby@0.2.15:
+    resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==}
+    engines: {node: '>=12.0.0'}
+
+  tldts-core@7.0.26:
+    resolution: {integrity: sha512-5WJ2SqFsv4G2Dwi7ZFVRnz6b2H1od39QME1lc2y5Ew3eWiZMAeqOAfWpRP9jHvhUl881406QtZTODvjttJs+ew==}
+
+  tldts@7.0.26:
+    resolution: {integrity: sha512-WiGwQjr0qYdNNG8KpMKlSvpxz652lqa3Rd+/hSaDcY4Uo6SKWZq2LAF+hsAhUewTtYhXlorBKgNF3Kk8hnjGoQ==}
+    hasBin: true
+
+  to-regex-range@5.0.1:
+    resolution: {integrity: sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==}
+    engines: {node: '>=8.0'}
+
+  toidentifier@1.0.1:
+    resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==}
+    engines: {node: '>=0.6'}
+
+  tough-cookie@6.0.1:
+    resolution: {integrity: sha512-LktZQb3IeoUWB9lqR5EWTHgW/VTITCXg4D21M+lvybRVdylLrRMnqaIONLVb5mav8vM19m44HIcGq4qASeu2Qw==}
+    engines: {node: '>=16'}
+
+  trim-lines@3.0.1:
+    resolution: {integrity: sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==}
+
+  trough@2.2.0:
+    resolution: {integrity: sha512-tmMpK00BjZiUyVyvrBK7knerNgmgvcV/KLVyuma/SC+TQN167GrMRciANTz09+k3zW8L8t60jWO1GpfkZdjTaw==}
+
+  ts-api-utils@2.5.0:
+    resolution: {integrity: sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==}
+    engines: {node: '>=18.12'}
+    peerDependencies:
+      typescript: '>=4.8.4'
+
+  ts-morph@26.0.0:
+    resolution: {integrity: sha512-ztMO++owQnz8c/gIENcM9XfCEzgoGphTv+nKpYNM1bgsdOVC/jRZuEBf6N+mLLDNg68Kl+GgUZfOySaRiG1/Ug==}
+
+  tsconfig-paths@4.2.0:
+    resolution: {integrity: sha512-NoZ4roiN7LnbKn9QqE1amc9DJfzvZXxF4xDavcOWt1BPkdx+m+0gJuPM+S0vCe7zTJMYUP0R8pO2XMr+Y8oLIg==}
+    engines: {node: '>=6'}
+
+  tslib@2.8.1:
+    resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
+
+  tsx@4.21.0:
+    resolution: {integrity: sha512-5C1sg4USs1lfG0GFb2RLXsdpXqBSEhAaA/0kPL01wxzpMqLILNxIxIOKiILz+cdg/pLnOUxFYOR5yhHU666wbw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  tw-animate-css@1.4.0:
+    resolution: {integrity: sha512-7bziOlRqH0hJx80h/3mbicLW7o8qLsH5+RaLR2t+OHM3D0JlWGODQKQ4cxbK7WlvmUxpcj6Kgu6EKqjrGFe3QQ==}
+
+  type-check@0.4.0:
+    resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==}
+    engines: {node: '>= 0.8.0'}
+
+  type-fest@5.5.0:
+    resolution: {integrity: sha512-PlBfpQwiUvGViBNX84Yxwjsdhd1TUlXr6zjX7eoirtCPIr08NAmxwa+fcYBTeRQxHo9YC9wwF3m9i700sHma8g==}
+    engines: {node: '>=20'}
+
+  type-is@2.0.1:
+    resolution: {integrity: sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==}
+    engines: {node: '>= 0.6'}
+
+  typescript-eslint@8.57.1:
+    resolution: {integrity: sha512-fLvZWf+cAGw3tqMCYzGIU6yR8K+Y9NT2z23RwOjlNFF2HwSB3KhdEFI5lSBv8tNmFkkBShSjsCjzx1vahZfISA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.0.0'
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  undici-types@7.18.2:
+    resolution: {integrity: sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==}
+
+  unicorn-magic@0.3.0:
+    resolution: {integrity: sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==}
+    engines: {node: '>=18'}
+
+  unified@11.0.5:
+    resolution: {integrity: sha512-xKvGhPWw3k84Qjh8bI3ZeJjqnyadK+GEFtazSfZv/rKeTkTjOJho6mFqh2SM96iIcZokxiOpg78GazTSg8+KHA==}
+
+  unist-util-is@6.0.1:
+    resolution: {integrity: sha512-LsiILbtBETkDz8I9p1dQ0uyRUWuaQzd/cuEeS1hoRSyW5E5XGmTzlwY1OrNzzakGowI9Dr/I8HVaw4hTtnxy8g==}
+
+  unist-util-position@5.0.0:
+    resolution: {integrity: sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==}
+
+  unist-util-stringify-position@4.0.0:
+    resolution: {integrity: sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==}
+
+  unist-util-visit-parents@6.0.2:
+    resolution: {integrity: sha512-goh1s1TBrqSqukSc8wrjwWhL0hiJxgA8m4kFxGlQ+8FYQ3C/m11FcTs4YYem7V664AhHVvgoQLk890Ssdsr2IQ==}
+
+  unist-util-visit@5.1.0:
+    resolution: {integrity: sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==}
+
+  universalify@2.0.1:
+    resolution: {integrity: sha512-gptHNQghINnc/vTGIk0SOFGFNXw7JVrlRUtConJRlvaw6DuX0wO5Jeko9sWrMBhh+PsYAZ7oXAiOnf/UKogyiw==}
+    engines: {node: '>= 10.0.0'}
+
+  unpipe@1.0.0:
+    resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
+    engines: {node: '>= 0.8'}
+
+  unplugin@2.3.11:
+    resolution: {integrity: sha512-5uKD0nqiYVzlmCRs01Fhs2BdkEgBS3SAVP6ndrBsuK42iC2+JHyxM05Rm9G8+5mkmRtzMZGY8Ct5+mliZxU/Ww==}
+    engines: {node: '>=18.12.0'}
+
+  until-async@3.0.2:
+    resolution: {integrity: sha512-IiSk4HlzAMqTUseHHe3VhIGyuFmN90zMTpD3Z3y8jeQbzLIq500MVM7Jq2vUAnTKAFPJrqwkzr6PoTcPhGcOiw==}
+
+  update-browserslist-db@1.2.3:
+    resolution: {integrity: sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==}
+    hasBin: true
+    peerDependencies:
+      browserslist: '>= 4.21.0'
+
+  uri-js@4.4.1:
+    resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}
+
+  use-callback-ref@1.3.3:
+    resolution: {integrity: sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-composed-ref@1.4.0:
+    resolution: {integrity: sha512-djviaxuOOh7wkj0paeO1Q/4wMZ8Zrnag5H6yBvzN7AKKe8beOaED9SF5/ByLqsku8NP4zQqsvM2u3ew/tJK8/w==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-isomorphic-layout-effect@1.2.1:
+    resolution: {integrity: sha512-tpZZ+EX0gaghDAiFR37hj5MgY6ZN55kLiPkJsKxBMZ6GZdOSPJXiOzPM984oPYZ5AnehYx5WQp1+ME8I/P/pRA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-latest@1.3.0:
+    resolution: {integrity: sha512-mhg3xdm9NaM8q+gLT8KryJPnRFOz1/5XPBhmDEVZK1webPzDjrPk7f/mbpeLqTgB9msytYWANxgALOCJKnLvcQ==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-sidecar@1.1.3:
+    resolution: {integrity: sha512-Fedw0aZvkhynoPYlA5WXrMCAMm+nSWdZt6lzJQ7Ok8S6Q+VsHmHpRWndVRJ8Be0ZbkfPc5LRYH+5XrzXcEeLRQ==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-sync-external-store@1.6.0:
+    resolution: {integrity: sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  util-deprecate@1.0.2:
+    resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
+
+  validate-npm-package-name@7.0.2:
+    resolution: {integrity: sha512-hVDIBwsRruT73PbK7uP5ebUt+ezEtCmzZz3F59BSr2F6OVFnJ/6h8liuvdLrQ88Xmnk6/+xGGuq+pG9WwTuy3A==}
+    engines: {node: ^20.17.0 || >=22.9.0}
+
+  vary@1.1.2:
+    resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
+    engines: {node: '>= 0.8'}
+
+  vfile-location@5.0.3:
+    resolution: {integrity: sha512-5yXvWDEgqeiYiBe1lbxYF7UMAIm/IcopxMHrMQDq3nvKcjPKIhZklUKL+AE7J7uApI4kwe2snsK+eI6UTj9EHg==}
+
+  vfile-message@4.0.3:
+    resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==}
+
+  vfile@6.0.3:
+    resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==}
+
+  vite@7.3.1:
+    resolution: {integrity: sha512-w+N7Hifpc3gRjZ63vYBXA56dvvRlNWRczTdmCBBa+CotUzAPf5b7YMdMR/8CQoeYE5LX3W4wj6RYTgonm1b9DA==}
+    engines: {node: ^20.19.0 || >=22.12.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^20.19.0 || >=22.12.0
+      jiti: '>=1.21.0'
+      less: ^4.0.0
+      lightningcss: ^1.21.0
+      sass: ^1.70.0
+      sass-embedded: ^1.70.0
+      stylus: '>=0.54.8'
+      sugarss: ^5.0.0
+      terser: ^5.16.0
+      tsx: ^4.8.1
+      yaml: ^2.4.2
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      jiti:
+        optional: true
+      less:
+        optional: true
+      lightningcss:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+      tsx:
+        optional: true
+      yaml:
+        optional: true
+
+  void-elements@3.1.0:
+    resolution: {integrity: sha512-Dhxzh5HZuiHQhbvTW9AMetFfBHDMYpo23Uo9btPXgdYP+3T5S+p+jgNy7spra+veYhBP2dCSgxR/i2Y02h5/6w==}
+    engines: {node: '>=0.10.0'}
+
+  web-namespaces@2.0.1:
+    resolution: {integrity: sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==}
+
+  web-streams-polyfill@3.3.3:
+    resolution: {integrity: sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==}
+    engines: {node: '>= 8'}
+
+  webpack-virtual-modules@0.6.2:
+    resolution: {integrity: sha512-66/V2i5hQanC51vBQKPH4aI8NMAcBW59FVBs+rC7eGHupMyfn34q7rZIE+ETlJ+XTevqfUhVVBgSUNSW2flEUQ==}
+
+  which@2.0.2:
+    resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
+    engines: {node: '>= 8'}
+    hasBin: true
+
+  which@4.0.0:
+    resolution: {integrity: sha512-GlaYyEb07DPxYCKhKzplCWBJtvxZcZMrL+4UkrTSJHHPyZU4mYYTv3qaOe77H7EODLSSopAUFAc6W8U4yqvscg==}
+    engines: {node: ^16.13.0 || >=18.0.0}
+    hasBin: true
+
+  word-wrap@1.2.5:
+    resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
+    engines: {node: '>=0.10.0'}
+
+  wrap-ansi@10.0.0:
+    resolution: {integrity: sha512-SGcvg80f0wUy2/fXES19feHMz8E0JoXv2uNgHOu4Dgi2OrCy1lqwFYEJz1BLbDI0exjPMe/ZdzZ/YpGECBG/aQ==}
+    engines: {node: '>=20'}
+
+  wrap-ansi@6.2.0:
+    resolution: {integrity: sha512-r6lPcBGxZXlIcymEu7InxDMhdW0KDxpLgoFLcguasxCaJ/SOIZwINatK9KY/tf+ZrlywOKU0UDj3ATXUBfxJXA==}
+    engines: {node: '>=8'}
+
+  wrap-ansi@7.0.0:
+    resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
+    engines: {node: '>=10'}
+
+  wrappy@1.0.2:
+    resolution: {integrity: sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==}
+
+  wsl-utils@0.3.1:
+    resolution: {integrity: sha512-g/eziiSUNBSsdDJtCLB8bdYEUMj4jR7AGeUo96p/3dTafgjHhpF4RiCFPiRILwjQoDXx5MqkBr4fwWtR3Ky4Wg==}
+    engines: {node: '>=20'}
+
+  y18n@5.0.8:
+    resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
+    engines: {node: '>=10'}
+
+  yallist@3.1.1:
+    resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
+
+  yargs-parser@21.1.1:
+    resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
+    engines: {node: '>=12'}
+
+  yargs@17.7.2:
+    resolution: {integrity: sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==}
+    engines: {node: '>=12'}
+
+  yocto-queue@0.1.0:
+    resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
+    engines: {node: '>=10'}
+
+  yoctocolors-cjs@2.1.3:
+    resolution: {integrity: sha512-U/PBtDf35ff0D8X8D0jfdzHYEPFxAI7jJlxZXwCSez5M3190m+QobIfh+sWDWSHMCWWJN2AWamkegn6vr6YBTw==}
+    engines: {node: '>=18'}
+
+  yoctocolors@2.1.2:
+    resolution: {integrity: sha512-CzhO+pFNo8ajLM2d2IW/R93ipy99LWjtwblvC1RsoSUMZgyLbYFr221TnSNT7GjGdYui6P459mw9JH/g/zW2ug==}
+    engines: {node: '>=18'}
+
+  zod-to-json-schema@3.25.1:
+    resolution: {integrity: sha512-pM/SU9d3YAggzi6MtR4h7ruuQlqKtad8e9S0fmxcMi+ueAK5Korys/aWcV9LIIHTVbj01NdzxcnXSN+O74ZIVA==}
+    peerDependencies:
+      zod: ^3.25 || ^4
+
+  zod-validation-error@4.0.2:
+    resolution: {integrity: sha512-Q6/nZLe6jxuU80qb/4uJ4t5v2VEZ44lzQjPDhYJNztRQ4wyWc6VF3D3Kb/fAuPetZQnhS3hnajCf9CsWesghLQ==}
+    engines: {node: '>=18.0.0'}
+    peerDependencies:
+      zod: ^3.25.0 || ^4.0.0
+
+  zod@3.25.76:
+    resolution: {integrity: sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==}
+
+  zod@4.3.6:
+    resolution: {integrity: sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==}
+
+  zwitch@2.0.4:
+    resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
+
+snapshots:
+
+  '@babel/code-frame@7.29.0':
+    dependencies:
+      '@babel/helper-validator-identifier': 7.28.5
+      js-tokens: 4.0.0
+      picocolors: 1.1.1
+
+  '@babel/compat-data@7.29.0': {}
+
+  '@babel/core@7.29.0':
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      '@babel/generator': 7.29.1
+      '@babel/helper-compilation-targets': 7.28.6
+      '@babel/helper-module-transforms': 7.28.6(@babel/core@7.29.0)
+      '@babel/helpers': 7.29.2
+      '@babel/parser': 7.29.2
+      '@babel/template': 7.28.6
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+      '@jridgewell/remapping': 2.3.5
+      convert-source-map: 2.0.0
+      debug: 4.4.3
+      gensync: 1.0.0-beta.2
+      json5: 2.2.3
+      semver: 6.3.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/generator@7.29.1':
+    dependencies:
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+      jsesc: 3.1.0
+
+  '@babel/helper-annotate-as-pure@7.27.3':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@babel/helper-compilation-targets@7.28.6':
+    dependencies:
+      '@babel/compat-data': 7.29.0
+      '@babel/helper-validator-option': 7.27.1
+      browserslist: 4.28.1
+      lru-cache: 5.1.1
+      semver: 6.3.1
+
+  '@babel/helper-create-class-features-plugin@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-annotate-as-pure': 7.27.3
+      '@babel/helper-member-expression-to-functions': 7.28.5
+      '@babel/helper-optimise-call-expression': 7.27.1
+      '@babel/helper-replace-supers': 7.28.6(@babel/core@7.29.0)
+      '@babel/helper-skip-transparent-expression-wrappers': 7.27.1
+      '@babel/traverse': 7.29.0
+      semver: 6.3.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-globals@7.28.0': {}
+
+  '@babel/helper-member-expression-to-functions@7.28.5':
+    dependencies:
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-imports@7.28.6':
+    dependencies:
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-transforms@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-module-imports': 7.28.6
+      '@babel/helper-validator-identifier': 7.28.5
+      '@babel/traverse': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-optimise-call-expression@7.27.1':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@babel/helper-plugin-utils@7.28.6': {}
+
+  '@babel/helper-replace-supers@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-member-expression-to-functions': 7.28.5
+      '@babel/helper-optimise-call-expression': 7.27.1
+      '@babel/traverse': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-skip-transparent-expression-wrappers@7.27.1':
+    dependencies:
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-string-parser@7.27.1': {}
+
+  '@babel/helper-validator-identifier@7.28.5': {}
+
+  '@babel/helper-validator-option@7.27.1': {}
+
+  '@babel/helpers@7.29.2':
+    dependencies:
+      '@babel/template': 7.28.6
+      '@babel/types': 7.29.0
+
+  '@babel/parser@7.29.2':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@babel/plugin-syntax-jsx@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-plugin-utils': 7.28.6
+
+  '@babel/plugin-syntax-typescript@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-plugin-utils': 7.28.6
+
+  '@babel/plugin-transform-modules-commonjs@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-module-transforms': 7.28.6(@babel/core@7.29.0)
+      '@babel/helper-plugin-utils': 7.28.6
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/plugin-transform-react-jsx-self@7.27.1(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-plugin-utils': 7.28.6
+
+  '@babel/plugin-transform-react-jsx-source@7.27.1(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-plugin-utils': 7.28.6
+
+  '@babel/plugin-transform-typescript@7.28.6(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-annotate-as-pure': 7.27.3
+      '@babel/helper-create-class-features-plugin': 7.28.6(@babel/core@7.29.0)
+      '@babel/helper-plugin-utils': 7.28.6
+      '@babel/helper-skip-transparent-expression-wrappers': 7.27.1
+      '@babel/plugin-syntax-typescript': 7.28.6(@babel/core@7.29.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/preset-typescript@7.28.5(@babel/core@7.29.0)':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/helper-plugin-utils': 7.28.6
+      '@babel/helper-validator-option': 7.27.1
+      '@babel/plugin-syntax-jsx': 7.28.6(@babel/core@7.29.0)
+      '@babel/plugin-transform-modules-commonjs': 7.28.6(@babel/core@7.29.0)
+      '@babel/plugin-transform-typescript': 7.28.6(@babel/core@7.29.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/runtime@7.29.2': {}
+
+  '@babel/template@7.28.6':
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
+
+  '@babel/traverse@7.29.0':
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      '@babel/generator': 7.29.1
+      '@babel/helper-globals': 7.28.0
+      '@babel/parser': 7.29.2
+      '@babel/template': 7.28.6
+      '@babel/types': 7.29.0
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/types@7.29.0':
+    dependencies:
+      '@babel/helper-string-parser': 7.27.1
+      '@babel/helper-validator-identifier': 7.28.5
+
+  '@dotenvx/dotenvx@1.57.0':
+    dependencies:
+      commander: 11.1.0
+      dotenv: 17.3.1
+      eciesjs: 0.4.18
+      execa: 5.1.1
+      fdir: 6.5.0(picomatch@4.0.3)
+      ignore: 5.3.2
+      object-treeify: 1.1.33
+      picomatch: 4.0.3
+      which: 4.0.0
+
+  '@ecies/ciphers@0.2.5(@noble/ciphers@1.3.0)':
+    dependencies:
+      '@noble/ciphers': 1.3.0
+
+  '@esbuild/aix-ppc64@0.27.4':
+    optional: true
+
+  '@esbuild/android-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/android-arm@0.27.4':
+    optional: true
+
+  '@esbuild/android-x64@0.27.4':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/darwin-x64@0.27.4':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.27.4':
+    optional: true
+
+  '@esbuild/linux-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/linux-arm@0.27.4':
+    optional: true
+
+  '@esbuild/linux-ia32@0.27.4':
+    optional: true
+
+  '@esbuild/linux-loong64@0.27.4':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.27.4':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.27.4':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.27.4':
+    optional: true
+
+  '@esbuild/linux-s390x@0.27.4':
+    optional: true
+
+  '@esbuild/linux-x64@0.27.4':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.27.4':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.27.4':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/sunos-x64@0.27.4':
+    optional: true
+
+  '@esbuild/win32-arm64@0.27.4':
+    optional: true
+
+  '@esbuild/win32-ia32@0.27.4':
+    optional: true
+
+  '@esbuild/win32-x64@0.27.4':
+    optional: true
+
+  '@eslint-community/eslint-utils@4.9.1(eslint@9.39.4(jiti@2.6.1))':
+    dependencies:
+      eslint: 9.39.4(jiti@2.6.1)
+      eslint-visitor-keys: 3.4.3
+
+  '@eslint-community/regexpp@4.12.2': {}
+
+  '@eslint/config-array@0.21.2':
+    dependencies:
+      '@eslint/object-schema': 2.1.7
+      debug: 4.4.3
+      minimatch: 3.1.5
+    transitivePeerDependencies:
+      - supports-color
+
+  '@eslint/config-helpers@0.4.2':
+    dependencies:
+      '@eslint/core': 0.17.0
+
+  '@eslint/core@0.17.0':
+    dependencies:
+      '@types/json-schema': 7.0.15
+
+  '@eslint/eslintrc@3.3.5':
+    dependencies:
+      ajv: 6.14.0
+      debug: 4.4.3
+      espree: 10.4.0
+      globals: 14.0.0
+      ignore: 5.3.2
+      import-fresh: 3.3.1
+      js-yaml: 4.1.1
+      minimatch: 3.1.5
+      strip-json-comments: 3.1.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@eslint/js@9.39.4': {}
+
+  '@eslint/object-schema@2.1.7': {}
+
+  '@eslint/plugin-kit@0.4.1':
+    dependencies:
+      '@eslint/core': 0.17.0
+      levn: 0.4.1
+
+  '@floating-ui/core@1.7.5':
+    dependencies:
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/dom@1.7.6':
+    dependencies:
+      '@floating-ui/core': 1.7.5
+      '@floating-ui/utils': 0.2.11
+
+  '@floating-ui/react-dom@2.1.8(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@floating-ui/dom': 1.7.6
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+
+  '@floating-ui/utils@0.2.11': {}
+
+  '@fontsource-variable/inter@5.2.8': {}
+
+  '@hono/node-server@1.19.11(hono@4.12.8)':
+    dependencies:
+      hono: 4.12.8
+
+  '@humanfs/core@0.19.1': {}
+
+  '@humanfs/node@0.16.7':
+    dependencies:
+      '@humanfs/core': 0.19.1
+      '@humanwhocodes/retry': 0.4.3
+
+  '@humanwhocodes/module-importer@1.0.1': {}
+
+  '@humanwhocodes/retry@0.4.3': {}
+
+  '@inquirer/ansi@1.0.2': {}
+
+  '@inquirer/confirm@5.1.21(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/core': 10.3.2(@types/node@25.5.0)
+      '@inquirer/type': 3.0.10(@types/node@25.5.0)
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/core@10.3.2(@types/node@25.5.0)':
+    dependencies:
+      '@inquirer/ansi': 1.0.2
+      '@inquirer/figures': 1.0.15
+      '@inquirer/type': 3.0.10(@types/node@25.5.0)
+      cli-width: 4.1.0
+      mute-stream: 2.0.0
+      signal-exit: 4.1.0
+      wrap-ansi: 6.2.0
+      yoctocolors-cjs: 2.1.3
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@inquirer/figures@1.0.15': {}
+
+  '@inquirer/type@3.0.10(@types/node@25.5.0)':
+    optionalDependencies:
+      '@types/node': 25.5.0
+
+  '@jridgewell/gen-mapping@0.3.13':
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/remapping@2.3.5':
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/resolve-uri@3.1.2': {}
+
+  '@jridgewell/sourcemap-codec@1.5.5': {}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    dependencies:
+      '@jridgewell/resolve-uri': 3.1.2
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  '@modelcontextprotocol/sdk@1.27.1(zod@3.25.76)':
+    dependencies:
+      '@hono/node-server': 1.19.11(hono@4.12.8)
+      ajv: 8.18.0
+      ajv-formats: 3.0.1(ajv@8.18.0)
+      content-type: 1.0.5
+      cors: 2.8.6
+      cross-spawn: 7.0.6
+      eventsource: 3.0.7
+      eventsource-parser: 3.0.6
+      express: 5.2.1
+      express-rate-limit: 8.3.1(express@5.2.1)
+      hono: 4.12.8
+      jose: 6.2.2
+      json-schema-typed: 8.0.2
+      pkce-challenge: 5.0.1
+      raw-body: 3.0.2
+      zod: 3.25.76
+      zod-to-json-schema: 3.25.1(zod@3.25.76)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@mswjs/interceptors@0.41.3':
+    dependencies:
+      '@open-draft/deferred-promise': 2.2.0
+      '@open-draft/logger': 0.3.0
+      '@open-draft/until': 2.1.0
+      is-node-process: 1.2.0
+      outvariant: 1.4.3
+      strict-event-emitter: 0.5.1
+
+  '@noble/ciphers@1.3.0': {}
+
+  '@noble/curves@1.9.7':
+    dependencies:
+      '@noble/hashes': 1.8.0
+
+  '@noble/hashes@1.8.0': {}
+
+  '@nodelib/fs.scandir@2.1.5':
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      run-parallel: 1.2.0
+
+  '@nodelib/fs.stat@2.0.5': {}
+
+  '@nodelib/fs.walk@1.2.8':
+    dependencies:
+      '@nodelib/fs.scandir': 2.1.5
+      fastq: 1.20.1
+
+  '@open-draft/deferred-promise@2.2.0': {}
+
+  '@open-draft/logger@0.3.0':
+    dependencies:
+      is-node-process: 1.2.0
+      outvariant: 1.4.3
+
+  '@open-draft/until@2.1.0': {}
+
+  '@radix-ui/number@1.1.1': {}
+
+  '@radix-ui/primitive@1.1.3': {}
+
+  '@radix-ui/react-accessible-icon@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-accordion@1.2.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collapsible': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-alert-dialog@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-dialog': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-arrow@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-aspect-ratio@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-avatar@1.1.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-is-hydrated': 0.1.0(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-checkbox@1.3.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-previous': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-collapsible@1.1.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-collection@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-compose-refs@1.1.2(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-context-menu@2.2.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-menu': 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-context@1.1.2(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-dialog@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      aria-hidden: 1.2.6
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      react-remove-scroll: 2.7.2(@types/react@19.2.14)(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-direction@1.1.1(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-dismissable-layer@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-escape-keydown': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-dropdown-menu@2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-menu': 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-focus-guards@1.1.3(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-focus-scope@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-form@0.1.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-label': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-hover-card@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-id@1.1.1(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-label@2.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-menu@2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      aria-hidden: 1.2.6
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      react-remove-scroll: 2.7.2(@types/react@19.2.14)(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-menubar@1.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-menu': 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-navigation-menu@1.2.14(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-previous': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-one-time-password-field@0.1.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/number': 1.1.1
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-effect-event': 0.0.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-is-hydrated': 0.1.0(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-password-toggle-field@0.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-effect-event': 0.0.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-is-hydrated': 0.1.0(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-popover@1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      aria-hidden: 1.2.6
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      react-remove-scroll: 2.7.2(@types/react@19.2.14)(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-popper@1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@floating-ui/react-dom': 2.1.8(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-arrow': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-rect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/rect': 1.1.1
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-portal@1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-presence@1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-primitive@2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-progress@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-radio-group@1.3.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-previous': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-roving-focus@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-scroll-area@1.2.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/number': 1.1.1
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-select@2.2.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/number': 1.1.1
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-previous': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      aria-hidden: 1.2.6
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      react-remove-scroll: 2.7.2(@types/react@19.2.14)(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-separator@1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-slider@1.3.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/number': 1.1.1
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-previous': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-slot@1.2.3(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-switch@1.2.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-previous': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-tabs@1.1.13(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-toast@1.2.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-toggle-group@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-toggle': 1.1.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-toggle@1.1.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-toolbar@1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-separator': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-toggle-group': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-tooltip@1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-id': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/react-use-callback-ref@1.1.1(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-controllable-state@1.2.2(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-use-effect-event': 0.0.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-effect-event@0.0.2(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-escape-keydown@1.1.1(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-is-hydrated@0.1.0(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+      use-sync-external-store: 1.6.0(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-layout-effect@1.1.1(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-previous@1.1.1(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-rect@1.1.1(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      '@radix-ui/rect': 1.1.1
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-use-size@1.1.1(@types/react@19.2.14)(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  '@radix-ui/react-visually-hidden@1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  '@radix-ui/rect@1.1.1': {}
+
+  '@rolldown/pluginutils@1.0.0-rc.3': {}
+
+  '@rollup/rollup-android-arm-eabi@4.59.0':
+    optional: true
+
+  '@rollup/rollup-android-arm64@4.59.0':
+    optional: true
+
+  '@rollup/rollup-darwin-arm64@4.59.0':
+    optional: true
+
+  '@rollup/rollup-darwin-x64@4.59.0':
+    optional: true
+
+  '@rollup/rollup-freebsd-arm64@4.59.0':
+    optional: true
+
+  '@rollup/rollup-freebsd-x64@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-arm-gnueabihf@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-arm-musleabihf@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-arm64-gnu@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-arm64-musl@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-loong64-gnu@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-loong64-musl@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-ppc64-gnu@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-ppc64-musl@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-riscv64-gnu@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-riscv64-musl@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-s390x-gnu@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-x64-gnu@4.59.0':
+    optional: true
+
+  '@rollup/rollup-linux-x64-musl@4.59.0':
+    optional: true
+
+  '@rollup/rollup-openbsd-x64@4.59.0':
+    optional: true
+
+  '@rollup/rollup-openharmony-arm64@4.59.0':
+    optional: true
+
+  '@rollup/rollup-win32-arm64-msvc@4.59.0':
+    optional: true
+
+  '@rollup/rollup-win32-ia32-msvc@4.59.0':
+    optional: true
+
+  '@rollup/rollup-win32-x64-gnu@4.59.0':
+    optional: true
+
+  '@rollup/rollup-win32-x64-msvc@4.59.0':
+    optional: true
+
+  '@sec-ant/readable-stream@0.4.1': {}
+
+  '@sindresorhus/merge-streams@4.0.0': {}
+
+  '@tabler/icons-react@3.40.0(react@19.2.4)':
+    dependencies:
+      '@tabler/icons': 3.40.0
+      react: 19.2.4
+
+  '@tabler/icons@3.40.0': {}
+
+  '@tailwindcss/node@4.2.2':
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      enhanced-resolve: 5.20.1
+      jiti: 2.6.1
+      lightningcss: 1.32.0
+      magic-string: 0.30.21
+      source-map-js: 1.2.1
+      tailwindcss: 4.2.2
+
+  '@tailwindcss/oxide-android-arm64@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-arm64@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-x64@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-freebsd-x64@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-musl@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-wasm32-wasi@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.2.2':
+    optional: true
+
+  '@tailwindcss/oxide@4.2.2':
+    optionalDependencies:
+      '@tailwindcss/oxide-android-arm64': 4.2.2
+      '@tailwindcss/oxide-darwin-arm64': 4.2.2
+      '@tailwindcss/oxide-darwin-x64': 4.2.2
+      '@tailwindcss/oxide-freebsd-x64': 4.2.2
+      '@tailwindcss/oxide-linux-arm-gnueabihf': 4.2.2
+      '@tailwindcss/oxide-linux-arm64-gnu': 4.2.2
+      '@tailwindcss/oxide-linux-arm64-musl': 4.2.2
+      '@tailwindcss/oxide-linux-x64-gnu': 4.2.2
+      '@tailwindcss/oxide-linux-x64-musl': 4.2.2
+      '@tailwindcss/oxide-wasm32-wasi': 4.2.2
+      '@tailwindcss/oxide-win32-arm64-msvc': 4.2.2
+      '@tailwindcss/oxide-win32-x64-msvc': 4.2.2
+
+  '@tailwindcss/typography@0.5.19(tailwindcss@4.2.2)':
+    dependencies:
+      postcss-selector-parser: 6.0.10
+      tailwindcss: 4.2.2
+
+  '@tailwindcss/vite@4.2.2(vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0))':
+    dependencies:
+      '@tailwindcss/node': 4.2.2
+      '@tailwindcss/oxide': 4.2.2
+      tailwindcss: 4.2.2
+      vite: 7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)
+
+  '@tanstack/history@1.161.6': {}
+
+  '@tanstack/query-core@5.91.2': {}
+
+  '@tanstack/react-query@5.91.2(react@19.2.4)':
+    dependencies:
+      '@tanstack/query-core': 5.91.2
+      react: 19.2.4
+
+  '@tanstack/react-router-devtools@1.166.9(@tanstack/react-router@1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(@tanstack/router-core@1.167.5)(csstype@3.2.3)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@tanstack/react-router': 1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@tanstack/router-devtools-core': 1.166.9(@tanstack/router-core@1.167.5)(csstype@3.2.3)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@tanstack/router-core': 1.167.5
+    transitivePeerDependencies:
+      - csstype
+
+  '@tanstack/react-router@1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@tanstack/history': 1.161.6
+      '@tanstack/react-store': 0.9.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@tanstack/router-core': 1.167.5
+      isbot: 5.1.36
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      tiny-invariant: 1.3.3
+      tiny-warning: 1.0.3
+
+  '@tanstack/react-store@0.9.2(react-dom@19.2.4(react@19.2.4))(react@19.2.4)':
+    dependencies:
+      '@tanstack/store': 0.9.2
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+      use-sync-external-store: 1.6.0(react@19.2.4)
+
+  '@tanstack/router-core@1.167.5':
+    dependencies:
+      '@tanstack/history': 1.161.6
+      '@tanstack/store': 0.9.2
+      cookie-es: 2.0.0
+      seroval: 1.5.1
+      seroval-plugins: 1.5.1(seroval@1.5.1)
+      tiny-invariant: 1.3.3
+      tiny-warning: 1.0.3
+
+  '@tanstack/router-devtools-core@1.166.9(@tanstack/router-core@1.167.5)(csstype@3.2.3)':
+    dependencies:
+      '@tanstack/router-core': 1.167.5
+      clsx: 2.1.1
+      goober: 2.1.18(csstype@3.2.3)
+      tiny-invariant: 1.3.3
+    optionalDependencies:
+      csstype: 3.2.3
+
+  '@tanstack/router-generator@1.166.13':
+    dependencies:
+      '@tanstack/router-core': 1.167.5
+      '@tanstack/router-utils': 1.161.6
+      '@tanstack/virtual-file-routes': 1.161.7
+      prettier: 3.8.1
+      recast: 0.23.11
+      source-map: 0.7.6
+      tsx: 4.21.0
+      zod: 3.25.76
+    transitivePeerDependencies:
+      - supports-color
+
+  '@tanstack/router-plugin@1.166.14(@tanstack/react-router@1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0))':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/plugin-syntax-jsx': 7.28.6(@babel/core@7.29.0)
+      '@babel/plugin-syntax-typescript': 7.28.6(@babel/core@7.29.0)
+      '@babel/template': 7.28.6
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+      '@tanstack/router-core': 1.167.5
+      '@tanstack/router-generator': 1.166.13
+      '@tanstack/router-utils': 1.161.6
+      '@tanstack/virtual-file-routes': 1.161.7
+      chokidar: 3.6.0
+      unplugin: 2.3.11
+      zod: 3.25.76
+    optionalDependencies:
+      '@tanstack/react-router': 1.167.5(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      vite: 7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@tanstack/router-utils@1.161.6':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/generator': 7.29.1
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
+      ansis: 4.2.0
+      babel-dead-code-elimination: 1.0.12
+      diff: 8.0.3
+      pathe: 2.0.3
+      tinyglobby: 0.2.15
+    transitivePeerDependencies:
+      - supports-color
+
+  '@tanstack/store@0.9.2': {}
+
+  '@tanstack/virtual-file-routes@1.161.7': {}
+
+  '@trivago/prettier-plugin-sort-imports@6.0.2(prettier@3.8.1)':
+    dependencies:
+      '@babel/generator': 7.29.1
+      '@babel/parser': 7.29.2
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+      javascript-natural-sort: 0.7.1
+      lodash-es: 4.17.23
+      minimatch: 9.0.9
+      parse-imports-exports: 0.2.4
+      prettier: 3.8.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@ts-morph/common@0.27.0':
+    dependencies:
+      fast-glob: 3.3.3
+      minimatch: 10.2.4
+      path-browserify: 1.0.1
+
+  '@types/babel__core@7.20.5':
+    dependencies:
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
+      '@types/babel__generator': 7.27.0
+      '@types/babel__template': 7.4.4
+      '@types/babel__traverse': 7.28.0
+
+  '@types/babel__generator@7.27.0':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@types/babel__template@7.4.4':
+    dependencies:
+      '@babel/parser': 7.29.2
+      '@babel/types': 7.29.0
+
+  '@types/babel__traverse@7.28.0':
+    dependencies:
+      '@babel/types': 7.29.0
+
+  '@types/debug@4.1.13':
+    dependencies:
+      '@types/ms': 2.1.0
+
+  '@types/estree-jsx@1.0.5':
+    dependencies:
+      '@types/estree': 1.0.8
+
+  '@types/estree@1.0.8': {}
+
+  '@types/hast@3.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
+  '@types/json-schema@7.0.15': {}
+
+  '@types/mdast@4.0.4':
+    dependencies:
+      '@types/unist': 3.0.3
+
+  '@types/ms@2.1.0': {}
+
+  '@types/node@25.5.0':
+    dependencies:
+      undici-types: 7.18.2
+
+  '@types/react-dom@19.2.3(@types/react@19.2.14)':
+    dependencies:
+      '@types/react': 19.2.14
+
+  '@types/react@19.2.14':
+    dependencies:
+      csstype: 3.2.3
+
+  '@types/statuses@2.0.6': {}
+
+  '@types/unist@2.0.11': {}
+
+  '@types/unist@3.0.3': {}
+
+  '@types/validate-npm-package-name@4.0.2': {}
+
+  '@typescript-eslint/eslint-plugin@8.57.1(@typescript-eslint/parser@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@eslint-community/regexpp': 4.12.2
+      '@typescript-eslint/parser': 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/scope-manager': 8.57.1
+      '@typescript-eslint/type-utils': 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/visitor-keys': 8.57.1
+      eslint: 9.39.4(jiti@2.6.1)
+      ignore: 7.0.5
+      natural-compare: 1.4.0
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/parser@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/scope-manager': 8.57.1
+      '@typescript-eslint/types': 8.57.1
+      '@typescript-eslint/typescript-estree': 8.57.1(typescript@5.9.3)
+      '@typescript-eslint/visitor-keys': 8.57.1
+      debug: 4.4.3
+      eslint: 9.39.4(jiti@2.6.1)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/project-service@8.57.1(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/tsconfig-utils': 8.57.1(typescript@5.9.3)
+      '@typescript-eslint/types': 8.57.1
+      debug: 4.4.3
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/scope-manager@8.57.1':
+    dependencies:
+      '@typescript-eslint/types': 8.57.1
+      '@typescript-eslint/visitor-keys': 8.57.1
+
+  '@typescript-eslint/tsconfig-utils@8.57.1(typescript@5.9.3)':
+    dependencies:
+      typescript: 5.9.3
+
+  '@typescript-eslint/type-utils@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/types': 8.57.1
+      '@typescript-eslint/typescript-estree': 8.57.1(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+      debug: 4.4.3
+      eslint: 9.39.4(jiti@2.6.1)
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/types@8.57.1': {}
+
+  '@typescript-eslint/typescript-estree@8.57.1(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/project-service': 8.57.1(typescript@5.9.3)
+      '@typescript-eslint/tsconfig-utils': 8.57.1(typescript@5.9.3)
+      '@typescript-eslint/types': 8.57.1
+      '@typescript-eslint/visitor-keys': 8.57.1
+      debug: 4.4.3
+      minimatch: 10.2.4
+      semver: 7.7.4
+      tinyglobby: 0.2.15
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/utils@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)':
+    dependencies:
+      '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.4(jiti@2.6.1))
+      '@typescript-eslint/scope-manager': 8.57.1
+      '@typescript-eslint/types': 8.57.1
+      '@typescript-eslint/typescript-estree': 8.57.1(typescript@5.9.3)
+      eslint: 9.39.4(jiti@2.6.1)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/visitor-keys@8.57.1':
+    dependencies:
+      '@typescript-eslint/types': 8.57.1
+      eslint-visitor-keys: 5.0.1
+
+  '@ungap/structured-clone@1.3.0': {}
+
+  '@vitejs/plugin-react@5.2.0(vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0))':
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.29.0)
+      '@babel/plugin-transform-react-jsx-source': 7.27.1(@babel/core@7.29.0)
+      '@rolldown/pluginutils': 1.0.0-rc.3
+      '@types/babel__core': 7.20.5
+      react-refresh: 0.18.0
+      vite: 7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  accepts@2.0.0:
+    dependencies:
+      mime-types: 3.0.2
+      negotiator: 1.0.0
+
+  acorn-jsx@5.3.2(acorn@8.16.0):
+    dependencies:
+      acorn: 8.16.0
+
+  acorn@8.16.0: {}
+
+  agent-base@7.1.4: {}
+
+  ajv-formats@3.0.1(ajv@8.18.0):
+    optionalDependencies:
+      ajv: 8.18.0
+
+  ajv@6.14.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-json-stable-stringify: 2.1.0
+      json-schema-traverse: 0.4.1
+      uri-js: 4.4.1
+
+  ajv@8.18.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-uri: 3.1.0
+      json-schema-traverse: 1.0.0
+      require-from-string: 2.0.2
+
+  ansi-regex@5.0.1: {}
+
+  ansi-regex@6.2.2: {}
+
+  ansi-styles@4.3.0:
+    dependencies:
+      color-convert: 2.0.1
+
+  ansi-styles@6.2.3: {}
+
+  ansis@4.2.0: {}
+
+  anymatch@3.1.3:
+    dependencies:
+      normalize-path: 3.0.0
+      picomatch: 2.3.1
+
+  argparse@2.0.1: {}
+
+  aria-hidden@1.2.6:
+    dependencies:
+      tslib: 2.8.1
+
+  ast-types@0.16.1:
+    dependencies:
+      tslib: 2.8.1
+
+  babel-dead-code-elimination@1.0.12:
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/parser': 7.29.2
+      '@babel/traverse': 7.29.0
+      '@babel/types': 7.29.0
+    transitivePeerDependencies:
+      - supports-color
+
+  bail@2.0.2: {}
+
+  balanced-match@1.0.2: {}
+
+  balanced-match@4.0.4: {}
+
+  baseline-browser-mapping@2.10.9: {}
+
+  binary-extensions@2.3.0: {}
+
+  body-parser@2.2.2:
+    dependencies:
+      bytes: 3.1.2
+      content-type: 1.0.5
+      debug: 4.4.3
+      http-errors: 2.0.1
+      iconv-lite: 0.7.2
+      on-finished: 2.4.1
+      qs: 6.15.0
+      raw-body: 3.0.2
+      type-is: 2.0.1
+    transitivePeerDependencies:
+      - supports-color
+
+  brace-expansion@1.1.12:
+    dependencies:
+      balanced-match: 1.0.2
+      concat-map: 0.0.1
+
+  brace-expansion@2.0.2:
+    dependencies:
+      balanced-match: 1.0.2
+
+  brace-expansion@5.0.4:
+    dependencies:
+      balanced-match: 4.0.4
+
+  braces@3.0.3:
+    dependencies:
+      fill-range: 7.1.1
+
+  browserslist@4.28.1:
+    dependencies:
+      baseline-browser-mapping: 2.10.9
+      caniuse-lite: 1.0.30001780
+      electron-to-chromium: 1.5.321
+      node-releases: 2.0.36
+      update-browserslist-db: 1.2.3(browserslist@4.28.1)
+
+  bundle-name@4.1.0:
+    dependencies:
+      run-applescript: 7.1.0
+
+  bytes@3.1.2: {}
+
+  call-bind-apply-helpers@1.0.2:
+    dependencies:
+      es-errors: 1.3.0
+      function-bind: 1.1.2
+
+  call-bound@1.0.4:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      get-intrinsic: 1.3.0
+
+  callsites@3.1.0: {}
+
+  caniuse-lite@1.0.30001780: {}
+
+  ccount@2.0.1: {}
+
+  chalk@4.1.2:
+    dependencies:
+      ansi-styles: 4.3.0
+      supports-color: 7.2.0
+
+  chalk@5.6.2: {}
+
+  character-entities-html4@2.1.0: {}
+
+  character-entities-legacy@3.0.0: {}
+
+  character-entities@2.0.2: {}
+
+  character-reference-invalid@2.0.1: {}
+
+  chokidar@3.6.0:
+    dependencies:
+      anymatch: 3.1.3
+      braces: 3.0.3
+      glob-parent: 5.1.2
+      is-binary-path: 2.1.0
+      is-glob: 4.0.3
+      normalize-path: 3.0.0
+      readdirp: 3.6.0
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  class-variance-authority@0.7.1:
+    dependencies:
+      clsx: 2.1.1
+
+  cli-cursor@5.0.0:
+    dependencies:
+      restore-cursor: 5.1.0
+
+  cli-spinners@2.9.2: {}
+
+  cli-width@4.1.0: {}
+
+  cliui@8.0.1:
+    dependencies:
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+      wrap-ansi: 7.0.0
+
+  clsx@2.1.1: {}
+
+  code-block-writer@13.0.3: {}
+
+  color-convert@2.0.1:
+    dependencies:
+      color-name: 1.1.4
+
+  color-name@1.1.4: {}
+
+  comma-separated-tokens@2.0.3: {}
+
+  commander@11.1.0: {}
+
+  commander@14.0.3: {}
+
+  concat-map@0.0.1: {}
+
+  content-disposition@1.0.1: {}
+
+  content-type@1.0.5: {}
+
+  convert-source-map@2.0.0: {}
+
+  cookie-es@2.0.0: {}
+
+  cookie-signature@1.2.2: {}
+
+  cookie@0.7.2: {}
+
+  cookie@1.1.1: {}
+
+  cors@2.8.6:
+    dependencies:
+      object-assign: 4.1.1
+      vary: 1.1.2
+
+  cosmiconfig@9.0.1(typescript@5.9.3):
+    dependencies:
+      env-paths: 2.2.1
+      import-fresh: 3.3.1
+      js-yaml: 4.1.1
+      parse-json: 5.2.0
+    optionalDependencies:
+      typescript: 5.9.3
+
+  cross-spawn@7.0.6:
+    dependencies:
+      path-key: 3.1.1
+      shebang-command: 2.0.0
+      which: 2.0.2
+
+  cssesc@3.0.0: {}
+
+  csstype@3.2.3: {}
+
+  data-uri-to-buffer@4.0.1: {}
+
+  dayjs@1.11.20: {}
+
+  debug@4.4.3:
+    dependencies:
+      ms: 2.1.3
+
+  decode-named-character-reference@1.3.0:
+    dependencies:
+      character-entities: 2.0.2
+
+  dedent@1.7.2: {}
+
+  deep-is@0.1.4: {}
+
+  deepmerge@4.3.1: {}
+
+  default-browser-id@5.0.1: {}
+
+  default-browser@5.5.0:
+    dependencies:
+      bundle-name: 4.1.0
+      default-browser-id: 5.0.1
+
+  define-lazy-prop@3.0.0: {}
+
+  depd@2.0.0: {}
+
+  dequal@2.0.3: {}
+
+  detect-libc@2.1.2: {}
+
+  detect-node-es@1.1.0: {}
+
+  devlop@1.1.0:
+    dependencies:
+      dequal: 2.0.3
+
+  diff@8.0.3: {}
+
+  dotenv@17.3.1: {}
+
+  dunder-proto@1.0.1:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-errors: 1.3.0
+      gopd: 1.2.0
+
+  eciesjs@0.4.18:
+    dependencies:
+      '@ecies/ciphers': 0.2.5(@noble/ciphers@1.3.0)
+      '@noble/ciphers': 1.3.0
+      '@noble/curves': 1.9.7
+      '@noble/hashes': 1.8.0
+
+  ee-first@1.1.1: {}
+
+  electron-to-chromium@1.5.321: {}
+
+  emoji-regex@10.6.0: {}
+
+  emoji-regex@8.0.0: {}
+
+  encodeurl@2.0.0: {}
+
+  enhanced-resolve@5.20.1:
+    dependencies:
+      graceful-fs: 4.2.11
+      tapable: 2.3.0
+
+  entities@6.0.1: {}
+
+  env-paths@2.2.1: {}
+
+  error-ex@1.3.4:
+    dependencies:
+      is-arrayish: 0.2.1
+
+  es-define-property@1.0.1: {}
+
+  es-errors@1.3.0: {}
+
+  es-object-atoms@1.1.1:
+    dependencies:
+      es-errors: 1.3.0
+
+  esbuild@0.27.4:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.27.4
+      '@esbuild/android-arm': 0.27.4
+      '@esbuild/android-arm64': 0.27.4
+      '@esbuild/android-x64': 0.27.4
+      '@esbuild/darwin-arm64': 0.27.4
+      '@esbuild/darwin-x64': 0.27.4
+      '@esbuild/freebsd-arm64': 0.27.4
+      '@esbuild/freebsd-x64': 0.27.4
+      '@esbuild/linux-arm': 0.27.4
+      '@esbuild/linux-arm64': 0.27.4
+      '@esbuild/linux-ia32': 0.27.4
+      '@esbuild/linux-loong64': 0.27.4
+      '@esbuild/linux-mips64el': 0.27.4
+      '@esbuild/linux-ppc64': 0.27.4
+      '@esbuild/linux-riscv64': 0.27.4
+      '@esbuild/linux-s390x': 0.27.4
+      '@esbuild/linux-x64': 0.27.4
+      '@esbuild/netbsd-arm64': 0.27.4
+      '@esbuild/netbsd-x64': 0.27.4
+      '@esbuild/openbsd-arm64': 0.27.4
+      '@esbuild/openbsd-x64': 0.27.4
+      '@esbuild/openharmony-arm64': 0.27.4
+      '@esbuild/sunos-x64': 0.27.4
+      '@esbuild/win32-arm64': 0.27.4
+      '@esbuild/win32-ia32': 0.27.4
+      '@esbuild/win32-x64': 0.27.4
+
+  escalade@3.2.0: {}
+
+  escape-html@1.0.3: {}
+
+  escape-string-regexp@4.0.0: {}
+
+  escape-string-regexp@5.0.0: {}
+
+  eslint-config-prettier@10.1.8(eslint@9.39.4(jiti@2.6.1)):
+    dependencies:
+      eslint: 9.39.4(jiti@2.6.1)
+
+  eslint-plugin-react-hooks@7.0.1(eslint@9.39.4(jiti@2.6.1)):
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/parser': 7.29.2
+      eslint: 9.39.4(jiti@2.6.1)
+      hermes-parser: 0.25.1
+      zod: 4.3.6
+      zod-validation-error: 4.0.2(zod@4.3.6)
+    transitivePeerDependencies:
+      - supports-color
+
+  eslint-plugin-react-refresh@0.4.26(eslint@9.39.4(jiti@2.6.1)):
+    dependencies:
+      eslint: 9.39.4(jiti@2.6.1)
+
+  eslint-scope@8.4.0:
+    dependencies:
+      esrecurse: 4.3.0
+      estraverse: 5.3.0
+
+  eslint-visitor-keys@3.4.3: {}
+
+  eslint-visitor-keys@4.2.1: {}
+
+  eslint-visitor-keys@5.0.1: {}
+
+  eslint@9.39.4(jiti@2.6.1):
+    dependencies:
+      '@eslint-community/eslint-utils': 4.9.1(eslint@9.39.4(jiti@2.6.1))
+      '@eslint-community/regexpp': 4.12.2
+      '@eslint/config-array': 0.21.2
+      '@eslint/config-helpers': 0.4.2
+      '@eslint/core': 0.17.0
+      '@eslint/eslintrc': 3.3.5
+      '@eslint/js': 9.39.4
+      '@eslint/plugin-kit': 0.4.1
+      '@humanfs/node': 0.16.7
+      '@humanwhocodes/module-importer': 1.0.1
+      '@humanwhocodes/retry': 0.4.3
+      '@types/estree': 1.0.8
+      ajv: 6.14.0
+      chalk: 4.1.2
+      cross-spawn: 7.0.6
+      debug: 4.4.3
+      escape-string-regexp: 4.0.0
+      eslint-scope: 8.4.0
+      eslint-visitor-keys: 4.2.1
+      espree: 10.4.0
+      esquery: 1.7.0
+      esutils: 2.0.3
+      fast-deep-equal: 3.1.3
+      file-entry-cache: 8.0.0
+      find-up: 5.0.0
+      glob-parent: 6.0.2
+      ignore: 5.3.2
+      imurmurhash: 0.1.4
+      is-glob: 4.0.3
+      json-stable-stringify-without-jsonify: 1.0.1
+      lodash.merge: 4.6.2
+      minimatch: 3.1.5
+      natural-compare: 1.4.0
+      optionator: 0.9.4
+    optionalDependencies:
+      jiti: 2.6.1
+    transitivePeerDependencies:
+      - supports-color
+
+  espree@10.4.0:
+    dependencies:
+      acorn: 8.16.0
+      acorn-jsx: 5.3.2(acorn@8.16.0)
+      eslint-visitor-keys: 4.2.1
+
+  esprima@4.0.1: {}
+
+  esquery@1.7.0:
+    dependencies:
+      estraverse: 5.3.0
+
+  esrecurse@4.3.0:
+    dependencies:
+      estraverse: 5.3.0
+
+  estraverse@5.3.0: {}
+
+  estree-util-is-identifier-name@3.0.0: {}
+
+  esutils@2.0.3: {}
+
+  etag@1.8.1: {}
+
+  eventsource-parser@3.0.6: {}
+
+  eventsource@3.0.7:
+    dependencies:
+      eventsource-parser: 3.0.6
+
+  execa@5.1.1:
+    dependencies:
+      cross-spawn: 7.0.6
+      get-stream: 6.0.1
+      human-signals: 2.1.0
+      is-stream: 2.0.1
+      merge-stream: 2.0.0
+      npm-run-path: 4.0.1
+      onetime: 5.1.2
+      signal-exit: 3.0.7
+      strip-final-newline: 2.0.0
+
+  execa@9.6.1:
+    dependencies:
+      '@sindresorhus/merge-streams': 4.0.0
+      cross-spawn: 7.0.6
+      figures: 6.1.0
+      get-stream: 9.0.1
+      human-signals: 8.0.1
+      is-plain-obj: 4.1.0
+      is-stream: 4.0.1
+      npm-run-path: 6.0.0
+      pretty-ms: 9.3.0
+      signal-exit: 4.1.0
+      strip-final-newline: 4.0.0
+      yoctocolors: 2.1.2
+
+  express-rate-limit@8.3.1(express@5.2.1):
+    dependencies:
+      express: 5.2.1
+      ip-address: 10.1.0
+
+  express@5.2.1:
+    dependencies:
+      accepts: 2.0.0
+      body-parser: 2.2.2
+      content-disposition: 1.0.1
+      content-type: 1.0.5
+      cookie: 0.7.2
+      cookie-signature: 1.2.2
+      debug: 4.4.3
+      depd: 2.0.0
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      finalhandler: 2.1.1
+      fresh: 2.0.0
+      http-errors: 2.0.1
+      merge-descriptors: 2.0.0
+      mime-types: 3.0.2
+      on-finished: 2.4.1
+      once: 1.4.0
+      parseurl: 1.3.3
+      proxy-addr: 2.0.7
+      qs: 6.15.0
+      range-parser: 1.2.1
+      router: 2.2.0
+      send: 1.2.1
+      serve-static: 2.2.1
+      statuses: 2.0.2
+      type-is: 2.0.1
+      vary: 1.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  extend@3.0.2: {}
+
+  fast-deep-equal@3.1.3: {}
+
+  fast-glob@3.3.3:
+    dependencies:
+      '@nodelib/fs.stat': 2.0.5
+      '@nodelib/fs.walk': 1.2.8
+      glob-parent: 5.1.2
+      merge2: 1.4.1
+      micromatch: 4.0.8
+
+  fast-json-stable-stringify@2.1.0: {}
+
+  fast-levenshtein@2.0.6: {}
+
+  fast-uri@3.1.0: {}
+
+  fastq@1.20.1:
+    dependencies:
+      reusify: 1.1.0
+
+  fdir@6.5.0(picomatch@4.0.3):
+    optionalDependencies:
+      picomatch: 4.0.3
+
+  fetch-blob@3.2.0:
+    dependencies:
+      node-domexception: 1.0.0
+      web-streams-polyfill: 3.3.3
+
+  figures@6.1.0:
+    dependencies:
+      is-unicode-supported: 2.1.0
+
+  file-entry-cache@8.0.0:
+    dependencies:
+      flat-cache: 4.0.1
+
+  fill-range@7.1.1:
+    dependencies:
+      to-regex-range: 5.0.1
+
+  finalhandler@2.1.1:
+    dependencies:
+      debug: 4.4.3
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      on-finished: 2.4.1
+      parseurl: 1.3.3
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  find-up@5.0.0:
+    dependencies:
+      locate-path: 6.0.0
+      path-exists: 4.0.0
+
+  flat-cache@4.0.1:
+    dependencies:
+      flatted: 3.4.2
+      keyv: 4.5.4
+
+  flatted@3.4.2: {}
+
+  formdata-polyfill@4.0.10:
+    dependencies:
+      fetch-blob: 3.2.0
+
+  forwarded@0.2.0: {}
+
+  fresh@2.0.0: {}
+
+  fs-extra@11.3.4:
+    dependencies:
+      graceful-fs: 4.2.11
+      jsonfile: 6.2.0
+      universalify: 2.0.1
+
+  fsevents@2.3.3:
+    optional: true
+
+  function-bind@1.1.2: {}
+
+  fuzzysort@3.1.0: {}
+
+  gensync@1.0.0-beta.2: {}
+
+  get-caller-file@2.0.5: {}
+
+  get-east-asian-width@1.5.0: {}
+
+  get-intrinsic@1.3.0:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-define-property: 1.0.1
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.1
+      function-bind: 1.1.2
+      get-proto: 1.0.1
+      gopd: 1.2.0
+      has-symbols: 1.1.0
+      hasown: 2.0.2
+      math-intrinsics: 1.1.0
+
+  get-nonce@1.0.1: {}
+
+  get-own-enumerable-keys@1.0.0: {}
+
+  get-proto@1.0.1:
+    dependencies:
+      dunder-proto: 1.0.1
+      es-object-atoms: 1.1.1
+
+  get-stream@6.0.1: {}
+
+  get-stream@9.0.1:
+    dependencies:
+      '@sec-ant/readable-stream': 0.4.1
+      is-stream: 4.0.1
+
+  get-tsconfig@4.13.6:
+    dependencies:
+      resolve-pkg-maps: 1.0.0
+
+  glob-parent@5.1.2:
+    dependencies:
+      is-glob: 4.0.3
+
+  glob-parent@6.0.2:
+    dependencies:
+      is-glob: 4.0.3
+
+  globals@14.0.0: {}
+
+  globals@16.5.0: {}
+
+  goober@2.1.18(csstype@3.2.3):
+    dependencies:
+      csstype: 3.2.3
+
+  gopd@1.2.0: {}
+
+  graceful-fs@4.2.11: {}
+
+  graphql@16.13.1: {}
+
+  has-flag@4.0.0: {}
+
+  has-symbols@1.1.0: {}
+
+  hasown@2.0.2:
+    dependencies:
+      function-bind: 1.1.2
+
+  hast-util-from-parse5@8.0.3:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      devlop: 1.1.0
+      hastscript: 9.0.1
+      property-information: 7.1.0
+      vfile: 6.0.3
+      vfile-location: 5.0.3
+      web-namespaces: 2.0.1
+
+  hast-util-parse-selector@4.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+
+  hast-util-raw@9.1.0:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      '@ungap/structured-clone': 1.3.0
+      hast-util-from-parse5: 8.0.3
+      hast-util-to-parse5: 8.0.1
+      html-void-elements: 3.0.0
+      mdast-util-to-hast: 13.2.1
+      parse5: 7.3.0
+      unist-util-position: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+      web-namespaces: 2.0.1
+      zwitch: 2.0.4
+
+  hast-util-sanitize@5.0.2:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@ungap/structured-clone': 1.3.0
+      unist-util-position: 5.0.0
+
+  hast-util-to-jsx-runtime@2.3.6:
+    dependencies:
+      '@types/estree': 1.0.8
+      '@types/hast': 3.0.4
+      '@types/unist': 3.0.3
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      estree-util-is-identifier-name: 3.0.0
+      hast-util-whitespace: 3.0.0
+      mdast-util-mdx-expression: 2.0.1
+      mdast-util-mdx-jsx: 3.2.0
+      mdast-util-mdxjs-esm: 2.0.1
+      property-information: 7.1.0
+      space-separated-tokens: 2.0.2
+      style-to-js: 1.1.21
+      unist-util-position: 5.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  hast-util-to-parse5@8.0.1:
+    dependencies:
+      '@types/hast': 3.0.4
+      comma-separated-tokens: 2.0.3
+      devlop: 1.1.0
+      property-information: 7.1.0
+      space-separated-tokens: 2.0.2
+      web-namespaces: 2.0.1
+      zwitch: 2.0.4
+
+  hast-util-whitespace@3.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+
+  hastscript@9.0.1:
+    dependencies:
+      '@types/hast': 3.0.4
+      comma-separated-tokens: 2.0.3
+      hast-util-parse-selector: 4.0.0
+      property-information: 7.1.0
+      space-separated-tokens: 2.0.2
+
+  headers-polyfill@4.0.3: {}
+
+  hermes-estree@0.25.1: {}
+
+  hermes-parser@0.25.1:
+    dependencies:
+      hermes-estree: 0.25.1
+
+  hono@4.12.8: {}
+
+  html-parse-stringify@3.0.1:
+    dependencies:
+      void-elements: 3.1.0
+
+  html-url-attributes@3.0.1: {}
+
+  html-void-elements@3.0.0: {}
+
+  http-errors@2.0.1:
+    dependencies:
+      depd: 2.0.0
+      inherits: 2.0.4
+      setprototypeof: 1.2.0
+      statuses: 2.0.2
+      toidentifier: 1.0.1
+
+  https-proxy-agent@7.0.6:
+    dependencies:
+      agent-base: 7.1.4
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  human-signals@2.1.0: {}
+
+  human-signals@8.0.1: {}
+
+  i18next-browser-languagedetector@8.2.1:
+    dependencies:
+      '@babel/runtime': 7.29.2
+
+  i18next@25.8.20(typescript@5.9.3):
+    dependencies:
+      '@babel/runtime': 7.29.2
+    optionalDependencies:
+      typescript: 5.9.3
+
+  iconv-lite@0.7.2:
+    dependencies:
+      safer-buffer: 2.1.2
+
+  ignore@5.3.2: {}
+
+  ignore@7.0.5: {}
+
+  import-fresh@3.3.1:
+    dependencies:
+      parent-module: 1.0.1
+      resolve-from: 4.0.0
+
+  imurmurhash@0.1.4: {}
+
+  inherits@2.0.4: {}
+
+  inline-style-parser@0.2.7: {}
+
+  ip-address@10.1.0: {}
+
+  ipaddr.js@1.9.1: {}
+
+  is-alphabetical@2.0.1: {}
+
+  is-alphanumerical@2.0.1:
+    dependencies:
+      is-alphabetical: 2.0.1
+      is-decimal: 2.0.1
+
+  is-arrayish@0.2.1: {}
+
+  is-binary-path@2.1.0:
+    dependencies:
+      binary-extensions: 2.3.0
+
+  is-decimal@2.0.1: {}
+
+  is-docker@3.0.0: {}
+
+  is-extglob@2.1.1: {}
+
+  is-fullwidth-code-point@3.0.0: {}
+
+  is-glob@4.0.3:
+    dependencies:
+      is-extglob: 2.1.1
+
+  is-hexadecimal@2.0.1: {}
+
+  is-in-ssh@1.0.0: {}
+
+  is-inside-container@1.0.0:
+    dependencies:
+      is-docker: 3.0.0
+
+  is-interactive@2.0.0: {}
+
+  is-node-process@1.2.0: {}
+
+  is-number@7.0.0: {}
+
+  is-obj@3.0.0: {}
+
+  is-plain-obj@4.1.0: {}
+
+  is-promise@4.0.0: {}
+
+  is-regexp@3.1.0: {}
+
+  is-stream@2.0.1: {}
+
+  is-stream@4.0.1: {}
+
+  is-unicode-supported@1.3.0: {}
+
+  is-unicode-supported@2.1.0: {}
+
+  is-wsl@3.1.1:
+    dependencies:
+      is-inside-container: 1.0.0
+
+  isbot@5.1.36: {}
+
+  isexe@2.0.0: {}
+
+  isexe@3.1.5: {}
+
+  javascript-natural-sort@0.7.1: {}
+
+  jiti@2.6.1: {}
+
+  jose@6.2.2: {}
+
+  jotai@2.18.1(@babel/core@7.29.0)(@babel/template@7.28.6)(@types/react@19.2.14)(react@19.2.4):
+    optionalDependencies:
+      '@babel/core': 7.29.0
+      '@babel/template': 7.28.6
+      '@types/react': 19.2.14
+      react: 19.2.4
+
+  js-tokens@4.0.0: {}
+
+  js-yaml@4.1.1:
+    dependencies:
+      argparse: 2.0.1
+
+  jsesc@3.1.0: {}
+
+  json-buffer@3.0.1: {}
+
+  json-parse-even-better-errors@2.3.1: {}
+
+  json-schema-traverse@0.4.1: {}
+
+  json-schema-traverse@1.0.0: {}
+
+  json-schema-typed@8.0.2: {}
+
+  json-stable-stringify-without-jsonify@1.0.1: {}
+
+  json5@2.2.3: {}
+
+  jsonfile@6.2.0:
+    dependencies:
+      universalify: 2.0.1
+    optionalDependencies:
+      graceful-fs: 4.2.11
+
+  keyv@4.5.4:
+    dependencies:
+      json-buffer: 3.0.1
+
+  kleur@3.0.3: {}
+
+  kleur@4.1.5: {}
+
+  levn@0.4.1:
+    dependencies:
+      prelude-ls: 1.2.1
+      type-check: 0.4.0
+
+  lightningcss-android-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-x64@1.32.0:
+    optional: true
+
+  lightningcss-freebsd-x64@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-musl@1.32.0:
+    optional: true
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    optional: true
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    optional: true
+
+  lightningcss@1.32.0:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.32.0
+      lightningcss-darwin-arm64: 1.32.0
+      lightningcss-darwin-x64: 1.32.0
+      lightningcss-freebsd-x64: 1.32.0
+      lightningcss-linux-arm-gnueabihf: 1.32.0
+      lightningcss-linux-arm64-gnu: 1.32.0
+      lightningcss-linux-arm64-musl: 1.32.0
+      lightningcss-linux-x64-gnu: 1.32.0
+      lightningcss-linux-x64-musl: 1.32.0
+      lightningcss-win32-arm64-msvc: 1.32.0
+      lightningcss-win32-x64-msvc: 1.32.0
+
+  lines-and-columns@1.2.4: {}
+
+  locate-path@6.0.0:
+    dependencies:
+      p-locate: 5.0.0
+
+  lodash-es@4.17.23: {}
+
+  lodash.merge@4.6.2: {}
+
+  log-symbols@6.0.0:
+    dependencies:
+      chalk: 5.6.2
+      is-unicode-supported: 1.3.0
+
+  longest-streak@3.1.0: {}
+
+  lru-cache@5.1.1:
+    dependencies:
+      yallist: 3.1.1
+
+  magic-string@0.30.21:
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.5.5
+
+  markdown-table@3.0.4: {}
+
+  math-intrinsics@1.1.0: {}
+
+  mdast-util-find-and-replace@3.0.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      escape-string-regexp: 5.0.0
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
+  mdast-util-from-markdown@2.0.3:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      mdast-util-to-string: 4.0.0
+      micromark: 4.0.2
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-decode-string: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+      unist-util-stringify-position: 4.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-autolink-literal@2.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-find-and-replace: 3.0.2
+      micromark-util-character: 2.1.1
+
+  mdast-util-gfm-footnote@2.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      micromark-util-normalize-identifier: 2.0.1
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-strikethrough@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-table@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      markdown-table: 3.0.4
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm-task-list-item@2.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-gfm@3.1.0:
+    dependencies:
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-gfm-autolink-literal: 2.0.1
+      mdast-util-gfm-footnote: 2.1.0
+      mdast-util-gfm-strikethrough: 2.0.0
+      mdast-util-gfm-table: 2.0.0
+      mdast-util-gfm-task-list-item: 2.0.0
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-expression@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdx-jsx@3.2.0:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      ccount: 2.0.1
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+      parse-entities: 4.0.2
+      stringify-entities: 4.0.4
+      unist-util-stringify-position: 4.0.0
+      vfile-message: 4.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-mdxjs-esm@2.0.1:
+    dependencies:
+      '@types/estree-jsx': 1.0.5
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      devlop: 1.1.0
+      mdast-util-from-markdown: 2.0.3
+      mdast-util-to-markdown: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  mdast-util-phrasing@4.1.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      unist-util-is: 6.0.1
+
+  mdast-util-to-hast@13.2.1:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@ungap/structured-clone': 1.3.0
+      devlop: 1.1.0
+      micromark-util-sanitize-uri: 2.0.1
+      trim-lines: 3.0.1
+      unist-util-position: 5.0.0
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+
+  mdast-util-to-markdown@2.1.2:
+    dependencies:
+      '@types/mdast': 4.0.4
+      '@types/unist': 3.0.3
+      longest-streak: 3.1.0
+      mdast-util-phrasing: 4.1.0
+      mdast-util-to-string: 4.0.0
+      micromark-util-classify-character: 2.0.1
+      micromark-util-decode-string: 2.0.1
+      unist-util-visit: 5.1.0
+      zwitch: 2.0.4
+
+  mdast-util-to-string@4.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+
+  media-typer@1.1.0: {}
+
+  merge-descriptors@2.0.0: {}
+
+  merge-stream@2.0.0: {}
+
+  merge2@1.4.1: {}
+
+  micromark-core-commonmark@2.0.3:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-factory-destination: 2.0.1
+      micromark-factory-label: 2.0.1
+      micromark-factory-space: 2.0.1
+      micromark-factory-title: 2.0.1
+      micromark-factory-whitespace: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-html-tag-name: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-autolink-literal@2.1.0:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-footnote@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-strikethrough@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-classify-character: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-table@2.1.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-tagfilter@2.0.0:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm-task-list-item@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-extension-gfm@3.0.0:
+    dependencies:
+      micromark-extension-gfm-autolink-literal: 2.1.0
+      micromark-extension-gfm-footnote: 2.1.0
+      micromark-extension-gfm-strikethrough: 2.1.0
+      micromark-extension-gfm-table: 2.1.1
+      micromark-extension-gfm-tagfilter: 2.0.0
+      micromark-extension-gfm-task-list-item: 2.1.0
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-destination@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-label@2.0.1:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-space@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-title@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-factory-whitespace@2.0.1:
+    dependencies:
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-character@2.1.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-chunked@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-classify-character@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-combine-extensions@2.0.1:
+    dependencies:
+      micromark-util-chunked: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-decode-numeric-character-reference@2.0.2:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-decode-string@2.0.1:
+    dependencies:
+      decode-named-character-reference: 1.3.0
+      micromark-util-character: 2.1.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-encode@2.0.1: {}
+
+  micromark-util-html-tag-name@2.0.1: {}
+
+  micromark-util-normalize-identifier@2.0.1:
+    dependencies:
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-resolve-all@2.0.1:
+    dependencies:
+      micromark-util-types: 2.0.2
+
+  micromark-util-sanitize-uri@2.0.1:
+    dependencies:
+      micromark-util-character: 2.1.1
+      micromark-util-encode: 2.0.1
+      micromark-util-symbol: 2.0.1
+
+  micromark-util-subtokenize@2.1.0:
+    dependencies:
+      devlop: 1.1.0
+      micromark-util-chunked: 2.0.1
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+
+  micromark-util-symbol@2.0.1: {}
+
+  micromark-util-types@2.0.2: {}
+
+  micromark@4.0.2:
+    dependencies:
+      '@types/debug': 4.1.13
+      debug: 4.4.3
+      decode-named-character-reference: 1.3.0
+      devlop: 1.1.0
+      micromark-core-commonmark: 2.0.3
+      micromark-factory-space: 2.0.1
+      micromark-util-character: 2.1.1
+      micromark-util-chunked: 2.0.1
+      micromark-util-combine-extensions: 2.0.1
+      micromark-util-decode-numeric-character-reference: 2.0.2
+      micromark-util-encode: 2.0.1
+      micromark-util-normalize-identifier: 2.0.1
+      micromark-util-resolve-all: 2.0.1
+      micromark-util-sanitize-uri: 2.0.1
+      micromark-util-subtokenize: 2.1.0
+      micromark-util-symbol: 2.0.1
+      micromark-util-types: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  micromatch@4.0.8:
+    dependencies:
+      braces: 3.0.3
+      picomatch: 2.3.1
+
+  mime-db@1.54.0: {}
+
+  mime-types@3.0.2:
+    dependencies:
+      mime-db: 1.54.0
+
+  mimic-fn@2.1.0: {}
+
+  mimic-function@5.0.1: {}
+
+  minimatch@10.2.4:
+    dependencies:
+      brace-expansion: 5.0.4
+
+  minimatch@3.1.5:
+    dependencies:
+      brace-expansion: 1.1.12
+
+  minimatch@9.0.9:
+    dependencies:
+      brace-expansion: 2.0.2
+
+  minimist@1.2.8: {}
+
+  ms@2.1.3: {}
+
+  msw@2.12.13(@types/node@25.5.0)(typescript@5.9.3):
+    dependencies:
+      '@inquirer/confirm': 5.1.21(@types/node@25.5.0)
+      '@mswjs/interceptors': 0.41.3
+      '@open-draft/deferred-promise': 2.2.0
+      '@types/statuses': 2.0.6
+      cookie: 1.1.1
+      graphql: 16.13.1
+      headers-polyfill: 4.0.3
+      is-node-process: 1.2.0
+      outvariant: 1.4.3
+      path-to-regexp: 6.3.0
+      picocolors: 1.1.1
+      rettime: 0.10.1
+      statuses: 2.0.2
+      strict-event-emitter: 0.5.1
+      tough-cookie: 6.0.1
+      type-fest: 5.5.0
+      until-async: 3.0.2
+      yargs: 17.7.2
+    optionalDependencies:
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - '@types/node'
+
+  mute-stream@2.0.0: {}
+
+  nanoid@3.3.11: {}
+
+  natural-compare@1.4.0: {}
+
+  negotiator@1.0.0: {}
+
+  node-domexception@1.0.0: {}
+
+  node-fetch@3.3.2:
+    dependencies:
+      data-uri-to-buffer: 4.0.1
+      fetch-blob: 3.2.0
+      formdata-polyfill: 4.0.10
+
+  node-releases@2.0.36: {}
+
+  normalize-path@3.0.0: {}
+
+  npm-run-path@4.0.1:
+    dependencies:
+      path-key: 3.1.1
+
+  npm-run-path@6.0.0:
+    dependencies:
+      path-key: 4.0.0
+      unicorn-magic: 0.3.0
+
+  object-assign@4.1.1: {}
+
+  object-inspect@1.13.4: {}
+
+  object-treeify@1.1.33: {}
+
+  on-finished@2.4.1:
+    dependencies:
+      ee-first: 1.1.1
+
+  once@1.4.0:
+    dependencies:
+      wrappy: 1.0.2
+
+  onetime@5.1.2:
+    dependencies:
+      mimic-fn: 2.1.0
+
+  onetime@7.0.0:
+    dependencies:
+      mimic-function: 5.0.1
+
+  open@11.0.0:
+    dependencies:
+      default-browser: 5.5.0
+      define-lazy-prop: 3.0.0
+      is-in-ssh: 1.0.0
+      is-inside-container: 1.0.0
+      powershell-utils: 0.1.0
+      wsl-utils: 0.3.1
+
+  optionator@0.9.4:
+    dependencies:
+      deep-is: 0.1.4
+      fast-levenshtein: 2.0.6
+      levn: 0.4.1
+      prelude-ls: 1.2.1
+      type-check: 0.4.0
+      word-wrap: 1.2.5
+
+  ora@8.2.0:
+    dependencies:
+      chalk: 5.6.2
+      cli-cursor: 5.0.0
+      cli-spinners: 2.9.2
+      is-interactive: 2.0.0
+      is-unicode-supported: 2.1.0
+      log-symbols: 6.0.0
+      stdin-discarder: 0.2.2
+      string-width: 7.2.0
+      strip-ansi: 7.2.0
+
+  outvariant@1.4.3: {}
+
+  p-limit@3.1.0:
+    dependencies:
+      yocto-queue: 0.1.0
+
+  p-locate@5.0.0:
+    dependencies:
+      p-limit: 3.1.0
+
+  parent-module@1.0.1:
+    dependencies:
+      callsites: 3.1.0
+
+  parse-entities@4.0.2:
+    dependencies:
+      '@types/unist': 2.0.11
+      character-entities-legacy: 3.0.0
+      character-reference-invalid: 2.0.1
+      decode-named-character-reference: 1.3.0
+      is-alphanumerical: 2.0.1
+      is-decimal: 2.0.1
+      is-hexadecimal: 2.0.1
+
+  parse-imports-exports@0.2.4:
+    dependencies:
+      parse-statements: 1.0.11
+
+  parse-json@5.2.0:
+    dependencies:
+      '@babel/code-frame': 7.29.0
+      error-ex: 1.3.4
+      json-parse-even-better-errors: 2.3.1
+      lines-and-columns: 1.2.4
+
+  parse-ms@4.0.0: {}
+
+  parse-statements@1.0.11: {}
+
+  parse5@7.3.0:
+    dependencies:
+      entities: 6.0.1
+
+  parseurl@1.3.3: {}
+
+  path-browserify@1.0.1: {}
+
+  path-exists@4.0.0: {}
+
+  path-key@3.1.1: {}
+
+  path-key@4.0.0: {}
+
+  path-to-regexp@6.3.0: {}
+
+  path-to-regexp@8.3.0: {}
+
+  pathe@2.0.3: {}
+
+  picocolors@1.1.1: {}
+
+  picomatch@2.3.1: {}
+
+  picomatch@4.0.3: {}
+
+  pkce-challenge@5.0.1: {}
+
+  postcss-selector-parser@6.0.10:
+    dependencies:
+      cssesc: 3.0.0
+      util-deprecate: 1.0.2
+
+  postcss-selector-parser@7.1.1:
+    dependencies:
+      cssesc: 3.0.0
+      util-deprecate: 1.0.2
+
+  postcss@8.5.8:
+    dependencies:
+      nanoid: 3.3.11
+      picocolors: 1.1.1
+      source-map-js: 1.2.1
+
+  powershell-utils@0.1.0: {}
+
+  prelude-ls@1.2.1: {}
+
+  prettier-plugin-tailwindcss@0.7.2(@trivago/prettier-plugin-sort-imports@6.0.2(prettier@3.8.1))(prettier@3.8.1):
+    dependencies:
+      prettier: 3.8.1
+    optionalDependencies:
+      '@trivago/prettier-plugin-sort-imports': 6.0.2(prettier@3.8.1)
+
+  prettier@3.8.1: {}
+
+  pretty-ms@9.3.0:
+    dependencies:
+      parse-ms: 4.0.0
+
+  prompts@2.4.2:
+    dependencies:
+      kleur: 3.0.3
+      sisteransi: 1.0.5
+
+  property-information@7.1.0: {}
+
+  proxy-addr@2.0.7:
+    dependencies:
+      forwarded: 0.2.0
+      ipaddr.js: 1.9.1
+
+  punycode@2.3.1: {}
+
+  qs@6.15.0:
+    dependencies:
+      side-channel: 1.1.0
+
+  queue-microtask@1.2.3: {}
+
+  radix-ui@1.4.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
+    dependencies:
+      '@radix-ui/primitive': 1.1.3
+      '@radix-ui/react-accessible-icon': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-accordion': 1.2.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-alert-dialog': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-arrow': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-aspect-ratio': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-avatar': 1.1.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-checkbox': 1.3.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-collapsible': 1.1.12(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-collection': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-compose-refs': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context': 1.1.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-context-menu': 2.2.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-dialog': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-direction': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-dismissable-layer': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-dropdown-menu': 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-focus-guards': 1.1.3(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-focus-scope': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-form': 0.1.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-hover-card': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-label': 2.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-menu': 2.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-menubar': 1.1.16(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-navigation-menu': 1.2.14(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-one-time-password-field': 0.1.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-password-toggle-field': 0.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-popover': 1.1.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-popper': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-portal': 1.1.9(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-presence': 1.1.5(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-primitive': 2.1.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-progress': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-radio-group': 1.3.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-roving-focus': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-scroll-area': 1.2.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-select': 2.2.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-separator': 1.1.7(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-slider': 1.3.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-slot': 1.2.3(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-switch': 1.2.6(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-tabs': 1.1.13(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-toast': 1.2.15(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-toggle': 1.1.10(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-toggle-group': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-toolbar': 1.1.11(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-tooltip': 1.2.8(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      '@radix-ui/react-use-callback-ref': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-controllable-state': 1.2.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-effect-event': 0.0.2(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-escape-keydown': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-is-hydrated': 0.1.0(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-layout-effect': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-use-size': 1.1.1(@types/react@19.2.14)(react@19.2.4)
+      '@radix-ui/react-visually-hidden': 1.2.3(@types/react-dom@19.2.3(@types/react@19.2.14))(@types/react@19.2.14)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+      '@types/react-dom': 19.2.3(@types/react@19.2.14)
+
+  range-parser@1.2.1: {}
+
+  raw-body@3.0.2:
+    dependencies:
+      bytes: 3.1.2
+      http-errors: 2.0.1
+      iconv-lite: 0.7.2
+      unpipe: 1.0.0
+
+  react-dom@19.2.4(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+      scheduler: 0.27.0
+
+  react-i18next@16.5.8(i18next@25.8.20(typescript@5.9.3))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3):
+    dependencies:
+      '@babel/runtime': 7.29.2
+      html-parse-stringify: 3.0.1
+      i18next: 25.8.20(typescript@5.9.3)
+      react: 19.2.4
+      use-sync-external-store: 1.6.0(react@19.2.4)
+    optionalDependencies:
+      react-dom: 19.2.4(react@19.2.4)
+      typescript: 5.9.3
+
+  react-markdown@10.1.0(@types/react@19.2.14)(react@19.2.4):
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      '@types/react': 19.2.14
+      devlop: 1.1.0
+      hast-util-to-jsx-runtime: 2.3.6
+      html-url-attributes: 3.0.1
+      mdast-util-to-hast: 13.2.1
+      react: 19.2.4
+      remark-parse: 11.0.0
+      remark-rehype: 11.1.2
+      unified: 11.0.5
+      unist-util-visit: 5.1.0
+      vfile: 6.0.3
+    transitivePeerDependencies:
+      - supports-color
+
+  react-refresh@0.18.0: {}
+
+  react-remove-scroll-bar@2.3.8(@types/react@19.2.14)(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+      react-style-singleton: 2.2.3(@types/react@19.2.14)(react@19.2.4)
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  react-remove-scroll@2.7.2(@types/react@19.2.14)(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+      react-remove-scroll-bar: 2.3.8(@types/react@19.2.14)(react@19.2.4)
+      react-style-singleton: 2.2.3(@types/react@19.2.14)(react@19.2.4)
+      tslib: 2.8.1
+      use-callback-ref: 1.3.3(@types/react@19.2.14)(react@19.2.4)
+      use-sidecar: 1.1.3(@types/react@19.2.14)(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  react-style-singleton@2.2.3(@types/react@19.2.14)(react@19.2.4):
+    dependencies:
+      get-nonce: 1.0.1
+      react: 19.2.4
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  react-textarea-autosize@8.5.9(@types/react@19.2.14)(react@19.2.4):
+    dependencies:
+      '@babel/runtime': 7.29.2
+      react: 19.2.4
+      use-composed-ref: 1.4.0(@types/react@19.2.14)(react@19.2.4)
+      use-latest: 1.3.0(@types/react@19.2.14)(react@19.2.4)
+    transitivePeerDependencies:
+      - '@types/react'
+
+  react@19.2.4: {}
+
+  readdirp@3.6.0:
+    dependencies:
+      picomatch: 2.3.1
+
+  recast@0.23.11:
+    dependencies:
+      ast-types: 0.16.1
+      esprima: 4.0.1
+      source-map: 0.6.1
+      tiny-invariant: 1.3.3
+      tslib: 2.8.1
+
+  rehype-raw@7.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+      hast-util-raw: 9.1.0
+      vfile: 6.0.3
+
+  rehype-sanitize@6.0.0:
+    dependencies:
+      '@types/hast': 3.0.4
+      hast-util-sanitize: 5.0.2
+
+  remark-gfm@4.0.1:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-gfm: 3.1.0
+      micromark-extension-gfm: 3.0.0
+      remark-parse: 11.0.0
+      remark-stringify: 11.0.0
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-parse@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-from-markdown: 2.0.3
+      micromark-util-types: 2.0.2
+      unified: 11.0.5
+    transitivePeerDependencies:
+      - supports-color
+
+  remark-rehype@11.1.2:
+    dependencies:
+      '@types/hast': 3.0.4
+      '@types/mdast': 4.0.4
+      mdast-util-to-hast: 13.2.1
+      unified: 11.0.5
+      vfile: 6.0.3
+
+  remark-stringify@11.0.0:
+    dependencies:
+      '@types/mdast': 4.0.4
+      mdast-util-to-markdown: 2.1.2
+      unified: 11.0.5
+
+  require-directory@2.1.1: {}
+
+  require-from-string@2.0.2: {}
+
+  resolve-from@4.0.0: {}
+
+  resolve-pkg-maps@1.0.0: {}
+
+  restore-cursor@5.1.0:
+    dependencies:
+      onetime: 7.0.0
+      signal-exit: 4.1.0
+
+  rettime@0.10.1: {}
+
+  reusify@1.1.0: {}
+
+  rollup@4.59.0:
+    dependencies:
+      '@types/estree': 1.0.8
+    optionalDependencies:
+      '@rollup/rollup-android-arm-eabi': 4.59.0
+      '@rollup/rollup-android-arm64': 4.59.0
+      '@rollup/rollup-darwin-arm64': 4.59.0
+      '@rollup/rollup-darwin-x64': 4.59.0
+      '@rollup/rollup-freebsd-arm64': 4.59.0
+      '@rollup/rollup-freebsd-x64': 4.59.0
+      '@rollup/rollup-linux-arm-gnueabihf': 4.59.0
+      '@rollup/rollup-linux-arm-musleabihf': 4.59.0
+      '@rollup/rollup-linux-arm64-gnu': 4.59.0
+      '@rollup/rollup-linux-arm64-musl': 4.59.0
+      '@rollup/rollup-linux-loong64-gnu': 4.59.0
+      '@rollup/rollup-linux-loong64-musl': 4.59.0
+      '@rollup/rollup-linux-ppc64-gnu': 4.59.0
+      '@rollup/rollup-linux-ppc64-musl': 4.59.0
+      '@rollup/rollup-linux-riscv64-gnu': 4.59.0
+      '@rollup/rollup-linux-riscv64-musl': 4.59.0
+      '@rollup/rollup-linux-s390x-gnu': 4.59.0
+      '@rollup/rollup-linux-x64-gnu': 4.59.0
+      '@rollup/rollup-linux-x64-musl': 4.59.0
+      '@rollup/rollup-openbsd-x64': 4.59.0
+      '@rollup/rollup-openharmony-arm64': 4.59.0
+      '@rollup/rollup-win32-arm64-msvc': 4.59.0
+      '@rollup/rollup-win32-ia32-msvc': 4.59.0
+      '@rollup/rollup-win32-x64-gnu': 4.59.0
+      '@rollup/rollup-win32-x64-msvc': 4.59.0
+      fsevents: 2.3.3
+
+  router@2.2.0:
+    dependencies:
+      debug: 4.4.3
+      depd: 2.0.0
+      is-promise: 4.0.0
+      parseurl: 1.3.3
+      path-to-regexp: 8.3.0
+    transitivePeerDependencies:
+      - supports-color
+
+  run-applescript@7.1.0: {}
+
+  run-parallel@1.2.0:
+    dependencies:
+      queue-microtask: 1.2.3
+
+  safer-buffer@2.1.2: {}
+
+  scheduler@0.27.0: {}
+
+  semver@6.3.1: {}
+
+  semver@7.7.4: {}
+
+  send@1.2.1:
+    dependencies:
+      debug: 4.4.3
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      fresh: 2.0.0
+      http-errors: 2.0.1
+      mime-types: 3.0.2
+      ms: 2.1.3
+      on-finished: 2.4.1
+      range-parser: 1.2.1
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  seroval-plugins@1.5.1(seroval@1.5.1):
+    dependencies:
+      seroval: 1.5.1
+
+  seroval@1.5.1: {}
+
+  serve-static@2.2.1:
+    dependencies:
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      parseurl: 1.3.3
+      send: 1.2.1
+    transitivePeerDependencies:
+      - supports-color
+
+  setprototypeof@1.2.0: {}
+
+  shadcn@4.1.0(@types/node@25.5.0)(typescript@5.9.3):
+    dependencies:
+      '@babel/core': 7.29.0
+      '@babel/parser': 7.29.2
+      '@babel/plugin-transform-typescript': 7.28.6(@babel/core@7.29.0)
+      '@babel/preset-typescript': 7.28.5(@babel/core@7.29.0)
+      '@dotenvx/dotenvx': 1.57.0
+      '@modelcontextprotocol/sdk': 1.27.1(zod@3.25.76)
+      '@types/validate-npm-package-name': 4.0.2
+      browserslist: 4.28.1
+      commander: 14.0.3
+      cosmiconfig: 9.0.1(typescript@5.9.3)
+      dedent: 1.7.2
+      deepmerge: 4.3.1
+      diff: 8.0.3
+      execa: 9.6.1
+      fast-glob: 3.3.3
+      fs-extra: 11.3.4
+      fuzzysort: 3.1.0
+      https-proxy-agent: 7.0.6
+      kleur: 4.1.5
+      msw: 2.12.13(@types/node@25.5.0)(typescript@5.9.3)
+      node-fetch: 3.3.2
+      open: 11.0.0
+      ora: 8.2.0
+      postcss: 8.5.8
+      postcss-selector-parser: 7.1.1
+      prompts: 2.4.2
+      recast: 0.23.11
+      stringify-object: 5.0.0
+      tailwind-merge: 3.5.0
+      ts-morph: 26.0.0
+      tsconfig-paths: 4.2.0
+      validate-npm-package-name: 7.0.2
+      zod: 3.25.76
+      zod-to-json-schema: 3.25.1(zod@3.25.76)
+    transitivePeerDependencies:
+      - '@cfworker/json-schema'
+      - '@types/node'
+      - babel-plugin-macros
+      - supports-color
+      - typescript
+
+  shebang-command@2.0.0:
+    dependencies:
+      shebang-regex: 3.0.0
+
+  shebang-regex@3.0.0: {}
+
+  side-channel-list@1.0.0:
+    dependencies:
+      es-errors: 1.3.0
+      object-inspect: 1.13.4
+
+  side-channel-map@1.0.1:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      object-inspect: 1.13.4
+
+  side-channel-weakmap@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      object-inspect: 1.13.4
+      side-channel-map: 1.0.1
+
+  side-channel@1.1.0:
+    dependencies:
+      es-errors: 1.3.0
+      object-inspect: 1.13.4
+      side-channel-list: 1.0.0
+      side-channel-map: 1.0.1
+      side-channel-weakmap: 1.0.2
+
+  signal-exit@3.0.7: {}
+
+  signal-exit@4.1.0: {}
+
+  sisteransi@1.0.5: {}
+
+  sonner@2.0.7(react-dom@19.2.4(react@19.2.4))(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+      react-dom: 19.2.4(react@19.2.4)
+
+  source-map-js@1.2.1: {}
+
+  source-map@0.6.1: {}
+
+  source-map@0.7.6: {}
+
+  space-separated-tokens@2.0.2: {}
+
+  statuses@2.0.2: {}
+
+  stdin-discarder@0.2.2: {}
+
+  strict-event-emitter@0.5.1: {}
+
+  string-width@4.2.3:
+    dependencies:
+      emoji-regex: 8.0.0
+      is-fullwidth-code-point: 3.0.0
+      strip-ansi: 6.0.1
+
+  string-width@7.2.0:
+    dependencies:
+      emoji-regex: 10.6.0
+      get-east-asian-width: 1.5.0
+      strip-ansi: 7.2.0
+
+  string-width@8.2.0:
+    dependencies:
+      get-east-asian-width: 1.5.0
+      strip-ansi: 7.2.0
+
+  stringify-entities@4.0.4:
+    dependencies:
+      character-entities-html4: 2.1.0
+      character-entities-legacy: 3.0.0
+
+  stringify-object@5.0.0:
+    dependencies:
+      get-own-enumerable-keys: 1.0.0
+      is-obj: 3.0.0
+      is-regexp: 3.1.0
+
+  strip-ansi@6.0.1:
+    dependencies:
+      ansi-regex: 5.0.1
+
+  strip-ansi@7.2.0:
+    dependencies:
+      ansi-regex: 6.2.2
+
+  strip-bom@3.0.0: {}
+
+  strip-final-newline@2.0.0: {}
+
+  strip-final-newline@4.0.0: {}
+
+  strip-json-comments@3.1.1: {}
+
+  style-to-js@1.1.21:
+    dependencies:
+      style-to-object: 1.0.14
+
+  style-to-object@1.0.14:
+    dependencies:
+      inline-style-parser: 0.2.7
+
+  supports-color@7.2.0:
+    dependencies:
+      has-flag: 4.0.0
+
+  tagged-tag@1.0.0: {}
+
+  tailwind-merge@3.5.0: {}
+
+  tailwindcss@4.2.2: {}
+
+  tapable@2.3.0: {}
+
+  tiny-invariant@1.3.3: {}
+
+  tiny-warning@1.0.3: {}
+
+  tinyglobby@0.2.15:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.3)
+      picomatch: 4.0.3
+
+  tldts-core@7.0.26: {}
+
+  tldts@7.0.26:
+    dependencies:
+      tldts-core: 7.0.26
+
+  to-regex-range@5.0.1:
+    dependencies:
+      is-number: 7.0.0
+
+  toidentifier@1.0.1: {}
+
+  tough-cookie@6.0.1:
+    dependencies:
+      tldts: 7.0.26
+
+  trim-lines@3.0.1: {}
+
+  trough@2.2.0: {}
+
+  ts-api-utils@2.5.0(typescript@5.9.3):
+    dependencies:
+      typescript: 5.9.3
+
+  ts-morph@26.0.0:
+    dependencies:
+      '@ts-morph/common': 0.27.0
+      code-block-writer: 13.0.3
+
+  tsconfig-paths@4.2.0:
+    dependencies:
+      json5: 2.2.3
+      minimist: 1.2.8
+      strip-bom: 3.0.0
+
+  tslib@2.8.1: {}
+
+  tsx@4.21.0:
+    dependencies:
+      esbuild: 0.27.4
+      get-tsconfig: 4.13.6
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  tw-animate-css@1.4.0: {}
+
+  type-check@0.4.0:
+    dependencies:
+      prelude-ls: 1.2.1
+
+  type-fest@5.5.0:
+    dependencies:
+      tagged-tag: 1.0.0
+
+  type-is@2.0.1:
+    dependencies:
+      content-type: 1.0.5
+      media-typer: 1.1.0
+      mime-types: 3.0.2
+
+  typescript-eslint@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3):
+    dependencies:
+      '@typescript-eslint/eslint-plugin': 8.57.1(@typescript-eslint/parser@8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/parser': 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+      '@typescript-eslint/typescript-estree': 8.57.1(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.57.1(eslint@9.39.4(jiti@2.6.1))(typescript@5.9.3)
+      eslint: 9.39.4(jiti@2.6.1)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  typescript@5.9.3: {}
+
+  undici-types@7.18.2: {}
+
+  unicorn-magic@0.3.0: {}
+
+  unified@11.0.5:
+    dependencies:
+      '@types/unist': 3.0.3
+      bail: 2.0.2
+      devlop: 1.1.0
+      extend: 3.0.2
+      is-plain-obj: 4.1.0
+      trough: 2.2.0
+      vfile: 6.0.3
+
+  unist-util-is@6.0.1:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-position@5.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-stringify-position@4.0.0:
+    dependencies:
+      '@types/unist': 3.0.3
+
+  unist-util-visit-parents@6.0.2:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+
+  unist-util-visit@5.1.0:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-is: 6.0.1
+      unist-util-visit-parents: 6.0.2
+
+  universalify@2.0.1: {}
+
+  unpipe@1.0.0: {}
+
+  unplugin@2.3.11:
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      acorn: 8.16.0
+      picomatch: 4.0.3
+      webpack-virtual-modules: 0.6.2
+
+  until-async@3.0.2: {}
+
+  update-browserslist-db@1.2.3(browserslist@4.28.1):
+    dependencies:
+      browserslist: 4.28.1
+      escalade: 3.2.0
+      picocolors: 1.1.1
+
+  uri-js@4.4.1:
+    dependencies:
+      punycode: 2.3.1
+
+  use-callback-ref@1.3.3(@types/react@19.2.14)(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  use-composed-ref@1.4.0(@types/react@19.2.14)(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  use-isomorphic-layout-effect@1.2.1(@types/react@19.2.14)(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  use-latest@1.3.0(@types/react@19.2.14)(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+      use-isomorphic-layout-effect: 1.2.1(@types/react@19.2.14)(react@19.2.4)
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  use-sidecar@1.1.3(@types/react@19.2.14)(react@19.2.4):
+    dependencies:
+      detect-node-es: 1.1.0
+      react: 19.2.4
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 19.2.14
+
+  use-sync-external-store@1.6.0(react@19.2.4):
+    dependencies:
+      react: 19.2.4
+
+  util-deprecate@1.0.2: {}
+
+  validate-npm-package-name@7.0.2: {}
+
+  vary@1.1.2: {}
+
+  vfile-location@5.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      vfile: 6.0.3
+
+  vfile-message@4.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      unist-util-stringify-position: 4.0.0
+
+  vfile@6.0.3:
+    dependencies:
+      '@types/unist': 3.0.3
+      vfile-message: 4.0.3
+
+  vite@7.3.1(@types/node@25.5.0)(jiti@2.6.1)(lightningcss@1.32.0)(tsx@4.21.0):
+    dependencies:
+      esbuild: 0.27.4
+      fdir: 6.5.0(picomatch@4.0.3)
+      picomatch: 4.0.3
+      postcss: 8.5.8
+      rollup: 4.59.0
+      tinyglobby: 0.2.15
+    optionalDependencies:
+      '@types/node': 25.5.0
+      fsevents: 2.3.3
+      jiti: 2.6.1
+      lightningcss: 1.32.0
+      tsx: 4.21.0
+
+  void-elements@3.1.0: {}
+
+  web-namespaces@2.0.1: {}
+
+  web-streams-polyfill@3.3.3: {}
+
+  webpack-virtual-modules@0.6.2: {}
+
+  which@2.0.2:
+    dependencies:
+      isexe: 2.0.0
+
+  which@4.0.0:
+    dependencies:
+      isexe: 3.1.5
+
+  word-wrap@1.2.5: {}
+
+  wrap-ansi@10.0.0:
+    dependencies:
+      ansi-styles: 6.2.3
+      string-width: 8.2.0
+      strip-ansi: 7.2.0
+
+  wrap-ansi@6.2.0:
+    dependencies:
+      ansi-styles: 4.3.0
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+
+  wrap-ansi@7.0.0:
+    dependencies:
+      ansi-styles: 4.3.0
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+
+  wrappy@1.0.2: {}
+
+  wsl-utils@0.3.1:
+    dependencies:
+      is-wsl: 3.1.1
+      powershell-utils: 0.1.0
+
+  y18n@5.0.8: {}
+
+  yallist@3.1.1: {}
+
+  yargs-parser@21.1.1: {}
+
+  yargs@17.7.2:
+    dependencies:
+      cliui: 8.0.1
+      escalade: 3.2.0
+      get-caller-file: 2.0.5
+      require-directory: 2.1.1
+      string-width: 4.2.3
+      y18n: 5.0.8
+      yargs-parser: 21.1.1
+
+  yocto-queue@0.1.0: {}
+
+  yoctocolors-cjs@2.1.3: {}
+
+  yoctocolors@2.1.2: {}
+
+  zod-to-json-schema@3.25.1(zod@3.25.76):
+    dependencies:
+      zod: 3.25.76
+
+  zod-validation-error@4.0.2(zod@4.3.6):
+    dependencies:
+      zod: 4.3.6
+
+  zod@3.25.76: {}
+
+  zod@4.3.6: {}
+
+  zwitch@2.0.4: {}
diff --git a/web/frontend/prettier.config.js b/web/frontend/prettier.config.js
new file mode 100644
index 000000000..492ef1dd7
--- /dev/null
+++ b/web/frontend/prettier.config.js
@@ -0,0 +1,17 @@
+//  @ts-check
+
+/** @type {import('prettier').Config} */
+const config = {
+  semi: false,
+  printWidth: 80,
+  tabWidth: 2,
+  importOrder: ["<BUILTIN_MODULES>", "<THIRD_PARTY_MODULES>", "^@/", "^[./]"],
+  importOrderSeparation: true,
+  importOrderSortSpecifiers: true,
+  plugins: [
+    "@trivago/prettier-plugin-sort-imports",
+    "prettier-plugin-tailwindcss",
+  ],
+}
+
+export default config
diff --git a/web/frontend/public/apple-touch-icon.png b/web/frontend/public/apple-touch-icon.png
new file mode 100644
index 000000000..d881c64af
Binary files /dev/null and b/web/frontend/public/apple-touch-icon.png differ
diff --git a/web/frontend/public/favicon-96x96.png b/web/frontend/public/favicon-96x96.png
new file mode 100644
index 000000000..5bdeccea5
Binary files /dev/null and b/web/frontend/public/favicon-96x96.png differ
diff --git a/web/frontend/public/favicon.ico b/web/frontend/public/favicon.ico
new file mode 100644
index 000000000..8b46b4b26
Binary files /dev/null and b/web/frontend/public/favicon.ico differ
diff --git a/web/frontend/public/favicon.svg b/web/frontend/public/favicon.svg
new file mode 100644
index 000000000..e2f412b70
--- /dev/null
+++ b/web/frontend/public/favicon.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" width="500" height="500" viewBox="0 0 500 500"><image width="500" height="500" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAfQAAAH0CAYAAADL1t+KAAAACXBIWXMAAAsTAAALEwEAmpwYAAAgAElEQVR4nOzdeXxV1bUH8N/a59wpc0KYxwwMRgQEQUERnEWtdUplkoJWnq2l1taxIteAc6u1Tm3VVhwAbZznOhVU6ohYVBxImCGMmchwp3PW++MGRLjn3Jubm5uQrO/n8977yDk5e98LL+vsvddeGxBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhOjIqK07IIQ4BI2a7cgb3LUXQR9IQD4RehAhDQwXAxoBBkA+ZrOBFbYBtIFNozwQrN+8ufTPPgDc1h/hEEQYNVvvk98z3aWFUk2dUjTWNDOEkNLR4AvUNmzemVGLpSUG5PvtlCSgCyFikl98bSYc7mM1wukMTARRf4DTCKSi/SwDJsA+YtrG4E/BvCxomEs3mFo5SksCyej/IafY6+zvNnprITWSFI1RREPBXMBAFkCpIOgAE0BMjBCD60GoBFAGxkqTjY/NoPb5eqzeidJSo60/jmh9EtCFEHaoYLq3gBiXADifCAPApINa9rujKcDXE/AFAy8YZujZdYtv2YjOPrIsLtbyVVEB6TiHgDNBNAzM6QApasZ3zgwm4hAzKhlYziY/YzbS6+tfKKluze6LtiUBXQgRCeVNnztIsf5bAk8BKKM5AaU5mMEg1BD49aBh/h0Vmz5ev3ShrzXaaq96nuVNcafzSZpSs4n4BGZKSdT33fT9MjE2MvFjhhl6dN3iWzYk4tmifZGALoT4kX5Tr8t2wHU5KfwGoFxK0u+JcODhAEy8B43vK9tV9SZev8+fjLbbSuGkOS4zK/sspehKAh3NgNZaL05A08gdXMGEBxpV4O9bHr9td2u1JZJPAroQYp+8qd4xGuE+EB1FQNS18dYQni5GkJmXwsBtZcbq9zvgGjDlTb1htKb0EgJOYia9NQP5gRgwwfw1m7imfBDeREmJmay2ReuRgC6EACZ69cJefCmIbiGi7Lbuzl4M9jHjaQ7h1rVPl3zf1v1JhJxJ3ozsHFxNwG+IKKMt+8LMjSD8zfT7StaW3lHTln0RLScBXYhOrnDSHBe65NxGoMsBOON8TADMdQD5mNBAzCkguBiUSoC7Jf1rmorfCubbyiqrHjmUp+H7TfMWOQkPAjS+rWZADtQ0Wn8vZGDW+qdK1rd1f0T8JKAL0Ynlnn1Nela650EQTY01wDRlqNcSYwUzv8+KPmbTKG9krcrU6xsdPsMMujWl1zncmseZ6WSzLysaRqAxBIwGUX9muJo7xcxgA8BbIQNXrl9S8m1cH7jtUN6UeWdpih4GqFscGesBZuwA0Rowl4N4Kwg1bJABYgeBcgHqB/BgEPIBZDRtJ4ypnaaXprWhkDlt/VMLPo73Q4q2JQFdiE5qwESv29ELj7Kin8USzJsC6jfMvBBEL5Z/U7EBKx4KNqNJyj37mrSsVNdQkDoLCucS08DwfurY7B2tmwZfsXYJPQ8cAmu/Xq/KL8NlGuF2gNJj/CkGOMCgL8H8MsN8x9cQ+nbLxt21Nt85DZjodVGvUHdibZxS9FMCTmFQdjNeICqChjFl/ZIFy2K8X7QjEtCF6Ixmz3YU1ve8B0SXRQvmTdue1sA076wJ0tM7S0vqEtGFrsXetDSdT9A0upSAE2PeqsVgJvazibv9wdqbN5f+uTER/WkVxcVavnPI1YrUTQRyRbudGQxwLYCXDDIf1nZXf1IW9xKDVw2YjH66hllEuISZekX7fpva3wEDk8ueKlkaX7uirUhAF6LzoYLp865SrG6NNjpm5kYGHq4PBG7eVnrbzlbpTXGxVqgPGQOlriDCWQClxvJjTWu/pfVm3a8rlty1q1X61hLFxVqBc8jvFWkLEENuAgMNYH7BMIN3rFty65dIYJGdgsk39CVNv44IP4/l+2XmrUHDPGvDUwtWJqoPovVJQBeikymc5j2VCM9F+8XO4G0GY866wOrnk7JtLBzYjyOlbgRoQixT8U0jyqUqELro+9JbtrR6H5shb+q8SzRF9xPINimwaQbkazZCV5dXaG9jaUmoVTrk9aq8Mpysg/7CwODoo3VezUbo9PKnbtnUKv0RCScBXYhOpO9kby+3jvcAKrC9kfFtkHnK+sUlXySpaz+YNMdVkJM9WRF5mWlALNPwDF4ZJOP8DU/cvC4ZXYymYIr3RKXoRRDSbG9kBEzwPxtM3FixpCQpswx9J1/Ty6V5HgTRT6LmTjC/XbWn8bxdL925Jxl9Ey2jtXUHhBBJUlysdXN0/TNAJ9oGSca3bBoXrF0y/8sk9u4HZZ8YVV8u+19G0cQXlYauxFQEihZ4qIfGND59yPi3ala/16b1yvOm3tBfU+pZJupmX2WP9zBwdfm3FbfUvXl3QvISYlH71fI9Ku/oV91ORxYIo+z6yKA8l1N3Vn257K1k9U/ETwK6EJ1E4YgLTiVSt5HNVDYzbwJwdtni+auT2LWIqr9aVl3pGPxydtfUCgIdwwyP1YtI+M+pp67RsRlDJr5cvXpZ0gLkjxR7nbm6egygMfYzC7zTYMwoX1SyGBUrkl4Fr+G75YHKsYPeyg6keQh0tNULU9NnOCpz6IT/VX+1rEMU9unIJKAL0QkUTprjQkrKIiLqa3NbrWHy9LWL57effcgVK8yqVctW5Bw+/gMoOpaYcq1OeiMCgai3UhieNeSYl6pWL096AZqCIydcTKSuJNsZBd4dAk9dt2j+G8nrWQQrVphVQyYuy9HRDSDLkToRaaRodPqwcc/UrHq/bV6UREzaRaUiIUTrMnO6nA+iI62uM9hkmLeuWzL/7WT2K1ZlSxZ8aJihSSB+L5wIZ4PoZHK670FxcbxV7+LSd7K3lwLdFGVdus5kvnTdk/PbxxR2aUmgvhpXAfyq7ffKKNBNx3xI3lW7JgFdiA6u51neFAVcbR9oaGnZ7qp70I7PI1+3+JYNjX6cB+YX7YIPEYiIZhQ6i36XxO6RU8N1DOppdQODDdPkG8oXzX8+if2KquKVkgauxy9A/LXVPUQgRTSjYIr3hGT2TTSPBHQhOrjUDD4FxEdYXWeggU3jmkOhRvrm0pLK6rrGGQR+wTaoA4oIc/OmzDslGf3Kv9A7kIgusl83p2fLt+LBZPSnucqfL9kBw5zNzLWWNxGcpOHWnmd5U5LYNdEMEtCF6NgIRJeBKeL/rzODwbywfPGCz5PdsXjteunOPbtROTP6NDGlaIr+ll/s7dfafVI6/RKMTMuuMG/w+YO/a7U95glQtmTBh0x8s/2SBo1OycD05PVKNIcEdCE6sP7FcweAaKLlyJFQY7LRrqfaI6lcdF9tvYlZAD6yvCmc+Z6nnLgLxcWtlgDcp9ibA/BUq++4qaLdgs3trPBNJH7/nvuZeLnVdQIUKVzdp/jKnGT2S8RGAroQHZjDoc4Bw7qGOPNzaxffXJbELiVMxZKSXf5Q6CIGl8PihaQpyJ5b4Cqa1lr9cDv4TIC6Wt7AvNIX3LO4tdpPpM2lf240GFeHj8K1wFTgdmbMSGK3RIxk25oQHRflDJt4OxENiHSRAdOEeVnVl+8lfOSYN8U7LHf4hCtyhk2cmXPEhOHZRxy/p8o5ZBcqViT0dLTar9+ryjj8+P8povOIIpdYJSIFxlFZIyY+W7VqWU0i2wdAOcMnLiCiwZEuMoNN0NUbnrr9kKmJXv3lsi05wyf2BNPoSLMOTdsDC9WAMQsbvlseaIs+ishkhC5EB9V/+h96gDDM6jqBv1q75f2EB5q8KfN+oil6B1DXEdF0kJqnSFs68LCeL+RP9Z4Mrzehv3fWL1nwHoCbwue0W6E+ysCNQGLb7lF8fS4YY6zv4I0K/Eoi20wCBuMOgHfb3JOfleY+J2k9EjGRgC5EB6WxYxRAGVbXGXgeS5cmNEmrT7E3R1d0LxFy947uwiM6pAF0hqbwWkEZnuw31ZufwGa57NuKB8hmO1t4Kxtm5E0NHZfAdpHqcAwFWU+3E/BS2aIS68zxBOk72durYMrc0wumzZtUOM3bBy3cL162qGQzmO+3/D4BBaL/Q7E3qXv9hT0J6EJ0UMQYY7X3nMEGh/Bmott06RjBBJuscnIQaLJL4e286QncUrbioaCf/VcRwXr5gMipQZ+f0CBEGGn9HcM0Ca8lrC2LHhROnXeRS8NHpGmvENHLRPRxwbR5v0ALg7ovaDwCguWRuUQYk6+FLGeARPJJQBeigyKCZWU4YtoRVP5vEt6oYheYbANJU931PI2pNH/KvPMT1fTGxbevZWYvg61roxOOK3Ti7ES1SaAi66tcEwhhVaLaiqRg2o3jiOivRNSXQBqBNAC9iOgvhVO8xS159ubSW7awyUust7GRQ2l6qyUbiuaTgC5ERxQeheZZXWbwdxsHuhKdIAYYxlcE2K297kNEmUpTjySy+EvZtxVPAFhm06YG4PoEFUchgvVsBAHbNq2psBzhJgKRmgU6+Fx7AnlIo3vyps+NmKwXKybzHwD7bG45H6NmO1rShkgcCehCdEADgjUpAHW3us7AtygpSWjGOQCUP3XLJhPm7QAHEa3mOgACsjRFD/cpvqF3Qjqw4qFgKGT+gYEG60ZpREom/6TljXmJCV2srjJjG1Y8FGx5O9aIMcDmck+NtTtbsgd/7aIFX4HwoU0P+uQP6np0vM8XiSUBXYgOiFJSM0GwHIUqYF1rtV2+6Jt7TBMzGLyUmRsRtWgN9XM79dsSlYG+/qkFnwBYbJfQRaCrW1xspng1gZFmdZlA9S16fgwY+Nb2xYlwZr6j6LSWNEEmnrAts6v0BLwciUSQgC5EB2QalEIMy+Qvk7Gj9VovNcoXlzyFyspJBpmnMfMbduvaTfuazx8w2RydoA6waYbuBPEeyzsIIwqdRSe1uCUiu5eVVj+ZLGiY/2CCzdIJKaXwe0z06vG2YWp4DYTGiE8nEAEnt2YlPhE7CehCdEDKQU62Lxxlty6aEGWv3+df9+SC98sqK89lE9exXZsMj0NTlyWq7bWLb14DxhPW7ZECMAct+R1YWsRg65cGJs6O+9kx2vDUgpUwzavAiLj9sOmM82Pz+piHx9tG+RMlO8H8vtV1Ag3KdxclZslEtIgEdCE6KPuTv5Lo9fv85YtxN2DeZDVSJwIx4cx+Z16XsCBosvEXgCNOezeNLE8onHLjYfG3UMKA9UwHMXr2Kb7SE//zY1O2lR4D+CXLqXcmp2I6qwVNMAhvWk27MyFFGWy5o0IkjwR0ITogzUDIdpobnOTM5BIzpNNfAHxgeQtTrp7lHJmoFtcuvrmMGZZnjzMoBUq1ZNsVA1hreZHQXdcz+rfg+bFZWhIyjNBtTIh4/C0RSIEmogVLAGyaywCOmERJgGKiRC2XiBaQgC5EBxQMcQMYlnW22SYDvrWsX1jiY+a/2FVzU0hoYGAm/BWI/D00VbCb3JItbAz+n/VF8ugaElqZzspa4/uVAL6wuaUIE71xr3NzMFBGoO1W1wlI2IuYiJ8EdCE6IANaDYEiJjIBAJH1HvXW5A/sWUaAdfY3oTCR7ZX78RkDn1nfQf1TMnlCvM8nCq2A3QsDozgpCWOlpQYxf2J5ndC1T9fauGdl1pa69zD4O+vH02DMlv3obU0CuhAd0Gagjm3Wd5lwRFtkJm8u/XMlE1uO9MDITWiDpSUBZnNhlC1sU+J9fH2141uArbcAEib0dw0cHu/zm4PB26yvQRl6xkEFaGJXYhLwpeXzCT0Kq7pkxf98kQgS0IXoiEpLAkQot7qsmA7L0wcmNnjGim2KvgARj0BtifpA8AXYbO0iwon9psaXjFfxSkkDGG/C6jx2kEuH4+pEn/IWCRPlWF0jJjb1essZm5ieb+I76/3o7A45nJLp3sYkoAvRQTH4M6vMZwa6EDmOTXafEN5JZR08iRJejnZb6W07wfxvq+sM6ulUrvHxPj/EeBJgy1PrCHROwdT4p/VjRAQ6yuoiE1du35QaMWkuVoZCmWXjIKXI6NOS54uWk4AuRAdlmvgAgOU2MSJMT3KXkDflD90Ati+X2gpMxr+szksnQMFE3NXO1i3GZwz81+o6AW5S6s784msz420jmv4Xzh1CDMuADqZvsbTE+tCaGGimuQVkXTFOkdajJc8XLScBXYgOymzAZ1GOv5yUf6F3UDL7pJQ+DiDLaXWC+X2rtBsMvA+bnAIQJna/6Ko415hLTMC426q4CwCAMUo53TeiVarHeZVD165iIGL/w9PkvBxRS/Daq4faThz5pSjcUILzH0SzSUAXooNa/0JJNYPfsrpOILfSMC+JyXFEoKlWBW8YMA2mT1uj4bLS23ZSOKhZ9Ax5aYZnSNzP/2bH68z8H6sljnAhG7oif8q8mUhwUC+cyucT0XSr75WIQwBeamk7pl7fyGR36A0kKa6NSUAXogNjA49ZTTUDABSd38LDO2JWOOXGIgCnWt/BFXVBrG6t9tnk162z3UkD1AlxP3zFQ0Gw6WWLmudNjehK0T15U+ddEHc7Bxgw5cYJUOp+wLpuPxgryyorV7a0rfRd/hDCh+1EZiKjpW2IlpGALkQHVv59xftgtv5lznAphfsHTPYOaNWOFBdrpKkbAEq3uevNnaUlda3WB8NcanXICABAUfwBHUDZkgUfwuS/2Z5MRpShEz1aOH3eL1t0jnhxsZY/fd4Uh6ZKidHV6jYGTJPxZ7x+X4sS4gCgbIffhEU1OgBgknjS1uQvQIiObMVDQRDuZLauoQ7QAF3Dov7T/9CztbpR6DjsPAAXWNeX56DJvKi12geAsqe1dQBblmol5qPiX0cPCzVgAYjtKrYBRKnE6p6BQ3o+HM+LVP/iuXkFrqIHFdQ/AeoKu5r9zB+UB/Fcc9uIKL/KBNCq57uLlpGALkQHF9q84SUQvW9TXIUAGutgR2lrjNQHTPWOgKJ7AYo8ImUwgz5VlVXWdd4TosQEY5nlZUKX1GBqCw5racpbMM1LwdgFuyQ0gpNBMxw6Piic5i3Jv9A7yDaXodjrzJt+4/CCad47nC59OTFdStH27DMqQbgSpSWWJYCbZWcRkcSMdq19nMYkhGhV+ZO9R2ka/QeENMubGMzgdWzi8vLQ6rdQWtqibU4AkDf9xuEaq1KACi1H54wQE59f9mRJixO3oimYNu9CgloSqS/hFx5zTtmi+Q+0tJ38qd7zFOFJIop62hozmMD1IKxkxidgLidGNYM1EHVlRUMU0xgGDwbIHcspegz2mwb/cu2S+Y+29LPsVThpjou6dFkHIOJMjsn89/JFJQk7Alc0n7xtCdEJrH2q5DMT5u22CXLhTOw8peGZga6iB/OLvf1a0KQqmO49XWP1im0wB8Dgd8o2L3utBW3FLhBYAXDEaWMiEENZ7+VuhrWLS54H+GoGR127Dh8SQ2kAjSei34PUA6zRE9C0x0DqLgWaDcIIIvLEdCQuIwSTb1sb+ubxRHyWvXxpugLDZfk5mKxr9IukkIAuRCdBlVV/AnOpXdJWeD2WUpnpUuWiTwumeW/Onzp3YDO2tlH/4rl5BdO8DxDjeYB6RwnmOwH8DkuXWu/hTiCqq98EwibL6+ARLUpW+wGXLZr/Vxj4NcB7mvODTVvcNAJUc8+0Z+ZGk42SsuA3NydihmV/TjidILbJMWje5xSJJ1PuQnQivWdc38VjOp8hpgm2yVRNGGBirmLgHSa8wgof1VY3Vuyq9TRiaUkIABVOmuMMpeVk605jGEM/lwjngNE9ejDiIDMuK1tU8s8EfbyYFE7zvkBEP43YI6C6zu8ftK30NsuCPM1EhVPnnQ1S9xPQO5bvPH682zTN35UvVk+Gi90k1oDJ3gG6jrLwFr8ITL5izeKSexPdroid3tYdEEIkz5bHb9s9oNg7RXfyEjBNiBZ0KTwRn0NAMYDzlcn1WemebdkZtJ2nefeAoIORoxN6E+u5RE2/U6KFcsAE496ywOrHEvXZYsa8EhYBHUBGiqb6A9YV9prbWtni+S8OmOL9Tle4G8CplgEx3gbABgFLOWReXf7UghbvN7dmdgdryurv1mBO1Hcm4iRT7kJ0MutLS7bVmyhm4qds19QPEM5wpnQiGgjgOCKaRKBTiGgUgXqAYhsghIM5LwxtwdxETwvHwgR9afm5GURKL0p0m+uXlHwbcuA8AJcBbHNqWewYMJmxGozZjf7an5S1ajAHFJH14SsMVmxWtGb7IjoZoQvRCVUsKdk1YKL3Yr0XfwWi6xlIbe56bTwYbMLEg3t21V+3femffK3dXiSKze+ItRDo4OpqTd9B3CVg7axfWOID8EiP4utfTHM6fsZQFxPzMAZpMX73zAyA4CfwZ2ziH77GwMtbnr9td2v090BElGd9kUOGAQnobUwCuhCd1PqlJT4At+ZN9b6tEf7IjGOJEjsdvBczGMQ1BL5pTfCb+/Fm8kfm+yi1CcR7AIp86huhVQ+saVqffwCT5jxSkJ01VCk6g0HjiGkQA7kAO/BD1TUDDD+AChC+MZnfN0369/oKlDXlMCQNEQZZ1+GnxhqnJgG9jUlAF6KTW7e45JPup151RlrXlKkAXQWgMJEFRBhsgOjjEOP36xfN/xgtPPWrpcoWoa5wOlUQEDGgE1AY/j+t3M/X7/OXAysArEBxsVboLEo1A8gyHchxGKYrCEAn1AU1o9K3I1C7/c3URmB+wpPdYuNVdi86BK6o3GJzcItICslyF0Ls02/qddlOck0B4RcEFDGTM+6peEaIwd8z4y8NtXiy4pWSdvML3zbTnbmmLLC6S1us77dXuWdfk56V4fmGQL0j3sB4dc2im85KcrfEAWSELoTYZ+Pi26sAPNjzrNkL3ZndjlOknQfgBDD6xlSlLBzEdwP4yDT5aaWqXi1ffF9tMvrePLTO+hKlF4T6dym3Oz+9k0lL9fQmoJvVdRP8dTL7IyKTgC6EOEjFKw81AHgTwJv5xddmQnMPVDqPMIGhxMgDIRcMF4gYzHUEVID4G4PwOYWMVeXG91vb9wiXN1hOUDKIXJ7ekIC+j0YYwUw6RfjKmMHMvCr5vRIHkoAuhLC1tvSOGgCfNf3PXoSJXg1gJDs5KxGIeJNVQCcCGZrqDaBVt4EdUgjjrGZniDgASEBvDySgCyHiwYdiIN+LDd5ql89P4FY7SvbQ41VENNbmhl31qtHyWFqRPFJYRgjR6YRY2W+xYuqepK60e4XFgS5gHmZ1nRmrtj/xJzmYpR2QgC6E6HTqDeyKcvJc1yR2p10znM4JVmfZc/jI3eXJ7pOITAK6EKLT2QkEAFhm3xOQk8TutGsa4zTb3Q2G8Z8kdkfYkIAuhOh8dsIkRrXVZQZlJ7M77VXhpDkuIjrZ6joBVeU1tSuS2SdhTQK6EKLzWVpisM353Yo4M5ndaa84M2cUiCMXkwHAxO/h9fv8yeyTsCYBXQjRWVkGdADpSetFO0Y6zmYmu91QryatMyIqCehCiM6IAdTZXExLYl/apcJJc1xgnGV9IAsaAibeTXa/hDUJ6EKIzsr6+FaGE538rAvOyTqKgMHWN/BnG7diYxK7JKKQgC6E6JQYsNw7TSB9wESvK5n9aW+I1GRQ5On2cLlXvHwoFxfqiCSgCyE6JbI7HpUADEhaV9qd3LOvSQfTOdZ3sI9hvJi8HolYSEAXQnRWliN0Znaoel+nHaFnprvPAKGX5Q2Ej9cu1sqT2CURAwnoQohOiUGWp8ERQGaqu3OuoRcXa0Q0k6zjA7OJJUCJdaU90SYkoAshhNgnTy86HMDx1ndwpRHES0nrkIiZBHQhhBD7aAqzCJRidZ0Zr60vLdmezD6J2EhAF0J0TsQ2v//sCsN2XL1nXN8FhGnWd3DQBD8Gu4RC0WYkoAshOiUCUm0uBkOO2k5X0tQVcswgkOVJc8xYtbay6oNk9knETgK6EKJzYvvCMfrOjE41Cs09+5p0jWi2zS0M4J9Su739sqvRK4QQLaEwarYGZ5WOGmj7/rQhNYT160PAUgNtOXVLsFknZmN919XBZHanrWWmu89j0GCrtxwGtgfYvySpnRLNIgFdCJEYo85KSXfm9nMARwA4ghQVmAj2Upyeydn8w57uLKpDr7wq0IDNzPQ9Ma9qNINfNYZSt2PFQ0kLogQ4ra9RCKWlltvaOpoBE71uIlxBFuVumcEMfnzj4turkt03ETsJ6EKI+BUVp2VmpY3RgJ+CaCKBC5jJAzABRAoIb+reP05Q+H9x+CZAkekhZ7VHC66mY2e+YYbMV6r2NH6L1aWBVuw5gZFmNenOZH1wS0ek9TLPAWsjrBchuBaEh5PZJ9F8EtCFEM2WPeqifnBpU4jUVABFtO93CYGaAnY0hH3neGkgdAEwHqDxSqc/5GSmfYhjZz1S6at7AytKa1rjMzAhzTp+sWUVuRYbNcoB9HSgrpuGXAB7giZCvmArv8BYmzTHpZS6DjajcwDPlj9ZUpbcjonmkoAuhIhZ2riLujlZvxxEFwPc22qKtmUolRROZmBijjvtKx47849VO7c/i7LXE5iMVaxgc0Qq25+V3gxelTN6Y2/WMZyIRwF0GAE9mJBFLqSAQZzm8AF6LY27eAcT1rBpfhFkY2Xdrl1rE/uZI8vPzr6AgaGWf5HEAZPNe1q7H6LlJKALIaIrnOTKyu0xWQE3EaF/eA69dSujhkf9NAIKj2d36zGbus24vvK/jxyNinEAACAASURBVH+ERCTSjcpWADIs2ya0ZFZAZY77eZ5G6mzwpnNAGEaMTCK17wvbfxKDDvzfROwkR2NOt57l1G3Wa0E2nqutafyiNUbwuWdfk66IrieQZnPbM2sXLfgy0W2LxJOALoSwlT3qon7k1P8Mop8QwZHs9gmkEWECQ38ta+zFd1cH9Luw4qGGFj20m0sBZBnQgbjKyqjMY2aNUIQriOgMMHehvS8+zXj3ISICkALgCDCGOpT+65zstP+aY2f8tXrnztcSOWrPynBPB+gwq+vM3GiQ+cdEtSdal+xDF0JYocxxs04kl/4fEM5ti2D+o84AWYpwU44r8HzO6Fl9W/KsAa4cDxgeq+vMqGzO8zLGTi/MGTfzH5pGy4hwEQG5TYG5ZcLPSCXGyUrpT2d36/Hv7GNnjgeK7UbUMelT7M0B0/WWh7A0rZ2ve1LJ6PwQIQFdCBEJZY2bNVMDPQcgL57gpIjgdjqQneZBt+wMdMvOQNesdGSmuOHUtbgm7ImgADoFTryRecyskXE8AgCgpSGXyLoLxLw7pgcVTnLljJt5qa6c7wH0cwLSEhLID+oQEQEOIhyvQK/njEu7O33MjC4teaTLiSsB6mN9B9cbJv4op6odOmTKXQhxIJU9buZliuguAO7mzBdnpXkwtKAPxo0YiKEFfdGnVy6y0jzwuJ0ACKZpoqHRj101dVi3aQc+/2YdPl5VhjWbd8AXiG0LOhERmA/TFL2YMXbG+bUfPv5Jcz8gGWZXaDaDXKKd0Z6RPmpKru7y3APCzwhwoBXi+EHdCjeSCvAch64fkzVu5v9V/3fhF819Tt70uYOJ6TK7lxoQFq9bUiKj80OIBHQhxP4oe+ysXymiPwJwx/IDDl3DiIF98bPTjsEJRw9F7x45UMp+8q9fn24YeXg+zj/9GASDIXy3dgteWfo5XvjPCqzftgscLe0tPGLto0N7LmPsjPOaG9QZqrtd+DWJbU8TSx8zY5BD158gwpjmtKsphRS3A2keN5xOBxQR/IEgGnx+1PsCCIZiq2XTNAswRkG9nj121qVVHz76SsydKC7WFLSbiJBreQ+j0s/+OyCHsBxSJKALIfbJHDfrfAW6AzEEcwIwckh/XHnRJBw36jB4PK5oPxKRw6Fj6OD+OHxQP1xywYl44a1P8NfSd7BlV/S8NCLq7YD2ZMbY6WfUfvhkzPukibin1cwDMxgGWQb0nGN/fjhYPQPw4FhmL1LdTowY1A/HjxyCEYcNQJ+eXZCR6oHL5YRSBL8/gPoGPyp2VuGb8i34YOV3+OSrtdhRHX3nHAE9QPRkztiZl1Z+uLA06g8AyHMddqJiOs+yqA6DCfzXjYtvXxvL80T70fpzREKIQ0LGuJmjdVKvEWxGbk1yM9Pw+4smYfJZxyElzkBuhZmxfWc1/viPl1D6zqfwB0NRf4CBD2EEJlV+vKg2ljYKpnkXKKK5ER8HmOCG/mWL7tx84LXMo2blay56DcyDoq2V9++eg+JTj8Z5p4xB/97doGkK0ZbXOVxjFbsqa/D2f7/EYy+/jy/LNsEwrQfK4Y+POpPM6dXLH3vJ7vm5Z1+TnpXuWUpElvkHDC5nwrjyJ0p22HZWtDstzpQUQhz6Mo+Ymu1w6aVEVBDt3pGD++Hv8y7BaccfCacj8ZN8RIS0VA9OGnsECnt3w4f/+x4Nfpv19XCU7AOlpTRuGvgWsDrqNHHOsIkziGhExMcxgmUBfS5WL/vR/HfG2EtydJ1LAYywC+YZKW788oIT8cerpuOU44YjJysdSkUP5ns/ChEhNcWNoYP64dyTRiO/V1d8U74F1XWNVj9DROQiqFNcfYe/5dv0xTar5/ccfdIVRGq6Zc12wITJ15Yvmi9HpB6CJMtdCEFamutGBiIGuP2dMW4Ynrj91xg6uH9MAaoldF3D2SePxqLbLkdBb8sjugHsC2r/lz0u5fTYnm6d3c2EbSgtOeANoljTybgLwFi7YD6isC+euesKXDv7HHTvmtWi72jvi83PzhiHF+79Pc4/YRQ0ZfM85i6K1GNpR86K+GXlX+gdpEDXWm5TC29U+6SsqurJuDst2pQEdCE6uexjfj6OFC6LNoX80+OPxP03XozcnIxWD+Z7ERGGF+Xh8Vt/hUF9u0e73U1Qf8oeVZxpf5tXKWLrfezMm3BAMlj2sSmTQXSR1XdERDh3wkg8dddvMLwoL2pSYHMQEXp2z8E9N8zCDZecDZcj8sRqU/b/EU4PbgW8P+5AcbGmdNwFkOVWN2b2hUzjOjnv/NAlAV2Izqyo2Kk0dTPYPglu4sjB+NM1FyE1JabE94QiIhT074G/zbsE3bPtirsBBAyGM/2XdvcUTkMabPIEGNi4/397xs7oTaxusSuPOvW0o3H39TOQnZVu27+WcDp0XDb1NMy/7HzboE5EF+WMW3/y/n+e7zhsMgiTrJ7ddADLkvVL1PuJ7bVIJslyF6ITy8lK+QkD4+1G5/m9cnHvDbOQkZ4S0zOZGX5/EOs278AX36zDt+u2YseuGhimCZdDR99eXTFsUF8cP7oIKTG+IBARigb2xZ+vmY5f3PQIGvwWZc2JiIivSBk//bGG95+siHSLyUZ3RXqq1Qcmwrr9/9NN+rUA97Pq20+OG45bfzcVbpfl8eo/wswwDBOGaYIZ0BRB17WYZj00pTDjvIkIhEK46e/PWyXLuQjqNoya/QFWPNSQN/WG/orodjApqzRoAlcEKDgXuFWKyBzCJKAL0XkpQPs92STHuh067rxyCrrnZsX0wLq6Rry69HMsfm05vizfjHrfwYE3zePCFVNOxfGji5rVWSLCCcccgdnnTcQ9S960vpHR3Wk4LmkAbo78INUPYIdlXpjJ+7ZrZYydXhAu5Ro52h6e1wu3xRjM6+oa8emXZVj+xff4bu1W7K6tR8g0kZ3qQX7fbph17kQMyu8d9TlKKVx8wUlYXb4VS978KOI9DBqR5fRfUF1cvEgj/Q6AelsVkQknwpneDUtujfgCJA4dEtCF6KSyj75oHIjH2O1evejMY3HsUZZnd+xjmoyPVn6HBX97Dl+s2QTTojJMisuJ+66bgdOPHwlll+BlQSnCb2acgTf+uwrfboiczE1EpIF+2/dcbxFp+ndkmGWMwIZgUN8IVOwCaKDVaJUZgKLyvf+tK/1yAiK+zXicDtz+28no2sV6yZ4ZqG9oxDNvfIhHX3wPazZtP2hUneJyYMJRh6Fvz6i7BffRdQ1zf3keVnyzDt9vOnjLPBGUgpqTpw12EOh8WAXz8FT722Uh9XjMjYt2SwK6EJ0UafosMCynYbvnZODX006PmuAVChlY+Nx/cPs/X8aeRvt8qiunnYZJE0a2KKkuxePCdRefjUtKHrbZn81dzGBgisPhBJNiRVrQqaMO6LeNTMNNGlskt3EgGPKvB4BwrXSabNWPqaePxejhAy37ycxYs64C1929GP/9qhwc4SVHEeGGS87GxcUnNTuRLjcnA9de/BPMXvBPGGaEmXLCkWYwdA903eb3PFcbJq5GaUnCj2YVyScBXYjOwOtV/Xa4Mz3OzL4ucg8KBX0jt69a8VOYkQMbAPz8rOPQvav9VDsz48En38Cdj7+GoGFftrRf9xxcdM6EFmfIExFOHHcERg7uj0+/WW95X6ixDo6U1KYyqeQkQg7AOXbltBhUYzSYAQCka9qpYHSPdH9Oegp+NfVUy8/CzPjy2w34hfchbNhufXDbyMH9cNG5E+POij9t/AgcddgAfPz1wUXdCKQF6+rTHG5XxH42jc7vXLekZFVcjYt2RwK6EB1MUbHX6e/SI8vtdgxUSg0lUkdRvTqC0imPiLIAcgTqawk21cfSPS5MPes42+DLzHjujQ9x+2Ov2FYy22viUYchKyM1rs90IKdDxyXnTsRn3yy0LDYe8jeCTROkfpwiQDblyZkpV7kyPulfPP8jf211v1BjHbFxcKW6c088Cr17WB92tmHLTsyc+1ds2VVj+zkuPH0sXM74T6V1OHT86sKT8cm8hyJ+qkBDI1KYESkFgIiXBzfjnrgbF+2OBHQhDmleVTinS5oLzjzlcB1JREcrTQ1zgQaCKBMgx4HJUMwMX3WV7VNPHF2E7l2zbe9Zt2k7vH99LqZgDgCH5fVK2P51IsLJ44aha1YadlTXRb6JTRgBP3T3Adn5diN0E4oIvQHtfFdGDlzpWTACfoT8DTB8DTBDQTg0heJTj7H8LH5/ENf/eXHUYA4ARwzuH/WeaI4fXYQ+XbOxaefBf6dsmggFgnC4f1yel8HVbJq/Xb90ga/FHRDthgR0IQ4hRcX/cob67O7qNPUipenHKqXGENFQKNUTTfukbY/EbOKvtT/45CcT7ZPWTNPEnf94CTtrLIJpBI4El4lNS/PghNFFePot64PWjIDvxwGd7EbnAJiwN+KHZ+o16O4UaC4PkJ4DI+hHloORlZWBkGFC19QBz2C8unQFlq74LqbPoNkd4Rojj8eFk48+HI++Erlaa8jn/1FAZ7DBzDeXL16wosWNi3ZFAroQ7VjhpHtdWoGnl0PXj9QUjoXuG+NC2hAQ5RBRXAuvZiiEUGPkuuBAuBb5yMPzbZ/x/doteH1585ZeN2yNesR4sxBR1IBuBn+cpEfEtseWW6UUhIM7QXd5UAeg+KbFGHd4P5w/YSiOOqwvUtxOEBFChomHn3nXMsv/QGXrt2LYYMst7jEhIowfNQQLX/kg4rS7EQiAmX+YUWC8Y2zZ+ECLGhXtkgR0IdqT4mKtsMepPT2EUUrTJkDXjyWigUSUCUAlYsraCPhhRlgX3qt/z1x0s9mKBQDPvf0pfNFOQTvAByu/hz8QjHnNmJkRDIbgtLl/RFEedEUIWUz7m6Hgj4IZ2YzQw43G9v1WN/jx2qdr8OaKcgzu2wUXnjAMpx89GNt3VOKLNZtiegYAvPDuZzjnlDFRk+JM08TGTTvQv1/3iFP9hw/sC5dDj/h3Yuz3ZwzeZpDxm/VLF8pUewckAV2ItkVDLr8/x6G7D9++6pOjc7KHnuzxuEeBVE4sU+fxMHzWo3MAGNSvu+30uGGYePujr5rd7pdlm/Huf7/E6ROOjGktfev2Sry+dAUuufAUy/u75mSga1Y6Kiojn5pqGgZgmsDeqW0mwCIpLsZB9Y+ETBNfb9iJeQvfwSOvfoo+GS4wUcwPe/ezb/DWB//DqeNH2H4nyz/7Fotf/QAPeC+NOMPQrUsm0tM88FUdfIY6G0a4P0QBsHn1ukU3x7YeIA45EtCFSLbif2lDu+4cRG7P8UpppyqljQo21vXQHE6nOyOTKIEHe0QSCthvOe7fy/5ks12VtdiwbXfz2zVNeB98BkMH9kXfKKen+f0BzLvvX6jeU49LLjzF8j6Xy4EeOZmWAR1gMJugpmJ4pqmg2Dw4KHL4mm3GXBQbd9Ziww5GSm5vBOpqEGzYA6uXh72CIQNX370YDl3DCWOPOCioM4cL9sy5/TGkp7hhGAaUOvjXtsvlRE6qBzsjBXTmpj3w/ERZ4NslcX9A0e5JQBei1XlV0SV9s1Qaj1Ka41Sl+U4llTkQoKZC5kz1OyqQ0q0nKAFJUtGYIZuzxQF0jXLASMWOSvjszie3sWF7JaZeez/+dNU0HHVEwUFJYcyMLdt2w3vfv/DK8lXom5v54/XfA2hKITsrzbpBZvABRVdCIQ2abvwodJsmgc2Wv0gREcjhhCsrF47UdPhrK2H47WdEtlftwcx5D+G8E0bhvJPHIK9PNxABGyt24/l3PsWz73yKel8AbJoIBEMRZ0+IgFSPK8LTATAzm7yKQ77fo7TUvliAOKRJQBeiNRT/SyvourOXx+maqDmcpyngeCjVA4DjwOBkhkLwVe9G18NbVkEtZlG2mbk99nXJ6+p9MDn+Mzy+37QdU669H5OOHYYzjz8SA/v3hMOhY8u23fjPJ1/j2bc/xdbd4S1flfU+29lrIoIn6gEv+z+AwAwYQX3fenr4+T9ktycCEUFzuuHJ6YFgwx4E9lQe9GKxP38whCVvfozSdz5FSlNd+EZ/AEEjIWelBAxfw682vHh39H104pAmAV2IBCmcc69LU/oAl/KcTlrjGaQyxhBRRtNJ1ZbRwlddCT0lDZojttO6Wl0ca8nNVe8L4Jl3PsNz764Ib/0i2ncC2f5iCbGRSqra2ftXwTEmwLUEKQVHagY0pxu+6p0HZd0fKGSYqG2InK+WkZ4Cp0VuAzNQb1F21zTNuqodNd82r+fiUCQBXYgW6Dnbm5Lt6jtYd2qTFGlnkqaGA5QSa0IbM6Nux1akdu3V2l39QZQ1+gaLgLJXZkYKlFIwEzB6NJkRCFnPAuemp9huM2NmNNRHSdhOxqyHbfMEzelCSm5P+Kp3ItRYH9dzCnt3s9y37vcHUFlnMbVPqK/lWvt5f9EhSEAXopkK59zrcpiuw3W346eackwiRUXNCeL7C/kaEKyvg6sgMznT7QBUlAIvO6oPTqzaX8+u2UhxOS1HkomU1zfyNq29DMNElW1xG0Kc2/UTjxTcWd3gw06EGmMvyLPXuCMHWb6bbN9dgz31FjGbaRs+hBy+0glIQBciBoVz7nXp5BnqcjjOJEXnktIPI4JFFlLsGnZug+5JheZM3nS77rTv9vrNO2wT0XKy01HYpxs+/35ja3TvR8YMtS9w4/MHULHbuuodKUJr7xqI1d7iNO6sXDQEAzBDscfYdI8Lp9tsbft6zSb4LesCcDkgyXCdgQR0Iax4vWpoTZ/BpOk/1ZR2Nik1LN6ReCSmEULDrh3w5HZHIhOyotFc9klk32/ablvQRSmFU8Yd0eoB3aEpnHD0UNsR+vZd1dhVYz2FTUoD2ssIvQmpcDnZQF3sAf2nE0eit8V56cyM9z//NmLqA4etjLOr4hAjAV2I/RUXa0O7TupFbnW21qCK4VIjCZTWGkVe/NWVCPkb4c7IStp0OzNDd7qgdIfl9rWN23ajYmcV+vfuZvmc808Zgweefht1Uc4/b4lRQwZg6CD7sqiffFluW2ZV6Y4kvirFhpkRirKVbX/dczLwu5lnQVn8G2ls9OOdj762+GliIopc5F10OBLQhQBo0Oy/d3G4tZN1h36h0rXxQOtVagPCv9Trd24DKQU9JTFHikZqAwifuGWGQjACQRjBIIxAEKTpgEVAr/cF8PEXa2wDer/e3fCzU8bgny+93yp91xTh8imnQtet9+UzM9792CqQhSmHq82T4g7ERjBqtvteKS4H7rhiMnp1z7G8Z+nHX2NzhJPWAIAI23ebe76Iq6PikCMBXXRafa6825NhZI5yOLRpStPOIKLeDFKtGcj3Cvka4aupgnK6oOnxn4e91/7B2wiFYPgDCPn9MALBcD3z/TLSmRmaw2lb8OTlZZ/jgkljLWuMExF+M30S3vroK2zaYX8UazzOHDccJ407uHLa/qpq6vD+5/ZVTDVntD3qScaMUGNDTLd6nA7cMudnOO1467XzUMjAw8++a7nTkJnfwIelkuHeSUhAF53LRK9+xNBehex0navr6kJyaocD0PYG8WSN5Rp3bQebBhzulLhGkMwMMMMMGQgFmoK3PwAjGPhR8I6EiKC5UoA66zoj733+HTZs3oG8fj0s7+nRLRt3/X4afn7j39EYiK9yXCSD+3XHgit+Znu0KDPj5XdXoNoqsxvhPeDtLaAzEFOGe16vXNx8eTFOOnaYZTBnZry+7HN8/PVai7bYMImeaEl/xaFFArroFAb89tGsdMYpykEXKaWNB6nMZIzEIzFNA/W7tgEIJ6jFsn6+tx63GQwh5Pch5PPDCATCJ2nFcaqI5nSBNB1sceqaLxjCo88vQ8lvfmbZPyLC8UcfjpsvvwBzH3gmIUG9X/ccPDj3YnTvmm17X6MvgMdftp/u11wp7SbDfS8zGIBhM93ePTsdF5w8BpcWn4Qe3bJt/23srtqDO/75MgzLyn+0strc81ELuywOIRLQRcc1e7ajKOWowx2acwoprZgU9Y9WtS0Z/DXVCDWdeKZbZJxzUw1yIxhEyB9AqNEHIxCAGWrekaWWSEF3pyBYb3WoCfDUvz/CzHMnIN9mlE5EmHr2eGRnpOL6e5/G9giHg8TUHQAjh/THvdf/HAX9e9oGMmbGS29/iq/XbrF9psNjU+O9jUw5YRjStSKsXrcVVdV7YDIjLS0F+b26YuzwgRg3cjByczKivuQFgyEsePAZrNm8I+J1BgyTzXtlur1zkYAuOpzCOfdmpGhppypduxiaOo6gWiVLPR7hZLiKff9N+62fm6YJIxBEyO9PfAA/ABHBkZJuG9Br6htx16Ov4C9zZ0G3mf5WSuGME0ahsH8P3P7wi3j709W21d8OlJnqxsyfjMdlU05FTpSDYQCgqroOf3r8VdsKtUp3QHN5Yu5DMrh0Db8unoBe3TJhmiZCIQPMgK5r0LTYZxJM08Qj/3oHpW9/an0TY2W1f9ezCei2OIRIQBcdBQ257K/99RTPFE1TM5TSCrHf2nh7YQT88FXvd/QoA77aPQg2+mD4/eHzu+M5mDsOyuGC5vTACFgP4l5Y9jkmHTcCZ544ynbUSEQYXNAHf5s/G5/+bw2eePl9LP/fGuyuqY+4rUzXFPp1y8Hpxw7DlDOPReGAnpYJePszDAO3PvR81EQ8R0pGu8tuHz+0P3p2zQAQfglyOpu/HGCaJha99D5uX/gyDIt/J8wcAOgGrHgltuw70WFIQBeHttmzHUWeY0bquvqFpmnnglp3u1k89iawGSED9TsqwMYPo1dfdQ2CDW1TlZOI4EzPQuNu64AeMkxcf9/TGFLQG4UDekZ9psvpwHGjizBu1BDsrt6D1Ws2Yc2Gbdi+uxb+kIEMtwO9enRBUX5vFPTvgbRUT8x78JkZz7z+IZ7698f2n0vToaekJ21vfywIwOSThreoT/5AEA899RbueOxVBC1mQJiZQXi0cnnft+NuSByy2s+/eCGaoajY60Tvfic5df3XpGkTElnBrSX2nfzFDCMYQsjnQ9DnhxHwwwwZaNy9BWbwhxro7uxebZqJzcxo3F0R9czuIwf1w+O3X46uMazvtgZmxkcrv8fMuX+zzWwHAFdmFzhSk1cbPxaFPXPw3C0XIcXd/BK/zIwdu6pR8uCzeGHp5wedSLfffQzgq0AjTqpb+ejOFnZZHIJkhC4OKQNm/jkrPSvjTM2h/1Yp7chk7Ru3s/8WsqDfj2BjIwyf/6D1bzaNHwXz9oCI4MrogoZdW2yn+ld+vxGX3fQIHir5BXJzMpPYw/D3+9mX5Zg9/5GowVw5nHCktM1Lh52fnXAEPK7m1RtgZtQ3+PDKuyvwx8dewead1jXrAQBEuzkUml638nEJ5p2UBHRxSCi68pEcxepCzen4pUaqCAQNaLsppr3byAx/AMHGxnAQDwRtg2LEtep2EHiUwwlnWhYCe+zXpZevWoOL5/4d9/7h5+jfu1tSgiYz453lq3Dln57EjmgZ9ERwZea2i+90f5keJ04fMyjm78s0TezYXYO3l6/CE698gFXlm2Fabk0LY6CaDfPiqo8fX5WIPotDU/v6ly/EAYZcfn8Xpyv1IqXpvyKNCsBQbTX62ruVLOTzI9DQgFCjL+YsdGZGoHYXQr4fB6W2nnLfi00zPPUeiD6DMKBnF9zx2ykYP7qoWdnZzeoPM3z+ABY+txR/XPgq6v3R8wycadlwZtjv3W4L7NuD4b0zcNyRgzGyKA99enRBZnoKHE1lbQ3DRF2jH9t2VuGrNZuwfOV3+PTrtdhZXWebyb/v+eBq0+RZ1R8ufKF1P4lo79rXv3whmgya/fdcd5pzutK1XxJpA9tqWp2ZwYaJoN+HYH0Dgo2+HyW1Nec5jbs3HVTIxZ3dE5qzfWyvMoMBNOyusCw2s78UlwOzzj4el00+Bd1ysxLbD5PxTdkm3PrQ83j3s29tD1/ZS3OlwJPTvd0VkmHTRMOOTTCbvlMCkOJ2ItXt2jcFHwiGUOcLoMHntykSY/F8xlY2zEurPl74WqL7Lg49EtBFu1I4596MFD19unJoV5BShdQGZ1+GR+KMkM+HQH193EF8f2YogMbdmw/6c1dWd+iu1jmcpbnCSwiNaKzcFvPWubxeufhl8Un46UmjkZmRGvfoeG8y4YbNO/Doc0vx9Jsfo6outl1XyuGEJ6cnlN7OVhCZEWzYA1914pe0mxLgPjPZ+L/qDx+X41EFAAnoop3o+qsH0nq6U89TmnYtaTQk2YF8b2JbKBBAoK4BwYZ6mM0ojhJNsKEWgT27DvpzZ0ZXODzRi6kkCzMj1FgXDkIxBnUC0Ld7Ds494SicPn44Buf3hsftAhHZLmczM0yTUbOnHiu+WosX3vkUb338NWqiJL7tT+kOeHJ6QDmanz3e2tg00bBrC8xgArclMjOI6tnkh81Gnl/9xcIomXKiM5GALtrWRK8+dETf0zSHY65S+lFEyU3UZGaYoRAC9Q0I1NdHTWyLtw1/zQ4Y/vqDrjnTcuBITeyUdUvFE9T38jgd6N+zC44c0h9DC/siv293dMvOQFq6Bw5dh88XQG1tHbburkHZ+m344rsNWLVmI7ZV1iIU5VCZAyndAXdOd2gOV7N+LlmCDXvgq4pcmjUeDISY+X0Qe6uW1/8XKE3cG6foECSgi7bh9aqiXb1G6ymeeZqmnQxmZ7KSmfZmqIcaffDX1SHU2Ahu5tpl89oz0bhrM9g8eG3akZIJZ3qXVms7XswMw9cAX/VOsBl/3FBE0JSCUgRQ+P3ANE0Yptmi9ybldMGT3R2k6e0uCQ4I/5037NgM0+LM+difw0xEDcz8Xzb5vqpd299E2euxHaYuOp12tugkOoPBv74vz1WXcZWWps0AkBY+tzQ5W6D2jsb9dXUwE3jkp227oVDEYA5gX7JUe0NE0Nwp8HTpCV/1Tpg2J4TZMZnD5WwTOJbUPWlwZeaClGqXwRwIH5FqGvH9+2KGSYR6MMqY8YZBeK7Gv+p/QX28UAAAIABJREFUWLEiOf9gxSFLArpImsEX/yPdlaUu0XT9GpDqkYzM9b3JViGfH/49dQg2NIAtKm21FsOmmAwboaZl0fYXmIgonHDWpScCeyoRrN8DxLSRqpX6ozQ4M3LgaGdlXQ/EpoFgQzVIEfZ+X8z44atjbGXm3QDCae4EA0z1DGxV4O+Z+X8w6ItKVbdOTksTzSEBXSSJV7ly9H9qun4eAUlJeDMNA8HGRvhr6xDytV2FNrvqcOGRO6O9rn4REUjT4MrMhe5Ohb+2Mu7Regt6Ad2dCmdGNjTd0e4Kx+yPmRFsrAUboaZuhvu6f5fZ4Lt2b9/2ADKbjrDbnWti/aMBAMl904ybV/UZW+vy98nQVAgpak+Vu7GuVrFiTdd/nJ0YCgUDUIqzsnuzT9fqTR0NLtQam0s3ByQHIPEkoIukOGx2r+5KqdOSEcxNw4C/rg7+2jqYwbadpWRmGDYBkE0DbBggvX3tnz4QEUF3p0BzuhBsqEOwvqbF68Ox0JweONOzoP0/e18eZ0dV5/v9nVN1l947+9oJJBIIhMUIAQGJIEsguACNggjIzOAyos57Om8cRjOBJzIOIz5nxhlQFlGGkTg4gzIojBJ2gkZEFBCULXt679t3q6pzfu+Pqrpb373v7b43ud98Kt1ddc6pU3Vv1ff89mD5RVxmEqwVnOhY4eMMrRgvNYMdfNaGTV1tbWo+s7lEAoexwGLBtAIkeoFZC9pAbWSgLQEVNINSMEMSsQlw6oMyDcMKdPQyQiEOE2LMiEHPSizvn72Pec0wg98kpp2s+fcMvYdj2L3zpxgFNjfJ4qax0CL0FqYFIizfTSQ66jW+bx9PRiaQjExMOW68VmCtCtrPfWhlQRiV5fmeKZCQMNu7YLZ1wEnEYMcibna5GkYGkJCQwTDM9q5UFr2mIHNm2NERMBfmIiK2lLZencZplUZ/v1wyvrqb2vUKkFgjSK4F0TEAloMCPQCHwe4nQMJXJbk/nMREyqSU/ojSn5URam8323v8z282EQDpay0kADAYIAEI4iR38viyfuwErv+d1vxrYvUb20q8skfF9uHBf2z4RdBMo0XoLUwLDMM4sx42c1cCtpGMRGBFotNuHy8FdkqHwWnbAhokuUw5ICKAJMxwB4xwB7RtwUnGoJJxaNuqyiuepAEZCMIItrnSeIN6rxeDtpNw4hNF2zAwNB6lPdM0pUKg3v7/09XphNaAjFMJOIW6cBSD5gIUmvycUl6LEGsFa6Jw/n+SBgKds4t+jgRknI1CJCgEYB6AtwuBy4ikE5DGWB86X+MLr3sW4KfYjv9i567hN7H91paTYA6a64lpoSmx8ppvBDvCPb8VQq6s1Zg+kSfGxmFHp9/RrVzY0VFYE8NF28hAG4I985uOwDLhOx+yVtCOA+0kwY4NrZSrpfCkVgK5Yp6UENKAMEwIMwAhDfi5hJrxPjBrJEb2lqymx4zHBh+7bT2m27tw/XpjYcdpi8yAOI0EnQsSJxFoAQOBahbazAw7Nga74HebEOyZDxmonamEGQyCJnBUM/8erH8ORz08Zlu/GnvgxlHMpMdmg6AlobdQdwR0aCWR6KvFWNlEHq1r/HgtUI6dWTtJgDXgqiCbEv5Lm6ThknPQVZVzEe1EMxJ3ITjxSFmlcRn8AqaLePr75QJ7xdKACJ4FabyPiE4CqDvTj6XqT0ArOLHCvgJGuLOmZA4A3sJDAtQliI5niHfAlP+7xwzs6r7o+q1a6/+yOfLkvh/eNICDlNxbhN5C3SGD8p0ATclIzF698cTYGKyJxlOt5wMzlxWLzFpBKwdSNC+hF8KBRNqFoJUNu4jq2QczM7mEXlf0vuf/dLd3tZ0uQR+GKU4D0SwwKL/ivHK40vl4QdOK62fRU/fP3iV4MgAsA+hyKcWHDfTsWXbRdQ9rR33fikWf3PfQTZPTMx7AaBF6C3WHFOYp1drP2UtMkhyPIDkeaQoiT4G5rMplgFsrXRiBg4IADyQwM6zIcFFHuDSIWfOv6zKR9euNpb2nHU4kLiMh+0F0SNYzV8OvFSsHdny84HGzvcfV0kwjvGs1AFpKJK8SAXFlyOh5pe/C6+5lrbbsGMHL2Lq5MbM41RCtt0cL1SCdMaMU+jcFjll+6C+lNNZUehKtteu1PjZedt3xRgIrB7Ghna46vQSEGUKod2GL0JsJzHASE0iOl11NLaESifnD2+4uzIaVYsM1wb7QnHeRQR8DxHuIqLtmY+cBM8OeGIZdQN1O0kR41iJQg2ibmMEAjwP8CFv27bain+358ebyyvg1IVoSegsVYfWffHuW6KBNIyPx63bd9amhUu2P6F00W5B4WyXnYGZY0RgSo6NusZQmBbMuO5xL281vRz/YoLVT0uExC8yvDm+7O1KLc89dv6kjNFucL4T4c4COB8iclsyL2oETL3wJZrgLM1DxuCA8tXw3M72PAoGNAfBvl1543S12LP4fex/8Su3r2s4wWoTeQtlY/clbjw20m7eA6NhAIHJDOX1kEGtAoqxyWOyVL42PjMKJNX/GS87K91myNVQyBqOBSqm2UBjMGtb4UEUhesz0a0zRWWv+WZ9rD3Z0XkBCfBokjiPCtK4AnXiksHmBBGSovSG1TGl7Ox0rJP452NH++b6LNt8aj+nvDPz35r0zPb9aoUXoLZTGpk3iyNG+y8xQ8KsEmscVVBShgHlsKcnBt5MnxsaRHI/UvHzpzKGy63ASUchQR0O+EFtIg5nhxMahrEo1t/q5qk+6/spQ3+xl7yVh/CVAxxDRtL+7Waui0rk0Qw2jai8GAgSIDgUZN7S360+GL7zuXywRv23vluaX2FuE3kJRrLrqts7AhNxshIxPEbme6pXQlIA4uthx1hrJaBTxkVGw0xjZ3WoFqjDLrbLjYO2AZHNkjTtYoe0krGhpr/YsMLMS/MuKT7b2arNv2cLTIIwvEYl3TrdE7sMtNxwpqpFolvS8PlxiF30kcEMQ7R/vu+i6r4876s7R/9w8OtNzqxaNY+xooeGw+upb+kKzzC2GaXzGJ/OKIcQR+XYzM5ykhci+/YgNDB1QZO6Hqym7QrMBu2r3YrHbLcwsWCnXCa7Cz4iBiG2r31fSZ+HGTYf3HbLkeyQD9xOJU2aKzAEAzLCLSOcAIMyyLGsNByIQES0jIf6h2zS29l20uR9rr27KVXVLQm8hL4781LdPNtuCdxKJFfniV9mxSi/F128yCLQqd7dWConxcSRGxw8Y9Tozg5UNlYzBSca8ZDGVX5sTj8AId9Vhhi1MFcwaycgAuLo653+YSIbLEusXf+ALs6UIf5qEuAagnulwdisGZoZKRkteN4nmphMCCQYdTULcs+zQpT/Fsk1ffPO+zc+hiZLUNPcn0EIdoGjNZ++81AgEvw7CnLwaNCIZ7uku+ZJZsaJ7uRAi5P/NzHASScSGhqEsq6azngkwM6AVlBX3ilQkywpRKwbtWNB2AjIQrtEsW6gF3MIro1DJ6iKemPB86dzjm8TCc2NnGUbbjYA4eqaJPBPF4s5dEKiBvNurhZ+NjiE2QJon9V143T+OK3Vzs6jhW4TeQgqr+zcFjL67PmcYwS+CKFS4JZF2jJIvm3Bn5xIGBJjBWiM+OnZAOL0xM9ix4CQicBLRqoqRFIMdG4cwQ01ljzyQwcxQiSjsaNXvdIbmXxRr0L7ukvnh4I6/ZdV5OSDCjUTm2k64YZWlwBoHihXX84rvhZR/0010duj8L/7J3h9d/7uZnlcptAi9BQCu85vRK78mDfNKUPHvBREBbaXHJHbV7XYigfjQSNNL5cwMbcVhx8ehrHjdFiYqGQM7NsgM1GX8FioAM7SdQDIyWP0QgALE9vxH++XsUzs2EtGNAFYBIFfD2yB87qV5LaMhtHYgpzlDXN3AYAYSYL0NWn9PGk5ThLYdIHe/hangsKtvmhPqkrcLwzyPylhiE4GCCZQOmBZifnx4FInxsaaVyn0HNWXFYEfHPEml3tfCsONjCBhzWlL6jMJ1bkyODUzJlELMI47Ur+Tu7zqpf5Zpdl4ngKtA1JA2Fq2cssPzlJWANIso9poAbmY5PcLM9yqtvrNr+M1fY+udpavuNAhahH6Q44g///ayYDjwfZLyhEqKN9hOfD6Aol6747t2LyM0LyMxs0fko+WpHGsIJzEBI9wN2ZLSZwxaKSTH9oP11NIOM+jl0a13ZuZKpd6TrzzFkOKfGTiqYVdtzHAS5ZvIVGIC3NbVhLZ0BjM5AL8Kre7QdvTuHfd/dfdMz6oatAj9IMZhn7rl8GBb4AdEcnWlNjuGLO2KrXUvmiDRRC7YU7Pa0VFXtT4zk4ATG4PoaknpMwHWLplrpxZmIr0Nvlpn+ZWhWX3izwXRFwGU9iydQbCXq75caMeCE5+AEe5smu8sMztg3s5a/fO41j9qFue3QmgR+kGKoz71r+8w2tq+TyQOqcYBxwi0lYrTJGYsaY7H2oUfemZHR+AkZr7qopOYgNHWBdmk8b3NCtbaJfMy6puXNR74aQCYc/JVi1jin4jwXjCLRldeKStWdrVAH/bECIQZbPzKgcwWMz+llf31HSNv/bSZ1OrF0CL0gxBHXPOtE41Q8AdCiMXVjmEIlJDQNxEJ1LXyUy3BWsGOjbkOQFMMPasd3MpWomdBY78cDyC4kvlALTUzCSehnus9+apTIHELAUcQGsmH3UWq7gADYA1mDacsZ7jccVzNRrB7PoRhNuL31mbmJ7Syv77j5Rd/ghe3NLenbg5ahH6Q4YjPfPtdwUDw34SsnswBQCmnr2iDDcMmYUHDe8j4STPsiRHo6hKG1BXKikMlo5DBxix6cSAhTea1q67JzDuMcGCDAF8H0OyaDVz8pNlum6xdwmYN1i5ZQzvQ2v3JWnm/q1SFwEoqBU46vbKRHN2LQOdsyKAbDjPT310GFLP+FTnOjW+O4L+xdXNNJfJH1q83lvYGZgU6jD5iXpWw1Hhy/85Hjtr6Yvk2ixqgRegHEY789G3vNkPBewTR/CkPJmVHscNLtNHOzO0z/SAXgqted8tfqmSt1evll4svB1ZkGCEzDJLN54/QLKgHmQMAgRaD+WYQ1cS7MS1JczZJa+XmQ9AK2vvJWkGzBnwSr6j63xTnqR0kx/ZBmEHIYDuMQBtoBiR2rx76q5rVjdZ45N59D9005Yd9EyAuvWT9rIAIrzSFPJYEvwMQxxChj0G9BDZgKx0L9/7+F+eefGfSjt19ysPPTYuTXYvQDxIc/tnbTjKDNSJzAAQuOk5SGoF2QkPmQ/YLTdjRkaklhSEBYQTczQxCCAMQBIAAraGVBZWMe+rb6l+krB3Y0WEEOlsOcvWAVg6s8Zqq2dMgtFWkX2cNVja0R9I+QWcSNnskDtZgj9wbFdpOQttJ2DQKYQZhBNshg20gIev+XWbmUdb6Gwk78c3999+wbypj7f3IWe02jKNAeBeRfJcgrAFoHsAhkEhdCHn/S0NIEFYDfGPAbPvEtg3vvMWKRG499YkXKqzqUxlahH4Q4OhrvnWiCAR+QKB5Ux2LmWHH44gODi4s1s40AyYDZkPRD7P78p4YqjqFJ0hAmiHIUDtkIJwqF5nv5SQ4BCPcBe0kYY0Pufndq4QTj0AG2tyXYYvUawLfCbJ23uxTh0rGEE9ObQHYkGANbcVhWXFgQkAGwjBCHZCBEECi1t9pi7V6IGnH/2bvf33lxWoGuLcf8nicO9cM0akgOl8LOkUAiwnIUTPkn7fpJdhhkABwiCDcEOzs+uizZ5/4pTd2jP/nxS++WJcvXIvQD3Acec2/HiPCoS1EYuFUXXGYGYnxCOLDI2CtZqPWuuU6wreVW5GhqqRykiaMUAeMUAdIGmW9gPw2wggi2DMfydF9UyJ1KzKEkBkEHSjZuGYQbmhiEsnx/RV7ctcfTfFIVQ/WUMkoVDIKkoYrtYc6XM94ANV6/3vq9ddY23/91ht7flg6d342FEB7L1k/G2b4DCZ5ERG9i4hmA26Vu0pmJQRBEEF72hMGCRBWQYrvLl/W86NtS074/LqHnn29kvmVg9ZS/wDGEZ++423BoPEACbFyymSuNWIjo0iOuZ6vzHrfm79z+vDi5rwrzYUbN/UFwuYrRDTDMVduHnlrYgROyQITk0FGAGZbN4xg25QkCWaGdiwkhndV1d+HDLQh2DOvCZN3NA78xV1yfLCBIhoOdpCrkg93QAaqUMkzkszOXVGd3DR43w17Kjnz61euDwk7vFYY4nJB4jwCFgCYktqAmbF/eAx2vrLQzAzQTpD63PHtz/wHbUHNikG0lvoHKFZe860lwZD8PtHUyVwrhejAEOxYhpqaRMfCQ9G150XkT3KtHcIMm9B9ErXGByuWjEmaMNu7YQQ7/ILJU5oLEXm29jB0pXXSM+BnrjPbe1uq9yrArGFHR2FHx3DAS8JNBTeZk2UnQEJCBttghDohzADcSm75v+vMYAK/qmz7/+z4z833Ayh7hbanf8NcOyzOF0x/SgHxDmIuT/VWBogIhpT5Cd09x1JAfPcXEyef9MTJ+NIpTz5ZvNh8mWgR+gGI5Vfe3NMRDHyPSB47VTJXtoOJgQGoRA4hMkLCwBKgAKELZ/pcavPArZA1gWRkqDIpjATMtm6YbV31sO1BBkJTInQAsKNjKRNAi9TLh1YOrMhg9f4TLUwLWCs48Qic+IQrtYc68jrSMaBY6x/YTuLzu//ryzvKHf+Ny85eaAjjo1rQVQaJQ8DserLW+FkyDAEUlSMoAOJPm1047KnTT7r6nT9/emrqO7QI/YDDwqtvaevuCt1C0njXVMncSVqY2D8Abec1RQmSvALAr/MdJGnMGKGz1rCjw2VWifJBkKF2BNp7UzbqWpOlK6WX1FpMMJgI1F64CcOKDEIICREIt0i9BPwqecnIELgBcw20UAgZUntUuuFvoQ4IM8QAj0CrL731xq5by7WVv/rhDUvChvg4kfgTAvwonbqVmzDKCjMlQeANZogefPq8Ez940gPPvDSlc06lcwuNhk1iTmfw/wpDXlRJoZVcMAAnkcDE/gFwPpWRB0nGIYWOCQUv8HV6yaaaECSSAQQ6eqfFg7yU7ZsZw1rrjwkprgXTO4kKVL9jRnJ8wM3IZQZbpF4ArDXsWEvF3uxwpfZxOPEIi0Db80Zn7yd23bc5nSO/CP7Y/57uQCj0MSnpEwCWTdfDUh6hAyAiBtYILe5/5qx1HzrxoW0FSu2WRsuz5sABrfnMsk8ahnkNoXqPKWaGHYtjYt/+omTuSv+0utBxS7BDoGkTh5gZyk4gMbKnAjInGG1dCPUunLZwMC6l/ideDEHjOpE8D4ybmFHwHmYWEOEGjkWeCbjfhyQSo3thR0fRIvPmh5vtje+dGI+ds+u+zc+gxIf6yPr1xo7Lzr0w2B56XBriKyBaPp0rXykqew0TsEIY8r5fnn3i26s9Z4vQDxCs+ext58hQ4CtE1WtdmBlWLIaJ/fvBqgy7M+EIoD/vMtSxI3EGpqXggeu1HENyZG/ZKlWSJoI98xHomA0h65/kwkepECkCScF0zvC2u8cHHx//aw18HswFVyisHTcczk62SN0DawU7OorEyJ4aFlipfKu231T7H6BIMuPGQaGujG77dskkMTsvP/ewty3ruEcYxj2CxBrMANeRF7pWfgcigPqUEP/xzBnrCgpLxdAi9AMAqz7xzVUyELy1uN21OJgZVjSK6P5BQJf7WqBDZm1Ynfecwx17owDVvWSZn/UtOb6/tPTrQYY6XKl8mu3Pvtd9KZCgMwEQsEUNP7bkHzXR3zK4oLrET7OprPhBTer+wi4xsgd2dGRKIWmFSZKKbJPHyEaxvrXrf6CROwMTzPrTQ4+NbypVFY2vXmvuuOy8q4WQWwXRhTSD2SoFEYSo/P1CwDIRNP7t1xtPqrjeRovQmxzLP3tzT7ij47tEtLhaJ7gUmQ8MVZpGcnbA0EvzHtmymsGqrhI6M8OOjsKKDJY3bxIIdM5BsGsuRJnJYWoNZZcOn2PgiDknX+Vl4tushx697SaA7uAibO2q3/fBSUwcdKTuL5SSY/uRGN075axvxQm8GCoj7Pr2d9HMxO59jweh8aHBx+64FdhSNF779Q+ds3xXcuE90pT/AqKFjeBYUqnaHYAnqfPRlqK7frt+ddGaGbloEXozY/0mo1v2fo2EfMcMkDkAkkHDODb/sc0M0P5q5lQOmDWsyJAriZUBYQQQ6l0AI9w5Y885K7s8kwCjUwk6LmOPTsbtvwJR8TSWzLDGB2BPDLu5vg8CaGXDnhhGfHj3lIvs5JfG64i6Dj+Z2JsJLpnTHnb44sHHb3ugRHN68/Lz3hMImQ8JogvQILxGRJCy2qkQAXh3NNxzA/ej7KpMDXHhLVSHNcct+7gwzI/MDJm7jnEssa7Q8GCuS4Uh1hrJ8cGyM7/JYDuCPQshjJn1BncS5RIOkwC/M3NP5Nm7hrRSn2PmkuKnHRtLSaoHorTOqZz8w0gM74YdG6txxrc8EjEBXGIrJWBP6oPKxijr/HmvxbtvNbxD9Qe9pZW6YPDJ2x8p1oqvXmvuvHzjX5hC3EfAykaQyjNRlYTug4iI8LFnIydeVm6XFqE3KVZ/5vZ1RsD8crVOcK4DXLxqMvdBEO8sdIwJNZfQWSskxwegEuWVGTbbexDsnjutjm/5wMxwypwzEZEQdDxyXtHDT0QfZtCPyxlDex7/TjxywJC6r1q3J0aQGN4FOzo6tWp5mWOnfitA5CBXaCqyMREYBbYSfUuOUU5fUAFyby5SZ/AuZrt/+Mk7nynW7rf96zt2JRd+Q0j6OxDNnOqtCKqX0H1QgIT4uyfOeceqclq3CL0JcdjVt8wJBI1bANFZTX+3YloCsYEybc/FQGJ1z/s/25P/RHjdLZhQG6RqVpelWiUEOud4KVJn/muurHhFSU2YsWrOyVfl2M+2KFL8lXKkdMC9X1ZkEMnRvVDN6gXv1f1WVgLW+IAnkdeOyIHCZJ5J5P7vTEU2j1DzStcZxFy0P6rsnzq324EnXU7DcV1+MO9X0JcMPX7Xs8Wa7fzAGbN7w53fE0JcDVDD5lOZkoSeAs03yLz5t6tXB0q1nPk3XQuVof9eGe4MfpVIHl2tqt1JJhEdGKiVnTXURd2n5Dug2Sk7HWMp+DHXyiojbScJBLvnzai9PBPMDCc2VlEfIsxPAoty9w8+ufRXAB6uZCxlxZEY3g0rMgTt2E1B7L5a3Y5HkBjZ7WobEhNlRzJUjslkDlCKTJFFoAIsvI1Ean+WlJ2zgQgsivd324nq+ovMc8OT2HMvy/2jUT99BkYV8JGRR+98vFi7tz505iLqaruPBN6LBucwURNCBwSJsyb6uq8s2a4mZ2th2nDk4omLhWFcVg2ZMzMcy8LE/sHy4szLBAn57rzn087rvrAwFaQk83ISxnhk3kh1w7VjQVkVOvwzBwzit00+sFkz87eYyy9C4Q0IJz6OxMhu2BPDDUnszOxmBEtGPWl8F6zIILSdRL1oKN+oPpm76utMEiWwENBSQAtvkwIspLvfOz6ZkDOO5emvvf7u+PkWBOX2F2ny9xchdblrdUGCmT8z/NjtDxVr9OqHNyyRweAPiHBqwzzgRVBN2FoBSCL60q/OPHnSIj/rfLU6Wwv1x/Ir/3mBGTD+gYiqiq3USmFi3wDYqV39ZyIQCToTa6+eNCdrdPQPYJ5StjjXAW6gLMmchESoZ/60x5cXgyudj6NiQiIiKXB43jEt6xEQqqqlzFrBjo0hPrwzlSKXtZ4RcmdPna6VAycxAWt8APGhnUiOeuF3NVSr5z1/vn2U8dMnVJ9oRZpIlZBQUrq/ewTLQkBnSs+pLaOv10dn9NcZ/blU/zznzyT4LIk/w1yQRuNJ6QwoDX3d0GO3f7dYu32XnDE/bMofENGJDfOAl4AQomap4glY5Jh8bdHz1eZULUwHpESHINFbTV+tdLFCK1MCQ6xcsmT+JPIZ2PrNKDTvrHpcrZEstzoWCQS65kKYoYZ61lk7cKoOpxIr8+0d3nb3OLF+cArTAjwnvcTIHldqj45AWQmwVnUld18KV1YCdmwMydG9SAzvRHJs/7SQeH7kOsLlqM5zSFRJmZKMU6TqE2omOfskn0XEwhvD+1tKKI/gtZDZ5J6vf9b5Rfb5M7QIadu7C26cRyILXm6Fe4YmfnMTiqwzXn//+h470PZdATqhoR7wEiBMvfRyejAiMF3xzIbCWeQa1pmghcmgNrVfA3EBhCrpx1ojOjQ0uQRq7RAS0twA4IXcUzPxSwSsqHRAZoY1MVyeNzsRgl1zG0oyB3zpPFJ1SBWDlxc6pkjeL5g/SYWKt1QA7Viu93h0FCRNSDMIYYbcoi9CgoSAT3rl3N+sBQFrsFbQjg3tJKHtpBtONyPE7U0p668MD3Bf1Z7pgOZJvVoQtBAACZAh0NHumnRisTgc23GvmRnEDMHs+ZpySu3tq84hCCQE2tvDEFIgHkvAtmzojP7ultnfV/+n+7e1hWAYBuLxBKykBdYMIg1oQGgNCAFonb66rEUaAXC9VWfyaXHJnH6RjNufxfbtBSWNHf0nhUVb+zeJ8J6GesDLAJGbMU7XTCfCbQLGtQq4TOZZALUIvYkQfX3I6TiiJwopy5bSmRnx0THYE/XLwkoEgqAL0N//D9iSnc2J3fKqGysZz80AN1JmnLnrzd5INnMfrBWcRKTq/oKocOrHRHwbBUPDAOZUfYI8YGXDUTbgLaRcQpcgaYCkASEMl9RIZLOBpz4HK2ilXElfOWDteM6XjaHkLZg4JkvV7m8uqftqbQiBnt4unH/OyVhxyGIQEfbtG8Z//8/TeOPNPYBnulAZhJwbbtbR2Y5zzzwJRxy2DNKQGBoaxYM/exavvPpmqj8X6R8MBXHOGetw9FErYZoGRsci+Nmj2/H8C6+CFVKOFUJrV6DzxiEQmPxx/QueWVInoiGH1Z9Gnr1rqFAbBdDe8KxNJOQH0TRzXTAhAAAgAElEQVSu+mkQ1VBC9wdkvO+XZ59wNH767PO5h1sq9ybCnh9vjjNR2SpsZkZyIorEaGUe1lWB6Lgl1uGTVEGs1HOVhK65udnHvQpZpWF29MIIdTQemTNDTVGFzOBerO7PG6oyvO3ucQ3+VdWDlzsHrVynvmQMTmwc1sSwGwo3vh/JsYxtfABWZBDWhLsQU8kotJP0rn/myLx4TvacNlmq9mzHMwgBIxjEJReeiTWrV6AtHEY4FMLyZYtw2cXnoLu3G5AytbEUYCkBkd4Hw8SF73033nHc4Whvb0MoGMTiRfNx6UVnYsGiefn7+2MICRgGzjv7ZJx84tHo7GhHKBjEgnlz0P/+07Hi0KVeP5llT08vTLxrLWBPn+4UsczQivmvRh67M1erl4WXP7D+UhLyL9DEXFWb0LVMcBsJ45P5jjTtTTpIwVBqoKyGzHASScQGCy5+awoiCgjT+HDufofxKyKU5YXnFteIwooMl3VOI9QJs6274cgcAMAMO1ZeJrvCY6BzTm9nsNBhYjwxtRMc2Che3CR3lx+/nekI5xIjhACkxLJli7Bs6ULkCopdne14+zGrwNLwyFekidhbDEBIzJs3C0cctnxS/7ZwCMe/fXUGeYuc392/O7s6ceyat03qHzANnLRuDSANIMO5TgtKOcnBT05T8J4Uume1B7tqiO8Pi9e+U6zdM+etWzuesL+hmUvGXzcyaujp7sJ94X3wqdMnF29pEXqzgejVcppppRAdrEHimApAJC+etWFTV9Y+Z89+Zv1Wqb7MDG0nkRwfRDmvFWGGEOic1ZBk7meFYz3VaAIKJ22n4MtMg58tVrDlYEb+Ais5bSgtmedmY2MiaEqTMQuJrs72lBo7d+vt7XbbSZFNxJ50zVKip7cbRJP7MgPdXR1gaaSl+jz9Q+1tMA0jT39Cb3cnyEhL8ymP94wwOGR6vU+6HZM1FvUD7XAUfQFbtxZ8QJ7ZsK5LKXGrZu61axiVMxOozzuKumQAl+bubRF6s8Fx3ijVhLVGdGAQ2p7mB4FoWUcb3pu5a8+Pb42x5u3FujEzWDlIju8vy4GMhESway7QABng8oLZzS8+VRCEIws7QGrJvydCGSEABxeKFVjJzJ+ellqzk7dkeqwjI8ZbCwEu8I+kgC1dT3WW0otN9+LTPc90NgyPLPP8I4ItvXPl6e94W7H+2uvvLkIoFbueXqQgrYFAPs/3+kvrDChmfe3oU7e9WaiNAkhDbGbGcQxQcrrfYzVGrZLLZIFARPSRR9Yvz3o/NOgbsYVCsLT+Y7HjvhOcE69r5dK8cB06jU9gwzXB7P3q8aJ2dHZjzVmV8+C6TnA0Q+VPS4GZ4SSjFaV5LTwYKCBlQZX7aCSwXzPKMsEcLChK5im+ykncItJbZohYprrbkQYcIfJK18yAJgFHStjS8MLKXEJWHhHbwg1PK9yf4IjC/R1f6gbnHwOALVwJn705s5DQnlOfm0kuV/1OGYub/Pet9qTODw/J1/+9WItnzz7xDM30Mf8BTzQ7odfvPXV4e9uiE7LOVa8ztVAfaI2XdIH8l8wMOxZHYmyKttupgMS6Je1zTs/cZdv6yUJ2dGaGFRmGtstbgBhtXQ3p0Z5GjaTzcrD91hiBSpozDgYUdXrLkciziDwjkYsS6aQvvg2bheESqmFAk4Rm5N+IAMOANgxY0tsMl6AdabjSuSjSH25/Vay/lNCaCvbX3oKCpXsuSE87kJXVbnI2Op/YUej+1eozYh6H5mtLqdo1ia8iIzQ36YcFNinq+K4ymHFR5o4WoTcbYsODYJ3X0007DqKDU6ueNlUQQUrQFzO9s3cPTLzMWk/yzmdPNV1uaJcwggi09zYwmQMqEQM7ZdVOKQ0Cm0xFVzpMXFRjc/AhR22cm/EtI/kKZySCSSVsMQzAkIBnz3Y8UnUJvrCEzaAML3WXgLX3E15/rrp/hrd7AQkdIMCQUIbhqu5lxnl9qV/kpInNm2Y2/72c6huFXU+4OwYfv6NoZIZi+WlmPjbzQ3SUgqpN3YkZQd1eV+6LcMPzZx3d7u9qEXqDYeHVt7St+Mjfzyt0/PdLY1EwJtmfWGtEB4fBauYSdqQgxLqlq1ZfkPr76ZvjzHqSR7ayErAnRsobkwiBrtlekpPGBLOGFSsv3K7MAVXSdopmAyLGQS+hp8kmn4rdL1Iy2Xs9nfnNgJbSI3KZCv9yDMMlc8NIOZoVnAMJQBjpMLXMcDUpAWG4bQr2p3R4WoH+ELLgWp2BVBslXa0Cy+zrycww55N6pho+dfvqQEAEGuSkdVOxNtvOOuEQgD+bu2JnBiy7Ad5rVaKuAgjRIXEZXuP/2bhvx4MUc9sDV4Znz/pgwQabN2ut1e8ydzEz4mPjcOJlFC+ZDjARSfO6BRu+MDe1i/GAb0d383fbsMYHUO7a32zrgTAKmpNnHK5ne7R20jkAgKKRiXjx9H6MXbUsUXugIE3m6dAtX72uhGujVoZnq05J5O6mpZFN5p7UDBIFVeYpQpZGlqSdSc4sivQHee3z9c/QEKCwyj2znz9/7XvOe2P7DnopNXy+gjD+/cu9p9V+FsysoW8d3nZ3wRwamwChDPNaZszKd7yZHeOqLIpZ5tiQxPJs/+8WoTcQDv/zf5otDPk5KeXpJZo+l/mHk7SmJ3lMmXCTI9HKQFvoWnjr/Xg0+RigI242MQ1rfLDssC5hBBs33txHrTzbM0DAKF5E0VUag/djesKHGxL5pPOsFK7kSp6+ijlVzCSLND0btWfDtg0TtmGmydwPHSMxKVFNeqMU6WZJ2SJnjEL9MyX0Yv05f38AOQsKj9Q9uz4bMkXs7DnduZJ6RqW3jDKx2Xb1qdnTCRggRd8s1mbjhpOO0Vp/qNBD3sx29JrHoeeC6D3K+5BahN5AMAPhPyMhl5OQJ6y66u86C7WzHfUce45xWusZt5vnAxGIhPHxpRduPgsABn96wz5tW0/b0RHEh3eXVwrVQ6BjVkOr2gG4cec1lc4BgHcDW4rqGrXmYVClpVQPYGRkRPO92nNV7JxD5NowoDwStw0TyvTJ3PAItQwbOhHySeVZqvMCMexpG7rItpfn9hfegqKYDV6krw0Z1+UYZmrRki2ti0kx61nq99wbWyG8fO13DD55++5in5oNfA6g9kINLMc5eFetJUDgNb8844RZQCuXe8Ng+ZU390gz8BdEIJJinmyfdSyAx/M2jqtXOchjAHrjI6PQVq2JpDYgQlCQuGXehs+fsf/Bv/9jdGTP9wXrs6gCUdsIdUIEKqpFM+1grWHX0nbug/BKyTZCj4ElN1+W66kjr3QOZCdRyalWlvJe90iyo6sDfUsWYvacHoSCQc8PLF1XPD0OYV53R8G59M3pxsYTVrszYH9W7Em97l+zOtsK9l/U24mNJxxZtH9bsHDV5K62MM5bdyRYa1BGoRe3OI7GeCSKHbv3Y9/eQehkAqQUoAhMCsq7f0IBgIaX5t39kZX/vSpELMf5VrEGT5110qpcb+1cOEpDKQVhNB9l1VuzSIROmPJYAD9rvrtzgKJzds/HicRcAGCGNIPGmShA6C+N/M/+Y7rPf01Z1trkePXFP+oJP/ObHR3t08nYLT3HXnkREvGHKRQcBjC7rEFIwGzvqe9EawAnESkzhr4ysMZvSrVRjhkzAi0JHUCK+HLD07LI3PP6DrW34dSTjsXRqw5FR1vI80Qu/eItpAib39WB+V2FCb9U/9kdbTj18GUl+xcaoyMUwCmrCvdnMJTS2L1/GI89+xv84Q9vArBTHtgaXpU37S8gvMItWeei9P6yZgqA8cDYU98pHokh8RlmKpneNWkrmE1I6PUGu8v54wH8rLH1mAcJVl5z+1xpGJ9KWf8IRJDn4Opb8i/Jt2xRyrG3xQaHG07VzszQjoXk+AASI3ugrBgBfLrRKe5QJkc1Y2u5Y5lt3Q2bQMaHVg7saO39FxhQCuoXpdoZmhIMbl6PoSqR71vvR2/5W0o6p0zJ3MCcBXNx5QfPxUnHrUZ7W9hzNCvgbHaAbMwEISSWLJiDD258N95z2gkwQsGUpiKVCU8IZMan549RL8+WzgwN8C3F2jy18aTFmuniMoZD0q5BsqYDEW5Jt3cALRt6QyBs0lUEsSiTuEjSmlVhdWihPtHde7Y6Sauh2Jy1gh0bQ2J4j1fH3J0eEREI7wuI0L8T+Jly8o+TMGC2dTU0mbuV4SI1yNmeb3DsV47xUqlmiUBCgaeoFG0yZF+sFyed6QiHbOncL5DCUqJ7Vg8uPv90zJ3dUziN6gH9z3XSOvHtq/Guk9d6fgKufd5d/JCXVY5yQ/qz7vfkzyEPCC8NDk08XfSzVPQhMJdVDjppNa9jXL3BwOG/Xb060NJfzDAOvfrGbmnIT9Kk2AYKBUToXAC/z9fPjsafkuG2BIBw/WdZHK56PeFmfCsQNk1ExMxnEug4zypXlKnN9h40bK52D/4Cph4g4mfGn769ZJC+TAoLYTRvkG6FyEfmqWMZ0jkyVO7w0riSIXHW+nWY1d3RaIqtGQBh3XGr8dpbu/HGH98CCQkwgzWDiTMk9Hy2dM/IjvTnkfswM4MJ+He8uKWgg8+9q1cHwPhIuat2Sym3VnwDL/JnEEutZcHuxn5jHgRo75j3ISK5NHc/EUFK4yJgU97PaOePv7wL0KWdpuoIZnYdwqIjSIzuLUjmPlxJneYSFdcMkTQbssZ5JpjZrdleRjGZyseG1kr/EAdxOFo+FCJzXzpHPuncT54iJJYuXYSVyxajxFryoIEUAqesOxZkGqkkMzqzOpsf8pcROZBGtvieFT4HgMAJxfq+YudfuqzreAaOKne+WjNs56BZu1YEAjptbS5qSegziJXXfCMopZFHOndBQhx/xKcXrnjpG8hfMlXzz1jwMTNBfG6FNBvJ8cGy87CXC7Otu475EqcGP4mLdizXGY4nuw55LSdfAAFU1oXxfiuefHCqcz1QMPnm5pJ5rnSeDsXy64NrIbD68BUQXuhZ3vMcwGJ7oXfEknmz0TN7Fkb27ncXPyygNYN8KZ3Jk9AB8sTufI5yPjIO/WY4ZpYo9Sw+CEBWch1Jx0EwUNjb/2AGkVjRIvQZRNjoOEcIcWTBBkSGaQQvBbA532Fm9SBBfBbT7AvBzFDJKKzIEFjXdsVM0phR6ZzZFfLA7BAhwZqjIOwH8yAzD4JoDysVdRITg1rpUQGe0GCbgfSqhgWR0G0CwlCgDsHcBUIPM3oBnk1E8wCex8AcgDoICDHD9AOuANwd2X7PYDnzDUiEADYOVKmzpIodSJc+9bLBaS9nO0Ra3Q7TxOL5c6DzetMxXnhzN57/ww5orV2tC3veZP4MKiV79v6r5nvMqf8mo+B46fA2UOYm0NkRxhnHrkJX22TrHAmBBQvmYmhgCFJrgAVYevZ29ixj2iXxLFLPmmLmnNh3THgA228t6MX2+vr1oV1svb/4jZiMpOWAwy21+yQQkYY4pEXoM4X+fiml/BgDsuAjSiBhyP4l/V/76s4t/2tSJpaxZHJ7T5u5D8DC+k42DWYNOzrmqpvroBE2w13TJp27OS+gwZiA1nuZ8BJYv6RZ/4FAr2q29kqLB/RwMrFzyU4LP9iiMfWLJqBf4CQEuqUZgjZnCaJFguRykrSSmVc4lv6ncgfTgqXBhXQ8zY2yyTwzTE346naXzNmT1kUggHA4lPfDG48n8aNnfoNEPAloBfikrnVW9pZa3eLcOeQfl/N+0ybZqgH4tc4BbwHjEXkqa50QCJkmznnH6jzPFqG3uwtKSAipQd5iRnnX7IrPGsweqYO89S4A4hxid8dj95n6abF7sLvNOgG68vdWc6aAnR7NDxEvbhH6DOHIBWccRVKuL7XSJBJH9CzpPnUn8FDusbEHbhzpvvD6xyDo4ul4pbNWSEaGPA/2OoAkjHBn3Vbfrrqck2DeB+bfafBTrO3tKskv7eHxvXjwHy3U/+ljYIvC04iPAXEAIwD+iHTOgWwdZgk4MMMSbBxojF6QzCmDxFI/fTLPqWXuZVlTUnqZBimvoB1LWBlk7hG6UiCtIVlD+ElagNTP1PmndF15r3Dyfi62tPHs10Ru7XMSUP71Z2izo/EkOHXzsmEYBpQUkFpACJlKTKO9RQzBu+5MjYW3P0Xs2ePuGVrQ9UKBS/L60gaGlpVqlhylobSGISvS1M8opsuSQ0wLW4Q+Q5Bm6CoiKsdDXUgprwbwMPI+js59oEA/6qhzdZ3fHCTHBmpuL8+EEe6ouWc7AwqsB6D5V4rVo1o5T0wkYi+P//Tm4ZqeqHao6PEPCm53dcsHKgqRue+wlUPm5IanQaRjqx0hYfh51Auo3FMSuUfmQimYWkF4UjoVeivnLj6nuhiddJ4cST11PJNYXfW68Dz6FQs4LL1sQ57qnXVahZ7nGlhIOEIjIH2NhHsGBW9ZwAxAu1I6Z/u5E1O2FzzzNvz7TQlsuTnvJT6yfr2hdfLMam6WZtcxrrkIfXoYnYF5LUKfARx69S3d0hBlJVMAAK30eQsvuLZvz31ffjP32Fgi+XBPmzkGorJiOSuF6/zmIDG2rw65yjNBNbGde05rCsxvaXa2Musfw1LP7gy/shdbiudFb0ZowoAA3wvgZAYtAbOsJLVuIyJbBvT2+b+mJHKk7eYZkjkLP+bc9Wy3U4VNRKqwSS68ogguqftkrhSEdqV0l8y8zqkpkR/PlbZdA+WLY2XpYfwJF/mZGo/cZ0cLSCFAkmED0L5/ATN0AZM+g7yyqxoOGIavjfDOoIggtE5J6mlp3W+TTeoMkT9ltYdQKLFEsVhVrQiStB2EgyUTyzUMpk1CB2a1CH0G0NZhng+S88ttnxgdC5kU/DiAL+QeG3vgxpGeC697EFJeWtNJAl7WNxvJsX1gVd8sTTIQgjCqe0hdRzZmaN6pWT8MR22JjI1vG9369TokWG8sDD92xw4Al3WfcmmvQeG3g/BeAGeA+W0AzGYndwBpEs1Qr/v51f3wNJVR6Yy9Aiy24ZYPheFVFAPyOsWxL7prDdLak8wdkMpwkPPJnOGxYia7+67fFdzqcl7yKZVCJpFnbH6bjPvjqr8ZAoBBBEsLQOjUSjcfuaQKy7C7CAAA6YWskZ/v3a22BMHuPRLwtBqYROrKMMSzuO46glKAlJPOyKDjQdxerVLRTzDTLF9tnq7oU6KuFqFPN/r7pZTG5eXYvJkZTjIJOxYHCXHF4g984aZdP/zKUG47BXW3ZHlJre3o2rE8Mq+/I4oRqtx27tnEE6z1Y1rZ37O0enj//TcclOVEx574txEAPwPws961/d0y3H4cS3EBMTYyeHmzEHte6RzIJnORLZmrVNGVNKE7XinUdCY0Cc6XwxTZhC61dqVR7avhM+zG7M0r7zCU8aNGand/rFxpPLMd+1IxXEIXblPSrlQttIbWnFoL5JXQiTx/A1eXbnv7DBAAx30uSYOFhlJeEglid52gPVU8POJijLYF5eub8LfYXKDEAINOwRRuUtJpLse46QuH5PYWoU8zDpv/nrcJEqeU2z4+OuZ7niwQou3jAL6c28YYws95rn4NECtqMcdUjPnovvqkNc0BCQkZLFyJKhfsGgR3aqW32LZzx97Qyy/jPw48dXq1GNm+ZQzAVgBbZ6378N8I0zyNpbiUQO9hxqxSiX0aCpTze8punkHmIm0z98ncSdUFT9cS11RAQvfTojBDcrZn+yQizZKGPW/yVO5z5DAmZfdJnzAPOOdXj6z9eDHfzp9J7uw7rKWlZNbaPSF5kjRraNbw077ml9C9BVHG/B1F0CCYBAilPHW+e0wTAKUBAQhoQFPKrk6ENxauWjn24pFbCLiQoRTlSukEnDgVims2xzidN1ay9mBGuEXo04xg0LwIVF66VieZhBNzo9WIQELg4ws2fOHWvQ9+ZSCz3RtbNyf6Ltr8PUB8qRZSOisHiWkicwCQwbay6p0zQzH0S3CcbyWU/f3999+wr57zurcf8vj29WYoGu7UIRm2HWexNNArZSDksJpPmrvBCBKJrOeISStiJDXRmBAYgOa41moMUuyOJZ24o+xxYL911JYX6173dnjb3eMAfgTggZ4Tr+wzguICZnwYwFFEpStczQwmO5r5Odp98tTC9eqGn6tdSgjThONVUxNGZh1zCWkaBW3ovoTunSHl5Z1/amkiZyEy5iNS3ub+/FMjZF5OoWEzGqRt1f5P3zHPG8A1+gPClZApo7/vqOafJ+2ohoI2dBC590sIQHke8lKBlIJWAkJ5zoFKwX8laACkOGX+IPJt6uKVJV1LFABsuk7Q5i9ls9kzG9Z1KeCwqerQkpYDI9wchD5dEjoRWrXophXrNxlCmheXo/1kZiRGc/OEi8WBcOiTyJNoRlv6e0aQ/xdAnVOZolYOkmP7624zz4QMFi87ycwOa34OyvlGTMf/a/D+r9a0ZuwmQPT3r2/rNOU8aZqHEIwjGXwkgZaDaTG3Yy4ROkwjYBJDgEAmSTAV0OF64UKuapIYAiyloTWz6gwZCXBokNExvOvKFa+D+U2t+RXFeMl07B3SxPD87z4UJ9S8JKoefebONwB8DSf1/8sss/NUCf4zBp0J5q5GVclnkWKmV7uncicpsWzloTjyyFVob2/3CAYARDo2mwgkCCHTLOqgRFkibG5DV9Xve4T7GeicjEQ26Rrq/nkrvchMKZ1TDmiCNaR2f4J0OvZba4DcoG8xacZe/zTF+8NOwhFLF2Lx7J4sm31q8ZDxt1YKO3bswvPPvYDERBRaeA5yvkMeAzDkKzhyNQZ+N5Df7Y+xnJm7pxoNkLQdtIeDUxpjuqCnS+XektCnF4cfveQYQaKs3MVOMgk7nh0iRgSClJ9aeMG1d+Z6vO+8f/Mfl1143Y9oCs5xrBWS4wMlc7LXEiQNSDP/g8kMBVa/Ucr5B+yN3Lfz6ZsnJdepBpsAcekl62cFZfthhqATQbSOwGuIaAmADhRgtyxnZqDcqBvyzKCSiEwAIRB6PEXKCSByi4ExM4zgmAJ277ry/Jd3Mj8Hxc85ZL8oE5G9S7c8XZNrBwA8vSU+7OY1eHjWyVesFlJ+lIEPgnlxQxG7d8Oz7OoZGeEgBNYccxROPe2dEGWqXwtK6JmnTP2WIdISwQgE0Le8DyQlmASUcOO+szKzZcy7fHD+Pz1NATMjHotjZHgYdizuLhR1hiqOubha17vAQlFr7aEg2kPlkePChfOxZMki/OiHD8CKx6GJINMx+SykfG2i4y06bX0Y+Qsly9W1cHFJ2nbTOMYpXft6D4XQIvRphGkY/eU6wyXGIwXUfjTbFKFrgU0fBzZnflPY0fY/GUJeTFT558rMbrU0q3a8UQ5koC2LGDnlEspvam19dWIs+W8j//N3Uy5p9sj69cbKJcHlgHE6CXG2EDiOCYuIEfC8fqZ6iinBI9IeAD0ErAbRBSCoAIkxbg++sePyjduh8ailk8/G7V1v1khdz8NPfud3AD43610f/X9E9BFi/jMGlmXMqQHgieeUXkixIJjBIN5x4lq39OcUpKCshwg+H2cqsl2yDnZ24syz3z0jtlutNcYiUbzw+z/iN799CZxIAIpApN1kOL4fQAEw2L3OGkiLCxYtwMpVK/Hi87+Fn2DHe4SUKc1d8/eFaY/VSak0cBl2dBY40rWVTA2W0zyV16bLhg5QrEXo04TV/ZsCUsqychcr24YdjeU95i4IxGWLLxD37LoPj2Qe2/XD65/pu+j6nxOJsyqZGzPDjo3BSdRUk10WZLAt9VB6XuujrJ1bkpGJm/c9dNP+qYzN69cbf1waODwA82wp6QIicTSY2/0T1sIhua4gSIBmEWGWlPR2SPxpiEOxUGDFH3ZeeehWVnjISehf3bnlv/dvnqKK3gt/u6Fz7SW3BtvCH4Wgq5l5ReOQuoeM6XR1dyIYDE6Zo/Kvm1P/ufZyT8VfzLxeTxAJ9HR14tTjj8GyxQvw0NankBgfBxzHm6VK83mW6j+NgollqsCcuXMyJ+f+ADvBsFn0mWXNh9ViDkozbKURLMP3ZibBzG59gOk4F1i1CH2aQIsWH0NCHFqqHTMjGZko+tYgQtgQ8qsLN246bc+PN2cyP0M7fw8ReDeAskoSMTOUFYc9UbL0du1BAtIMefOAAquHbcv+6933X/9rTEEvt+uSjXOU1OfvkvKSMPEJBOpKrRoajJ8qBBFRO4BjCHQMDP5z0S73/dkV5z/zJ1r9WNl66yH//pM3MYV7F9l+z2AE+Pv2dX96VyigrwLwKQALG47YASQTSWjFkDV6i6XMKETIShjjOd/pIpXapg+EpQvn4+zTT8H9P/m5K6k7jmuYyJpcpgmAUubwWn2KiUSGOTDldE/xUG9vUW0agxbVZgaAZTsImo1PYdMmoRPijX83DhAII7ARoJL3m7WGNVFGrnSitWZI/CVcB7nUN+atN/c82rd8ycMk5Iay1PvKgTU+iClwQNWQgRBAglnrvUo7X9o5jO9h6/VV5Za9tx/yJOOcIykgPwqifoOMhWB2vaEOWJBBhMVEuEAI4wNS8tiuK87fpjXfl7Stn/xKPbT74i2oKpwvuu3b+6LAV2at+/B3RTDwGQb92cw5z6UlS/Jd1ZkxEZnAa6+9gRUrD50SU+VV16ck9IzkNVQ4Oc30grB43lwc//Zj8NQzv4Tpp2uFzpLSM5Xwvr9bLaaeSCTwysuvpgb0LehEnOheOGdi3/w4nxAGY7fXwVO3P3/W0e1RYEmtbl/CstERDja02p3Zr1o3HWip3KcH6zcZUtC5pQiWmWFNRMGqtIrGHUv+76UXbPr5jvs2P5Y6sP1WW/V98f8aQr4bKB4ex8xIjg9OW3haLmQgrFirnyqt/mLXDze/Us0Yv1y71py/et47SchPCSHOyVSpN7k0XgncEGCiXhDOkYLOCsvgyCl8/tadl6l7Oan+Z+mWn1aVu3542907AfxlzylXfU9K/A2Y3zu94W6p+l6u1KAUokoAACAASURBVOwRCLEbc/34o09CE6GvbwnkJNs2Zf0qfG/sQqA8fxAA8sjcD02ryXVNEUQ4atVKvPDKHxEdGnLTvbpG8qw2mSF0heatmb0EMZnIF7AOjI9H8PSTT2N0aDgV6pd23qP4mrXHJnYgv9ZdW8LUIbRXdqGFYTVBghnNPH1e7sB4i9CnASvXLFoGEmtKNvTV7WWCiDqENP9lwYYvrM+MTd/1w+uf6bvwuu9DyCsKLSKYGXZ0FNqeXic4AGDXWj7BjC/r3SPf2FWF9zqvX2+8tTR0ohTmXxPh3QQEAdBBROLFIIhoNggXCpLvZ0Pu3HH5efezxXct7dr3PN26vdKYRB594vbnsXbtpbPDx2yExPVgHDH9CWr8ECovOxozEtEofv7Tn6OzpxsiHIYjBFh6MdWpLHECgUAA5687FqHAZEvUpPctUcZO1wFP+9npZsiGng8B08DhKw/BtpFRSKGzJ+b7pWQ8Dpz6Lxsv79iLX/3hDa84jZr0k5SCqTVIKURGx2An4qmwOpfUU26LEyMJizvQx49uG8BpOeeJhdtmE6O9VrevGRzjpst+DgDEPNoi9GlAWBpnEImSUo2dTEJZlTkvE9HqQHv4m+jf9GFs2ex3ZkvFNgdF+zmAWJCvn7YTXk3zGcErDtsfG3zgq49W2pEB8eZlZx+7W5pfNEicSwQTje3aNrMgkgQsk1JewyH+2O7komfeumL+nWaMf7xwy4MDpQfIwPbt9hC2/7D7lEu3GhT+PAifBKOrFsmM8oJT5l/4WdH8MC5i7eYO1xqsHIyPjoEjE7Ckn/JVeoll3N+DwSCU5gKZ4nxkeLanCNFTuZMASEBzI6jcfRD6Fi7ENuMFKK0gmd1iMu6h3OiRgvOOJpIYGBkFlFc+NvOncmAqBcMrJ5smej9GPi2hA4i2z01ydOBFzD0SjN9lnycA7rIIIRRK31AhmF1SDwUa1zFOqWn8shAPNe6dOIAgDOPsctTtyfHq6oyTEBf0sfEFZBDb3v+88Q1W+gbmyTZU1hpWZAjTrTxkZtbMT9lsbxh9/LsVk/nv+09fvPPy875umsGfk6D3ESGAFpmXDSIKkKB3GcL4tu4wntp5xcbrX//QOcsrHWfsiX8bGXr8tmuVwxsBfpbrbSTk7A85JRFmkomfi90vg5ran/47lf40d0v9lwd+jDWlw+YaaQuFQyApU1XV0h7uvqo9m9Tzj+OxveZ01TmvlKz0tvS95JR0PimjHhPjDaB35FAGgNwscUlHyXSO3NogaU1fAqxqoPT0ZaRmiIEWodcZ8z/y9+0k6NRS7Vhr2LH8oWqlQCAhSHyh78LNf5q5/6344K3M/HPOKPfjqtpHoOtaCnUyvJf+T5LM7x977LuvV9L39fXrQ29dft5VHe3tT0ohPkVA98FkIK8DBIFWCqJrgyHzlzsvP+9fd3z43DWMilToPPLk7U8MqsEzmfEVANWtRss/nbt55Our3d1DadWv8DKrZZE6fOck5N/ynS4j9CvNQanwyoJbwrYRSSQRiScRiScytjgm/C3mbRn7IvF4um0iActxis/Z20i4OaF1ZqY6b+OctS4XmLt7QGfc4/QmJ5G3f685Z2EFEHF03/x4wcWdlKKj1iu/hN3YdnSnDH+o2oH3tlTudcbs3lnHEYlZpdolJ6KFpYRyQAiSkF9b8oFNQzt/uPk+AMCD/5i0N37h04Fw+xMAzQYAbSdhx8erP0+VYKLfJRKxj0a33VORmve1y85ZZUrjJinE2VxmKF4LZcI1Ps4WUn6MBX9w9xXn/+drln3zoff85AWUq7558v7IEPDFWadduVWw/H9EOKKuc84CZ//uE0/u8RSplx7F/zvfarGYIO/jqd+/jj/u3OOpppVbxMQrOZoizcwxfPL1Mt/5FePCoRDeftihOHzxgqI2Yje0PJ0ON8v+n2M/Lxm2lrO6Ic6S74t+I1xzSHFnSSGNuUrp2kroduOWUmVmOGr6JHTSvLslodcZhiFPA6jofXa926cu4BBRhzQD315yweYP+Pv2/PgrL2tHfR6A7YbEDU9t4VAdktD4bHTbPWUXU+H+fvnW5eddFZLmI4LovBaZ1xdE1EOEK4JB89GdV2z85lsf3FBJ5T49/OidD7Ntn8mM7zN4ZirfEXKk0skSqu91nLn5pAighHl3ct/czbIsJGIxJKJRJCYmkIhGkJiIID4RQXxiAonxCBKR9Bb3tsRExG0/EUUiGsXI6Cge/82LiCWtoudzH2XXLKCRaR7IL53nH8e/XZR9yyg37W6xOwMAuugzSoXq104BSulploIrg5quuTEzkdjRIvQ6QwhaX8p+riwLKlkbFTgBvYaU3+m7cPMVwCYBADuM396lHPUtJxFhbVcV5l012MV/DT1+2yPl9tnTv2HurnDsNkOKWyBoYUMuvw9EEBER9Qiij8k245kdl5+76dX+DXPL7T709F27BnfvvgJMf8VcWxV8iqi9+HBGhircsxkz3Apsk+zJ3pYyE+dseWT6QpNwz1FgHLc0uAYcG3Cc1Ea2DWnbCFgWgvbkzbQtCNt2+ymvr1KwkklEk3bR82n/nqTIOIfIM/7UKHL9fk56+LnpRcoZkEV+dX5q889Nwpy/L5w+43XXUc5cplQ4qsBH0rDha5p5+ggdAGvrrRah1xF9n/hmL4nixViYGVaBNK9Vg6iThPEvfRfKv8Taq01s2aLizsRfWdHRhzPt6dMBApKs+WsoMzXpWx857yjVLn8ihLgcZSTiaaEOICICzZHS+FJ7u/HYWx8570O/XLu2PA3JHx5MDj522z8oxocYvKsmDnMeLfikzgSPbDIIxq9+lqqPniYm//dCEyk1w0z7ccnL8TzDXWK2YXgkHrAtSI+4hW1BWBaEt8+wbQQcG6ZjA7bt9Xc35hKPDef8mqVm96zcqUxxBebuZcJL3Sv//kkJJ1VzXqRJ38ulnxkU4J6P27AcGOl9jQBgE/426zQCIlr8YqpDskHt6FrraYtBZ1BUO2KwReh1RFcouAKgkhJOzQkdABHCJOWX+5Yv/e7cczctGLz/q5HYhHUFiLfX3Ss5eyaPDz1xx7OlWm0CxK7Lz33f/2fvvePkqs7z8ec9596Z2b6rXTUQKiCK1SiiSTYgYhuQjHGcXxQ7NBvs4ATbgO0kTpwYWZjkm8RxnLiDTbETxzEy4AIGCWNEEUII0QyiC3UJadvs9Ln3nPf3xy1zp8/uzs4uZp/P526ZOffeMzN37nPe9rxSit8J0MmTVvmEgADoBMOQP5m5aOadb1yyqrqWggMeePSWezM23gvgmRFfbxTgK5c8PEvRtxgDRKSlBEvplqzJQB26BAlHdKZaUlxhop1fZ+0OrJakBq0dMrZtmLYFU9kg291UzmpH4G9SNoRtw7CdEjGHzN3ysHJzDszdX+igeNHChb9LzRnkE7jXP97/2zCgpAHtP5dbIOng5+B8Xdv278lKYAEOvzi16PurxygUk8na1Rda44CGxs/Bb+mkmBSWGUtkU9kDhhnqI9C0cmPsTAbaGpvSCwIEhPizSJgX9pxz5TW9D9+6Ubzn8kvC0vglgBPG5KQBMDNr8C2o4slUAO2+eOWnII1/I3DLZAb7BILzSQgiujBiyGV7Lr/wRqT6bq6lnWts062vqLMuvbCZQj9g5lWjl411Xet5RCLQM3Mm5h47H2ZTc4DwBeCKwQAEIQUMaZR0ExVyQVGJHDOEy+YaVVxNrAGlIL3abWU7iXHaS47L71HOJPwJEACDCEoLR5BE65xbvQzK1ZaXsta1r0+fj1nTerAiEgksYAIJhu4mmMHKxqEDB7Hr1Vdgp9NuD3j2FxQEhA9vfaVZrlRDpdqnssWD9ZYiIrC2bTXIjCkT7a5hWQ0kdKLdyzY/npkk9DHEq9//q32LP3fbrRQKfbFcHH0srPN8MFnJ6EICft191pW3KkVfV2R9RJLxcwDzx1Kbm4BeKeL3Vhv3zKpli8x48j+6Q+2RScN8goKIiNAjmb6um3s+sOuSldfN+cl926vtlnz0fw5EzrjkYoqE/xPA5QQMs/dooEDKs9LhEjYRZh87H2ecdRZMs7aIQClDriQnBgbmBFQ0wFTZRa81hFIwg1nurhiL0G5JXXA4MTRyrmyvll6zWzvPpedcce5F8Cz40jt0Njejs7m5piPNmzcPR846EpseeABKZ5zPxovhM5qSg9FWACXLaGy2BggGc8X0uhrBzBC0RxB9XQp+Wmn1WyGM2pq6NwiW3cAadObXCNCTLvcxRjYa/xaDS4obO21Lx1Z6VdtZqHScAGohwmcMkzcJMlcD+GsivDiW7nfNuOfwxnVVk6MU06UZ246k09kJ6TqbRAAEKQS93zCNB/de/oGPPbRiRVWjoH/LT4b6dumrwfwtZozKHZVLwAKkaeKk00+HYZhVXeFVXeX+yyu4/jwLVTvWtebKteGkNQxXLtUvVWP2ydxbHHi13YLz1dbyar7ZFcOpZe5VFsIM534z2veJQThi9mwcOW+en4iXc/kjnE4mOqe/1UQHXm3LTUgpAgAphC6oKxwpYgL4LwPq3ct+8/g3Y3HzCQI9W4fj1g3MDKtRyXrMTOCXgOEJSUxiBHjl1s/u11b2W1wiGc3OZsfM3Q64F1VA3tUxsuhIAv8DEd3CjGwgaljvczPAv6w27qmlS5sJ+BAADCVSk4T+NgERzRBS3HTs7JZvH77yourZyztvT/f2xr7IzF9jjKADXAm+am3vQKSpuXIWeA1b7pJz/2AnMu39zhGvdku/ym3OWKl1HikTF0e3K9Fv8BtZ+XxlrPcSZWvA6N6j/HMSeqZPL/Fi2MiqTNmcITI5BlCmwkuvAtYEPCSFfv/69Zu/cOZ9W/YCwLkbN9oA1k2km4dTg964DHel9IvAJKE3BPH4oW9rrV4pvN7G3jrPQGWKXfqum72HiE4ZqwYbBOrLJtObqo1TPZGlTDQfcJJIEqnMRPpeTqIiKCyEuCqj9f37Lr3g+KrDt6/L9j0au541/+uwLfUSl4RtWXXpNe0buVzwoM+m2nWZ67IubqUUdu7eg0P79/tWuce2hfuwtxUKwsDTjUcum7zKyyv5fAk/fTXX/XBhlZZcFZy1jiy7z2CyFyMpZ3RuCPsl86ez6f2rlv3miS1rC1ILNKy7GBjFYqG+aKS7HaCMgH4ZmCT0hmDHzX8Xte3sWhD5PhhmhpUaO0J33PlDqDXKVvfzg7fGtv20r+pA0h8MxlXjyXRdbtKTaBCISICWkWGu33vJhe+tvsM61Zc0vsKs/30kAjS5fuhAIjaEgwcO+IlqI93yrrY8X3bOUidXTpYL9lXMONzXh989+ig2PfYo0vF4bmEQrIEnR55Vi8DmPsZeiZ2XPS4C5WGgqvP3510FhXMf6Za1LOx5c4fngw960cm2eO5b01M887hYbkJuP/T2ZsoCGG7pmiJBdxlKrVi2/onvn7txZ0khjdv+e8MuAj8xzGOPGbINLKVj8MHeHQOHgElCbxhefGbPz5Vt+wli2lZ1E5MpBVYWVGZMyj6rn5uZQfgtqqwmXliwICRInB98TGmNWHLS9f62AhGBaA6FxJ27L111xR2rV1dOfNt2s9X3aPzLYHyLuZo+geeuZv9q8vqhQ2tse+wRHNy/H7ZtO3W/WkNrhtYMFdi05ooxZN+9HjhvboD2/c2em1szIxaPY8tTT2H9g7/FgX173Ux25OqzA6V1LAW0FFBCOpuU0NJ53Kv9ZiGgpPO8V46nUS2mXQsCjWlKHKPwvfLeL2fT/qaURiKewFObHsPg4cPOQiegr++sGFRZhcETNzyfALC3tikzE+EtA3x1NvX4R898YMtrlYavBbRmvmMi3DiYuaGELggvrnr99QwATGa5Nwob19rW8d//G9HRerYQ1GVn0vX1gRXASsXG9PgVQaQtrTdWGxY/sm2OICwofDyRSqMlEoZpTl6ebycQ0CEN+d0zRXLmQytW/Jsb2yyDdap398f/vnu27ALz5bVVWwRi0uwQdGpoCJs2rEd7Tw9CrW1QUoJdQsz9FjBNE2eecDxCRvE15XFALhQcZHrvmZwbPZPNYOcbb2D7yy8hmUz5CfgAHGU2FrmGZ4IKLP6Cd4zIKa8TElpK2F4duEfqgfmVfktKP0coPp0ztHj8rsO9eH2fEyogN7zgeCScxD5yO67pbBaxvl6k4zF3TC4/wA0YgIFjBl+Oi4ejTeqc0jPeCeA95V+Q84KFEI8Ltq8+8/4tz1ccG4CdtO43WyJDBHTUus9YoZHqdcy8zft78o7ZQLx001++tuRzt62lkPkfVio9Zt4RrRRUeoybX1UEH47a8ZeqjSIp/gglrkFmIJpIorujbVJf5m0GIooYUqydP7ul/YXVC65ftG57eTfUztvTPP2SaygSns7M5xeROvsiZ77l6xG5T+qaoS0Lg4cOQff1wfL7oRuAYfgiKWY4Avu440o2BODgH0GC9P92T64V9u7ZjVdf+D2ig4PQRBBEvoa6hqNYJ4hBTM61y17DmGJzOijKoqSEJY0CYRyZ02cvAw3yX4EoULKHM+u8dIBSX6ehRBL7Dx7IidkoG7l+6Mrph+5m7vv90DmXrZ+3+NF8VN/WF1tO/PDCgcJ+6C5ecZc4pb/YzJYQuKVV0JeW3LtloMJLL8Jt6zbsuupjH9wMoguGs1+9YSvVUA13Jmz1/p10uTcYSTv2fW3b99mpzJiZzyoTBzewD28RNJ7C5nVVEwSI6Nxyz6UzFtJZayJ40CYxbJBhSPnX7c3H/Gs1ydj+LT8ZSqVTHwehvCXmudp9l3vA7c7a34idGm7Pyizs7c3M5TPFuZgMC+eQicfw1MaHMNTXB1/FDY6jXpEjO2sLCUtIWFLCNpzFhTJMdzOgvf9NZ7NNE1nTRNYwwYa7CDECCneolnFeUD4T+L7kQhXsz7Wk/rwbvij1nhlaQepACZ7XD90TgQ/6/Z2VV0802jcTANYWSL8CgCH42bLfaUZcCPH5TCr82SX3PjYsMnfOBw2Mv9u9ke52EFJk2895/04S+tig7L3h9W9dk0n291+jrOz+sTgxM8NOjad1DjCwudqYh1bAAGh5pTFD8eR4fzcnMUIwIA1B18xYNPP/cZVa9cSWn75lK3yMmct+J/Li6Bys14ZvIZJ26sVFgOSD7vPql1KAmbzBXPCYS+SeNrxyE9086VSW0idtywwha4aQCYWQCYWRCUeQDoWRCTv/Z80QLDMEFQoDZggwTECarnfBRGtbG5ojkeozDpTHFb1vnBtX7rvEeUH1IGlrSJ3LV3DZ34+dB13tgbcupC3lqFBef33RCR3yoSLGI6CfgI+fcd+m71QO1VRGJpv6DaO+jYGGA2ZGpnQFwFjhjea9Cb+L5aTLfQww/4qvXzKw67mH+n73432lnn/tts/vOOrDaz8tDOOnRGiq57m1lYa2x696w0mIq55tGjHOPBbgGZUqci1bIZ5Ko625adL1/vaEEEJct39Oq3poxYp/qHSjHnzs1ue63nPFp6Sgn4FQQbbMdX/n/Z/7lRc7znOhO0RUqoAij+dKkR4HfNVuCICJoNz4PIQASQPtHR1obW7OqaeVO54HL9BOgN/4xE2GC4XCeNec2ZBClpV3zb1GuO5v5JN68DvjJQSWOUTRI5wj6+JEQWehUCiR6/5BUPZSAHeVmu69G7buO++C5TsYCJY5DhD44uXrN6+v8Eprwq4Dqu/YObyTiGrtO1B3ZLKNjJ9j66LtubDWJKGPAcLtHSvNUMdqrPj4R7Dx9pJlFnvu1r+e/af2f4KML1KdPCUTwToHKJ5SeLnaKGnKUwCuev3FEmk0h8MwjGEqhk5iokCSoM/Pn93Sr4B/k6U5BQAw8Nht90455xP/Sow15fURyizsSj3sZZq7/yigJDlWjHYWtGj1SFd5XcikROeUbpxw3PGYOXV63a5TTx29WgWncq1qX54W8BcgeQI1cF9nqfVKqbNTHo3n1NrdX5z3eMHxNE4vN9+1gD6f+CFm8gg9ZRCuOvO+0ZM5ABw9q+VKQVSUaNso2LaC0o2LnxPhseBDky73emP1HdIwjRMi7Z0XTlHiBpR1N67Vet/gV4nVvYVhsBGDNexxKlXzQMCbybcOVK0/Z9ZLa1F0ZmZEJ13vo4ITO/bKtmpoAVp3kCGE+MqByz54aZWB3J8d+hqD7yuWJKa8X17sOqeKRn5LVR14zCcnypFa0RY8U2ABUPwyHA15TU6sXIbCWLhwMVYsPwuzZhwBaRgIOqNHs+ka6s+dkjbHHZ7Tmg+4z/2SPwdeo5fSdfiB99J97zQ5uQFFveVBfp913/+R93bxom3rtrWW+5AF6G4AisBaEP37afc9fme5scPBG5esWmwY4kYQjdvqP91IdzshrVltCT40Seh1xsyugTCRmN7cM0MIQddN1cd8GmXMir2bv5FKJGJXEesX6kHqdiblfKnHEcz8Il6/r7rPX9BJpXNui5HKZJHOTOq8jxRZy8aBvigO9EXx1sAQ+obiiMaTSGWysJVqCMkTUYQkvrn3spV/VHHg5nUpLczPgLA7t3OAdJyDueSa+xuCnLptzw0e6IPudWWrRJIFsy3wJ1OeS9yWAqHmZpxxxnIcf+zxEKbpLCTKHHsst6xlgZRykgGD2eYFn2fZxQzchZGggteZ80Tkid8E2tfmtbINfDxM1B3vjS5ac4Mo+f2OqvgmAm8H0Yshmf6XSl6bWrHvwqXNYVN8i6h6u+qxAjMjnR07bZES2NX/Wt8bwQcmCb3OaAmbLUQ0I9zajlBzqwngn3vO+sRHyo0//JuvHbRU9jJAHxgNqTPzOJequfMgeq7amF8tXdpMoLICFKUQjU+KzYwUhpSwbIW0ZSOZsTCUzKAvlsSB/iHsPTyIA/1RDMaTyGQt35IfCxBRp5DGrTsuXjWn0rjBB7+zC0yfZ8D2Z0KOFRiUS+U8ghHQwolr53p2B/+mPA9FvreC4amyFUw4n8RcghORJpx2+jJMnzbdTzYbr62/rw9kW24WetA6R34GuvdvqeMA+e+VyNXCa+Fk73PeQqmY1PNWQMykWJWtNT9/w/MJyfpaYv6bU+/ZVo92k8TdMz8vQGfX4VgjhtaMbANbpkLjMU9QxsNkDL3OCKvUXBJhCQCtM2ZhYMfLzQDf3H3WJ9J9j97yi1L77Lv7q8/N+uM1lxim+QuARiSKwFpBWWOrDV91DsysVYXyIxfd08NTAe6plBBXCFspxBIptLc2TybIDRNCEEKmRLpEso5mRjprI521MRBPIWRItDaF0RIJwZCy/u810ZyQKW5/+aJ3X3TCrzbFyg3rm37eL3sOrb+NQZ9Enr8951r3CKi5qxvT5sxDqLXNEZJxLU3/tyAIISCkUTqGzsHDB1zu/p85QlNSYvGSk9HdPbVqfHusobTC7jdfd/queyVnPoMLP7ENcBP0gZK28NQp3Vi8YJGbKa9z7no/e97tNJfNYPCtg+jds8sP45Cb7U8EgMmXCwBw7sP4yteB60sy3JnrtzxUr/dh96UfeI8Q4osYzg1lDJBpZJktM2uNoryDSUKvM0So2W9O0Nw9FbF9u2BnUm0Abu0+6wrue/S2kh3I9v5i7cbZf7zmKjLNW4moZbjnVZlk5YzaBoCAtNJUUaIRAMJaHaVH0Ls4nkqjKRJCqMbe15NwQESIhMyShF6IrK3QH0simkihORJCe3MEIcOoK7ELonNaOru+rIAvlnW3LniRIylzbSqhzgUwP5cN7u7gWoZdRx6Fhe8+B6FIbcUipdjFa7mS8wbkJ4V5rnYtBDqmTseRs2aPoF1cncGM3W/uQPzQWzkyzwu3BUrK4Lw2FczWD6CtpQVtLbXdcmYdewL2v/EaXn3iUbDXrMYldUf4x/2tcfL2x/Z1AyjZOrpeeGH1+VOEFN8GUDZm3wgwM1JjKOVdCAIlslTc/GrS5V538HHeXyQNtM6c5fxN6CIhftR91hUfQpmV5O5frF2nlfUZZh6Wqc3MJbuqNRpM1DcUHTpYbZwmYw5GcO0xA4Ox5GTzlhGgKRQa1nilGbFkBvv7ojgcjSNr2fWzPohICHHt3stWXlhp2PylH3lLGMaXuLBu2XWPkzRw7GnLYISbRtcSNHfgfFJHLqbMRLCFxOyj5zsegtGcb5Sb0oz9e3bj9We3gWzbVXDTuTp5Bgp97X4MfZTnZhKYccxx6D5qDvKy4Yvi6DxVa3HqyC6Q2qAA6oyYNwrCuJWoedC6sfXnDN727vXbiu61k4ReZ5Ap/aQMIkLLtJkwIk5ZLQEdJMSPus/+xOUoU/Gx5661P2KlPjcsUmc97u52Zx7Yhe3rqgbyNevZGKF7LGvZSKTSk/H0YSJsSogRWNnMQDzlEHt/LAFb6bq890QIGdL45u6Pvv+IUs+vcVXG5q889x4i8evgjs5voKm9HU0t1VuxVwP7PmPkW+eB2LkWAiIUwpTuqRgvzy4zI5VK4uXnn8ZLT24CZ9IBMtc5Uvdi54WJcfVbj6Fz+szA21D8fhBArPUHAABKjckbtu/SlR8iKT4xEWJwXv5JQ8DMzHxvKe/WJKHXGzpnoQOAkAbaj5rn/09AhwB/r+fsKz9fpqSNd9+lf8BaXctcW6tBlR3bRi+1gqFfqWWcJJo5mvMMJVJ+dvYkagMRITyKZjeaGdFEGgf6BpFI16dnPQFzRCj8L3esRlGZkScbOmvWAhXpbruBCf0A8q5zrVRdLF4/h6wosz1H7JoIMhSGNMyaLGhbKdi2s1mBLWvZyGSzyGSzSGezSKbSSKRSSKRSiCeTiMVi/jY0NIRoNIpodBD79+3FC88+hS0PrseBl7cDmUxAW13lk7lfJY4Cpbg6eglUvnu/zOd7Ad57w7BDa7Vg7yUrZ0lpfIOopDx/Q8HMSGYaJ+bFoAxDl6zbn4yh1xkkZVfhY81TpiLZ1YP0QK87iJoA/MtUffTR6owj/75/y0+G8vdYq3ffiR8e9eE1Oc/7pgAAIABJREFUMWGYNxFRe6VzjnftuQdiqioo42JUpSXMjMFYAt2d7eObBfM2AhGhKWwiNUq3oKU0Dg3G0RrJoqutBYYUIzeQiIgkfXRZ04V3A/fcXfj01IWHGZiKk9931qtb7rr/e7atvwSAvGStdGwIg32H0TF1+qheU77L3XGv+4pr5CXhCUi3WUq1V/v6nl3Yf2C/2+REO30VXMJlrcGsfLe4VtrnQ2ad68HgJ6S5SWlKQ2rlSNt6VnlAX92bL7sNYQrhJ8XVAVrZ6N39ZkFGPfJ/A2Dw3Cl88OR+KatKQQ8HD61YYbAhvykIrt9/fKG1bqi7ncDbk+mm7aWem7TQ64mrrjLBPK/wYRICnXPmQ5q5xSoBBoP+ksLhOzqXXzynxNF4z91r/4+z2UuZ+a1yJW3MDJ0tKUbXcDD41VrGaWDKaM+VydpIJidd78NBJFQ/YyaezuJAfxTJUeoDEGCSoH99Y/X78qs7XB3wroE09xzXpqfOmX0ziHZ6JCLcePHrTzyK2EC/08N7pBane0pGwEoP1Fh7YjXs1ZpXOV4mnUY6mUA6kUA6HkPG34aQjQ/Bisdhx2Ow43FwMgFOJcCpOCidhMhkIDNpGJkMzGwGoYyzmVYW0rJAtp3rhqYVSDna9cIXkSlws5P7LqMeMXRGNpvFzue2IXboYEBP35XDKSB1AhFgrx7xxVEG82e1XCmFuGgiuNoBRyejYbchR3j/nnIyypMWeh0xPXVsSHSJkkE9I9KEtlnzMPhmzoglggDjPNNsenDKWVd8uv/R2zag4Bu5+5c3/Pqoi9ZcSCHjfwExnwoMBG1nwbqB3X3KgBlaK/uN6iMBovpkpA4lUgiHzMm+6TUiZEhIQVC6PncfW2m8NRBDR0sEXa3NEGJk9oEA5oebI38N4Mulnm9LzeKl78n2bdi3/xuZrPWfxBCkGSCN1EAfXnjgHrROn4lwWwe0lLlmKSRdrXWCkCbmzp4LQxZfK5qRI/AC2VNfOMXdVDFnFoG9FqQqQL5Kg7QjACO0R4CuWxwotqq954K15RxMfHOb0VSYDAeyzxlw5l4CfYMD6Os75Fv85DdoyfVCJ2bY6RTih99CJjoAuH3Sg6SOEosKwfhjnPfXX8aGf6+LG3HHn1+wREjxT0BxmGY8wMxIpBraO8OGtu8o9+TknbCO6GxtmQWUbrZCRCAZgtncASsZDT5OAI6Rgu7sOeuKr0PTv/duujWvPnfPr9Y+Ne1P1lzQJIxbGOKcIKmr7ARIhgMAcNzO2FUz3AGAmVrrsbbWzBiMO673kSR8vdPgxNFNJOtcXhNNpJG1FHo6WmGORMuciATor9788/N+Mu+nG16GlAylaMGLq/lhbOSpXRFGpE3PPXHxHa9ufeZTYL2QGBAajjxpOoXo3l1gIcGGgayU0F4/dOm0IpXhCGYdORuixPTyosGeRZtTPXN6jntyqFzdx8t+K1I3vq0UpNtTXOgCRTegTP4L57LV/SS3fPGY4k7p+UI43vy9UIKzcCk+01BsCPt27XD7oSv/Nykbpjv3vOQ75br+OdgTHSUXOkyY3ZXpP3sAuK/K21YVBy87r0VL479A1DPaY9ULWcuGZTe0iPH3S9dvLeluByZd7nVFKNwyBWUWScwMlbVgtnZBhks1k6IWkPhHSLq3591XnoqCr96hu9buiNr2h1nZNwOwvGNOFHc7gXpjaItWHwkQcd2uu0zWRmLS9V4TvDj6WCCVtXCgP+q6H0fyWfAUMxT+ogpc92vxFUxdeJi7BtLcksjwcSfMjpuh0HcA1oIZQjOEcslTKZBWINtGSCkIZTvEFCApRjmlOMAjQ3Y1zD1+8tXQAl/HWhTc8snchqlsCHeOfhKb93deu9dg21edI/uS72lunhoEnSff6gjhaF/ZzUuMKzFXl6R9Mlc2hG0jZNuQfllc7nmhtbMwCSTiBdvbOh4H/10VkulSVF8HVYUS4S8AdM5oj1MvNNw6dy7W/60klTtJ6HWFfXxJ5Qa45GtZIBIIt0+FMIv7HBNBEOEsGHig5+wr17Sdfnl38PnBX6wd3N2vP6Nt+7PM3AsGj2er1CCYsA/bbh4X3/9QIgXLHv+ww9sBkTEMT3gu+ERqBFnwRCSIPrLn0vNP9h+7/npe8OJqfnV/jBMtU3U60qbnzZ97lwC9RG7fc6FVSVI3PavSI3btadajxJabq3Y14vMlZuEQIhF02WMEk8xdt7h2eoobvns612s8Z3XX+v7kvVdO5r0gaBHQrw9sXqmd9mRvgbJz9xcXHpkrGyHbgrBtkB86cMlcaXdh4rrbfY+Dl1HPha+JAF7VvezykuWJtWL3xavOJkF/M1Hi5gCgdePFZKxM6ueVxkwSeh1Bhphb7jlt244rDgAJiXDHVAijtNgHgToB+nIkYv6u5+wrL8orb9u41t5915qbtcqs0nbqGa3LRcYaDObdqPn2RHVlX2bG4FACulFtC9/GMA0Dhhy7r71mxuFoHEOJEWjvE5oMaThWupQM5Kz0w1MPa6BdzX736UNSiO+Bmcm1FKVWTua3ckldKQjbsYp9y1Nrp9wKJTb2VOhySXAemfvNS1weUeWOEdh8fXjWkJ5bOuhCH8Yb4jO5Z3kXatR7m/R+S7CUvu68N95zuZear/Y8Cj6ZO1Y5eR4O92+pVC7TPhBDd8jci6GXRAeZxkeH8cLzsGf1+VNkSH4T46wGFwQzI1mn8s1aT6iJH1z+u2f2VBo2Sej1AwkSJxUmrXlQVn5ZgxAGwp0zUE4BlQiCwYsB+nmPOubXU865clmA2HnPXV/dmjiw81xm/DMDseJ2k40FM3bVPri2+vrhIGurkZHIOwxEGFU9ei1gAH2xJPpjw297K4S48MDFq070H7j+el734os89XCO1Lvnv+v/SGMvuRYwaQ2ptBPrtR1iIqUgC0i9bB06kBd7ViTczSlXC7ZidSzdypvD2wVxbv9tKNCND7jIi7bCZilSOjkBhnTyA4KbNMCGCZYGtGEga5hQbv6AR+rlstzB7FrfLpkHLHOybUhbwVAKMmid60CGe5DM8z5u5x8nT4iuwoqPF7slq0ABRE3GPxOwZLj7jiWYGfFUA8OdBBZa30pVqg8nCb1OWPC5H3ZByDPLPa8K6xSJIKSBcOe0ku53ZwgREUwSuEACD/Tw0T/uPuvy04HVEgD6t/xkqO+RW74MpS4C6GnmupWaDhskULUHugcG1xRrHy7iyTTSjWyQ8DYEEaGpjuVrlRBNpNA3FB+mVC81kyGuDlrpnuvdI/XF56yICUm3gpl9t69rNYpAQhppBcMles9CL9lC1GH0EqVqItdb3eXhsscIbMHrL8fjgWQ1n6QDLnLPsq5pM/I3w4Q2TWjDgGUYyEoDWroLAO/4nlxtuflq7YQptNvoRSm39t0Ja1AgZh4kcs/NXo7Mcx8rjpmixAeGcSEAAPZdvuoikvLKieRq93Tb88V1xvqc2BHSyQerjZsk9DpBGqFPEmhaqee8+HkpCGkg0jm9TKJcENQCxkcFmQ9NPaft/3rOufJcd8XLvY/dvtEW6n0A38CM/nGx1oeV6Mm9YzWNwaEE1KTrvSLqWY9eDUPJjEvqw/hMBP7s4EfPc5ogeK7363XOUn/xsBat5n8DHM0TX3Hj6tIndYfYDZfcnaS44hgySQkSAkFS92rPcxnjwcSyKjH0gJvcE6phn8iFk43vkrg2DChpQEkJ2zBgGaa/Zc3atoyR22zDBHtWu2fZkwAJUX7u2ln0CO0I2HghiiCRezkAnmWeV6pWlAuQ+4dyv4UQdC0WrK65qcAbq983Wwr5X8Q84aqx4snGJiMT40cnbni+qmdzwr1Rb0e865ofLjKI/r6cux0AlFUubExuTH0asrF+2KmhMuP8ErdmgP4UzBf1sNyCs674MWDd27vx9oMA1nYu//gvTUNcD2AVgDGRXRwtiMT+sTq20hqDQwl0d7ZNpEX9hIJhSBhSwG6QhRFzM4G721tqqlUnEh3aNC8H8E8A4JWx4frreR3Aa14UFJv26u5d0afuZcbF7OahAxrQnjebwFqDyLHatW3DsizIULE3zAw3oefIueg/sBusbEBpaNvyJuNb6AyqyQXmOpoB5Cx9Z71AEEIWeAFyCwemAP0FfhW8OyUfIpBzvedtzgLCCEXQPX2WU35XNFlGJplwFz05TXivLK2w1tyrmfePVGQ6FJO59y8BM9s70DoEV8a3Ap5autQMNzV9g4DZE+2LnMpkG1uqxhzN2Jkf1zJ0ktBHiUXX/mC6EQnfCojyfcyZoVXlPDAigVBbN4QRQjbej/xWiKXGUwjAWQzxbiC0r+ecT6zXzOuQyTxx+FD/n3fPPPICIvVlQJwMMNEYfylYUs3XEiu1i+TY6UKksxbiyTRamyMT7V4wIUBwrPR4A0tuYqkMCMCUGkkdkj72wuoFX1u0bruTRuy535WitddrXnPDVepbbzz9I1Lqo8QkGciRjVvSprQGhGu5W1mkY0MIN5fQfSKBWccuxPTZx4C1RiadxOtPPlw4CO7ha1MF85LshIANhmCBlp4ZOGrxaf7zOeIvOs0IUH5HaZowDLPsvDPRgUCowrHCS5K5514veZyi1Pai02jFfzu0eV1VMgeAaQumf0JIKtuZcrzAzIglGqn9wQzgruW/3VYxGc7DJKGPAsd/5pYjjLD5PwRxaiXrnJnBNVhDRASzuQ3CDCM71ItaStKIIAA6CsAnBeEKCod3dR8xYyMT369JfFxoPoeAq5lxwlgSOzFXixnkxgKvOysWGrOQz1AiiZBpINxA9/LbBV4cvZGEDgBDqQxAhO72lqoLLUHimPbIvHOB7flNKDwXvFKY+94Zj8Z432sgPoHge4AdQiINrR0rHaQgFGFo/y60TjuiNEUQQbo91YuX3rkYugJQRoXZh3aPB0EAE7SQ0MzQZgiyZXwStR17snje2UQc1kBvoC4+P4M9P/ENJci8KpGDnRjgTX2P3fqLWua65/ILlgghb8QEUYMLIpVusHUOpLRS36lUex7EZAx9hFj42e+fGGkyf0UkV1QicwDQStW4rAcAgjTDiHTNgNncgeEsUAkkQXS0IHGlAP/UYDwkiC4B4zmAXyj1dawfqKXWkcz6DQBjyibMwMBQvKGJK28nhE1jXEyfoWQaA/East+ZSQi6uOzzUvLOB6/PEPgOcoPDnpyqH093Wp+5VqdCYt8upOPRqjFwf26FcyRUqGUvtN6DCXBuOZkQNZy7kRuj/81XgEAbVuHmIRCzn7Lv3TXy7x75gfN86Z3gx8gM0NO2Tn8lb4cyeO6y81pIGN+kOvR7qDe01oglG2idMzNrPLB7w5Zna91lktCHiQVXf6d1yedvuy7U1PpbIeQp1cgcQE3WeSFISJitUxDpKl/aVnF/kATQA2AZET4KYDHyG0TWGzU3plYxeZAZb43hXAA4QieDsfhk1nsJmIaEMRKZ1jpgMJ6qXmLoCM2c/9KH39tddoyUrAjrmNlxy3NwY0d4hgMJcpk0Dv3+Kdi2XTVTnfLmxv5xtRtHr5jlHpCKDZafsVc6NhE2BmK9byH25itO7Nx3t3uCMez1nkOxm706kQcQZVv9VfSx/x2oPMzBFGH+rQCdPdFiZV7deWOtc7Jtjf/4s2GkHE8Seo2YftnXWhZde+tHQq1tD0rT/DoJ6iEC5ctHloZWI7sIiAgy1IRI10yEWqeASglR13ggDyM7QC3gorax5bB88+YUgV8au7nkkMpYiCcn69MLQURjqhpXDf2xZHVFOaKpra2RcyodZ2DqrFcBPJMrnwpa6m4cWGnfUs8c3Ive32+FsqyK1qvwk8Ty5zdsCz1vG2+LPGeZJ/sP49DTjwPZbJ6rXXiWeWARk3/TYO/VVde0Z2jNWNv3+O1bqwwF4KjBSRJfmGhkDjiqcI2NnQMgPLhhw+OPDWeXyRh6Jay+Qx4/PTo7EjI+TEJeLgy5EO575nyxNaxEAkJIGM3NZa9DHiGheyAhYDR3QEZaYSejsFMxcJWkucaDyltSpbEVzBc04ss7FE/BNJx4+gS8V4wbmsKmn4HeaDCA3qEEpBSIlP9cBBEuAnBX2QOtW2vh7L+4h6FPJ7dVug+tIUAAaSgNn4HiO1+FlYyja+FShNo63XPnzq+ZITWDiGGzy8KuDrzHddVeWz7jeaI0boOUcQND2zZi+3ci+tKz0OmEoy3v1p/nYueulR7QZx/2mZgZRPf298a+W8v4fX++ogem/BaIas7FaRSYGbFkqm5dCmtERiv829oqQjKFmCT0Aiy4+jutwgwdLYU8m8zUKqKm5QR0+N2LmMFKwUomYMWGoK0sSAg0h46ENEuXWNZDktTp1mbAbJ0Co7kddioGKzE46uPWEVMcwZt1Na1eWGErGWA0IIuVAQwMJdDT1QbTmLzkPTSyHr0UNDMOD8YxY0o7QmW8BSTE+15YvSDkZ7sXg22m3xjAl0EIAQUlVawh3K9f7sJkZA7uxcG+Q4hMPxJNM46C2dYJr/Iim05CagUSApo1NAvf9Naozm8lbVhyfpT7cmjbhm2lyx+cCEQCZjiCUu0iWCtYmXTOReCvbBxCtjNpZAYPI7V/F9RgnyPt6pN5oEyNA3XlRdZ54KVUAQG7rIy6BtvXVRU7Z0DsM1tuFIIW13j4hsKyFRKNVIVzsgjv373+8UeGu+s7++62+g55XNdAlxGWR5uGPIWkOBNCLCXQPBA1B+PjzM7q1krEYMVj4EAzENYa6b5eNE+b4QpU5IPrQOgeHGI3YUTaJhihcw8WQGJ7bfEeSdltGuEMyrSbrTeC9ekj7dv9hwYpBExDNjprNw+21jg8GMOMKR2QJTTmiWhmk5y7BNj+VLljRO2Wl7pDsR1gnECeQe0Ru2YA2oktMueU0chxwaf37EBq75uOuIzfahTOQgDODTJL2omDM0MxIKpa6IVEDv+45Yy82NAADr3++0K/fZ7LPtTchlnvWlqS8TKpJPZuf8rtv67zuqcJrSBsy++cRn63N+3o3ns9z8t0Twu+slrAzFlm+tzgE7fvrGX8nktXXmRKeWWZ9cO4gpkRjScLIy9jC0KaGP80nNi5hz94Qp/78TUREToiHCaeZjSZPUzyKIJeKKWcz5Q+XlDzbJDoAiAJTMHVL7sXt8pmkI3HYCcTzhehBFQ6hUx0AOHOKUXuw3oSugdtTYwuaz6I2ts72msSjQCAU9dvO/jkyuWvg7B4rKfmIWPZiMaT6GyrXjb1TgARoTlkqiFbDTHQBOaw93gjb64ZW6F3KI6pnW2l+tqLUAjnAihL6Nj8jRTO/uRGEE5wfD4MYgJ7UjDaOaZwV+haO1I0LLRj+QKAsnNtUsnRhfD2EcxOAxMXw7u3l4pAF4OZwbbl3F/YM5HzRWLYFbspdQzWDLYsQFl+17Rc61ZP8c1tYOPHzN3EQY/Mg4lwXNhopWYyZwDf7Xv0ll/WMn7HxavmSEN+k4EJV1/qJcJlCmW7x/SkYAZ+esb9j9eUd1CItzWhT129prW9e0ZzsyGmKBJTTVN2KM3zjJDZqpV9vJBmB7SeBynbiNFNAmFmCpfPTM+51bWyYScTsBIJ6EwGtVzQ2aEoZDgCs7mggmsMlnfKmhh90H0wmonsLtRI6AAYTI80ktABIJHKwDQkWpomRWcAoCliWolk5iJL2ykh5TwCLQD00WA6GsA8BnrAHHYXumP2hiXSWYTiSXS2FueiEImzAHyt0v7M9FtAf4qIiBhgn9Rd21i75M0ACZfQ2ZVlBRwyz9NbB6Ad9TUSXoKYQ+xU5fucX6eevxDQZfZlryc5M/L6oPuKbwzWuuz+uY5pOTI33OY0XklaTuM+R+Z+xzRP0jVI5iVOVekCcEvUtlo6dUPpvfPx1NKlZtgU3yBgVrWx4wGlNYbiyQaflfuh7BtHuvcEJnRFC1bfYKY6urpaWlqmM/hYaZizAMwTguYwiSMI1ENAOxGFDSBCjsNbAIBhSndZ7rrx3Cux3D2c2fnCqEwaViIOO5Usa42XBTPS/b0QoRCkYQYeri+hO9rwE8tCJ4IhiI4A8Eat+zD0g8TiatRQ+ldPRONJGFJOJskBCJtmyDSp88xfb3kMwDbA6XD1zNKlRqqpqdXosGdAy7kgfhc0FmtgIQizmdEJsAkmqtfnNxhPIWQaaA6H8j4XIjrxufOWtFTSsk7ZmSdazFAabgjHJ3U43OgTFGl4jjiPxNnXXAeYBFh4NwvHzS5YQ7n8VJPLvTSfuwuC0vv4hOz1TPd3JEBogAWgFVQZ1wmDXSIvJHOv21xA0jUgGuMQOnJu9pJknssKqAwahOJPRzfVVqI2beGMvyAhLqrp0A0GMyMaSzY2EY6ZNfPXz9zw5JsjPcREIXSaftnXmrvbumaKMC2WQi4G/WQJ0THvCpOYBqI2EJtgiHI3YCr4XQvySDyZhEolHS3nUYBt24mnT52ei6fXm9C1glYNdAPVBhIk5wJ4tNYdbJ3YZMq2JICaRWnqAWagfyiOqV3t7/gkOUEkwqHQmQDu8R6TAGPbNgvAgLu9BOA+wLGqVKdst8PGUQQsIMYSzTiJgOM1eCqAJgLRSFz2DKA3GsfMKR0wDRkk9WmdU4+cAzy/vdy+qc2pg81nmy8T6GTvMWK4bndCjqFcVzY7s2TXXeeRuyan1pyJANYgFk4pF7tZ7kBV0zPfJg/8x1w2KMqaXQs9F8d2XwXABJCTjFvOxAha6EVkXpj45vcx95TgMGoyZ0Ax6a/0bbqtfGgkgD2XrFoshPgqJqAaHAAk0xmkMlXz+eoLwnOA/s5oDjFud7MFq+8I6WmDc01TrhCGcRaROIUEzSagiUGi2C1Oo17HeZYyKwU7k4adTECl06Mm8UKoVBLZ2BBC7R1OPLLOizxtZ1FN6308QMRzhzN+34bn++auXP4UQOeM0ZTKQmtGfzSOns72kslY7ySETeM0BVAt8pKnOkTf527PAvjfO1ZDLji8oikZtuZo4sUafAoRnc7ACawxBWCj1ri80ozeqJP57hE6AWEhxAkAyhK6U13xyS0Au4Tu7uvG1Jkd7xxz7jGPKP17CwHCtYYdHXjhkh58N3ux6EwxnKQ6DvC5e98Bl3eZg/3YNmntxrLdxQU7Lndo7YwrcQjNCMTMXTe78pLiAnKu2lXSc61yP4WvAplXgxs3v7evN/79WsYfvOy8FiXktwmoWbuikbBthWiswa52hsXMf3fm/VvKd+eqAQ0l9Pmf/WZ7k2g+SUj5IZLp95FoPsFtMpKHevlfvKQ21hrKykKlU7DTaehsZkzi2kFkBvshw2EYkaa61owzM3R2gsXPPQg6bjjD/wxQW4D7CGg4oQNOOcrAUBxTOtogRL2uurcXiAimIU/av3pZBOs2j0g548/WQQEb4wBedLf/A4BnVpzUmW6OHC9YnqbB79HAycx8JBjlRRsApC0bA7Ekpnia70QEgUWoVI8OAFBPgOlTxVmpfnZMwcNOnN0ndRCgCQJw+4cHMr7dvzVz2bCdf1w/qS23H8BgzWUtbNYMsm1It/2rt2hgImhNUEICyoZiLvnWsdYwbBuGrVwyd6xzEST0QKwcvvqba4EX3Q5zD1SOm4MJ2KXAn6mlRA0AbBH6O0E4ayLGu7RmDAzFyy68xgROmdqPTr1/84bRHmrsCX3FGmPh4pkLZTjyESHERSTksQTU3BO3VvjWt9sqUVtZqEwGKptxepHrBpfmMDuu9xkz637oCZcQ54KYjxn2PjbWw+QbgOKFXSOQzloYiifR0VaRY/6gYUrZPZQ15wP4fT2Pe/LGZwcBbHG3b7980bvbBjL6WAItY8K5GjiNGUegxH0omkwjEjLRHHHi6US0oNr5lCWeN0y2AKce3UHgM2Uvh8a12EE56x0BCvNd0TlSptxTtRmuvixbIMGNubwdoRkhl3zBOUIHkZ9pD6XA5dSbmR3LXKs8Sz9nnTuWec697rwPpZPfaiNzFzYrXNu/6baauoHtvnjV2YLo8xPxy+Z0UksiU7bV9RidF3jDUqk1tTZgqYQxI/QFV3+nVYQj75fS+JSQ8j1Afl33SJFH3MoGWxaUZUFbWWjLAit71Mps9YK2skj399fhYwqA2XG5T0Aw6CgsuawFz/932eSlQvQah17q5ukvE2HJWM6tEuKpNKQktDY3TcT7zJiDiES4KXI66kzohTjhV5tiAJ4G8LQCvrvl/GVdhqCTGLTSZn0eQMe5GfUEOEpyR5gGDClAoFns9C8r6+5imdoJivQTMCM/jp1P6vAeoRyxs1897o71Cdkb7+Su6xoyANnf1920G3lXtuMaL5nVpgNys0HJWSfTXjBDaFUQlc8/p+9mdxPgZEAsxnstlbPY8x+o4XUyA9/r23Trr6oMBQAcWL1yqg6JbwPUEO2J4YCZkc5kEUs22ljirND46/c88Mz+ehyt7oS+4OrvtBqRyJ+QNK+RQp4IGt05PGU2ZVvQ2Sx0NgtlZcG25dR3N7Tif/iwEzForl/eh1bWhIyfAwABUzpaxYzoMDLdV933embLymm/BmjcCB0AovEUpJBoioTeeaRORCHTXArglkadUgKM9Zv7AfwOwO+eO2/JV9KidYkifJgJH2Lm+Upr0TcUx/SudgA8a+eKFSFs3Fj2jht97H8He86+cg8IM/Is7lLWuvswEfzEOS/SnV+DnUse037ZWuXXxpzbz7eUmUHxKDRrlGyhER9yRWECrnoPTtMIcCoJZWVBZmGzJoYdGwQHRGN8oRj3HplXklZy/sOyyr2RW5VQa2oZyYDY1yS+KkCLGl3VUgtsW2EgVrMdUh84+ri33rt+06/rdcj6EfqKNcbik466UJjmP0ppnDjcY+dKuxjasqGyGahMGiqbAVs2uNEu8zpCQEFBoB7ZAdqecNntPhiISJOOxjAIHQC01ndJKf8O45zxOhBLQAh6Z5azCXHmeJ7eLUnbDGDz4+cv+xeD8F5FfG0yY50RS6ZlW3OkFZ2wsOk4AAAgAElEQVSIAKhkQjEYL4NwGpD7thUTe+DZQLJc8dG8xLZc4liNaWJ5ZG644i0iMYTsvh0wjzwmVz/LDM4kYe96xWkiU+Ciz9XGMziVgL3zFRjzF+ftD9uCvWO7k9Veop+5FzMvFovJf0+GVSEERKH404OP3F6TXOXeyz7wx0LIKycimSul0T8Uh25wiRqAZ5G1/nHtMPXaK6EuhL7o2h8skWb4RiHFBURUs+KPlzyibRsqnYadSeeyzieU5U1MUkKYJpGUjns/W9ntPVbTZzUx3e2AE+4TEIsBPDCc/Z7vtX5/8nTxe4BOGqOp1QRmRv+Qk/leUDb1Bw9BOOa11SunHrvuvsPjPZfljuW+7oXVC34Zi7VfOBhP3Rg2jXnc3NwBoCKBsMDLhZ9a8P+Srnj/T/cPhmvRetY7cqSYf5Ayk8i52yVrSJVreGJv3wqkEpAz5oAMEzraB+vVZ4DYQN5+ufM79fFwBW7sV58GrAzEkceAQmHo+CDs154DDxzKqzMXQTIPWuV5c+ei96cWMKAY+vpaS9R2XLxqjhDyv4gmnhqcZicJbhzkjwdszX+5/MEn++p50FER+tyPr4l0TJl7tTDNLwE0pabe4O4Fpqws7GQSdjoJnZ14bmQGawINyHBT1mxv7zbCTSbAyMaijuhMpX29BXqea60+5FDvErt6g3n4rvNPbdtmPbnq3XcAfGJ56Z/GQGtGXzSGqZ3t49YvfJzQ0mSKRQAeGu+JeHAbstz11PlnbR5Kpm4OGxSptg9p2sHEXK5VcL4rPohgvbqbvFZIsNp9vJYsd80QWsNwJVc9nXSybdivPA312vPOcTy5V9ei9mPeweN5wjduxY792nPAmy8CQjr7K+WLxARrzf24uZcAVwcyd14c3dO3/+BNtQx/YfWCUNgU3yDiIyeafgwzYyieRLqR0q5wFkRg/tLy9ZufrPexR0zoC67+znyzufXbwpDvJ1DFQt48Ek8kYKUSju7wBAI732ILoN0g3mQ2tx0Id3WdLQzzNDAMKxGnTLQ/rylLhWO5ZF7fC9iTpJ3IIGARll5lYtvNw/qAtWX/XJjy7wC0j9HUaoZSGn3RGLo722DIdwypCzZwOiYQoXs4df2jB5547xmfHIqYVd1TWvAuwVSRdnOknhuWn+Xu/CAvlM2cK/vys98rwM1u9+LYuVh2Lp4N2/YtZ981jqCLPHA4wFG044CqnZv464UCRGDRQcHzuAuUojq+Sm9QRdBOpbLX4PX7apKq7Gia9ykS4kMjPt0YwcloTyHe4CQ4Amtm/sHp92/+wVgcf0SEvuhzt5xnGKGbhRSzUeGDytdEj0Nnsqjur2o4LGZ+E+ANNvN9rT0zpdHS/DEpxHUMRFQmg8xgP1S6thJdZ3FefzLPnWBieTJK4OjWZqszDgzLdXvfA1veWLVy+SNEuHCsJjYcWLZCfzSO7s42yHdCdzYiIqLlvAaC1tYvplcvnPnglrdqGadYHBTQ9ojKIP3cOZdog3Xk7EjA1nT3cuPnnla6Q+Q6zxL3XOpBxTZf4MVLqvPgBvkpIFEbjKEXHif/dyCaEMAI704ZBl83sOm/d9cy2FWDW4uSWYDjB2ZGMpXBUGJEsgujOjEDDzH0FytVa4wGwyP01avlotmr/sI0zH8lojaUuS6YnQ5lVjwGK5FofA14BbAjhKCYeDezXg/GXRkr+0zXUfOOl6HwF4SUKwGKaG1TJjoIKzY0rIB4rSOt1JDjlgtFIAwTXnlKtaOPRee2+oI7Q4RjMUxCXwvolRq3k+RVqOLxaRSylo2BaBxTOlrfES1XicT79+/64F27P6Z+ppJ4aPa637xVj9rYRkIkov1obc+iitZFede7B48Uc4QstK6tDp3ZKRnz3N4ekRfoqAeT7fL+Rn5CH3l+ftfxkN8nxx3vLzwCpWnewqCEq324cNXgvtf7yK01ZWS/fNG728gQ3yWgc0QnHCMwM1LpLAYbndEOAKBXobJXnLlh66jU4CqhdkK/6iZzSWvoH6Rhfqlc4hszw06nYMWGnDjzBEpsYye75SCDf6dZ/UzFs4/tvjccXXDdkUvajMi3haSLiEQzM8NKxpEZ6PfbFQ7jHNDsKk5VgUonobJJAARhmJChJshwM4QRAkiUJncG6qk6NxYgIhKazwDw+HD3NXoz9+lp4Z0gHF3/mY0M6ayFgaEEutpb/uBJnQhNAH1IQl4kW3DgwMc++LvdSq9LqcTjx/90Y+94z68WDGxbNzT1nCszALUOf2+PHHNhQmJH4Y20hrAtsJUFwlXKqLWTDOd3OPMs9kAJWz7h5s5bSLj55XMuqXPwmYJ9fUJ3/q9WYlcTHDJ/UiViXymaYGlQc1fnF4UQyzFiZ0D94ZH5QCze+FUq836h9cWnbthakwDPSFEboa++Q57UnlxL0vgbIirax7PIs9HBiUfkQBqatzDox+l05oH9vzT2ATfoBVfdNHvJFyI3SkP+OUCdRCBlWcgM9sNOxEdxxtquX/Jjs45QjLazsJJRkDQgzYhD7mYEJHLZ1lxWVmKCgcQZI9nt1G3bkk+uWn4bgK/WeUajQiqTBYaAro7WUv26/+DgJpQdQYRLpZAfEUbbnr2Xf+B+1rQOmb4tR41QIrZBYDCiIHTXOtzLbPck3R2rGH6SmmK3p3oqAfv3j0EuOBOiqa3sEUu52oV24tvCJff8RDX2p0Jlvt9+NKDokeC/QcGY8iVqI8hqj9mgvxrcti5ay/jdH1t1liTxOUwgV3semTf4FkrAoAKuOH39E0834FxVsGKNceLSuV8Vhvm3RPmuUGan5CwTHXBIcIIQOTMUwLuY+edg9T87DouXsHGtDQALPvEfU4yOKZ8ShryOSEwlArHWyCZiyAwMjDg84Fnn7F7DwjAcLfdwCMIwYKWTsJMpaNuxsO10AplolbAgCUgzDBlqhgw3ASCk+vZiwpM6483DCXn8cBPjAODJ8047Cob5LEBTxmJqo0FzJIzO9pZ3BKkXgZlBUKx5B5jvzir9C5ipZ+fdXl7oZbww9ewrnwfR4mrjct8id8HsurLZa6kqBbQQ0FJCSwlIAywluLkV8vjTIbpnlryBqle2Qu951e92Rkr5Lng/251zVjSAgCVd6btNeb+KX0iAsIsOM2IyV8x8bd8jt9bUBezA6pVTdYuxsRap3kbBi5kPxhPjQVExUnzFaesfv7MRJ6tmodOSU+ZcJwzzC0VkrjWy8Riy0YEJIbXqutQzYP0Ea/wgY2fW77v7/+Vq/K66yVzUHPqgYcq1JMUCAglmhrIspPv7oKqUolU9PwAmCbO5CeG2VhjhMEgIsFZIRwcBOwtpChABytKQoQhIGpXL0FhDZVNQ2RSQIAhhYMKTOQAGZk1tyc49DLw23H1P37B1zxMrl98pwJ+caIXgyXQGBKDTaxryToLzgg0SdByY/zYk5DVg48W9l3/gbmXZv5x9IPMKbdw4IUowGEjW8ukUxtGDPdSdA+Usaie73HaeS8ahX9wEnrMQ8qjjnPKxIIKZ7X4ZWS65Lj9+7v/IJ9u8iRU8WOkWUPK5Ed4zmJlAv+zdf+CHNQ1fDbmvWdwogHeN7IT1BzMjkUojGkuOg5sdCRBfe8r6x6s0FaofKhL6os/dslqaoa8GY+bMDG1ZSPf31pz5PZZgp6VxP4F/ZbO+eefrB7YVWIb0rmt+uDAUCv2zkOICgAwCiNldkAwMjFqFjhmQTa1o7eqEDIXclqkMZVvIRAf8UjcigjAESBDsLGA2dyIbqzE0yTwRe6CXARsatBwjIHQAMFl9Wwl5CYDm+s5r9EiknWqddySpe3B88k0gOpVYLBXh0Jf2zwlt23P5B36ubdw7e39i93iSOwO/IGAaA0dRTWFF198e/Bfw3G4gMARpp5c5KWdkJg1+41nY8QHI+acAoUjeQsBrkJLrP16QDFfkIq8yvRGhXDy+RhDtVKyvq7VEbXfkA39ikLxioqjBMTOGEinEGp3NDoDBKTB9+tT7Hv9xIxNLy77xCz77w5NDTZHfCpFzfTKzS4L94y7FygwGeC+Y/zvDfNvedWvfQMEbN/e62zo7JF1D0rjWex1emCA90AeVrEOmI0kOdU2hcFtbLtbt5hSkowNuY4YS89cMO2Mj2bcfeoJ2TxsNNPj2vodvvWKk+29ZuXwdEf1pPedUT7REwuhoa/6DT5QbFpxU6CgYj7FWd6Y0/3b+T+7bP1YlOpXQvuwTUwxTv19AXALgPQB3lhKbKXS7e+F0diVXmQgsBFg47nclhGORC+G0iiEBbuuCfNcyoK0LRAT94uPg3S+DCnuRe+VpRRb6WKDolQ0XGYZa3fvw7TVlte+4eNWccNh4jIBZIztdfaG1xmAsgWR6XJQ1hwC+7vTfPH5bo09c8rNe8LkfTgkboQcg5MlOXwCnXCoz2O+UcY0jXCLfxay+n02q/9l7zz/tKx6laOE1P1xhhpv+jaQ8hdzkDCeDPYFMf9+oFdcczwAfiHRPazJb27qCZG5n0shEB1GtZpyZYaXSSB7eN+4LpHqDGa/2WkMnYfO6ES2Pn7xg+Wkgeny0zX3GEk3hELraW9+xvdQrwMneZD6kNT/MwM8olnpk1t0P1lXmsiasWGG0WUcfEzHw/zHjIwC9i8BG0L1S5PAmuPXeQVInn9S1EM5zQrj14AQORyCOPx00Yy70C5tAu1+GULladPIS4VgHatwLJ1sru5e63or3HelV6Zao/VfvI7d+ATUsxl5YvSDU1Xz0z4joQxPBbWUrhYGhBDINVoBzMUjMf3HKfY/fOR4lnyXe/DViyRfm3SQN8xOelKuyLKR6D0Fnxs+SdOrHeadi/d10Mn77gXu+XtJXfcKnv90dirR9WRryKqJcmz6tVN0WJAxoaL0x3DP9hXBb22e8/IIcmQ/UnCDIzLAScST7Dr4NasxrBzMsBbV04JHbR9SScw0gVq1cficBE+ImUQ5N4RA621veGeIzI4XDEHvBvF4rfadtJJ+Yd/vGmpp61BXLVjd1m63LAFxCROeDaSYRRClb1hNvYZQgdSIwCef/wKXJQkLMXQhKxkF7X8uReSCGXrrjWXXX+GioflhgZhBtsePygoFtN9eU1b7nslXXSMP4BsY5q52ZHe2IoThs1fh7KYP3kdIfP339E79t+MldFH3+iz/3gw8ZoaZ1RGQ6ruMs0r1vQY+jVCszDoPV9zNs37R3XSmL3MGCa3743lA4/O8kxIneYsR3f/f1QmdrCgVVngtYQ+tbwl1Tfxbq6Lwj6MofLpn7x2SGyqSQOHxwQndTGw6YmZn4ur6Hb/vmSI+x9fxlp2tBDxNV1/AeT0RCJro6WidJvQYwwwL4DcX6fqmwLrs38fS8Ci1RxwjUvezyI9iQKwXRxQScyf7ivxKpA0yOq93PhPdLSnMNWElIkJUtiJnnfhe72keWgT4WYCBqaf1H0Udvq6nE6vWPnLeoqSnyGBE6xnpuleAkv2UwFE9Cj0MqOzO2s7IvP3PDlm0NP3kAedfQMX/5vWlt7a2PCSGO9Qgqffitcclid13rKYb+mZVR/7TnFzeWbck5/7PfbG8Ot/6tlObnCKIJATLPxqLIDJaPZQ9rPoS01urGcGTqTeHp7fcKIU/3QhIqm0F6sH/YZB6EsiwkDu2HymbwdshmrwYG7u99+JZVGOGLYUBsXbn8xwAunshWOgCETANTXFKf4FOdGGBmJmSZ+VVmvltl9C+sKLYfe19tCVh1w9KrzM4me4EU+ChAfwKio4nZF3/IlbKhyGKH/5gzJpfk5gq8sP7/27vzOCnKa2/gv/NUdc8Ow2ZcWPSKmqCiERVBNENcImg2zRhxxetyc5OrWczNzSqZGO+bPW5JXIFIvEZHjTHCgNE4gDCATlxiSOLCqiDMvvVSVc9z3j+qB4aZ7mGgq3q28/18JpHunqqC6elTz/Oc5xykq9wWSJOUEDBYs8FXG1YvvLsvr99dXlbsFBWvUKRmhn1tmTAzjGG0tMcQS+T2rZO6AgOmF6Cd604PuWhMX3R9H9HUWxb/1LIjXwOYdDKB2O5d/VK21Z/S5vXamG9voY2rUVmZ8SJO/Op9J1qRwntI0azOJjH+mr9GorEhyyIx+1xUu4b+0maz8ZETJ8y93Y5Ev9E5C+C5DhJNDVnfNBjPQ7KhDsYYGO1Cex6Ydfcc3EGDGW2e0hObq/vWMzmdmnPP+IiKWBuIcBCVv3IrYlsYPbIYEXvALvsPTP6UfIwZb4D5Cdd1lh3pjXybevm9D0PpyfNLrRKrjIjmMXAeiEsJRPsE9VT1GcbegN7z7+P/T9e95umDeeqx0P5GfcfMzKA/NNS3zsPGyv1mkmmAdl5z4W1KWd9CP021d06xN7d19Ef7UwDswOBeQ/p7Z1St79/kspQ976UTvvzAVDu/YA0BxTqZQLw/Rub+qLyJ2fy4JRH/Tf0zP2nL+Nryx60Tj2i7zI5Gf4FUgRigyxR7fR2Mm32Go781lZuYzXXvPl7x9JSvPPDxvLyCpUSU798d+jcOWbc1Ta2ld96AcGqkb4z2g3uqR/xgCu7MzKzN5xrWLM5qH+aGOTPvAHDzYBj62pbC6JElw66feoAMmNsZWG80VyZdZ/nRxz33fk4bxpSXWyMbx06yPO8zivlyKJzAfm142mdE3hng0X3jW+d+8W6V2wIq9hIGBrYaolmN1Q++15fXb7n8wtmRqHqWiHK+tZSZwcxojyXQFovnvliM/+FcD8L/bCla+/CllRgwGc3+e2nBAnVSx789Ydn2Zz0nifiunTkP5gw2YKwx8G7a/Nhtr/f22sk33TWiMFry/yw7ckP3PfJue1sgo+W914VdDO+KTb//wQvH3njf2MLSgmqlrOMBf2tEorkBxgngxoEZyYa6jP/unNqHrj0PxgyI+h19wuAl9SsXXp3NMdbNmT6eYNUQ0YDYErM/ShFGjyhGXjQiQT0b/si9mRl/MdBP6hheXFy5bHdFrrbBaU045wd54/j90wwwD+CLQHQ4AGvfkXnG0m17p9y7PTyQgjmApKfN55peWvRsX168s3zOOC6yq9EP1eCYGa7robk9BsfN/ecg+ZX9a+Dyf53+57Wv5fwC9oMAYMrN983KKyh6gbWOxnbtDGRkeyAYSLA2dzQ1xX/U9PyPe82snHzTfUcX5+U/RJZ9NnUpYMDGINHcCLe1T4mZfbsuRh2Mvuzdyoq/AMBJtyy6R9nRL3aumydbW+DFg+nao5NJOM2NfbgmBrOB1h6M58KwGSgfCmkx8w6TTH6kcf0jWU1JbZg782YAv8QA6cS2P0SEUSVFKMiPSlDPHgMwDOxkrV+AQWUymXzp6Mrng/tlz0Rr/4d32ZNqbOvaQ9hpPw9MVwKYAXARQD3LqHQpxdq9yFv3F/X3O4P9D5Q76lcv+jr6cKPkV4P75K8V4YZcv7GNMWiLJdAeS+yZwcwtjoHp1x3xjttnV7+W+10afUAof9w6+cj400TWhbG6naTjuauqk9qKtlMb98ubK3/4JPaTPDX15gfPsfKjC0HWhK5T7EZ7SDTUZ12+dd+LQ53L/Pmtjy94EQCmfPXBC/Ki+c90Zv+78Ric1mB+pswMp6X5gLYFdp2S154Loz3wAFmP64oBDejP9rVARSavTJtWqA/J/wsRDqrxS38ZUVSAkqICCepB8bdVMZi3GIPlFnuPtxu8eswjVeGuYXYGdgDT/vNB+723Xj1Oky5nwxcDOJYoTbvW/ZRhHRDvCEaNTiYu6OsN9/tXz/k8rMgSAtJ23AwDMyORdNDSHofXL2XG2YDxOrH52inL160cyC2F6fgv339aNL9odaKpIc8NKED1RSqLfaNrvGu2Vd7We6p/ebk1dfwF861I9Gek1J7+ukGvl++9OLQZw/M2VS5YCgD+VHvhKqXURwBAuw7ijfVZZbR3ZbRGsqHuoI/X2epRGw/adQZci1XD/HDDqoXXZHucDXNmfAykqgDsp3/lwFJUkIeRxVJVLiRJY8xbxFiqtfdUspHeCDVTvktgxw9+QCNf2D0yGjEzmPXlYJzH4HGUNlMOGGjBnMHNnmtmN69d3Kep402Xz52UF7XWENERYV8bkJpe9zTaOuJ+x8P+0QzG3ey4d05/YUPuCyMdIDrp64uX6GTyykTdfjp/BYgZDOZ1xnPmbX7q9q29vvjG+yJTiyML7Ej0FnTZj+xXfYv5684BZuIzc4yBGzc9tuAR/5EF6qSvHXWnikS+RAQyxiDeWH/AvdJ7OR+8WAxeewAFb5jhuUlor9/e/JnsSsTd49s2PJzVL4QGqHbuzHvA+M/BNuTNi9oYNUK2tYXG7wYXZ8P/MMyVxvWeDb1hTNfgftmTqrRhxXhL01xmvkKBTmFwvl9uNsua6iFgwGNjvtqwetE9fXn923Pm5BUcYlUqoovCfgMzM7QxaO9IoCOR7K/pdQdMKwhmwSlVNa8N5FF5V7Z2nVHJxoacJU+ngnm1bm+/fMuyn37Q22uP+/cfl+SX5P1M2fb16NLtbc/+8qbs9n2n4YLpW5sev/X/Oh+YevOE2VbEvh6pdXOnvTWwYN4pqCY3AzVQMPMhefmRT7QB/7f/V2dmAbwuqX9AUet8AiYHdX25kHQ81De1YtSIYkQj9oD9WQ1a/j9oISmaZjGfYuXlfWfnpEjt+1dd9IR29PIJj1VtDrymvGV1/fDRzVpvg2Xdizk3LRwTS0xlw/OI+FMAjgRgDZSfuF/0if7QsPODB/r6Pflj6AtKqbkIMU50BvKOeBId8QSM6ZcYqsH8OjP/sGhb89ITNm4ccKOj3tCki799mGVH/khknZomvSNQ/jS7qW13+MJdf6jY3dtrJ99014iivBGLlW1/uuv+coCRaGpC0MsDzGCG+eUm8/dvdO57n3zTXSOKC0pXKWWdtGd6vynYWRftOHACPKabjEMPwK5sDF5ev3LhQReZ6Wr9BTM+S0pVArD2++IBRhFhZEkhCvPzJKjnhmHmZmZeA2MqbXgrDl3yXB1yM+KiktOvHh2Jqo8rRVcBVAagOF2TmJxi3qKVOquvW9S2XzH3RIrYq1VI1eD87b97A7nuj0Du52a8DWN+rjznsVOfrw0/4TIEBACHf/o7EwryI88C6sSwgnpqZP6WdswFW56u2NLbaz/8pXvG5BWUPGJZ9vldW/EZo5FoqA+uWEyXa2PGk2a3vmpLdUVnZhpNvWXRDy07+q09U+0NddnvN+92YqetNbBkPmaG68RhArhG/yY+0A+eDvZ4Wv2ahf/K9kAaoNo5Mx8CMH+wRsXiwnyMKCqQdfVc8qvTNbDh59lwJVFi5WEPv9CYo+lUNXLWtUfaii4l4FIi+giD8zKvt4eEOc5M5fWrH1ral5enqsE9r0gFnozKzPC0Rkc8iVg82T8lWwFNjH8Smd+0x+KPDNTs9b7a82YaX75gch6pp0B0QhhBnZmbtOvM3fLU7et6e93km+4aV5Q/6lGl1Me7XofRGvH63cFmsu+9tr8alZy7+dH/3ZNIcOLND0yzCwr+QkQjmBnJtlZ4sYBvJIxBoqEuuD3zQQZ08NZU84qe2bsHczxmBtNt9asfWhDE8TbMPe1QcGQlgGMGa1DPi0YwqqQItj3oJhoGP4YGeLthPKfZVMabm9d/+Jk1mQtZBWnajYVjCvUMIp4H0FwAHyIKv9qa/zuIX9avXvjf6MPygwbo/asv/KFtWd9EgNXgOiu8dcQTiCfd/lkjZ7ggfhXAvcnWtqfPeulvTbm/iODt80E44TPfPTqaF6kE6ORAgzqzp7X3n5ufuO3B3l525FcWlY60rSeVZc3uen7teUjU74JOBN/DgYFdrHHepspb93QFm1K+IBo96t/+rJR9NgB4nVPtAb/xvHgs4H3zDCcZCypJsI4NPwlF1xOCaWHKwDu63Tq1r12c9mfd+dPPU7b1NJD7alVBsZRC6Ygi5EsRmv7hJ9NpZrzLhpd6rvdEvm3eOHTJc8EUmOgdFZ02/0N5BdZcBb4CoNMADm1K3jDWkebz69cs7NONy3vXXHSOUvRMEL9fnevjiaSLWCLZL0VhOgsVKeAFw/xgLLFz5ezqLf3XQjQEPd44h3/6OxPy8+xHiayZQQR1fzpbP7JpN65FdUXGn+KR839ZWjp21O/IiszdN5i7iO/eFUintB7XBiSgef67lQse6/r4iV956EY7L//ezgIy8cb6wIvtMDOcpsZAj8vMcBIdgW1bM4buJph8EK4P4kOGGQZkrqxfuejRIK4PAK2fM/OHBHxrMEdDAlBcVICSwnyZgu9nDE7CYCOz+YPnmGfb9da/n1CZg8SoadMipUUnn2ARyon5syCaHNSNNJDaoqZR1vzSwl6rcHZ6u3zOuKJieyVAH8nmvMYYOK6HWMJBwnH6KdGNHTDeZOApxfTEs8vXvJ2zaoM5lvZD8NDyb40rRN6vyVIXU5ZTLcxmkxOPnbX9mZ/syPSaI+cvyB8x5qiFViTy+c7zdRaMCS2Y+/vgf/GuefN/ujZ/OfqLv5pQUjSiRlnqiKALyHRlXBfJxrQt3Q8aMyOZaA9sJoEZTWBzLoh+BkJZEOt9DH6pfuWEjwEVgfxCvVg2pbiooPSPAGYP5qAO+FPwpSWFsC2pA9/v/CSpDjb8mjb6KdLus+P/78/vBp4pn0Zp2fxSYussi/lKgM4FeJRfOv7g3hQMaDb4SsPqh/q0RY3Ly60dhfF7iei6A3kjdk6dMwOu5yGedJBIurkvBuNfiAeizYa5ShGe6og1/3V29cZg10wHoIw/rCPL5uersRNvJcv6KkB5Bzladz0vWb7lidv/mPEVZQvsqacc9VMrEvly9+pvIY7MGcBL7Y2tc3Y997MuU2uaTrrldw8q276WCGS09hPhgu44l6o578WCndVjZiTj7Qgqx8fvwIS7PcN3RpRaSYSsa6kzw2ity5rWLF4dxDUCwLrzph+jItbzAE0M6pj9RSnCyGLJgh9Q/ADRppnXgU2lYue5w6qK1a4AACAASURBVJc8/14OgjuVnjF/koqoz1iKPg/gZGbOO5DZMvY90dDQfmVfuqgBwLYr586zbXsx+pA/s7diJcPxPCSTLhKOA0/neADsL520AfgnDP+FWS1z2/HarDU5yosYIHp/Y5SXW0fxRy5WSv0CpI44kKDODDZGP7C5Ev/Z22jspFsW3aTsyM87m6z4wVwjvvuDUIJ56urqmc3sdx+reLPro1NueuCsvMLCPxMhz99z3ga3I/j3AxuDZEN94DcKfkAP/HrrjeOezLZ9hqXoEQB5WR+R+Q91qxZ+DgF+IK6fO+MisKokQv7+Xz3wFebnYWRxASxLEuYGGAPmejCvMtpUclI/P6Fyxf6bMGRr2kWFowo/9FFFPI8InwHj8L4Edga2mkRiVuP6R/q0RW3T5R+flBctWkt+E5r0x0x1ffQ8Dcf1kHAcuK6GDii5t0+YGaAkwFtBeNkwv2hrrN3R4Gz7VG1t8JnTg0SfAvRRF39nEiz7x8pSnwbvf7Tur5ubNcbhT255uiLjfPWJNz8w1y4oqOzags94HmJ1uw6orvkBYXia+Aubf7/goa4PHzl/QX7puKOrlWVNB/xEvHhDHRBCGVWdSMBpCT6pko3xp9yDPCYzE+jWulXj/3fM2dvuJNCXsl5PZ44b9soaVj+8IaDLBABaN3fGNxXUDxDg2mN/siyF0uIi5OdJwtyAs6emPHYZY55jxuNeW/vaiU9Xt4S9Da7k9KvH5EWt86HoKgBnAihJ+zt5gFvUFgDq+qsvfMBS6jIQomBYnIoRxvhbzBzX8788DzoXo3A/cGsCEiBuMIx3wfw6kVrvMF5TLWbbzJqaBAZJJbew9f1TYtqNkX876pBPkGV/i6BOZSCSLrD7+8312njSm7fjj7dvz3S4E26672g7v2Clsqw9dYGN0Yjv3hVY5bR0DPDEpg/0vO4Jeid+beF/RCJ5vwLBCrqTWld+I5YmmGTwsw/GaDiJ9NfMgAdm66CCMfOWug77+BFRnR+N8loCHZflpbIx5omG1YsuQ4Cj9GVzJueNxSEPAbh8KEXAooI8jCgqhFI0lP5aQwx7xvBWZl7GBpVRcv8aeqZ8WZk9Wh91rAI+R4rKmek4IqRmOmEMzC8aV038nwPJV9l6+YWjLOVNhLImMNTRnuce1hFPTko43gSG+ZAxGAFQoSJEDGATc3a1jP0bI53aRpgAoR1AEzPeJ2ATgHeZ+F/MZlM8ntxRNu61NhpA/ccHmgP+QYyf8dUC+9CijynbuooUzSTQOAARELnG8HsM8zA7Lb/e8vQdGUfmH7rq4aJDD+U/KWWXdd4UmNSe7KCLxnSzIwZ1xo7ff3efG40pX/zVoXnFI9aTUhOBVGZ9Fs1SemM8z0+GC+HYWntwk+lnm5j5bRAdQjjwak+pQk6XNb70UOXYj133SQIqkeXUOzM70Dizfs3CV7I5Tncvlp1cWlRQWAVg+lCKfralMLK4EPl50o51QGNmBrnM5i0YPO2x+wd+L7nxqOrqcLdHTSkvHl1aOFPZ1tUgOpeY361LJucgy7bFgL8ffVVZmZWXTEZUoRmRpzAiQTRaKSolUqVs9ChFVMKEYmIqBlGEKW0DpSQZTjJxO4M6FHMLK9VkmJuhdQOBGzVZLc2qrqO96h3vUkjgPlBZfTKMnrNgRLGdmKAidolmbnc6nM37JpmlN/VrC//XiuR9s2sSXKKxAW5biNX2GJ5mfe3mxyt+1/2pk7626OcqEv1q5za1RGtzWAVs4MU64LWHk6fheQ48J/3nBoOfT627TTmYYzNzVf2qhRcB5TT27BEPAzwv26l3ZiytXzX+U0FlvHd6Zc7Mow2hCsBk5LoSV8gK86MYUVQIy5ImL4MCc8KAXyfGU57jLq17q/6tU2trQ63NPHr69eOBOPq6bi6Gjpx/Iky5+b5ZeQWFfyZS+UCXRiuN4XWmS21Re+ZdYy5FZcU+mZ7H/8e9U6KlxTWdFeGM9kIbnTOznwwXZPnYLjw3Cc9NP5VvwIvBdIQinHcwx2bmVgfm1NZVi98umXX1sXkqso4Io7K5XmZ2DPOnGlcvWpHNcdJZf8HMGaToGQBjgz52f7OUQklRAQoL8kAYuE15RBepTHnD/LLR/KRFyaVHLHl+O2TtVwQop1Usjpz/y9JotOCersHci8f8rmkhInCTA3VL92CO8nLLLilYAFBJ50NuR0cowRwAjOuEFswB9F5Qhvk9wGSsBbA/RFQSZfUZAGh76eG3QHwPZ1mzkYiiiug2TL2qKJvjpDN9+doa9sy1DB5y21a0MWhu60B9UyuSrtdP7SXFASEiEI1QSp1j2+pXsApef++aTz6z9aq5V2277LzD9cDoqioGuZwG9BGjR3yFLGtq55+N6/q1zEP8QPIz7unH2x/73rvdnztx/JxZlmV9as/UvzHwEuHseGBm6Hh4yX4AwL1UYSKD7QB6bVe7HwTCJUi9ZxKG7wbo/SyO13nYaWNG2tdmf5yepj9Xs5SZvwIg3H/4fuK4HhqaWtHU2gHP0xLYBwsiIqJSpeiiiG0vtvLzX94x/6LfvX/13E9vnl9W2t+XJwavnAX04//j3imWnfeVvUlwfrMVDrGKUGqqvbYl0f6bHk+WLbCVbd8Koj37lp1YcFXWejAGOqyteOjcG5p+hO5nvKptBKrL8jQfLZl19WQAaF+9qA4wd2Y/SodSSn23dOZ1k7K8tnS4qqpmsYH5FpgHXk/ZADCAWCKJ3U0taOuIwxgjgX1wUUR0uEXqcrKsJ6Ioef29qy+8d+sVF5zzZnlZcX9fnBhcchTQFyi7JH8BKRoJpNaSmxpDLBzjI7Crjfle/TM/6THtOvWkiXOVUmWdfzbGhJIIB6RG58lEqDMRnefJ8IzHBu8xI6tEBSKK5pE9t/PPyYReBFDGrYl9xcyH2DbfDpQHXkWlAjBVy2ruBvg2HqJBHfD3Cbd2xLG7scVvRZnLIh8iIGQT0URlWTfa0WjVqKKSV7ZfM/fH710x54zt5TPSZY0LsY+cBPQpNx8+U1nWpwE/6Lgd7XDbst5N0TsGG+ZntkzBc92fmnzTXXkqGvk2Ee35+3uJODjED0EvxL31Pu7thiHmWmYXQEEUpb8QqfdN24aHGxjm/mwP6M9A0iVjZhXPzvrq0qgATEc87/8R88/B6Ic2T7njaYOmtg7UNbUilvB7TMuIfdAhAiJEdJxF1n+rqP2iKhyzets1F3136xVzprwybVqkvy9QDEzhB/SyBXYkmvdNIpUHAEZ7SISY0d6JgRZN1q2o6LklqjBafLFS1ql7XssMN+C66vtci+eC3XAHh/v50K5vj0WaQSb7uyiiUwrPuvJDnX9MMu5ncBA3CvlKqe9jSnkg/de7m11d7W1ZXvNdkPkZmId0UAcA19NobGlHfVMrEkm/y5UE9kGIiADKJ6Wm2UrdZkfsDYccf+gN/X1ZYmAKPaBPOXHCKcqyzwP27jdH0M1OukmtnT+09bHv/aP7c0fOX5SvlPUNEPZM72rHAXvhBVwv5GQ4oPeATqDNqL3fBesAqvbwqEKVt+dmqH31ojoGBdIOlYEZo8eUfDKIY6VzKaDVLudWEP9sqK6pd+e4Hhpa2lHfnArsEtQHLWaOMfOPknXmof2/WgxHoQf0SNS+mYiinVPtOsSR8B6ED5y4+UW6p0pG6YtJ2Sd1/tlvkRri6DzkZLiu58n0UW3Ab/mvoaz/okREzOacro95SfMggKwTIoigFNG3MKM8tPXCU2tr3Y5YzfcI9P3hEtSBvYG9rrEFHfGEJM8NJn7G6xZmc+lhv3329mOqqsJNPhKDVqgB/bj/uvtwsqzPAABrHfp+c6Bzmxru2v5MRc8919NujNh23i1da9CHHXB1MgmEnKDEzGA2aTeyprLQ/wEAioIJYAQ1A2VlexqgtLiRvzFQE8SxQTh5XKT4U4EcK4PZ1fA2V635MRO+iSG6pS0T19Noau3A7kY/K97Tst1tgDMAPa9hzh//26VLw278Iga3UAN6JFI4j0gV+s1OmkMtqtKJgB3Ntv51uudOOHv6RaTUSV0f8xLx0LLPmTnURjP7nCvjTQMxwP8AAEcp5kx72w4AEaYUOxNG73mg9n7XGPNItlvYAIAAi4m+jslzsm/T2otLAb112do7Af4SMUJtIDAQedrsyYpvbuuAkypQI8G9/6V+Dux5Xp3n6W9EFC6ZsPjZt/v7usTAF15AL1tg27Z9KRHIuE74We1Ijc6BHzU+UtHzZGULbMuOfLXr2jkzh5p9ztqDcZ39vzCIc2WuEqfj7PojdAcuEYIYpRfnKXtq1wcc7T0DUDA9YZlOGXPY4XMCOVYvLgX06cvWLoLhK8G8Gzz8Rj/GMDriSdQ1tqA+lRmvZTq+XzAzXM9Deyyh65taX/hgd8vsiUuW/nzcwmeGXLVDEY7QAvrxxx12rFLWVGZGsqU59D3YPt7ktsceSffMiR+ddKZS6oyujxnPDS3g+qPz8Pee7z1fhoBO2BVb/btdAABlMYKasiN1Wtc/tq9dspuJ/xLIoQlKEb6OHJXDPG3F2j8a1pcAvDUX5xuIGEDS9fzp+AZ/1J50XNn2FjJmhudptMfiqG9qxe6GltbmttitiDd95vQVa/7e39cnBpfQArpVFDmfQXnaSYbdEhXAntH53duW/ijtKFFZ1peJKLL39Qw35OnwnE23c+aEODDeQKrnuGFEGBzMHlbCqd0fUozKIKbdAYCJzxhz1jUfD+JYfXHG8vUvWYbPA3jDcI9g2hh/1N7UirrUWrvrehLcA9C5rOGPxP0gvquhGc1tHSbpeGscw+dOr1rzvyc990YOsofFUBNaQCeyzwGYnJYQW6Luc0K857XHH0731EduvvcYZVk9pnB1IrxkOOMkQy1ru8+5etkGyMCrnf8dtVxFoECqsRFwArA3MQ4AYnGzKqhpdwIpIutm5LA88bQVNe/kefgkA08CvXW6GT5cT+9Za69vakVbLA4nFdxF3zAzjDFwHBdtHXHUNbWmchdiSLoeDNBEBj9wWjHnzOVrX+7v6xWDVygflpNvuiuPFJ1hPBdeiFvCOjGDwXxfptF5JFJwA3Wp2Q4AOsTOZ34XudwlT7NJn+HuP4lXOv/TMAVWYYoIRxTP7JIYB6Dj5cW7ibAhuFPQuaUz50/d/0uDc9Jza3frZr4aoJ+AEf5+w0GC4W99a22Po66xBXWpZLpE0pE19246R+GepxGLJ/fsKtjd1IrWjngqAREAoAl4EcD5pyxf+4NZa9bIWrnISigBPeJGjiGlRjttbblZQybsdsgsSvfUlOt+Mdqy1Oe7P+6FODpno0OvU9/9fGkfZ3a03jtCJ5sKAzsnkB+17cndHjZseEVgn+6EQtumLwRyrAMws6YmvmXZmu+C+QYwZ9vQZshh+CP39lgC9c1t2N3QgsaWdrR3jt6HYYD3p9E14okkWtpjqGtswa7GFjS2tiOWSMLT3SZ8GDsNzC2NXtsnpy9b84psRxNBsPf/koM4aF5kKhjkxXKzdg7w77c/lmbfOQBrxKgLoGj8vt/Doe09z30yHMNknB2mLc1RvWvPn6CC697ErGBwHIC13Z5YBVIOgIC2nalLi6bPW9Cx/tFd+39tcC4FNJav/d2GC2b+i4EHCXyiX4ZTdKeNQTzpIJ50QAAsSyFi24hG/C/btqC6/NMN1n/GrjcpnQHc9Tw4rv//nt7PjYz/pMfA0yDvu2cs2/BW+FcthpNQArqy7cleIkbs5WLfOXc4nvdA2ifLyy1lW/MJtM9MhHbdUPfE5yoZDkh9RmT+EHkF1Yv33LmwoZEU0JyM30+Fj+n+eL3X/o9x0ZKdAB0ZzHkwqiBacHUH8NMgjnegTl++9uW/zvnouS4X/JyAeaBwfmeGCoa/x93TfoAHAEUE27YQ2fNlw7IUlFJ7looGWpDvDMz++jfD0xqe1nC7BO8DyyNgA8JGsPl2LL6uanb10G4SJPpHOB9OjGPCbHay76no+W1P3rYx3XNTxpUdpZSatc/rQxydA4BxXeTiRqZTpul2AGDwPqNnZjMqyFUWIjq6x4M1lXFz9nV/VYQjAzuRomsw7aJfofbZcPrb7scpVa/WPT5lyvWTJpW+DFAFMUpBudlSNxQYZjiuB8fd+3tBRLCUgm0pWJaCbVuwlQXLUrAUgYj2CfJBB/w9ATv132wY2hh42kCngrfWBp4xqSWErE7WyIy74Xp3T39hQ/idqcSwFUpAJ8KYsHqLd8WANtC/QYb1Jyu/+BIi6lEX3HNCnG7Pwd+7q0wZ7sxwtcFLXR9TSo0J8txENBFYoIB9O9oReC1AFwd3Jv7w2OKx59QDfwrumAfm0o0bHWzE3evnnlkD8G8IOIUR1HzH8MO8d9TbHRGgSIEUwSKCUgoqFeSVIv85AgipoJ8h1nNqL2tnkppJZZubLgG887/DydrnOBjPKM3fP/W5mn+GcAIh9hFKQPeS8Qk52bLF/I/NrY0r0z5X/rhlWYlLenyL0eG1Mg159N/zdJx5hE68ozluv93tGw5BgCMdBh+GGRvzULNvPXQP9LLNzBTQsIpAFlhdC2ApkH3p2mxMX7bmlTcunHV+wpgFIL4BCC7RUPiYAc0GMBiU89IMaGLewMwVp5fUPE+VyM3+VTHshTLC8BKJ/P2/Kjv+jTX9FlV3p00nP2Fc3bGkqMeWJy+k7PM9U/k5zu41mWq4M61D7f37ThcoOizQkzNGlTh2UfeHdUdsI0DBJhIQnTdy1rVHBnrMgzR16UtNW6rW3sLgzwN4a9ildIv0mJmZ34Ex/9ERbz5/+vKaFRLMRS6FEtB1MpGDxCFugZeszPQs5efPAahHprVOhredTOdw7znQOd2ePpYYY1akeXh8mseyQIUqLzqy+6Nttcc2gnhbsOdCcVRhXsDHPGiXAnr6sppnEzpRBuBB2bM+jDEzg98n4HtWPDlj+vKah2ZXbxx2DX9E/wsloBsnkYum59Wbn7o9Q+3tBUpZkfO6z/gyM7QTUu12L3eNWPacM3NCXEID3ZYiyi0wHxHwJSiLaFzPhysMpVq2BorUZWF3YTtQZ6+o3dkRX/tFhpkHltH6MNRExHdEjZl1WtXa20+trq3v7wsSw1coAd31zOe10XezMduYoTngLlZ+rotekun5KdeNLCVSp3d/3Hgu0EtWeDa8RG6T4ZgZJsPWO2b+W8tLm/cdIZehgBDwlDuYlLLSJtoZQ4EnATHw4bGHHXrG/l+ZW7Or4U2vqnk6gdgsgO4Eo0MC+xDmZ9m1EMy9xvWmn7as5paPLl+3pb8vS4hQAvq2J2/7++bHK74ci7VNM9qbZ7R+2DBvZmYniOBO4KaOpo50U8oAAFNYfCIRjer+eGijczah1oXPJGMNd8JyoHqfaD/WLTmCCT0y/rNBRMQKo9M9x2zeDvpGjgAbpAbMtHt3Z1e9Wnda1ZpbAHMhQGulHvwQ4xd9aAXjIUV81rPLar50xp/Xvw2p8iYGiDDXunnnsz+vB1AJ4InRcxaUjCh0PkLKPg2kTlNQx4MwnoiKAUQZUOAMNxgEJoZhsAYQZ2Me2/XczzJO60ftyJmUZp+wDmlKXCeTQKbktJAY7YHRc8cOMztseGmPbyBzLFipILPc/Qvh0nQPk8JWIO0lZodwYenJ80ubX1vcHOhxA0KAQVXNytfPn/oJxyq6gYH/BnDYgKucIvqOmUHUDMaTnst3rXi+5u8V/bzbQoh0clX1ihurKlobgfXwv4DycusId3JpRGEcyDqUCGOJ6RAGCkFEqV1PzAYOmFtI8Q543GwUb98ab2vs7WSk6LTujzEzTAjb1fy957lNhgMAY7xMkfKdBt3+RvcHWanjQ4kopEakfVjT+7DYAyga6OmYj7BHWmehH/ek90Wq/eUdNRec8bSC+g6Ay4i4CIHfUYnQMDMTdhPwe036vhnL1wWfFyJEgPqvjGVlpX4faID/Feh6K5E6ofO/O5cytRNOdzXWOvfJcMzQafb5+8m29CxqKnvcYRDoxHSzFlkj3WPbGgAkFDfmE8UABBrQUzd7n8MAD+idZixft+Vx4AtHf+LMh7XCAhDKAATSwlaExB+Rbwd4sZN0fzvzhVc2S/MUMRgMvUpXN94YgaUmMjO06yLZ2oa2D3ahdccH0K4ONFfJb8QS74e95zr98iyRdmEe6/H4tBsjfv/yMC6G0jZ8affa2wEKZesOgS7CjPJA8wHCdCmgp61Ys1rtTs4hw1cC/Jqsrw9AzC6YXwHjvzjpnnJ6Vc2Cs154ZZMEczFYDLlGE5Pix4xPWu2WG+uATjrgLmvb2jNQdrD3MLlsxAL0nt0O8N9bVre/3v3RsYWxsYzoUaGUH8+0NlxTmcTZ/94azgwzjxptF5/dCGRMjByITq2tdQH8fvWsE1fkjSi+GoybARwl6+v9ixjtDPwFMA8WxltfPEH2kItBasiN0Lcuad8aq69/2Ysn9gnmAPyajAGO0o3jICclbrvRumcugD/djiVAZY8LMmyfBCC41qldEWc6LhOoKZRzAiBSF4V17LCd9dLfmk5fVnOncfRMgBcA/L5sc8sh/99aM/MWMP+cyMzsiEcuOb1q3Z8kmIvBbMiN0IEKY7yKH6mI/RT1uGEhGM/AslXWuUnMnPO95wBgtE4/xU/U6iX1k+m+R1lqJoWUjKUy7Uzwr7IljJP6NeL5XEwpj2JjZW4TGAJ0xgvrdwG4bfW5034bsfNuUMD1AH9IRuwhYWYGdRCwhjQ/wp637HTpfiaGkCEY0AGryaww40wtkeqR7Q74o3QrSll9brIxMCGWkU17TmZo3TN+sT/iWNG8bnG6ynkExsf6p9kntwe9a60TgY4cVTri2CbgzVBOkENnPV+7DcCta+bOfNBm3EDM10K2ugXDD+KaiN9hgyeZvMe3bmv756UbNw7aG0EhMhmSAX1LdUVi4sULfsJ29PfUI6OYYDRDGQZZB/l5yQzTD41YMq6fE2l2zX1Ik7wzYsZ1owCcGtY1GVDGrQMMiocWkZjzVITPwhAI6Cl85rK1WwF8d9050+9WUetKMF8L0HGgofl7Ghr/BtcD8D6A58joSq+V1sysqcn9/lIhcmjIflBs29m6dNL4MX8D0ck9nyVoV4PUwY3SGYCX473nzAztZRhUML/REN28Kt1TEYs/BqAgrJEyYDKuOxA4Gdp5/Xn3swD8JpwT9J/UVPzPXzl32oMmkn8BM/87AbMAFMiovVcajB0MelEZfoqSyTWnVtc2QLLUxTAxZAM6an4Z1xd//6eWHVnScy0dYMNgbUD2gW8JNp4L9kLqqZ4RZ0yGY+BOVFenHSkrC58Kt5iJ6rf2kMSYjmk3RlB7f65/GDlx6vO1LQAeexx4YtInTj+BlD0P4E+D6WgQIv19ff3On05PgnizYl7pgZ9hQ+tnrqjptfCUEEPV0A3oALSz42lLTXgTSvXoiw4QtGdAljqwQU9/VIZjhvbcDFP89G6Dan0q3beNK/tiMXPy3FCHdMw56KyXAdERpXn68GYgQ9e9oeFSQGPFhtcBvP5i2ck/KswrPBOEz5CicxiY2HNZaegisGFGE4DXQXgRhl9g6L+fVrW+tb+vTYj+NqQD+s5n74+Nv7jiLkup+zON0o02UAcQ1JkZOpnbRiwMhpemGh377kR1ZdqtNp6JnW2ROiy86XYgrOIxfcHMUYpgCoZ4QO9qdvVrzQCWamDZqrJpY4oLIqcxqYsYmE1M/wZwlAjgoVBilplBYDDamOgdxbzWML/oOfTXvJbkjtS+fiFEypAO6ACQ8DoeL7JGfAVEaSqlEbTrB/Q+6QzmOWzEwtwZzNMuA75jYpGMbWQtsuaFPnpjtGR8jijUOgdERBbjeABVYZ5nILIAht97uwpA1evnTy1yrKJjwarMwJwF4KN+u1yODpp1d2aGP4VeD8a/QPQyG7MhouivH/CuD+ZWvZPbbSVCDDJDPqDXP/OTtsKLK+6BZf8mbS1zZhhPQ9nWfj/3GLmtDMfMYGPSJsOlCsn8oqn2/rQBtei0+YcScEHY10gwvRSP4aJwZwcAgI8O+QSDQqoZzKsAXn0cuGv8J2aMBHiyBT6FlDodRFPBfBSIRoB5/2/2EFGqDymABDPqCHgH4DdB9DoMv6ms5GbsRIuMwIU4MEM+oAOA65gl0QL+OkCTez5L0C5DWbzf3DH2PJiQeqpn4rqJ9D1ICW/Uu22/zfR9+YWqnJnHhPm5zcxsLK7P/ArKQb11mhj+OQYXf829phHAhtTXvS+WwS7BtFLkRSZqiz5MTB8GcDQRJhnmDxFRKTPyiTgKkAJYgXFg20D8piaGGUyAZrBDoAQITQDqwPweA1vY0DuK9DvkuZt2NKG+trY2Ie1IhcjesAjoO5+tiE24pOIXyrLvSbeWDjC0Z2BFMn9+7WnEkiP+VHsSbHSanudwmc3303VVAwBMnpOnmK5HKMXbuyAYw1YvAZ2LczBCHxPyCYaE2dXwgNp6APUA/goAGqBVZWVWxHUL8osTxUnOG2MTjWLwaCJTClIjFKOEGcWsYBO4iMF7fn+IVYJAjiETV6AOQ9RGrNsUW02a0Gg0NxcBjZbTHKvDIYmzq6u1NDoRIjzDIqADQJs2j45UfAuI0kzR+iVhld17cpyXCD8Zzq+JwdCel3GqnYFnGmJ/W5rpGGMOO/QCJj4+/HhOnkom6jI+DZSGegE+2b51kPx1+GoPQFvqa2d4Z9sY3qGFEACGYHOWTJqfrmhm7d7DnGmEQL02bjHJJGCC33LNzKkKcBqe68B14kgmOuC56W8eiKjBMd63kWl9cUp5lIi+TKBcbGVqBpBhu1C5IlAOAjrJiE8IITCMAjoAtMexEDA7Mj3Pmv2CM92CelCNWDqDNzPDGAPPc+E5CTiJDjhJP4gb7WUsKcsMow3f3vbSw29lOse4sUXnAjQr64vtC0ZdY8H7af9hxp5ZUuhPuYeLCFJERAghMMwCemNVRSuY79jf3MLTdgAAB0tJREFUKL071vqgk+H2BnEDoz14bhJOIgYn0Q7PiUNrF8z7zwfyZ9q5qnHnzsylTqeURxnqVspRFTEm3oLq6vTTFsopZqaisK/BMGe8uRFCiOFkWAV0ANBteiHYvJ/p+c5iM11H6foAG7F0BnGtPXieAzcZQzLeAdeJQ3sOmA9m6p62u3BvwjtVGffijhlbPA+gtB3mwsDM7yJDkpNLlA/ADbPPt3+TY/4S1vGFEGIwGXYB/b0VFY2Gzb29j9L3jpj7kt2+dxo9tQ6ejCOZaIebjEG7SRijkU1yL4M7DPiGllVLNmd6TeFZVx6miL5PlJufKTMzmcyZTi2rlmxh0CzDuIcZO5iD3ZaU+vn9q6G+47kgjyuEEIPVsAvoAJB0kw8CJnNGb6rYDAAY1wF7Xren910HdzvXwVPJbMZkXgc/UMzssOFvNq5a2FvgUoUUvZUZkwI5aV8QGU3m7728ghtWPfiPhtULvwzNp7HRN7Hhlxho5yxH7anlhzoGfwkb05e9FUKI4WbYNHXoquNfqztGfrisBEp9jNJulCawAZRF8Do6YNxUQnlqFK49F57n+KNv7aXWwIOfWfb3m6OiYXX7HcDGjCcYPeu6TxDhJ0SUu22IjJhrJb7nbHlzv9mCse2vtsW3vfZyrHjyI9H86J+IsA1AFKASEKJgJupDARO/uRa1MtOfjGeub1yzeH0gfxchhBgChs0+9O4SXvLeAsv6EojGpX8Fw3M8uPEOGM+F1h7YhBO495yRYQBuBehdEDYw47mG1QufwX6qaDGh1K/ulUOEd9qqHz2wDPONlU4z8Dr8r5+MLrvicOVFT4aiU8E4kWEmEdEYBhUQsw0QMyEBRiMB7zDxSsfDirY1C9+CFCgRQoh9DI6mDSGZdEnFD2HZ304/Sge8eBuSrZnqpgSFO5jxLhjrQVQNzbX1pm1bxipwaZVbY88u+TWAG/oy0g0CM+6rX/XQFwI8JKFsfl5JzBRFSBcYithQFrs6lujwStpQe38CUh5UCCEyGrYjdABwPee+CKkboNQh3Z9jZrjxtsDOxWAGEwPcDqJ3wdgA6FUO8HLrNmzHlsVZlKGr1Lqj/BtW4YhjGfhY2iY0gdOrAj4go3pxog3IbW9aIYQYIob1CB0AJlzyg58qZd3SPQga10G88X1klZ3OzASKA/wug9YCvBoar9S3ue/hjSUd2V57d6Uzr5tk2/xnIjom6GPvgznuaffDTWuWbAv1PEIIIfpsWI/QAUB7ybtUtOA6gEZ1PsbM8JLtOKBg7mdsMQEJEDYZNhtgVDVr/XJDh96ON5bEDuyAB6557UNbx57575ezzU8T4/AQW2S+1hTZnrHinhBCiNwb9iN0AJh4ScUdpOybO0fpzAbxhvfA2uv1+1J7qzuIeCuD1jGbl0jTugNfAw/W2LL5ZWTUYyDqsZSQLQYzMd1at+qhHwZ9bCGEEAdv2I/QAYC1ezcpdQ2gSgHAOIkewbxz7zQBCQZtJ6DGQK+C5vWNibzNqL0/jgGSeV1fvbh6zKxrr1AWPQrmMUGO1ImR8Dw8HdTxhBBCBENG6CkTP1dxF5H9XwBTsqUOOtm+ZwQOwjZmrgXjRZBa37Dj/U29lWAdKMaede3HQOp3RBgf1DGZ+YX6VW2fACqDbz0nhBDioMkIPcVz3F9F861rWJs87cS3GOb1DFrJ7L7SpOKbsHLwVSSrX71o5cizrv10hOgRAMcRshup+0l+/IAEcyGEGHhkhN7FxM8uuMjT5n239Z9v11VXdmCATKFna9SZV020rMi9AH0im1rvhvlvDcqcjupsttgJIYQIgwT04WJKefHYcSXfANNXAS460AI0zHANzFWNqxY9FtYlCiGEOHjDspb7sFS30YltfXVldOLJaxTRFIAO72sBGn+qHU831LffjrqNMt0uhBADkAT04YUT217bGht5wqOF+dZ2AEeDeDT1Ugc+FczfZHYuj9X+viWH1yqEEOIAyJT7MFZ68vxSq4QuIqWuAGM6gJFd19gZ0GBe47h0XWvNQ+/046UKIYTYDwnoAgBozIyrDzdKnaRsezLBjIUhZqNfb0jUL0fts/ttkSqEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEIIIYQQQgghhBBCCCGEEEKE5/8Dg+uBQCiEMh8AAAAASUVORK5CYII="></image></svg>
\ No newline at end of file
diff --git a/web/frontend/public/lark.svg b/web/frontend/public/lark.svg
new file mode 100644
index 000000000..0761f278f
--- /dev/null
+++ b/web/frontend/public/lark.svg
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><svg width="24" height="24" viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M17 29C21 29 25 26.9339 28 23.4065C36 14 41.4242 16.8166 44 17.9998C38.5 20.9998 40.5 29.6233 33 35.9998C28.382 39.9259 23.4945 41.014 19 41C12.5231 40.9799 6.86226 37.7637 4 35.4063V16.9998" stroke="#000" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/><path d="M5.64808 15.8669C5.02231 14.9567 3.77715 14.7261 2.86694 15.3519C1.95673 15.9777 1.72615 17.2228 2.35192 18.1331L5.64808 15.8669ZM36.0021 35.7309C36.958 35.1774 37.2843 33.9539 36.7309 32.9979C36.1774 32.042 34.9539 31.7157 33.9979 32.2691L36.0021 35.7309ZM2.35192 18.1331C5.2435 22.339 10.7992 28.144 16.8865 32.2239C19.9345 34.2667 23.217 35.946 26.449 36.7324C29.6946 37.522 33.0451 37.4428 36.0021 35.7309L33.9979 32.2691C32.2049 33.3072 29.9929 33.478 27.3947 32.8458C24.783 32.2103 21.9405 30.7958 19.1135 28.9011C13.4508 25.106 8.2565 19.661 5.64808 15.8669L2.35192 18.1331Z" fill="#000"/><path d="M33.5947 17C32.84 14.7027 30.8551 9.94054 27.5947 7H11.5947C15.2174 10.6757 23.0002 16 27.0002 24" stroke="#000" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/></svg>
diff --git a/web/frontend/public/logo_with_text.png b/web/frontend/public/logo_with_text.png
new file mode 100644
index 000000000..70f26788c
Binary files /dev/null and b/web/frontend/public/logo_with_text.png differ
diff --git a/web/frontend/public/site.webmanifest b/web/frontend/public/site.webmanifest
new file mode 100644
index 000000000..981d97f15
--- /dev/null
+++ b/web/frontend/public/site.webmanifest
@@ -0,0 +1,21 @@
+{
+  "name": "MyWebSite",
+  "short_name": "MySite",
+  "icons": [
+    {
+      "src": "/web-app-manifest-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "maskable"
+    },
+    {
+      "src": "/web-app-manifest-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ],
+  "theme_color": "#ffffff",
+  "background_color": "#ffffff",
+  "display": "standalone"
+}
diff --git a/web/frontend/public/web-app-manifest-192x192.png b/web/frontend/public/web-app-manifest-192x192.png
new file mode 100644
index 000000000..01933339b
Binary files /dev/null and b/web/frontend/public/web-app-manifest-192x192.png differ
diff --git a/web/frontend/public/web-app-manifest-512x512.png b/web/frontend/public/web-app-manifest-512x512.png
new file mode 100644
index 000000000..e0b4aab9c
Binary files /dev/null and b/web/frontend/public/web-app-manifest-512x512.png differ
diff --git a/web/frontend/scripts/ensure-backend-gitkeep.cjs b/web/frontend/scripts/ensure-backend-gitkeep.cjs
new file mode 100644
index 000000000..db9782ab4
--- /dev/null
+++ b/web/frontend/scripts/ensure-backend-gitkeep.cjs
@@ -0,0 +1,9 @@
+const fs = require("node:fs")
+const path = require("node:path")
+
+const gitkeepPath = path.resolve(__dirname, "../../backend/dist/.gitkeep")
+const gitkeepContents =
+  "# Keep the embedded web backend dist directory in version control.\n"
+
+fs.mkdirSync(path.dirname(gitkeepPath), { recursive: true })
+fs.writeFileSync(gitkeepPath, gitkeepContents)
diff --git a/web/frontend/src/api/channels.ts b/web/frontend/src/api/channels.ts
new file mode 100644
index 000000000..d4c3ac74b
--- /dev/null
+++ b/web/frontend/src/api/channels.ts
@@ -0,0 +1,87 @@
+// API client for channels navigation and channel-specific config flows.
+
+export type ChannelConfig = Record<string, unknown>
+export type AppConfig = Record<string, unknown>
+
+export interface SupportedChannel {
+  name: string
+  display_name?: string
+  config_key: string
+  variant?: string
+}
+
+interface ChannelsCatalogResponse {
+  channels: SupportedChannel[]
+}
+
+interface ConfigActionResponse {
+  status: string
+  errors?: string[]
+}
+
+const BASE_URL = ""
+
+async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(`${BASE_URL}${path}`, options)
+  if (!res.ok) {
+    let message = `API error: ${res.status} ${res.statusText}`
+    try {
+      const body = (await res.json()) as {
+        error?: string
+        errors?: string[]
+        status?: string
+      }
+      if (Array.isArray(body.errors) && body.errors.length > 0) {
+        message = body.errors.join("; ")
+      } else if (typeof body.error === "string" && body.error.trim() !== "") {
+        message = body.error
+      }
+    } catch {
+      // Keep default fallback message if response body is not JSON.
+    }
+    throw new Error(message)
+  }
+  return res.json() as Promise<T>
+}
+
+export async function getChannelsCatalog(): Promise<ChannelsCatalogResponse> {
+  return request<ChannelsCatalogResponse>("/api/channels/catalog")
+}
+
+export async function getAppConfig(): Promise<AppConfig> {
+  return request<AppConfig>("/api/config")
+}
+
+export async function patchAppConfig(
+  patch: Record<string, unknown>,
+): Promise<ConfigActionResponse> {
+  return request<ConfigActionResponse>("/api/config", {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(patch),
+  })
+}
+
+// WeChat QR login flow API
+
+export interface WeixinFlowResponse {
+  flow_id: string
+  status: "wait" | "scaned" | "confirmed" | "expired" | "error"
+  qr_data_uri?: string
+  account_id?: string
+  error?: string
+}
+
+export async function startWeixinFlow(): Promise<WeixinFlowResponse> {
+  return request<WeixinFlowResponse>("/api/weixin/flows", { method: "POST" })
+}
+
+export async function pollWeixinFlow(
+  flowID: string,
+): Promise<WeixinFlowResponse> {
+  return request<WeixinFlowResponse>(
+    `/api/weixin/flows/${encodeURIComponent(flowID)}`,
+  )
+}
+
+export type { ChannelsCatalogResponse, ConfigActionResponse }
diff --git a/web/frontend/src/api/gateway.ts b/web/frontend/src/api/gateway.ts
new file mode 100644
index 000000000..9e02a02b5
--- /dev/null
+++ b/web/frontend/src/api/gateway.ts
@@ -0,0 +1,84 @@
+// API client for gateway process management.
+
+interface GatewayStatusResponse {
+  gateway_status: "running" | "starting" | "restarting" | "stopped" | "error"
+  gateway_start_allowed?: boolean
+  gateway_start_reason?: string
+  gateway_restart_required?: boolean
+  pid?: number
+  boot_default_model?: string
+  config_default_model?: string
+  [key: string]: unknown
+}
+
+interface GatewayLogsResponse {
+  logs?: string[]
+  log_total?: number
+  log_run_id?: number
+}
+
+interface GatewayActionResponse {
+  status: string
+  pid?: number
+  log_total?: number
+  log_run_id?: number
+}
+
+const BASE_URL = ""
+
+async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(`${BASE_URL}${path}`, options)
+  if (!res.ok) {
+    throw new Error(`API error: ${res.status} ${res.statusText}`)
+  }
+  return res.json() as Promise<T>
+}
+
+export async function getGatewayStatus(): Promise<GatewayStatusResponse> {
+  return request<GatewayStatusResponse>("/api/gateway/status")
+}
+
+export async function getGatewayLogs(options?: {
+  log_offset?: number
+  log_run_id?: number
+}): Promise<GatewayLogsResponse> {
+  const params = new URLSearchParams()
+  if (options?.log_offset !== undefined) {
+    params.set("log_offset", options.log_offset.toString())
+  }
+  if (options?.log_run_id !== undefined) {
+    params.set("log_run_id", options.log_run_id.toString())
+  }
+  const queryString = params.toString() ? `?${params.toString()}` : ""
+  return request<GatewayLogsResponse>(`/api/gateway/logs${queryString}`)
+}
+
+export async function startGateway(): Promise<GatewayActionResponse> {
+  return request<GatewayActionResponse>("/api/gateway/start", {
+    method: "POST",
+  })
+}
+
+export async function stopGateway(): Promise<GatewayActionResponse> {
+  return request<GatewayActionResponse>("/api/gateway/stop", {
+    method: "POST",
+  })
+}
+
+export async function restartGateway(): Promise<GatewayActionResponse> {
+  return request<GatewayActionResponse>("/api/gateway/restart", {
+    method: "POST",
+  })
+}
+
+export async function clearGatewayLogs(): Promise<GatewayActionResponse> {
+  return request<GatewayActionResponse>("/api/gateway/logs/clear", {
+    method: "POST",
+  })
+}
+
+export type {
+  GatewayStatusResponse,
+  GatewayLogsResponse,
+  GatewayActionResponse,
+}
diff --git a/web/frontend/src/api/models.ts b/web/frontend/src/api/models.ts
new file mode 100644
index 000000000..aa66a7389
--- /dev/null
+++ b/web/frontend/src/api/models.ts
@@ -0,0 +1,93 @@
+import { refreshGatewayState } from "@/store/gateway"
+
+// API client for model list management.
+
+export interface ModelInfo {
+  index: number
+  model_name: string
+  model: string
+  api_base?: string
+  api_key: string
+  proxy?: string
+  auth_method?: string
+  // Advanced fields
+  connect_mode?: string
+  workspace?: string
+  rpm?: number
+  max_tokens_field?: string
+  request_timeout?: number
+  thinking_level?: string
+  extra_body?: Record<string, unknown>
+  // Meta
+  configured: boolean
+  is_default: boolean
+  is_virtual: boolean
+}
+
+interface ModelsListResponse {
+  models: ModelInfo[]
+  total: number
+  default_model: string
+}
+
+interface ModelActionResponse {
+  status: string
+  index?: number
+  default_model?: string
+}
+
+const BASE_URL = ""
+
+async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(`${BASE_URL}${path}`, options)
+  if (!res.ok) {
+    throw new Error(`API error: ${res.status} ${res.statusText}`)
+  }
+  return res.json() as Promise<T>
+}
+
+export async function getModels(): Promise<ModelsListResponse> {
+  return request<ModelsListResponse>("/api/models")
+}
+
+export async function addModel(
+  model: Partial<ModelInfo>,
+): Promise<ModelActionResponse> {
+  return request<ModelActionResponse>("/api/models", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(model),
+  })
+}
+
+export async function updateModel(
+  index: number,
+  model: Partial<ModelInfo>,
+): Promise<ModelActionResponse> {
+  return request<ModelActionResponse>(`/api/models/${index}`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(model),
+  })
+}
+
+export async function deleteModel(index: number): Promise<ModelActionResponse> {
+  return request<ModelActionResponse>(`/api/models/${index}`, {
+    method: "DELETE",
+  })
+}
+
+export async function setDefaultModel(
+  modelName: string,
+): Promise<ModelActionResponse> {
+  const response = await request<ModelActionResponse>("/api/models/default", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ model_name: modelName }),
+  })
+
+  await refreshGatewayState()
+  return response
+}
+
+export type { ModelsListResponse, ModelActionResponse }
diff --git a/web/frontend/src/api/oauth.ts b/web/frontend/src/api/oauth.ts
new file mode 100644
index 000000000..a1ed1afcb
--- /dev/null
+++ b/web/frontend/src/api/oauth.ts
@@ -0,0 +1,102 @@
+export type OAuthProvider = "openai" | "anthropic" | "google-antigravity"
+export type OAuthMethod = "browser" | "device_code" | "token"
+
+export interface OAuthProviderStatus {
+  provider: OAuthProvider
+  display_name: string
+  methods: OAuthMethod[]
+  logged_in: boolean
+  status: "connected" | "expired" | "needs_refresh" | "not_logged_in"
+  auth_method?: string
+  expires_at?: string
+  account_id?: string
+  email?: string
+  project_id?: string
+}
+
+export interface OAuthFlowState {
+  flow_id: string
+  provider: OAuthProvider
+  method: OAuthMethod
+  status: "pending" | "success" | "error" | "expired"
+  expires_at?: string
+  error?: string
+  user_code?: string
+  verify_url?: string
+  interval?: number
+}
+
+export interface OAuthLoginRequest {
+  provider: OAuthProvider
+  method: OAuthMethod
+  token?: string
+}
+
+export interface OAuthLoginResponse {
+  status: string
+  provider: OAuthProvider
+  method: OAuthMethod
+  flow_id?: string
+  auth_url?: string
+  user_code?: string
+  verify_url?: string
+  interval?: number
+  expires_at?: string
+}
+
+interface OAuthProvidersResponse {
+  providers: OAuthProviderStatus[]
+}
+
+const BASE_URL = ""
+
+async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(`${BASE_URL}${path}`, options)
+  if (!res.ok) {
+    const message = await res.text()
+    throw new Error(message || `API error: ${res.status} ${res.statusText}`)
+  }
+  return res.json() as Promise<T>
+}
+
+export async function getOAuthProviders(): Promise<OAuthProvidersResponse> {
+  return request<OAuthProvidersResponse>("/api/oauth/providers")
+}
+
+export async function loginOAuth(
+  payload: OAuthLoginRequest,
+): Promise<OAuthLoginResponse> {
+  return request<OAuthLoginResponse>("/api/oauth/login", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  })
+}
+
+export async function getOAuthFlow(flowID: string): Promise<OAuthFlowState> {
+  return request<OAuthFlowState>(
+    `/api/oauth/flows/${encodeURIComponent(flowID)}`,
+  )
+}
+
+export async function pollOAuthFlow(flowID: string): Promise<OAuthFlowState> {
+  return request<OAuthFlowState>(
+    `/api/oauth/flows/${encodeURIComponent(flowID)}/poll`,
+    {
+      method: "POST",
+    },
+  )
+}
+
+export async function logoutOAuth(
+  provider: OAuthProvider,
+): Promise<{ status: string; provider: OAuthProvider }> {
+  return request<{ status: string; provider: OAuthProvider }>(
+    "/api/oauth/logout",
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ provider }),
+    },
+  )
+}
diff --git a/web/frontend/src/api/pico.ts b/web/frontend/src/api/pico.ts
new file mode 100644
index 000000000..9a1a553d5
--- /dev/null
+++ b/web/frontend/src/api/pico.ts
@@ -0,0 +1,38 @@
+// API client for Pico Channel configuration.
+
+interface PicoTokenResponse {
+  token: string
+  ws_url: string
+  enabled: boolean
+}
+
+interface PicoSetupResponse {
+  token: string
+  ws_url: string
+  enabled: boolean
+  changed: boolean
+}
+
+const BASE_URL = ""
+
+async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(`${BASE_URL}${path}`, options)
+  if (!res.ok) {
+    throw new Error(`API error: ${res.status} ${res.statusText}`)
+  }
+  return res.json() as Promise<T>
+}
+
+export async function getPicoToken(): Promise<PicoTokenResponse> {
+  return request<PicoTokenResponse>("/api/pico/token")
+}
+
+export async function regenPicoToken(): Promise<PicoTokenResponse> {
+  return request<PicoTokenResponse>("/api/pico/token", { method: "POST" })
+}
+
+export async function setupPico(): Promise<PicoSetupResponse> {
+  return request<PicoSetupResponse>("/api/pico/setup", { method: "POST" })
+}
+
+export type { PicoTokenResponse, PicoSetupResponse }
diff --git a/web/frontend/src/api/sessions.ts b/web/frontend/src/api/sessions.ts
new file mode 100644
index 000000000..10b0d28fd
--- /dev/null
+++ b/web/frontend/src/api/sessions.ts
@@ -0,0 +1,51 @@
+// Sessions API — list and retrieve chat session history
+
+export interface SessionSummary {
+  id: string
+  title: string
+  preview: string
+  message_count: number
+  created: string
+  updated: string
+}
+
+export interface SessionDetail {
+  id: string
+  messages: { role: "user" | "assistant"; content: string }[]
+  summary: string
+  created: string
+  updated: string
+}
+
+export async function getSessions(
+  offset: number = 0,
+  limit: number = 20,
+): Promise<SessionSummary[]> {
+  const params = new URLSearchParams({
+    offset: offset.toString(),
+    limit: limit.toString(),
+  })
+
+  const res = await fetch(`/api/sessions?${params.toString()}`)
+  if (!res.ok) {
+    throw new Error(`Failed to fetch sessions: ${res.status}`)
+  }
+  return res.json()
+}
+
+export async function getSessionHistory(id: string): Promise<SessionDetail> {
+  const res = await fetch(`/api/sessions/${encodeURIComponent(id)}`)
+  if (!res.ok) {
+    throw new Error(`Failed to fetch session ${id}: ${res.status}`)
+  }
+  return res.json()
+}
+
+export async function deleteSession(id: string): Promise<void> {
+  const res = await fetch(`/api/sessions/${encodeURIComponent(id)}`, {
+    method: "DELETE",
+  })
+  if (!res.ok) {
+    throw new Error(`Failed to delete session ${id}: ${res.status}`)
+  }
+}
diff --git a/web/frontend/src/api/skills.ts b/web/frontend/src/api/skills.ts
new file mode 100644
index 000000000..307cbd788
--- /dev/null
+++ b/web/frontend/src/api/skills.ts
@@ -0,0 +1,79 @@
+export interface SkillSupportItem {
+  name: string
+  path: string
+  source: "workspace" | "global" | "builtin" | string
+  description: string
+}
+
+export interface SkillDetailResponse extends SkillSupportItem {
+  content: string
+}
+
+interface SkillsResponse {
+  skills: SkillSupportItem[]
+}
+
+interface SkillActionResponse {
+  status?: string
+  name?: string
+  path?: string
+  source?: string
+  description?: string
+}
+
+async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(path, options)
+  if (!res.ok) {
+    throw new Error(await extractErrorMessage(res))
+  }
+  return res.json() as Promise<T>
+}
+
+export async function getSkills(): Promise<SkillsResponse> {
+  return request<SkillsResponse>("/api/skills")
+}
+
+export async function getSkill(name: string): Promise<SkillDetailResponse> {
+  return request<SkillDetailResponse>(`/api/skills/${encodeURIComponent(name)}`)
+}
+
+export async function importSkill(file: File): Promise<SkillActionResponse> {
+  const formData = new FormData()
+  formData.set("file", file)
+
+  const res = await fetch("/api/skills/import", {
+    method: "POST",
+    body: formData,
+  })
+  if (!res.ok) {
+    throw new Error(await extractErrorMessage(res))
+  }
+  return res.json() as Promise<SkillActionResponse>
+}
+
+export async function deleteSkill(name: string): Promise<SkillActionResponse> {
+  return request<SkillActionResponse>(
+    `/api/skills/${encodeURIComponent(name)}`,
+    {
+      method: "DELETE",
+    },
+  )
+}
+
+async function extractErrorMessage(res: Response): Promise<string> {
+  try {
+    const body = (await res.json()) as {
+      error?: string
+      errors?: string[]
+    }
+    if (Array.isArray(body.errors) && body.errors.length > 0) {
+      return body.errors.join("; ")
+    }
+    if (typeof body.error === "string" && body.error.trim() !== "") {
+      return body.error
+    }
+  } catch {
+    // ignore invalid body
+  }
+  return `API error: ${res.status} ${res.statusText}`
+}
diff --git a/web/frontend/src/api/system.ts b/web/frontend/src/api/system.ts
new file mode 100644
index 000000000..543c8694d
--- /dev/null
+++ b/web/frontend/src/api/system.ts
@@ -0,0 +1,62 @@
+export interface AutoStartStatus {
+  enabled: boolean
+  supported: boolean
+  platform: string
+  message?: string
+}
+
+export interface LauncherConfig {
+  port: number
+  public: boolean
+  allowed_cidrs: string[]
+}
+
+async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(path, options)
+  if (!res.ok) {
+    let message = `API error: ${res.status} ${res.statusText}`
+    try {
+      const body = (await res.json()) as {
+        error?: string
+        errors?: string[]
+      }
+      if (Array.isArray(body.errors) && body.errors.length > 0) {
+        message = body.errors.join("; ")
+      } else if (typeof body.error === "string" && body.error.trim() !== "") {
+        message = body.error
+      }
+    } catch {
+      // Keep fallback error message when response body is not JSON.
+    }
+    throw new Error(message)
+  }
+  return res.json() as Promise<T>
+}
+
+export async function getAutoStartStatus(): Promise<AutoStartStatus> {
+  return request<AutoStartStatus>("/api/system/autostart")
+}
+
+export async function setAutoStartEnabled(
+  enabled: boolean,
+): Promise<AutoStartStatus> {
+  return request<AutoStartStatus>("/api/system/autostart", {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ enabled }),
+  })
+}
+
+export async function getLauncherConfig(): Promise<LauncherConfig> {
+  return request<LauncherConfig>("/api/system/launcher-config")
+}
+
+export async function setLauncherConfig(
+  payload: LauncherConfig,
+): Promise<LauncherConfig> {
+  return request<LauncherConfig>("/api/system/launcher-config", {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  })
+}
diff --git a/web/frontend/src/api/tools.ts b/web/frontend/src/api/tools.ts
new file mode 100644
index 000000000..9f09efbfd
--- /dev/null
+++ b/web/frontend/src/api/tools.ts
@@ -0,0 +1,56 @@
+export interface ToolSupportItem {
+  name: string
+  description: string
+  category: string
+  config_key: string
+  status: "enabled" | "disabled" | "blocked"
+  reason_code?: string
+}
+
+interface ToolsResponse {
+  tools: ToolSupportItem[]
+}
+
+interface ToolActionResponse {
+  status: string
+}
+
+async function request<T>(path: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(path, options)
+  if (!res.ok) {
+    let message = `API error: ${res.status} ${res.statusText}`
+    try {
+      const body = (await res.json()) as {
+        error?: string
+        errors?: string[]
+      }
+      if (Array.isArray(body.errors) && body.errors.length > 0) {
+        message = body.errors.join("; ")
+      } else if (typeof body.error === "string" && body.error.trim() !== "") {
+        message = body.error
+      }
+    } catch {
+      // ignore invalid body
+    }
+    throw new Error(message)
+  }
+  return res.json() as Promise<T>
+}
+
+export async function getTools(): Promise<ToolsResponse> {
+  return request<ToolsResponse>("/api/tools")
+}
+
+export async function setToolEnabled(
+  name: string,
+  enabled: boolean,
+): Promise<ToolActionResponse> {
+  return request<ToolActionResponse>(
+    `/api/tools/${encodeURIComponent(name)}/state`,
+    {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ enabled }),
+    },
+  )
+}
diff --git a/web/frontend/src/components/app-header.tsx b/web/frontend/src/components/app-header.tsx
new file mode 100644
index 000000000..4f0688008
--- /dev/null
+++ b/web/frontend/src/components/app-header.tsx
@@ -0,0 +1,251 @@
+import {
+  IconBook,
+  IconLanguage,
+  IconLoader2,
+  IconMenu2,
+  IconMoon,
+  IconPlayerPlay,
+  IconPower,
+  IconRefresh,
+  IconSun,
+} from "@tabler/icons-react"
+import { Link } from "@tanstack/react-router"
+import * as React from "react"
+import { useTranslation } from "react-i18next"
+
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog.tsx"
+import { Button } from "@/components/ui/button.tsx"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu.tsx"
+import { Separator } from "@/components/ui/separator.tsx"
+import { SidebarTrigger } from "@/components/ui/sidebar"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
+import { useGateway } from "@/hooks/use-gateway.ts"
+import { useTheme } from "@/hooks/use-theme.ts"
+
+export function AppHeader() {
+  const { i18n, t } = useTranslation()
+  const { theme, toggleTheme } = useTheme()
+  const {
+    state: gwState,
+    loading: gwLoading,
+    canStart,
+    restartRequired,
+    start,
+    restart,
+    stop,
+  } = useGateway()
+
+  const isRunning = gwState === "running"
+  const isStarting = gwState === "starting"
+  const isRestarting = gwState === "restarting"
+  const isStopping = gwState === "stopping"
+  const isStopped = gwState === "stopped" || gwState === "unknown"
+  const showNotConnectedHint =
+    !isRestarting &&
+    !isStopping &&
+    canStart &&
+    (gwState === "stopped" || gwState === "error")
+
+  const [showStopDialog, setShowStopDialog] = React.useState(false)
+
+  const handleGatewayToggle = () => {
+    if (gwLoading || isRestarting || isStopping || (!isRunning && !canStart)) {
+      return
+    }
+    if (isRunning) {
+      setShowStopDialog(true)
+    } else {
+      void start()
+    }
+  }
+
+  const handleGatewayRestart = () => {
+    if (gwLoading || isRestarting || !restartRequired || !canStart) return
+    void restart()
+  }
+
+  const confirmStop = () => {
+    setShowStopDialog(false)
+    stop()
+  }
+
+  return (
+    <header className="bg-background/95 supports-backdrop-filter:bg-background/60 border-b-border/50 sticky top-0 z-50 flex h-14 shrink-0 items-center justify-between border-b px-4 backdrop-blur">
+      <div className="flex items-center gap-2">
+        <SidebarTrigger className="text-muted-foreground hover:bg-accent hover:text-foreground flex h-9 w-9 items-center justify-center rounded-lg sm:hidden [&>svg]:size-5">
+          <IconMenu2 />
+        </SidebarTrigger>
+        <div className="hidden w-36 shrink-0 items-center sm:flex">
+          <Link to="/">
+            <img className="w-full" src="/logo_with_text.png" alt="Logo" />
+          </Link>
+        </div>
+      </div>
+
+      {/* Center prominent connection status */}
+      <div className="pointer-events-none absolute left-1/2 hidden h-full -translate-x-1/2 items-center justify-center lg:flex">
+        {showNotConnectedHint && (
+          <div className="text-muted-foreground flex items-center gap-2 rounded-full border border-dashed px-4 py-1.5 text-xs shadow-sm backdrop-blur-md">
+            <span className="bg-destructive/50 relative flex size-2 shrink-0 items-center justify-center rounded-full">
+              <span className="bg-destructive absolute inline-flex size-full animate-ping rounded-full opacity-75"></span>
+            </span>
+            {t("chat.notConnected")}
+          </div>
+        )}
+      </div>
+
+      <AlertDialog open={showStopDialog} onOpenChange={setShowStopDialog}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>
+              {t("header.gateway.stopDialog.title")}
+            </AlertDialogTitle>
+            <AlertDialogDescription>
+              {t("header.gateway.stopDialog.description")}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>{t("common.cancel")}</AlertDialogCancel>
+            <AlertDialogAction
+              onClick={confirmStop}
+              className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+            >
+              {t("header.gateway.stopDialog.confirm")}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+
+      <div className="text-muted-foreground flex items-center gap-1 text-sm font-medium md:gap-2">
+        {restartRequired && (
+          <Tooltip delayDuration={700}>
+            <TooltipTrigger asChild>
+              <Button
+                variant="secondary"
+                size="icon-sm"
+                className="bg-amber-500/15 text-amber-700 hover:bg-amber-500/25 hover:text-amber-800 dark:text-amber-300 dark:hover:bg-amber-500/25"
+                onClick={handleGatewayRestart}
+                disabled={gwLoading || isRestarting || isStopping || !canStart}
+                aria-label={t("header.gateway.action.restart")}
+              >
+                <IconRefresh className="size-4" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>
+              {t("header.gateway.restartRequired")}
+            </TooltipContent>
+          </Tooltip>
+        )}
+
+        {/* Gateway Start/Stop */}
+        {isRunning ? (
+          <Tooltip delayDuration={700}>
+            <TooltipTrigger asChild>
+              <Button
+                variant="destructive"
+                size="icon-sm"
+                className="size-8"
+                onClick={handleGatewayToggle}
+                disabled={gwLoading}
+                aria-label={t("header.gateway.action.stop")}
+              >
+                <IconPower className="h-4 w-4 opacity-80" />
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>{t("header.gateway.action.stop")}</TooltipContent>
+          </Tooltip>
+        ) : (
+          <Button
+            variant={
+              isStarting || isRestarting || isStopping ? "secondary" : "default"
+            }
+            size="sm"
+            className={`h-8 gap-2 px-3 ${
+              isStopped ? "bg-green-500 text-white hover:bg-green-600" : ""
+            }`}
+            onClick={handleGatewayToggle}
+            disabled={
+              gwLoading || isStarting || isRestarting || isStopping || !canStart
+            }
+          >
+            {gwLoading || isStarting || isRestarting || isStopping ? (
+              <IconLoader2 className="h-4 w-4 animate-spin opacity-70" />
+            ) : (
+              <IconPlayerPlay className="h-4 w-4 opacity-80" />
+            )}
+            <span className="text-xs font-semibold">
+              {isStopping
+                ? t("header.gateway.status.stopping")
+                : isRestarting
+                  ? t("header.gateway.status.restarting")
+                  : isStarting
+                    ? t("header.gateway.status.starting")
+                    : t("header.gateway.action.start")}
+            </span>
+          </Button>
+        )}
+
+        <Separator
+          className="mx-4 my-2 hidden md:block"
+          orientation="vertical"
+        />
+
+        {/* Docs Link */}
+        <Button variant="ghost" size="icon" className="size-8" asChild>
+          <a href="https://docs.picoclaw.io" target="_blank" rel="noreferrer">
+            <IconBook className="size-4.5" />
+          </a>
+        </Button>
+
+        {/* Language Switcher */}
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="ghost" size="icon" className="size-8">
+              <IconLanguage className="size-4.5" />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end">
+            <DropdownMenuItem onClick={() => i18n.changeLanguage("en")}>
+              English
+            </DropdownMenuItem>
+            <DropdownMenuItem onClick={() => i18n.changeLanguage("zh")}>
+              简体中文
+            </DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+
+        {/* Theme Toggle */}
+        <Button
+          variant="ghost"
+          size="icon"
+          className="size-8"
+          onClick={toggleTheme}
+        >
+          {theme === "dark" ? (
+            <IconSun className="size-4.5" />
+          ) : (
+            <IconMoon className="size-4.5" />
+          )}
+        </Button>
+      </div>
+    </header>
+  )
+}
diff --git a/web/frontend/src/components/app-layout.tsx b/web/frontend/src/components/app-layout.tsx
new file mode 100644
index 000000000..ff9877bae
--- /dev/null
+++ b/web/frontend/src/components/app-layout.tsx
@@ -0,0 +1,27 @@
+import type { ReactNode } from "react"
+import { Toaster } from "sonner"
+
+import { AppHeader } from "@/components/app-header"
+import { AppSidebar } from "@/components/app-sidebar"
+import { SidebarProvider } from "@/components/ui/sidebar"
+import { TooltipProvider } from "@/components/ui/tooltip"
+
+export function AppLayout({ children }: { children: ReactNode }) {
+  return (
+    <TooltipProvider>
+      <SidebarProvider className="flex h-dvh flex-col overflow-hidden">
+        <AppHeader />
+
+        <div className="flex flex-1 overflow-hidden">
+          <AppSidebar />
+          <div className="flex w-full flex-col overflow-hidden">
+            <main className="flex min-h-0 w-full max-w-full flex-1 flex-col overflow-hidden">
+              {children}
+            </main>
+          </div>
+        </div>
+        <Toaster position="bottom-center" />
+      </SidebarProvider>
+    </TooltipProvider>
+  )
+}
diff --git a/web/frontend/src/components/app-sidebar.tsx b/web/frontend/src/components/app-sidebar.tsx
new file mode 100644
index 000000000..0e135c0c1
--- /dev/null
+++ b/web/frontend/src/components/app-sidebar.tsx
@@ -0,0 +1,241 @@
+import { IconChevronRight } from "@tabler/icons-react"
+import {
+  IconAtom,
+  IconChevronsDown,
+  IconChevronsUp,
+  IconKey,
+  IconListDetails,
+  IconMessageCircle,
+  IconSettings,
+  IconSparkles,
+  IconTools,
+} from "@tabler/icons-react"
+import { Link, useRouterState } from "@tanstack/react-router"
+import * as React from "react"
+import { useTranslation } from "react-i18next"
+
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@/components/ui/collapsible"
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarRail,
+} from "@/components/ui/sidebar"
+import { useSidebarChannels } from "@/hooks/use-sidebar-channels"
+
+interface NavItem {
+  title: string
+  url: string
+  icon: React.ComponentType<{ className?: string }>
+  translateTitle?: boolean
+}
+
+interface NavGroup {
+  label: string
+  defaultOpen: boolean
+  items: NavItem[]
+  isChannelsGroup?: boolean
+}
+
+const baseNavGroups: Omit<NavGroup, "items">[] = [
+  {
+    label: "navigation.chat",
+    defaultOpen: true,
+  },
+  {
+    label: "navigation.model_group",
+    defaultOpen: true,
+  },
+  {
+    label: "navigation.agent_group",
+    defaultOpen: true,
+  },
+  {
+    label: "navigation.services",
+    defaultOpen: true,
+  },
+]
+
+export function AppSidebar({ ...props }: React.ComponentProps<typeof Sidebar>) {
+  const routerState = useRouterState()
+  const { i18n, t } = useTranslation()
+  const currentPath = routerState.location.pathname
+  const {
+    channelItems,
+    hasMoreChannels,
+    showAllChannels,
+    toggleShowAllChannels,
+  } = useSidebarChannels({
+    language: (i18n.resolvedLanguage ?? i18n.language ?? "").toLowerCase(),
+    t,
+  })
+
+  const navGroups: NavGroup[] = React.useMemo(() => {
+    return [
+      {
+        ...baseNavGroups[0],
+        items: [
+          {
+            title: "navigation.chat",
+            url: "/",
+            icon: IconMessageCircle,
+            translateTitle: true,
+          },
+        ],
+      },
+      {
+        ...baseNavGroups[1],
+        items: [
+          {
+            title: "navigation.models",
+            url: "/models",
+            icon: IconAtom,
+            translateTitle: true,
+          },
+          {
+            title: "navigation.credentials",
+            url: "/credentials",
+            icon: IconKey,
+            translateTitle: true,
+          },
+        ],
+      },
+      {
+        label: "navigation.channels_group",
+        defaultOpen: true,
+        items: channelItems.map((item) => ({
+          title: item.title,
+          url: item.url,
+          icon: item.icon,
+          translateTitle: false,
+        })),
+        isChannelsGroup: true,
+      },
+      {
+        ...baseNavGroups[2],
+        items: [
+          {
+            title: "navigation.skills",
+            url: "/agent/skills",
+            icon: IconSparkles,
+            translateTitle: true,
+          },
+          {
+            title: "navigation.tools",
+            url: "/agent/tools",
+            icon: IconTools,
+            translateTitle: true,
+          },
+        ],
+      },
+      {
+        ...baseNavGroups[3],
+        items: [
+          {
+            title: "navigation.config",
+            url: "/config",
+            icon: IconSettings,
+            translateTitle: true,
+          },
+          {
+            title: "navigation.logs",
+            url: "/logs",
+            icon: IconListDetails,
+            translateTitle: true,
+          },
+        ],
+      },
+    ]
+  }, [channelItems])
+
+  return (
+    <Sidebar
+      {...props}
+      className="bg-background border-r-border/20 border-r pt-3"
+    >
+      <SidebarContent className="bg-background">
+        {navGroups.map((group) => (
+          <Collapsible
+            key={group.label}
+            defaultOpen={group.defaultOpen}
+            className="group/collapsible mb-1"
+          >
+            <SidebarGroup className="px-2 py-0">
+              <SidebarGroupLabel asChild>
+                <CollapsibleTrigger className="hover:bg-muted/60 flex w-full cursor-pointer items-center justify-between rounded-md px-2 py-1.5 transition-colors">
+                  <span>{t(group.label)}</span>
+                  <IconChevronRight className="size-3.5 opacity-50 transition-transform duration-200 group-data-[state=open]/collapsible:rotate-90" />
+                </CollapsibleTrigger>
+              </SidebarGroupLabel>
+              <CollapsibleContent>
+                <SidebarGroupContent className="pt-1">
+                  <SidebarMenu>
+                    {group.items.map((item) => {
+                      const isActive =
+                        currentPath === item.url ||
+                        (item.url !== "/" &&
+                          currentPath.startsWith(`${item.url}/`))
+                      return (
+                        <SidebarMenuItem key={item.title}>
+                          <SidebarMenuButton
+                            asChild
+                            isActive={isActive}
+                            className={`h-9 px-3 ${isActive ? "bg-accent/80 text-foreground font-medium" : "text-muted-foreground hover:bg-muted/60"}`}
+                          >
+                            <Link to={item.url}>
+                              <item.icon
+                                className={`size-4 ${isActive ? "opacity-100" : "opacity-60"}`}
+                              />
+                              <span
+                                className={
+                                  isActive ? "opacity-100" : "opacity-80"
+                                }
+                              >
+                                {item.translateTitle === false
+                                  ? item.title
+                                  : t(item.title)}
+                              </span>
+                            </Link>
+                          </SidebarMenuButton>
+                        </SidebarMenuItem>
+                      )
+                    })}
+                    {group.isChannelsGroup && hasMoreChannels && (
+                      <SidebarMenuItem key="channels-more-toggle">
+                        <SidebarMenuButton
+                          onClick={toggleShowAllChannels}
+                          className="text-muted-foreground hover:bg-muted/60 h-9 px-3"
+                        >
+                          {showAllChannels ? (
+                            <IconChevronsUp className="size-4 opacity-60" />
+                          ) : (
+                            <IconChevronsDown className="size-4 opacity-60" />
+                          )}
+                          <span className="opacity-80">
+                            {showAllChannels
+                              ? t("navigation.show_less_channels")
+                              : t("navigation.show_more_channels")}
+                          </span>
+                        </SidebarMenuButton>
+                      </SidebarMenuItem>
+                    )}
+                  </SidebarMenu>
+                </SidebarGroupContent>
+              </CollapsibleContent>
+            </SidebarGroup>
+          </Collapsible>
+        ))}
+      </SidebarContent>
+      <SidebarRail />
+    </Sidebar>
+  )
+}
diff --git a/web/frontend/src/components/channels/channel-config-page.tsx b/web/frontend/src/components/channels/channel-config-page.tsx
new file mode 100644
index 000000000..7f1f695bc
--- /dev/null
+++ b/web/frontend/src/components/channels/channel-config-page.tsx
@@ -0,0 +1,553 @@
+import { IconLoader2 } from "@tabler/icons-react"
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import { useTranslation } from "react-i18next"
+
+import {
+  type ChannelConfig,
+  type SupportedChannel,
+  getAppConfig,
+  getChannelsCatalog,
+  patchAppConfig,
+} from "@/api/channels"
+import { getChannelDisplayName } from "@/components/channels/channel-display-name"
+import { DiscordForm } from "@/components/channels/channel-forms/discord-form"
+import { FeishuForm } from "@/components/channels/channel-forms/feishu-form"
+import { GenericForm } from "@/components/channels/channel-forms/generic-form"
+import { SlackForm } from "@/components/channels/channel-forms/slack-form"
+import { TelegramForm } from "@/components/channels/channel-forms/telegram-form"
+import { WeixinForm } from "@/components/channels/channel-forms/weixin-form"
+import { PageHeader } from "@/components/page-header"
+import { Button } from "@/components/ui/button"
+import { Switch } from "@/components/ui/switch"
+import { useGateway } from "@/hooks/use-gateway"
+import { refreshGatewayState } from "@/store/gateway"
+
+interface ChannelConfigPageProps {
+  channelName: string
+}
+
+const SECRET_FIELD_MAP: Record<string, string> = {
+  token: "_token",
+  app_secret: "_app_secret",
+  client_secret: "_client_secret",
+  corp_secret: "_corp_secret",
+  channel_secret: "_channel_secret",
+  channel_access_token: "_channel_access_token",
+  access_token: "_access_token",
+  bot_token: "_bot_token",
+  app_token: "_app_token",
+  encoding_aes_key: "_encoding_aes_key",
+  encrypt_key: "_encrypt_key",
+  verification_token: "_verification_token",
+  password: "_password",
+  nickserv_password: "_nickserv_password",
+  sasl_password: "_sasl_password",
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>
+  }
+  return {}
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : ""
+}
+
+function asBool(value: unknown): boolean {
+  return value === true
+}
+
+function buildEditConfig(config: ChannelConfig): ChannelConfig {
+  const edit: ChannelConfig = { ...config }
+  for (const secretKey of Object.keys(SECRET_FIELD_MAP)) {
+    if (secretKey in config) {
+      edit[SECRET_FIELD_MAP[secretKey]] = ""
+    }
+  }
+  return edit
+}
+
+function normalizeConfig(
+  channel: SupportedChannel,
+  rawConfig: ChannelConfig,
+): ChannelConfig {
+  const config = { ...rawConfig }
+  if (channel.name === "whatsapp_native") {
+    config.use_native = true
+  }
+  if (channel.name === "whatsapp") {
+    config.use_native = false
+  }
+  return config
+}
+
+function buildSavePayload(
+  channel: SupportedChannel,
+  editConfig: ChannelConfig,
+  enabled: boolean,
+): ChannelConfig {
+  const payload: ChannelConfig = { enabled }
+
+  for (const [key, value] of Object.entries(editConfig)) {
+    if (key.startsWith("_")) continue
+    if (key === "enabled") continue
+
+    if (key in SECRET_FIELD_MAP) {
+      const editKey = SECRET_FIELD_MAP[key]
+      const incoming = asString(editConfig[editKey])
+      payload[key] = incoming !== "" ? incoming : value
+      continue
+    }
+
+    payload[key] = value
+  }
+
+  if (channel.name === "whatsapp_native") {
+    payload.use_native = true
+  }
+  if (channel.name === "whatsapp") {
+    payload.use_native = false
+  }
+
+  return payload
+}
+
+function isConfigured(
+  channel: SupportedChannel,
+  config: ChannelConfig,
+): boolean {
+  switch (channel.name) {
+    case "telegram":
+      return asString(config.token) !== ""
+    case "discord":
+      return asString(config.token) !== ""
+    case "slack":
+      return asString(config.bot_token) !== ""
+    case "feishu":
+      return (
+        asString(config.app_id) !== "" && asString(config.app_secret) !== ""
+      )
+    case "dingtalk":
+      return (
+        asString(config.client_id) !== "" &&
+        asString(config.client_secret) !== ""
+      )
+    case "line":
+      return asString(config.channel_access_token) !== ""
+    case "qq":
+      return (
+        asString(config.app_id) !== "" && asString(config.app_secret) !== ""
+      )
+    case "onebot":
+      return asString(config.ws_url) !== ""
+    case "weixin":
+      return asString(config.account_id) !== ""
+    case "wecom":
+      return asString(config.bot_id) !== ""
+    case "whatsapp":
+      return asString(config.bridge_url) !== ""
+    case "whatsapp_native":
+      return asBool(config.use_native)
+    case "pico":
+      return asString(config.token) !== ""
+    case "maixcam":
+      return asString(config.host) !== ""
+    case "matrix":
+      return (
+        asString(config.homeserver) !== "" &&
+        asString(config.user_id) !== "" &&
+        asString(config.access_token) !== ""
+      )
+    case "irc":
+      return asString(config.server) !== ""
+    default:
+      return false
+  }
+}
+
+function getRequiredFieldKeys(channelName: string): string[] {
+  switch (channelName) {
+    case "telegram":
+      return ["token"]
+    case "discord":
+      return ["token"]
+    case "slack":
+      return ["bot_token"]
+    case "feishu":
+      return ["app_id", "app_secret"]
+    case "dingtalk":
+      return ["client_id", "client_secret"]
+    case "line":
+      return ["channel_secret", "channel_access_token"]
+    case "qq":
+      return ["app_id", "app_secret"]
+    case "onebot":
+      return ["ws_url"]
+    case "wecom":
+      return ["bot_id", "secret"]
+    case "whatsapp":
+      return ["bridge_url"]
+    case "pico":
+      return ["token"]
+    case "maixcam":
+      return ["host"]
+    case "matrix":
+      return ["homeserver", "user_id", "access_token"]
+    case "irc":
+      return ["server"]
+    default:
+      return []
+  }
+}
+
+function isMissingRequiredValue(value: unknown): boolean {
+  if (value === null || value === undefined) {
+    return true
+  }
+  if (typeof value === "string") {
+    return value.trim() === ""
+  }
+  if (Array.isArray(value)) {
+    return value.length === 0
+  }
+  return false
+}
+
+function getChannelDocSlug(channelName: string): string {
+  return channelName.replaceAll("_", "-")
+}
+
+const CHANNELS_WITHOUT_DOCS = new Set([
+  "pico",
+  "wecom",
+  "matrix",
+  "irc",
+  "whatsapp",
+  "whatsapp_native",
+])
+
+export function ChannelConfigPage({ channelName }: ChannelConfigPageProps) {
+  const { t, i18n } = useTranslation()
+  const { state: gatewayState } = useGateway()
+
+  const [loading, setLoading] = useState(true)
+  const [saving, setSaving] = useState(false)
+  const [fetchError, setFetchError] = useState("")
+  const [serverError, setServerError] = useState("")
+  const [fieldErrors, setFieldErrors] = useState<Record<string, string>>({})
+
+  const [channel, setChannel] = useState<SupportedChannel | null>(null)
+  const [baseConfig, setBaseConfig] = useState<ChannelConfig>({})
+  const [editConfig, setEditConfig] = useState<ChannelConfig>({})
+  const [enabled, setEnabled] = useState(false)
+
+  const loadData = useCallback(
+    async (silent = false) => {
+      if (!silent) setLoading(true)
+      try {
+        const [catalog, appConfig] = await Promise.all([
+          getChannelsCatalog(),
+          getAppConfig(),
+        ])
+        const matched =
+          catalog.channels.find((item) => item.name === channelName) ?? null
+
+        if (!matched) {
+          setChannel(null)
+          setFetchError(
+            t("channels.page.notFound", {
+              name: channelName,
+            }),
+          )
+          return
+        }
+
+        const channelsConfig = asRecord(asRecord(appConfig).channels)
+        const raw = asRecord(channelsConfig[matched.config_key])
+        const normalized = normalizeConfig(matched, raw)
+
+        setChannel(matched)
+        setBaseConfig(normalized)
+        setEditConfig(buildEditConfig(normalized))
+        setEnabled(asBool(normalized.enabled))
+        setFetchError("")
+        setServerError("")
+        setFieldErrors({})
+      } catch (e) {
+        setFetchError(e instanceof Error ? e.message : t("channels.loadError"))
+      } finally {
+        if (!silent) setLoading(false)
+      }
+    },
+    [channelName, t],
+  )
+
+  useEffect(() => {
+    loadData()
+  }, [loadData])
+
+  const previousGatewayStatusRef = useRef(gatewayState)
+  useEffect(() => {
+    const previousStatus = previousGatewayStatusRef.current
+    if (previousStatus !== "running" && gatewayState === "running") {
+      void loadData()
+    }
+    previousGatewayStatusRef.current = gatewayState
+  }, [gatewayState, loadData])
+
+  const savePayload = useMemo(() => {
+    if (!channel) return null
+    return buildSavePayload(channel, editConfig, enabled)
+  }, [channel, editConfig, enabled])
+
+  const configured = useMemo(() => {
+    if (!channel || !savePayload) return false
+    return isConfigured(channel, savePayload)
+  }, [channel, savePayload])
+
+  const docsUrl = useMemo(() => {
+    if (!channel) return ""
+    if (CHANNELS_WITHOUT_DOCS.has(channel.name)) return ""
+    const language = (
+      i18n.resolvedLanguage ??
+      i18n.language ??
+      ""
+    ).toLowerCase()
+    const base = language.startsWith("zh")
+      ? "https://docs.picoclaw.io/zh-Hans/docs/channels"
+      : "https://docs.picoclaw.io/docs/channels"
+    return `${base}/${getChannelDocSlug(channel.name)}`
+  }, [channel, i18n.language, i18n.resolvedLanguage])
+
+  const channelDisplayName = useMemo(() => {
+    if (!channel) return channelName
+    return getChannelDisplayName(channel, t)
+  }, [channel, channelName, t])
+
+  const hiddenKeys = useMemo(() => {
+    if (!channel) return []
+    if (channel.name === "whatsapp") {
+      return ["use_native"]
+    }
+    if (channel.name === "whatsapp_native") {
+      return ["use_native", "bridge_url"]
+    }
+    return []
+  }, [channel])
+  const requiredKeys = useMemo(
+    () => getRequiredFieldKeys(channelName),
+    [channelName],
+  )
+
+  const handleChange = useCallback((key: string, value: unknown) => {
+    const normalizedKey = key.startsWith("_") ? key.slice(1) : key
+    setEditConfig((prev) => ({ ...prev, [key]: value }))
+    setFieldErrors((prev) => {
+      if (!(key in prev) && !(normalizedKey in prev)) {
+        return prev
+      }
+      const next = { ...prev }
+      delete next[key]
+      delete next[normalizedKey]
+      return next
+    })
+  }, [])
+
+  const handleReset = () => {
+    setEditConfig(buildEditConfig(baseConfig))
+    setEnabled(asBool(baseConfig.enabled))
+    setServerError("")
+    setFieldErrors({})
+  }
+
+  const handleSave = async () => {
+    if (!channel || !savePayload) return
+
+    const missingRequiredFields = requiredKeys.filter((key) =>
+      isMissingRequiredValue(savePayload[key]),
+    )
+    if (missingRequiredFields.length > 0) {
+      const requiredFieldError = t("channels.validation.requiredField")
+      const nextFieldErrors: Record<string, string> = {}
+      for (const key of missingRequiredFields) {
+        nextFieldErrors[key] = requiredFieldError
+      }
+      setFieldErrors(nextFieldErrors)
+      setServerError("")
+      return
+    }
+
+    setSaving(true)
+    setServerError("")
+    setFieldErrors({})
+    try {
+      await patchAppConfig({
+        channels: {
+          [channel.config_key]: savePayload,
+        },
+      })
+      await loadData()
+    } catch (e) {
+      const message =
+        e instanceof Error ? e.message : t("channels.page.saveError")
+      setServerError(message)
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const handleWeixinBindSuccess = useCallback(async () => {
+    try {
+      setEnabled(true)
+      await Promise.all([loadData(true), refreshGatewayState({ force: true })])
+    } catch (e) {
+      const message =
+        e instanceof Error ? e.message : t("channels.page.saveError")
+      setServerError(message)
+      await loadData(true)
+    }
+  }, [loadData, t])
+
+  const renderForm = () => {
+    if (!channel) return null
+    const isEdit = configured
+
+    switch (channel.name) {
+      case "telegram":
+        return (
+          <TelegramForm
+            config={editConfig}
+            onChange={handleChange}
+            isEdit={isEdit}
+            fieldErrors={fieldErrors}
+          />
+        )
+      case "discord":
+        return (
+          <DiscordForm
+            config={editConfig}
+            onChange={handleChange}
+            isEdit={isEdit}
+            fieldErrors={fieldErrors}
+          />
+        )
+      case "slack":
+        return (
+          <SlackForm
+            config={editConfig}
+            onChange={handleChange}
+            isEdit={isEdit}
+            fieldErrors={fieldErrors}
+          />
+        )
+      case "feishu":
+        return (
+          <FeishuForm
+            config={editConfig}
+            onChange={handleChange}
+            isEdit={isEdit}
+            fieldErrors={fieldErrors}
+          />
+        )
+      case "weixin":
+        return (
+          <WeixinForm
+            config={editConfig}
+            onChange={handleChange}
+            isEdit={isEdit}
+            onBindSuccess={() => void handleWeixinBindSuccess()}
+          />
+        )
+      default:
+        return (
+          <GenericForm
+            config={editConfig}
+            onChange={handleChange}
+            isEdit={isEdit}
+            hiddenKeys={hiddenKeys}
+            requiredKeys={requiredKeys}
+            fieldErrors={fieldErrors}
+          />
+        )
+    }
+  }
+
+  return (
+    <div className="flex h-full flex-col">
+      <PageHeader
+        title={channelDisplayName}
+        titleExtra={
+          channel ? (
+            <div className="flex items-center gap-1.5">
+              {enabled ? (
+                <span className="rounded-full bg-emerald-500/10 px-2 py-0.5 text-[10px] font-medium text-emerald-600 dark:text-emerald-400">
+                  {t("channels.page.enabled")}
+                </span>
+              ) : configured ? (
+                <span className="rounded-full bg-amber-500/10 px-2 py-0.5 text-[10px] font-medium text-amber-600 dark:text-amber-400">
+                  {t("channels.status.configured")}
+                </span>
+              ) : null}
+            </div>
+          ) : undefined
+        }
+      />
+
+      <div className="flex min-h-0 flex-1 justify-center overflow-y-auto px-4 pb-8 sm:px-6">
+        {loading ? (
+          <div className="flex items-center justify-center py-20">
+            <IconLoader2 className="text-muted-foreground size-6 animate-spin" />
+          </div>
+        ) : fetchError ? (
+          <div className="text-destructive bg-destructive/10 rounded-lg px-4 py-3 text-sm">
+            {fetchError}
+          </div>
+        ) : (
+          <div className="w-full max-w-250 space-y-5 pt-2">
+            <div className="flex items-center gap-2 text-sm">
+              <p className="font-medium">
+                {t("channels.edit", {
+                  name: channelDisplayName,
+                })}
+              </p>
+              {channel && docsUrl && (
+                <a
+                  href={docsUrl}
+                  target="_blank"
+                  rel="noreferrer"
+                  className="text-muted-foreground hover:text-foreground text-xs underline underline-offset-2"
+                >
+                  {t("channels.page.docLink")}
+                </a>
+              )}
+            </div>
+
+            <div className="border-border/60 bg-background flex items-center justify-between rounded-lg border px-4 py-3">
+              <p className="text-sm font-medium">
+                {t("channels.page.enableLabel")}
+              </p>
+              <Switch checked={enabled} onCheckedChange={setEnabled} />
+            </div>
+
+            {renderForm()}
+
+            {serverError && (
+              <p className="text-destructive text-sm">{serverError}</p>
+            )}
+
+            <div className="border-border/60 flex justify-end gap-2 border-t py-4">
+              <Button variant="outline" onClick={handleReset} disabled={saving}>
+                {t("common.reset")}
+              </Button>
+              <Button onClick={handleSave} disabled={saving}>
+                {saving ? t("common.saving") : t("common.save")}
+              </Button>
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/channels/channel-display-name.ts b/web/frontend/src/components/channels/channel-display-name.ts
new file mode 100644
index 000000000..fe70f5f5e
--- /dev/null
+++ b/web/frontend/src/components/channels/channel-display-name.ts
@@ -0,0 +1,23 @@
+import type { TFunction } from "i18next"
+
+import type { SupportedChannel } from "@/api/channels"
+
+export function getChannelDisplayName(
+  channel: Pick<SupportedChannel, "name" | "display_name">,
+  t: TFunction,
+): string {
+  const key = `channels.name.${channel.name}`
+  const translated = t(key)
+  if (translated !== key) {
+    return translated
+  }
+
+  if (channel.display_name && channel.display_name.trim() !== "") {
+    return channel.display_name
+  }
+
+  return channel.name
+    .split("_")
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1))
+    .join(" ")
+}
diff --git a/web/frontend/src/components/channels/channel-forms/discord-form.tsx b/web/frontend/src/components/channels/channel-forms/discord-form.tsx
new file mode 100644
index 000000000..300175e20
--- /dev/null
+++ b/web/frontend/src/components/channels/channel-forms/discord-form.tsx
@@ -0,0 +1,109 @@
+import { useTranslation } from "react-i18next"
+
+import type { ChannelConfig } from "@/api/channels"
+import { maskedSecretPlaceholder } from "@/components/secret-placeholder"
+import { Field, KeyInput, SwitchCardField } from "@/components/shared-form"
+import { Input } from "@/components/ui/input"
+
+interface DiscordFormProps {
+  config: ChannelConfig
+  onChange: (key: string, value: unknown) => void
+  isEdit: boolean
+  fieldErrors?: Record<string, string>
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : ""
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((item): item is string => typeof item === "string")
+}
+
+function asBool(value: unknown): boolean {
+  return value === true
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>
+  }
+  return {}
+}
+
+export function DiscordForm({
+  config,
+  onChange,
+  isEdit,
+  fieldErrors = {},
+}: DiscordFormProps) {
+  const { t } = useTranslation()
+  const groupTriggerConfig = asRecord(config.group_trigger)
+  const tokenExtraHint =
+    isEdit && asString(config.token)
+      ? ` ${t("channels.field.secretHintSet")}`
+      : ""
+
+  return (
+    <div className="space-y-5">
+      <Field
+        label={t("channels.field.token")}
+        required
+        hint={`${t("channels.form.desc.token")}${tokenExtraHint}`}
+        error={fieldErrors.token}
+      >
+        <KeyInput
+          value={asString(config._token)}
+          onChange={(v) => onChange("_token", v)}
+          placeholder={maskedSecretPlaceholder(
+            config.token,
+            t("channels.field.tokenPlaceholder"),
+          )}
+        />
+      </Field>
+
+      <Field
+        label={t("channels.field.proxy")}
+        hint={t("channels.form.desc.proxy")}
+      >
+        <Input
+          value={asString(config.proxy)}
+          onChange={(e) => onChange("proxy", e.target.value)}
+          placeholder="http://127.0.0.1:7890"
+        />
+      </Field>
+      <Field
+        label={t("channels.field.allowFrom")}
+        hint={t("channels.form.desc.allowFrom")}
+      >
+        <Input
+          value={asStringArray(config.allow_from).join(", ")}
+          onChange={(e) =>
+            onChange(
+              "allow_from",
+              e.target.value
+                .split(",")
+                .map((s: string) => s.trim())
+                .filter(Boolean),
+            )
+          }
+          placeholder={t("channels.field.allowFromPlaceholder")}
+        />
+      </Field>
+
+      <SwitchCardField
+        label={t("channels.field.mentionOnly")}
+        hint={t("channels.form.desc.mentionOnly")}
+        checked={asBool(groupTriggerConfig.mention_only)}
+        onCheckedChange={(checked) => {
+          onChange("group_trigger", {
+            ...groupTriggerConfig,
+            mention_only: checked,
+          })
+        }}
+        ariaLabel={t("channels.field.mentionOnly")}
+      />
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/channels/channel-forms/feishu-form.tsx b/web/frontend/src/components/channels/channel-forms/feishu-form.tsx
new file mode 100644
index 000000000..386adf9a5
--- /dev/null
+++ b/web/frontend/src/components/channels/channel-forms/feishu-form.tsx
@@ -0,0 +1,131 @@
+import { useTranslation } from "react-i18next"
+
+import type { ChannelConfig } from "@/api/channels"
+import { maskedSecretPlaceholder } from "@/components/secret-placeholder"
+import { Field, KeyInput, SwitchCardField } from "@/components/shared-form"
+import { Input } from "@/components/ui/input"
+
+interface FeishuFormProps {
+  config: ChannelConfig
+  onChange: (key: string, value: unknown) => void
+  isEdit: boolean
+  fieldErrors?: Record<string, string>
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : ""
+}
+
+function asBool(value: unknown): boolean {
+  return typeof value === "boolean" ? value : false
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((item): item is string => typeof item === "string")
+}
+
+export function FeishuForm({
+  config,
+  onChange,
+  isEdit,
+  fieldErrors = {},
+}: FeishuFormProps) {
+  const { t } = useTranslation()
+  const appSecretExtraHint =
+    isEdit && asString(config.app_secret)
+      ? ` ${t("channels.field.secretHintSet")}`
+      : ""
+  const verificationExtraHint =
+    isEdit && asString(config.verification_token)
+      ? ` ${t("channels.field.secretHintSet")}`
+      : ""
+  const encryptExtraHint =
+    isEdit && asString(config.encrypt_key)
+      ? ` ${t("channels.field.secretHintSet")}`
+      : ""
+
+  return (
+    <div className="space-y-5">
+      <Field
+        label={t("channels.field.appId")}
+        required
+        hint={t("channels.form.desc.appId")}
+        error={fieldErrors.app_id}
+      >
+        <Input
+          value={asString(config.app_id)}
+          onChange={(e) => onChange("app_id", e.target.value)}
+          placeholder="cli_xxxx"
+        />
+      </Field>
+
+      <Field
+        label={t("channels.field.appSecret")}
+        required
+        hint={`${t("channels.form.desc.appSecret")}${appSecretExtraHint}`}
+        error={fieldErrors.app_secret}
+      >
+        <KeyInput
+          value={asString(config._app_secret)}
+          onChange={(v) => onChange("_app_secret", v)}
+          placeholder={maskedSecretPlaceholder(
+            config.app_secret,
+            t("channels.field.secretPlaceholder"),
+          )}
+        />
+      </Field>
+
+      <Field
+        label={t("channels.field.verificationToken")}
+        hint={`${t("channels.form.desc.verificationToken")}${verificationExtraHint}`}
+      >
+        <KeyInput
+          value={asString(config._verification_token)}
+          onChange={(v) => onChange("_verification_token", v)}
+          placeholder={maskedSecretPlaceholder(
+            config.verification_token,
+            t("channels.field.secretPlaceholder"),
+          )}
+        />
+      </Field>
+      <Field
+        label={t("channels.field.encryptKey")}
+        hint={`${t("channels.form.desc.encryptKey")}${encryptExtraHint}`}
+      >
+        <KeyInput
+          value={asString(config._encrypt_key)}
+          onChange={(v) => onChange("_encrypt_key", v)}
+          placeholder={maskedSecretPlaceholder(
+            config.encrypt_key,
+            t("channels.field.secretPlaceholder"),
+          )}
+        />
+      </Field>
+      <SwitchCardField
+        label={t("channels.field.isLark")}
+        hint={t("channels.form.desc.isLark")}
+        checked={asBool(config.is_lark)}
+        onCheckedChange={(checked) => onChange("is_lark", checked)}
+      />
+      <Field
+        label={t("channels.field.allowFrom")}
+        hint={t("channels.form.desc.allowFrom")}
+      >
+        <Input
+          value={asStringArray(config.allow_from).join(", ")}
+          onChange={(e) =>
+            onChange(
+              "allow_from",
+              e.target.value
+                .split(",")
+                .map((s: string) => s.trim())
+                .filter(Boolean),
+            )
+          }
+          placeholder={t("channels.field.allowFromPlaceholder")}
+        />
+      </Field>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/channels/channel-forms/generic-form.tsx b/web/frontend/src/components/channels/channel-forms/generic-form.tsx
new file mode 100644
index 000000000..1a872542b
--- /dev/null
+++ b/web/frontend/src/components/channels/channel-forms/generic-form.tsx
@@ -0,0 +1,388 @@
+import { useTranslation } from "react-i18next"
+
+import type { ChannelConfig } from "@/api/channels"
+import { maskedSecretPlaceholder } from "@/components/secret-placeholder"
+import { Field, KeyInput, SwitchCardField } from "@/components/shared-form"
+import { Input } from "@/components/ui/input"
+
+interface GenericFormProps {
+  config: ChannelConfig
+  onChange: (key: string, value: unknown) => void
+  isEdit: boolean
+  hiddenKeys?: string[]
+  requiredKeys?: string[]
+  fieldErrors?: Record<string, string>
+}
+
+// Secret field names that should use masked input.
+const SECRET_FIELDS = new Set([
+  "token",
+  "app_secret",
+  "client_secret",
+  "corp_secret",
+  "channel_secret",
+  "channel_access_token",
+  "access_token",
+  "bot_token",
+  "app_token",
+  "encoding_aes_key",
+  "encrypt_key",
+  "verification_token",
+  "secret",
+  "password",
+  "nickserv_password",
+  "sasl_password",
+])
+
+// Fields to skip in the generic form (handled by enabled toggle or internal).
+const SKIP_FIELDS = new Set(["enabled", "reasoning_channel_id"])
+
+// Fields that are objects/nested — show as JSON or skip.
+const OBJECT_FIELDS = new Set([
+  "group_trigger",
+  "typing",
+  "placeholder",
+  "allow_token_query",
+  "allow_from",
+  "allow_origins",
+  "groups",
+])
+
+function formatLabel(key: string): string {
+  return key
+    .split("_")
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ")
+}
+
+function formatSentenceFieldName(key: string): string {
+  const label = formatLabel(key)
+  return label.charAt(0).toLowerCase() + label.slice(1)
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : ""
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((item): item is string => typeof item === "string")
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>
+  }
+  return {}
+}
+
+function asBool(value: unknown): boolean {
+  return value === true
+}
+
+export function GenericForm({
+  config,
+  onChange,
+  isEdit,
+  hiddenKeys = [],
+  requiredKeys = [],
+  fieldErrors = {},
+}: GenericFormProps) {
+  const { t } = useTranslation()
+  const hiddenFieldSet = new Set(hiddenKeys)
+  const requiredFieldSet = new Set(requiredKeys)
+  const groupTriggerConfig = asRecord(config.group_trigger)
+  const typingConfig = asRecord(config.typing)
+  const placeholderConfig = asRecord(config.placeholder)
+  const placeholderEnabled = asBool(placeholderConfig.enabled)
+
+  const fields = Object.keys(config).filter(
+    (k) =>
+      !k.startsWith("_") &&
+      !SKIP_FIELDS.has(k) &&
+      !OBJECT_FIELDS.has(k) &&
+      !hiddenFieldSet.has(k),
+  )
+
+  const buildHint = (key: string): string => {
+    const descriptions: Record<string, string> = {
+      ws_url: t("channels.form.desc.wsUrl"),
+      reconnect_interval: t("channels.form.desc.reconnectInterval"),
+      bridge_url: t("channels.form.desc.bridgeUrl"),
+      session_store_path: t("channels.form.desc.sessionStorePath"),
+      use_native: t("channels.form.desc.useNative"),
+      host: t("channels.form.desc.host"),
+      port: t("channels.form.desc.port"),
+      homeserver: t("channels.form.desc.homeserver"),
+      user_id: t("channels.form.desc.userId"),
+      device_id: t("channels.form.desc.deviceId"),
+      join_on_invite: t("channels.form.desc.joinOnInvite"),
+      app_id: t("channels.form.desc.appId"),
+      client_id: t("channels.form.desc.clientId"),
+      corp_id: t("channels.form.desc.corpId"),
+      bot_id: t("channels.form.desc.appId"),
+      websocket_url: t("channels.form.desc.wsUrl"),
+      dm_policy: t("channels.form.desc.genericField", { field: "DM policy" }),
+      group_policy: t("channels.form.desc.genericField", { field: "group policy" }),
+      group_allow_from: t("channels.form.desc.allowFrom"),
+      send_thinking_message: t("channels.form.desc.genericField", {
+        field: "thinking message behavior",
+      }),
+      agent_id: t("channels.form.desc.agentId"),
+      webhook_url: t("channels.form.desc.webhookUrl"),
+      webhook_host: t("channels.form.desc.webhookHost"),
+      webhook_port: t("channels.form.desc.webhookPort"),
+      webhook_path: t("channels.form.desc.webhookPath"),
+      reply_timeout: t("channels.form.desc.replyTimeout"),
+      max_steps: t("channels.form.desc.maxSteps"),
+      welcome_message: t("channels.form.desc.welcomeMessage"),
+      allow_token_query: t("channels.form.desc.allowTokenQuery"),
+      ping_interval: t("channels.form.desc.pingInterval"),
+      read_timeout: t("channels.form.desc.readTimeout"),
+      write_timeout: t("channels.form.desc.writeTimeout"),
+      max_connections: t("channels.form.desc.maxConnections"),
+      server: t("channels.form.desc.server"),
+      tls: t("channels.form.desc.tls"),
+      nick: t("channels.form.desc.nick"),
+      user: t("channels.form.desc.user"),
+      real_name: t("channels.form.desc.realName"),
+      channels: t("channels.form.desc.channels"),
+      request_caps: t("channels.form.desc.requestCaps"),
+      max_base64_file_size_mib: t("channels.form.desc.maxBase64FileSizeMiB"),
+    }
+    return (
+      descriptions[key] ??
+      t("channels.form.desc.genericField", {
+        field: formatSentenceFieldName(key),
+      })
+    )
+  }
+
+  return (
+    <div className="space-y-5">
+      {fields.map((key) => {
+        const isRequired = requiredFieldSet.has(key)
+        if (SECRET_FIELDS.has(key)) {
+          const editKey = `_${key}`
+          const extraHint =
+            isEdit && config[key] ? ` ${t("channels.field.secretHintSet")}` : ""
+          return (
+            <Field
+              key={key}
+              label={formatLabel(key)}
+              required={isRequired}
+              hint={`${buildHint(key)}${extraHint}`}
+              error={fieldErrors[key]}
+            >
+              <KeyInput
+                value={asString(config[editKey])}
+                onChange={(v) => onChange(editKey, v)}
+                placeholder={maskedSecretPlaceholder(config[key])}
+              />
+            </Field>
+          )
+        }
+
+        const value = config[key]
+        if (typeof value === "boolean") {
+          return (
+            <SwitchCardField
+              key={key}
+              label={formatLabel(key)}
+              hint={buildHint(key)}
+              error={fieldErrors[key]}
+              checked={value}
+              onCheckedChange={(checked) => onChange(key, checked)}
+              ariaLabel={formatLabel(key)}
+            />
+          )
+        }
+
+        if (Array.isArray(value)) {
+          return (
+            <Field
+              key={key}
+              label={formatLabel(key)}
+              required={isRequired}
+              hint={buildHint(key)}
+              error={fieldErrors[key]}
+            >
+              <Input
+                value={asStringArray(value).join(", ")}
+                onChange={(e) =>
+                  onChange(
+                    key,
+                    e.target.value
+                      .split(",")
+                      .map((s: string) => s.trim())
+                      .filter(Boolean),
+                  )
+                }
+              />
+            </Field>
+          )
+        }
+
+        return (
+          <Field
+            key={key}
+            label={formatLabel(key)}
+            required={isRequired}
+            hint={buildHint(key)}
+            error={fieldErrors[key]}
+          >
+            <Input
+              value={String(value ?? "")}
+              onChange={(e) => {
+                // Attempt to preserve number types
+                const v = e.target.value
+                if (typeof config[key] === "number") {
+                  onChange(key, v === "" ? 0 : Number(v))
+                } else {
+                  onChange(key, v)
+                }
+              }}
+            />
+          </Field>
+        )
+      })}
+
+      {/* Allow From field */}
+      {config.allow_from !== undefined && !hiddenFieldSet.has("allow_from") && (
+        <Field
+          label={t("channels.field.allowFrom")}
+          hint={t("channels.form.desc.allowFrom")}
+        >
+          <Input
+            value={asStringArray(config.allow_from).join(", ")}
+            onChange={(e) =>
+              onChange(
+                "allow_from",
+                e.target.value
+                  .split(",")
+                  .map((s: string) => s.trim())
+                  .filter(Boolean),
+              )
+            }
+            placeholder={t("channels.field.allowFromPlaceholder")}
+          />
+        </Field>
+      )}
+
+      {config.allow_origins !== undefined &&
+        !hiddenFieldSet.has("allow_origins") && (
+          <Field
+            label={t("channels.field.allowOrigins")}
+            hint={t("channels.form.desc.allowOrigins")}
+          >
+            <Input
+              value={asStringArray(config.allow_origins).join(", ")}
+              onChange={(e) =>
+                onChange(
+                  "allow_origins",
+                  e.target.value
+                    .split(",")
+                    .map((s: string) => s.trim())
+                    .filter(Boolean),
+                )
+              }
+              placeholder={t("channels.field.allowOriginsPlaceholder")}
+            />
+          </Field>
+        )}
+
+      {config.allow_token_query !== undefined &&
+        !hiddenFieldSet.has("allow_token_query") && (
+          <SwitchCardField
+            label={formatLabel("allow_token_query")}
+            hint={buildHint("allow_token_query")}
+            checked={asBool(config.allow_token_query)}
+            onCheckedChange={(checked) =>
+              onChange("allow_token_query", checked)
+            }
+            ariaLabel={formatLabel("allow_token_query")}
+          />
+        )}
+
+      {config.group_trigger !== undefined &&
+        !hiddenFieldSet.has("group_trigger") && (
+          <>
+            <SwitchCardField
+              label={t("channels.field.groupTriggerMentionOnly")}
+              hint={t("channels.form.desc.groupTriggerMentionOnly")}
+              checked={asBool(groupTriggerConfig.mention_only)}
+              onCheckedChange={(checked) =>
+                onChange("group_trigger", {
+                  ...groupTriggerConfig,
+                  mention_only: checked,
+                })
+              }
+              ariaLabel={t("channels.field.groupTriggerMentionOnly")}
+            />
+            <Field
+              label={t("channels.field.groupTriggerPrefixes")}
+              hint={t("channels.form.desc.groupTriggerPrefixes")}
+            >
+              <Input
+                value={asStringArray(groupTriggerConfig.prefixes).join(", ")}
+                onChange={(e) =>
+                  onChange("group_trigger", {
+                    ...groupTriggerConfig,
+                    prefixes: e.target.value
+                      .split(",")
+                      .map((s: string) => s.trim())
+                      .filter(Boolean),
+                  })
+                }
+                placeholder={t("channels.field.groupTriggerPrefixes")}
+              />
+            </Field>
+          </>
+        )}
+
+      {config.typing !== undefined && !hiddenFieldSet.has("typing") && (
+        <SwitchCardField
+          label={t("channels.field.typingEnabled")}
+          hint={t("channels.form.desc.typingEnabled")}
+          checked={asBool(typingConfig.enabled)}
+          onCheckedChange={(checked) =>
+            onChange("typing", { ...typingConfig, enabled: checked })
+          }
+          ariaLabel={t("channels.field.typingEnabled")}
+        />
+      )}
+
+      {config.placeholder !== undefined &&
+        !hiddenFieldSet.has("placeholder") && (
+          <SwitchCardField
+            label={t("channels.field.placeholderEnabled")}
+            hint={t("channels.form.desc.placeholderEnabled")}
+            checked={placeholderEnabled}
+            onCheckedChange={(checked) =>
+              onChange("placeholder", {
+                ...placeholderConfig,
+                enabled: checked,
+              })
+            }
+            ariaLabel={t("channels.field.placeholderEnabled")}
+          >
+            {placeholderEnabled && (
+              <div className="space-y-1">
+                <Input
+                  value={asString(placeholderConfig.text)}
+                  onChange={(e) =>
+                    onChange("placeholder", {
+                      ...placeholderConfig,
+                      text: e.target.value,
+                    })
+                  }
+                  placeholder={t("channels.field.placeholderText")}
+                  aria-label={t("channels.field.placeholderText")}
+                />
+              </div>
+            )}
+          </SwitchCardField>
+        )}
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/channels/channel-forms/slack-form.tsx b/web/frontend/src/components/channels/channel-forms/slack-form.tsx
new file mode 100644
index 000000000..54650e842
--- /dev/null
+++ b/web/frontend/src/components/channels/channel-forms/slack-form.tsx
@@ -0,0 +1,86 @@
+import { useTranslation } from "react-i18next"
+
+import type { ChannelConfig } from "@/api/channels"
+import { maskedSecretPlaceholder } from "@/components/secret-placeholder"
+import { Field, KeyInput } from "@/components/shared-form"
+import { Input } from "@/components/ui/input"
+
+interface SlackFormProps {
+  config: ChannelConfig
+  onChange: (key: string, value: unknown) => void
+  isEdit: boolean
+  fieldErrors?: Record<string, string>
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : ""
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((item): item is string => typeof item === "string")
+}
+
+export function SlackForm({
+  config,
+  onChange,
+  isEdit,
+  fieldErrors = {},
+}: SlackFormProps) {
+  const { t } = useTranslation()
+  const botTokenExtraHint =
+    isEdit && asString(config.bot_token)
+      ? ` ${t("channels.field.secretHintSet")}`
+      : ""
+  const appTokenExtraHint =
+    isEdit && asString(config.app_token)
+      ? ` ${t("channels.field.secretHintSet")}`
+      : ""
+
+  return (
+    <div className="space-y-5">
+      <Field
+        label={t("channels.field.botToken")}
+        required
+        hint={`${t("channels.form.desc.botToken")}${botTokenExtraHint}`}
+        error={fieldErrors.bot_token}
+      >
+        <KeyInput
+          value={asString(config._bot_token)}
+          onChange={(v) => onChange("_bot_token", v)}
+          placeholder={maskedSecretPlaceholder(config.bot_token, "xoxb-xxxx")}
+        />
+      </Field>
+
+      <Field
+        label={t("channels.field.appToken")}
+        hint={`${t("channels.form.desc.appToken")}${appTokenExtraHint}`}
+      >
+        <KeyInput
+          value={asString(config._app_token)}
+          onChange={(v) => onChange("_app_token", v)}
+          placeholder={maskedSecretPlaceholder(config.app_token, "xapp-xxxx")}
+        />
+      </Field>
+
+      <Field
+        label={t("channels.field.allowFrom")}
+        hint={t("channels.form.desc.allowFrom")}
+      >
+        <Input
+          value={asStringArray(config.allow_from).join(", ")}
+          onChange={(e) =>
+            onChange(
+              "allow_from",
+              e.target.value
+                .split(",")
+                .map((s: string) => s.trim())
+                .filter(Boolean),
+            )
+          }
+          placeholder={t("channels.field.allowFromPlaceholder")}
+        />
+      </Field>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/channels/channel-forms/telegram-form.tsx b/web/frontend/src/components/channels/channel-forms/telegram-form.tsx
new file mode 100644
index 000000000..169ddec63
--- /dev/null
+++ b/web/frontend/src/components/channels/channel-forms/telegram-form.tsx
@@ -0,0 +1,147 @@
+import { useTranslation } from "react-i18next"
+
+import type { ChannelConfig } from "@/api/channels"
+import { maskedSecretPlaceholder } from "@/components/secret-placeholder"
+import { Field, KeyInput, SwitchCardField } from "@/components/shared-form"
+import { Input } from "@/components/ui/input"
+
+interface TelegramFormProps {
+  config: ChannelConfig
+  onChange: (key: string, value: unknown) => void
+  isEdit: boolean
+  fieldErrors?: Record<string, string>
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : ""
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((item): item is string => typeof item === "string")
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>
+  }
+  return {}
+}
+
+function asBool(value: unknown): boolean {
+  return value === true
+}
+
+export function TelegramForm({
+  config,
+  onChange,
+  isEdit,
+  fieldErrors = {},
+}: TelegramFormProps) {
+  const { t } = useTranslation()
+  const typingConfig = asRecord(config.typing)
+  const placeholderConfig = asRecord(config.placeholder)
+  const placeholderEnabled = asBool(placeholderConfig.enabled)
+  const tokenExtraHint =
+    isEdit && asString(config.token)
+      ? ` ${t("channels.field.secretHintSet")}`
+      : ""
+
+  return (
+    <div className="space-y-5">
+      <Field
+        label={t("channels.field.token")}
+        required
+        hint={`${t("channels.form.desc.token")}${tokenExtraHint}`}
+        error={fieldErrors.token}
+      >
+        <KeyInput
+          value={asString(config._token)}
+          onChange={(v) => onChange("_token", v)}
+          placeholder={maskedSecretPlaceholder(
+            config.token,
+            t("channels.field.tokenPlaceholder"),
+          )}
+        />
+      </Field>
+
+      <Field
+        label={t("channels.field.baseUrl")}
+        hint={t("channels.form.desc.baseUrl")}
+      >
+        <Input
+          value={asString(config.base_url)}
+          onChange={(e) => onChange("base_url", e.target.value)}
+          placeholder="https://api.telegram.org"
+        />
+      </Field>
+      <Field
+        label={t("channels.field.proxy")}
+        hint={t("channels.form.desc.proxy")}
+      >
+        <Input
+          value={asString(config.proxy)}
+          onChange={(e) => onChange("proxy", e.target.value)}
+          placeholder="http://127.0.0.1:7890"
+        />
+      </Field>
+      <Field
+        label={t("channels.field.allowFrom")}
+        hint={t("channels.form.desc.allowFrom")}
+      >
+        <Input
+          value={asStringArray(config.allow_from).join(", ")}
+          onChange={(e) =>
+            onChange(
+              "allow_from",
+              e.target.value
+                .split(",")
+                .map((s: string) => s.trim())
+                .filter(Boolean),
+            )
+          }
+          placeholder={t("channels.field.allowFromPlaceholder")}
+        />
+      </Field>
+
+      <SwitchCardField
+        label={t("channels.field.typingEnabled")}
+        hint={t("channels.form.desc.typingEnabled")}
+        checked={asBool(typingConfig.enabled)}
+        onCheckedChange={(checked) =>
+          onChange("typing", { ...typingConfig, enabled: checked })
+        }
+        ariaLabel={t("channels.field.typingEnabled")}
+      />
+
+      <SwitchCardField
+        label={t("channels.field.placeholderEnabled")}
+        hint={t("channels.form.desc.placeholderEnabled")}
+        checked={placeholderEnabled}
+        onCheckedChange={(checked) =>
+          onChange("placeholder", {
+            ...placeholderConfig,
+            enabled: checked,
+          })
+        }
+        ariaLabel={t("channels.field.placeholderEnabled")}
+      >
+        {placeholderEnabled && (
+          <div className="space-y-1">
+            <Input
+              value={asString(placeholderConfig.text)}
+              onChange={(e) =>
+                onChange("placeholder", {
+                  ...placeholderConfig,
+                  text: e.target.value,
+                })
+              }
+              placeholder={t("channels.field.placeholderText")}
+              aria-label={t("channels.field.placeholderText")}
+            />
+          </div>
+        )}
+      </SwitchCardField>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/channels/channel-forms/weixin-form.tsx b/web/frontend/src/components/channels/channel-forms/weixin-form.tsx
new file mode 100644
index 000000000..20e66ffc2
--- /dev/null
+++ b/web/frontend/src/components/channels/channel-forms/weixin-form.tsx
@@ -0,0 +1,351 @@
+import {
+  IconCheck,
+  IconLoader2,
+  IconQrcode,
+  IconRefresh,
+  IconX,
+} from "@tabler/icons-react"
+import { useCallback, useEffect, useRef, useState } from "react"
+import { useTranslation } from "react-i18next"
+
+import type { ChannelConfig } from "@/api/channels"
+import { pollWeixinFlow, startWeixinFlow } from "@/api/channels"
+import { Field } from "@/components/shared-form"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+
+type BindingState =
+  | "idle"
+  | "loading"
+  | "waiting"
+  | "scaned"
+  | "confirmed"
+  | "expired"
+  | "error"
+
+interface WeixinFormProps {
+  config: ChannelConfig
+  onChange: (key: string, value: unknown) => void
+  isEdit: boolean
+  onBindSuccess?: () => void
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : ""
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((item): item is string => typeof item === "string")
+}
+
+export function WeixinForm({
+  config,
+  onChange,
+  isEdit,
+  onBindSuccess,
+}: WeixinFormProps) {
+  const { t } = useTranslation()
+
+  const [bindState, setBindState] = useState<BindingState>("idle")
+  const [qrDataURI, setQrDataURI] = useState<string | null>(null)
+  const [accountID, setAccountID] = useState<string | null>(null)
+  const [errorMsg, setErrorMsg] = useState("")
+
+  const pollTimerRef = useRef<ReturnType<typeof setInterval> | null>(null)
+  const pollGenerationRef = useRef(0)
+  const isBound = isEdit && asString(config.account_id) !== ""
+  const existingAccountID = asString(config.account_id)
+
+  const stopPolling = useCallback(() => {
+    pollGenerationRef.current += 1
+    if (pollTimerRef.current !== null) {
+      clearInterval(pollTimerRef.current)
+      pollTimerRef.current = null
+    }
+  }, [])
+
+  useEffect(() => () => stopPolling(), [stopPolling])
+
+  useEffect(() => {
+    if (!existingAccountID) return
+    stopPolling()
+    setAccountID(existingAccountID)
+    setBindState("confirmed")
+    setErrorMsg("")
+  }, [existingAccountID, stopPolling])
+
+  const startPolling = useCallback(
+    (id: string) => {
+      stopPolling()
+      const generation = pollGenerationRef.current
+      let inFlight = false
+      pollTimerRef.current = setInterval(async () => {
+        if (inFlight) return
+        inFlight = true
+        try {
+          const resp = await pollWeixinFlow(id)
+          if (generation !== pollGenerationRef.current) {
+            return
+          }
+          if (resp.status === "scaned") {
+            setBindState("scaned")
+          } else if (resp.status === "confirmed") {
+            stopPolling()
+            setAccountID(resp.account_id ?? existingAccountID ?? null)
+            setBindState("confirmed")
+            onBindSuccess?.()
+          } else if (resp.status === "expired") {
+            stopPolling()
+            setBindState("expired")
+          } else if (resp.status === "error") {
+            stopPolling()
+            setBindState("error")
+            setErrorMsg(resp.error ?? t("channels.weixin.errorGeneric"))
+          }
+        } catch {
+          // transient network error — keep polling
+        } finally {
+          inFlight = false
+        }
+      }, 2000)
+    },
+    [existingAccountID, stopPolling, onBindSuccess, t],
+  )
+
+  const handleBind = async () => {
+    setBindState("loading")
+    setErrorMsg("")
+    setQrDataURI(null)
+    stopPolling()
+    try {
+      const resp = await startWeixinFlow()
+      setQrDataURI(resp.qr_data_uri ?? null)
+      setBindState("waiting")
+      startPolling(resp.flow_id)
+    } catch (e) {
+      setBindState("error")
+      setErrorMsg(
+        e instanceof Error ? e.message : t("channels.weixin.errorGeneric"),
+      )
+    }
+  }
+
+  const handleRebind = () => {
+    stopPolling()
+    setBindState("idle")
+    setQrDataURI(null)
+    setAccountID(null)
+    setErrorMsg("")
+    void handleBind()
+  }
+
+  const renderBindSection = () => {
+    if (bindState === "idle") {
+      if (isBound) {
+        return (
+          <div className="flex flex-col items-center gap-3 py-6">
+            <div className="flex items-center gap-2 rounded-full bg-emerald-500/10 px-4 py-2 text-sm font-medium text-emerald-600 dark:text-emerald-400">
+              <IconCheck size={16} />
+              {t("channels.weixin.bound")}
+            </div>
+            {existingAccountID && (
+              <p className="text-muted-foreground font-mono text-xs">
+                {existingAccountID}
+              </p>
+            )}
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={handleRebind}
+              className="mt-1 gap-2"
+            >
+              <IconRefresh size={14} />
+              {t("channels.weixin.rebind")}
+            </Button>
+          </div>
+        )
+      }
+      return (
+        <div className="flex flex-col items-center gap-4 py-6">
+          <p className="text-muted-foreground text-sm">
+            {t("channels.weixin.notBound")}
+          </p>
+          <Button onClick={handleBind} className="gap-2">
+            <IconQrcode size={16} />
+            {t("channels.weixin.bind")}
+          </Button>
+        </div>
+      )
+    }
+
+    if (bindState === "loading") {
+      return (
+        <div className="flex flex-col items-center gap-3 py-8">
+          <IconLoader2
+            className="text-muted-foreground animate-spin"
+            size={32}
+          />
+          <p className="text-muted-foreground text-sm">
+            {t("channels.weixin.generating")}
+          </p>
+        </div>
+      )
+    }
+
+    if (bindState === "waiting" || bindState === "scaned") {
+      return (
+        <div className="flex flex-col items-center gap-4 py-4">
+          {qrDataURI ? (
+            <img
+              src={qrDataURI}
+              alt="WeChat QR Code"
+              className="border-border/60 h-48 w-48 rounded-xl border bg-white p-2 shadow-sm"
+            />
+          ) : (
+            <div className="border-border/60 bg-muted flex h-48 w-48 items-center justify-center rounded-xl border">
+              <IconLoader2
+                className="text-muted-foreground animate-spin"
+                size={32}
+              />
+            </div>
+          )}
+          {bindState === "scaned" ? (
+            <div className="flex items-center gap-2 rounded-full bg-amber-500/10 px-4 py-2 text-sm font-medium text-amber-600 dark:text-amber-400">
+              <IconLoader2 size={14} className="animate-spin" />
+              {t("channels.weixin.scanned")}
+            </div>
+          ) : (
+            <p className="text-muted-foreground text-sm">
+              {t("channels.weixin.scanHint")}
+            </p>
+          )}
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={handleRebind}
+            className="text-muted-foreground"
+          >
+            <IconRefresh size={14} className="mr-1" />
+            {t("channels.weixin.refresh")}
+          </Button>
+        </div>
+      )
+    }
+
+    if (bindState === "confirmed") {
+      return (
+        <div className="flex flex-col items-center gap-3 py-6">
+          <div className="flex h-14 w-14 items-center justify-center rounded-full bg-emerald-500/10">
+            <IconCheck
+              size={28}
+              className="text-emerald-600 dark:text-emerald-400"
+            />
+          </div>
+          <p className="text-sm font-medium text-emerald-600 dark:text-emerald-400">
+            {t("channels.weixin.bound")}
+          </p>
+          {accountID && (
+            <p className="text-muted-foreground font-mono text-xs">
+              {accountID}
+            </p>
+          )}
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={handleRebind}
+            className="mt-1 gap-2"
+          >
+            <IconRefresh size={14} />
+            {t("channels.weixin.rebind")}
+          </Button>
+        </div>
+      )
+    }
+
+    if (bindState === "expired") {
+      return (
+        <div className="flex flex-col items-center gap-4 py-6">
+          <div className="flex h-14 w-14 items-center justify-center rounded-full bg-amber-500/10">
+            <IconX size={28} className="text-amber-600 dark:text-amber-400" />
+          </div>
+          <p className="text-sm text-amber-600 dark:text-amber-400">
+            {t("channels.weixin.expired")}
+          </p>
+          <Button onClick={handleRebind} className="gap-2">
+            <IconRefresh size={14} />
+            {t("channels.weixin.retry")}
+          </Button>
+        </div>
+      )
+    }
+
+    if (bindState === "error") {
+      return (
+        <div className="flex flex-col items-center gap-4 py-6">
+          <div className="bg-destructive/10 flex h-14 w-14 items-center justify-center rounded-full">
+            <IconX size={28} className="text-destructive" />
+          </div>
+          <p className="text-destructive text-sm">
+            {errorMsg || t("channels.weixin.errorGeneric")}
+          </p>
+          <Button variant="outline" onClick={handleRebind} className="gap-2">
+            <IconRefresh size={14} />
+            {t("channels.weixin.retry")}
+          </Button>
+        </div>
+      )
+    }
+
+    return null
+  }
+
+  return (
+    <div className="space-y-5">
+      {/* QR Bind Section */}
+      <div className="border-border/60 bg-muted/30 rounded-xl border">
+        <div className="border-border/60 border-b px-4 py-3">
+          <p className="text-sm font-medium">
+            {t("channels.weixin.bindTitle")}
+          </p>
+          <p className="text-muted-foreground mt-0.5 text-xs">
+            {t("channels.weixin.bindDesc")}
+          </p>
+        </div>
+        {renderBindSection()}
+      </div>
+
+      {/* allow_from */}
+      <Field
+        label={t("channels.field.allowFrom")}
+        hint={t("channels.form.desc.allowFrom")}
+      >
+        <Input
+          value={asStringArray(config.allow_from).join(", ")}
+          onChange={(e) =>
+            onChange(
+              "allow_from",
+              e.target.value
+                .split(",")
+                .map((s: string) => s.trim())
+                .filter(Boolean),
+            )
+          }
+          placeholder={t("channels.field.allowFromPlaceholder")}
+        />
+      </Field>
+
+      {/* proxy */}
+      <Field
+        label={t("channels.field.proxy")}
+        hint={t("channels.form.desc.proxy")}
+      >
+        <Input
+          value={asString(config.proxy)}
+          onChange={(e) => onChange("proxy", e.target.value)}
+          placeholder="http://localhost:7890"
+        />
+      </Field>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/chat/assistant-message.tsx b/web/frontend/src/components/chat/assistant-message.tsx
new file mode 100644
index 000000000..05da3ceb1
--- /dev/null
+++ b/web/frontend/src/components/chat/assistant-message.tsx
@@ -0,0 +1,69 @@
+import { IconCheck, IconCopy } from "@tabler/icons-react"
+import { useState } from "react"
+import ReactMarkdown from "react-markdown"
+import rehypeRaw from "rehype-raw"
+import rehypeSanitize from "rehype-sanitize"
+import remarkGfm from "remark-gfm"
+
+import { Button } from "@/components/ui/button"
+import { formatMessageTime } from "@/hooks/use-pico-chat"
+
+interface AssistantMessageProps {
+  content: string
+  timestamp?: string | number
+}
+
+export function AssistantMessage({
+  content,
+  timestamp = "",
+}: AssistantMessageProps) {
+  const [isCopied, setIsCopied] = useState(false)
+  const formattedTimestamp =
+    timestamp !== "" ? formatMessageTime(timestamp) : ""
+
+  const handleCopy = () => {
+    navigator.clipboard.writeText(content).then(() => {
+      setIsCopied(true)
+      setTimeout(() => setIsCopied(false), 2000)
+    })
+  }
+
+  return (
+    <div className="group flex w-full flex-col gap-1.5">
+      <div className="text-muted-foreground flex items-center justify-between gap-2 px-1 text-xs opacity-70">
+        <div className="flex items-center gap-2">
+          <span>PicoClaw</span>
+          {formattedTimestamp && (
+            <>
+              <span className="opacity-50">•</span>
+              <span>{formattedTimestamp}</span>
+            </>
+          )}
+        </div>
+      </div>
+
+      <div className="bg-card text-card-foreground relative overflow-hidden rounded-xl border">
+        <div className="prose dark:prose-invert prose-p:my-2 prose-pre:my-2 prose-pre:rounded-lg prose-pre:border prose-pre:bg-zinc-950 prose-pre:p-3 max-w-none p-4 text-[15px] leading-relaxed">
+          <ReactMarkdown
+            remarkPlugins={[remarkGfm]}
+            rehypePlugins={[rehypeRaw, rehypeSanitize]}
+          >
+            {content}
+          </ReactMarkdown>
+        </div>
+        <Button
+          variant="ghost"
+          size="icon"
+          className="bg-background/50 hover:bg-background/80 absolute top-2 right-2 h-7 w-7 opacity-0 transition-opacity group-hover:opacity-100"
+          onClick={handleCopy}
+        >
+          {isCopied ? (
+            <IconCheck className="h-4 w-4 text-green-500" />
+          ) : (
+            <IconCopy className="text-muted-foreground h-4 w-4" />
+          )}
+        </Button>
+      </div>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/chat/chat-composer.tsx b/web/frontend/src/components/chat/chat-composer.tsx
new file mode 100644
index 000000000..7d696b898
--- /dev/null
+++ b/web/frontend/src/components/chat/chat-composer.tsx
@@ -0,0 +1,67 @@
+import { IconArrowUp } from "@tabler/icons-react"
+import type { KeyboardEvent } from "react"
+import { useTranslation } from "react-i18next"
+import TextareaAutosize from "react-textarea-autosize"
+
+import { Button } from "@/components/ui/button"
+import { cn } from "@/lib/utils"
+
+interface ChatComposerProps {
+  input: string
+  onInputChange: (value: string) => void
+  onSend: () => void
+  isConnected: boolean
+  hasDefaultModel: boolean
+}
+
+export function ChatComposer({
+  input,
+  onInputChange,
+  onSend,
+  isConnected,
+  hasDefaultModel,
+}: ChatComposerProps) {
+  const { t } = useTranslation()
+  const canInput = isConnected && hasDefaultModel
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.nativeEvent.isComposing) return
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault()
+      onSend()
+    }
+  }
+
+  return (
+    <div className="bg-background shrink-0 px-4 pt-4 pb-[calc(1rem+env(safe-area-inset-bottom))] md:px-8 md:pb-8 lg:px-24 xl:px-48">
+      <div className="bg-card border-border/80 mx-auto flex max-w-[1000px] flex-col rounded-2xl border p-3 shadow-md">
+        <TextareaAutosize
+          value={input}
+          onChange={(e) => onInputChange(e.target.value)}
+          onKeyDown={handleKeyDown}
+          placeholder={t("chat.placeholder")}
+          disabled={!canInput}
+          className={cn(
+            "placeholder:text-muted-foreground max-h-[200px] min-h-[60px] resize-none border-0 bg-transparent px-2 py-1 text-[15px] shadow-none transition-colors focus-visible:ring-0 focus-visible:outline-none dark:bg-transparent",
+            !canInput && "cursor-not-allowed",
+          )}
+          minRows={1}
+          maxRows={8}
+        />
+
+        <div className="mt-2 flex items-center justify-between px-1">
+          <div className="flex items-center gap-1">{/* action buttons */}</div>
+
+          <Button
+            size="icon"
+            className="size-8 rounded-full bg-violet-500 text-white transition-transform hover:bg-violet-600 active:scale-95"
+            onClick={onSend}
+            disabled={!input.trim() || !canInput}
+          >
+            <IconArrowUp className="size-4" />
+          </Button>
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/chat/chat-empty-state.tsx b/web/frontend/src/components/chat/chat-empty-state.tsx
new file mode 100644
index 000000000..0574c44d1
--- /dev/null
+++ b/web/frontend/src/components/chat/chat-empty-state.tsx
@@ -0,0 +1,87 @@
+import {
+  IconPlugConnectedX,
+  IconRobot,
+  IconRobotOff,
+  IconStar,
+} from "@tabler/icons-react"
+import { Link } from "@tanstack/react-router"
+import { useTranslation } from "react-i18next"
+
+import { Button } from "@/components/ui/button"
+
+interface ChatEmptyStateProps {
+  hasConfiguredModels: boolean
+  defaultModelName: string
+  isConnected: boolean
+}
+
+export function ChatEmptyState({
+  hasConfiguredModels,
+  defaultModelName,
+  isConnected,
+}: ChatEmptyStateProps) {
+  const { t } = useTranslation()
+
+  if (!hasConfiguredModels) {
+    return (
+      <div className="flex flex-col items-center justify-center py-20 opacity-70">
+        <div className="mb-6 flex h-16 w-16 items-center justify-center rounded-2xl bg-amber-500/10 text-amber-500">
+          <IconRobotOff className="h-8 w-8" />
+        </div>
+        <h3 className="mb-2 text-xl font-medium">
+          {t("chat.empty.noConfiguredModel")}
+        </h3>
+        <p className="text-muted-foreground mb-4 text-center text-sm">
+          {t("chat.empty.noConfiguredModelDescription")}
+        </p>
+        <Button asChild variant="outline" size="sm" className="px-4">
+          <Link to="/models">{t("chat.empty.goToModels")}</Link>
+        </Button>
+      </div>
+    )
+  }
+
+  if (!defaultModelName) {
+    return (
+      <div className="flex flex-col items-center justify-center py-20 opacity-70">
+        <div className="mb-6 flex h-16 w-16 items-center justify-center rounded-2xl bg-amber-500/10 text-amber-500">
+          <IconStar className="h-8 w-8" />
+        </div>
+        <h3 className="mb-2 text-xl font-medium">
+          {t("chat.empty.noSelectedModel")}
+        </h3>
+        <p className="text-muted-foreground mb-4 text-center text-sm">
+          {t("chat.empty.noSelectedModelDescription")}
+        </p>
+      </div>
+    )
+  }
+
+  if (!isConnected) {
+    return (
+      <div className="flex flex-col items-center justify-center py-20 opacity-70">
+        <div className="mb-6 flex h-16 w-16 items-center justify-center rounded-2xl bg-amber-500/10 text-amber-500">
+          <IconPlugConnectedX className="h-8 w-8" />
+        </div>
+        <h3 className="mb-2 text-xl font-medium">
+          {t("chat.empty.notRunning")}
+        </h3>
+        <p className="text-muted-foreground mb-4 text-center text-sm">
+          {t("chat.empty.notRunningDescription")}
+        </p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex flex-col items-center justify-center py-20 opacity-70">
+      <div className="mb-6 flex h-16 w-16 items-center justify-center rounded-2xl bg-violet-500/10 text-violet-500">
+        <IconRobot className="h-8 w-8" />
+      </div>
+      <h3 className="mb-2 text-xl font-medium">{t("chat.welcome")}</h3>
+      <p className="text-muted-foreground text-center text-sm">
+        {t("chat.welcomeDesc")}
+      </p>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/chat/chat-page.tsx b/web/frontend/src/components/chat/chat-page.tsx
new file mode 100644
index 000000000..ebcde8981
--- /dev/null
+++ b/web/frontend/src/components/chat/chat-page.tsx
@@ -0,0 +1,175 @@
+import { IconPlus } from "@tabler/icons-react"
+import { useEffect, useRef, useState } from "react"
+import { useTranslation } from "react-i18next"
+
+import { AssistantMessage } from "@/components/chat/assistant-message"
+import { ChatComposer } from "@/components/chat/chat-composer"
+import { ChatEmptyState } from "@/components/chat/chat-empty-state"
+import { ModelSelector } from "@/components/chat/model-selector"
+import { SessionHistoryMenu } from "@/components/chat/session-history-menu"
+import { TypingIndicator } from "@/components/chat/typing-indicator"
+import { UserMessage } from "@/components/chat/user-message"
+import { PageHeader } from "@/components/page-header"
+import { Button } from "@/components/ui/button"
+import { useChatModels } from "@/hooks/use-chat-models"
+import { useGateway } from "@/hooks/use-gateway"
+import { usePicoChat } from "@/hooks/use-pico-chat"
+import { useSessionHistory } from "@/hooks/use-session-history"
+
+export function ChatPage() {
+  const { t } = useTranslation()
+  const scrollRef = useRef<HTMLDivElement>(null)
+  const [isAtBottom, setIsAtBottom] = useState(true)
+  const [hasScrolled, setHasScrolled] = useState(false)
+  const [input, setInput] = useState("")
+
+  const {
+    messages,
+    connectionState,
+    isTyping,
+    activeSessionId,
+    sendMessage,
+    switchSession,
+    newChat,
+  } = usePicoChat()
+
+  const { state: gwState } = useGateway()
+  const isGatewayRunning = gwState === "running"
+  const isChatConnected = connectionState === "connected"
+
+  const {
+    defaultModelName,
+    hasConfiguredModels,
+    apiKeyModels,
+    oauthModels,
+    localModels,
+    handleSetDefault,
+  } = useChatModels({ isConnected: isGatewayRunning })
+  const canSend = isChatConnected && Boolean(defaultModelName)
+
+  const {
+    sessions,
+    hasMore,
+    loadError,
+    loadErrorMessage,
+    observerRef,
+    loadSessions,
+    handleDeleteSession,
+  } = useSessionHistory({
+    activeSessionId,
+    onDeletedActiveSession: newChat,
+  })
+
+  const syncScrollState = (element: HTMLDivElement) => {
+    const { scrollTop, scrollHeight, clientHeight } = element
+    setHasScrolled(scrollTop > 0)
+    setIsAtBottom(scrollHeight - scrollTop <= clientHeight + 10)
+  }
+
+  const handleScroll = (e: React.UIEvent<HTMLDivElement>) => {
+    syncScrollState(e.currentTarget)
+  }
+
+  useEffect(() => {
+    if (scrollRef.current) {
+      if (isAtBottom) {
+        scrollRef.current.scrollTop = scrollRef.current.scrollHeight
+      }
+      syncScrollState(scrollRef.current)
+    }
+  }, [messages, isTyping, isAtBottom])
+
+  const handleSend = () => {
+    if (!input.trim() || !canSend) return
+    if (sendMessage(input.trim())) {
+      setInput("")
+    }
+  }
+
+  return (
+    <div className="bg-background/95 flex h-full flex-col">
+      <PageHeader
+        title={t("navigation.chat")}
+        className={`transition-shadow ${
+          hasScrolled ? "shadow-sm" : "shadow-none"
+        }`}
+        titleExtra={
+          hasConfiguredModels && (
+            <ModelSelector
+              defaultModelName={defaultModelName}
+              apiKeyModels={apiKeyModels}
+              oauthModels={oauthModels}
+              localModels={localModels}
+              onValueChange={handleSetDefault}
+            />
+          )
+        }
+      >
+        <Button
+          variant="secondary"
+          size="sm"
+          onClick={newChat}
+          className="h-9 gap-2"
+        >
+          <IconPlus className="size-4" />
+          <span className="hidden sm:inline">{t("chat.newChat")}</span>
+        </Button>
+
+        <SessionHistoryMenu
+          sessions={sessions}
+          activeSessionId={activeSessionId}
+          hasMore={hasMore}
+          loadError={loadError}
+          loadErrorMessage={loadErrorMessage}
+          observerRef={observerRef}
+          onOpenChange={(open) => {
+            if (open) {
+              void loadSessions(true)
+            }
+          }}
+          onSwitchSession={switchSession}
+          onDeleteSession={handleDeleteSession}
+        />
+      </PageHeader>
+
+      <div
+        ref={scrollRef}
+        onScroll={handleScroll}
+        className="min-h-0 flex-1 overflow-y-auto px-4 py-6 md:px-8 lg:px-24 xl:px-48"
+      >
+        <div className="mx-auto flex w-full max-w-250 flex-col gap-8 pb-8">
+          {messages.length === 0 && !isTyping && (
+            <ChatEmptyState
+              hasConfiguredModels={hasConfiguredModels}
+              defaultModelName={defaultModelName}
+              isConnected={isGatewayRunning}
+            />
+          )}
+
+          {messages.map((msg) => (
+            <div key={msg.id} className="flex w-full">
+              {msg.role === "assistant" ? (
+                <AssistantMessage
+                  content={msg.content}
+                  timestamp={msg.timestamp}
+                />
+              ) : (
+                <UserMessage content={msg.content} />
+              )}
+            </div>
+          ))}
+
+          {isTyping && <TypingIndicator />}
+        </div>
+      </div>
+
+      <ChatComposer
+        input={input}
+        onInputChange={setInput}
+        onSend={handleSend}
+        isConnected={isChatConnected}
+        hasDefaultModel={Boolean(defaultModelName)}
+      />
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/chat/model-selector.tsx b/web/frontend/src/components/chat/model-selector.tsx
new file mode 100644
index 000000000..2364f9bf2
--- /dev/null
+++ b/web/frontend/src/components/chat/model-selector.tsx
@@ -0,0 +1,84 @@
+import { useTranslation } from "react-i18next"
+
+import type { ModelInfo } from "@/api/models"
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
+
+interface ModelSelectorProps {
+  defaultModelName: string
+  apiKeyModels: ModelInfo[]
+  oauthModels: ModelInfo[]
+  localModels: ModelInfo[]
+  onValueChange: (modelName: string) => void
+}
+
+export function ModelSelector({
+  defaultModelName,
+  apiKeyModels,
+  oauthModels,
+  localModels,
+  onValueChange,
+}: ModelSelectorProps) {
+  const { t } = useTranslation()
+
+  return (
+    <Select value={defaultModelName} onValueChange={onValueChange}>
+      <SelectTrigger
+        size="sm"
+        className="text-muted-foreground hover:text-foreground focus-visible:border-input h-8 max-w-[160px] min-w-[80px] bg-transparent shadow-none focus-visible:ring-0 sm:max-w-[220px]"
+      >
+        <SelectValue placeholder={t("chat.noModel")} />
+      </SelectTrigger>
+      <SelectContent position="popper" align="start">
+        {apiKeyModels.length > 0 && (
+          <SelectGroup>
+            <SelectLabel>{t("chat.modelGroup.apikey")}</SelectLabel>
+            {apiKeyModels.map((model) => (
+              <SelectItem key={model.index} value={model.model_name}>
+                {model.model_name}
+              </SelectItem>
+            ))}
+          </SelectGroup>
+        )}
+        {apiKeyModels.length > 0 &&
+          (oauthModels.length > 0 || localModels.length > 0) && (
+            <SelectSeparator />
+          )}
+
+        {oauthModels.length > 0 && (
+          <SelectGroup>
+            <SelectLabel>{t("chat.modelGroup.oauth")}</SelectLabel>
+            {oauthModels.map((model) => (
+              <SelectItem key={model.index} value={model.model_name}>
+                {model.model_name}
+              </SelectItem>
+            ))}
+          </SelectGroup>
+        )}
+        {oauthModels.length > 0 &&
+          (localModels.length > 0 || apiKeyModels.length > 0) && (
+            <SelectSeparator />
+          )}
+
+        {localModels.length > 0 && (
+          <SelectGroup>
+            <SelectLabel>{t("chat.modelGroup.local")}</SelectLabel>
+            {localModels.map((model) => (
+              <SelectItem key={model.index} value={model.model_name}>
+                {model.model_name}
+              </SelectItem>
+            ))}
+          </SelectGroup>
+        )}
+      </SelectContent>
+    </Select>
+  )
+}
diff --git a/web/frontend/src/components/chat/session-history-menu.tsx b/web/frontend/src/components/chat/session-history-menu.tsx
new file mode 100644
index 000000000..009e8fbb9
--- /dev/null
+++ b/web/frontend/src/components/chat/session-history-menu.tsx
@@ -0,0 +1,109 @@
+import { IconHistory, IconTrash } from "@tabler/icons-react"
+import dayjs from "dayjs"
+import type { RefObject } from "react"
+import { useTranslation } from "react-i18next"
+
+import type { SessionSummary } from "@/api/sessions"
+import { Button } from "@/components/ui/button"
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu"
+import { ScrollArea } from "@/components/ui/scroll-area"
+
+interface SessionHistoryMenuProps {
+  sessions: SessionSummary[]
+  activeSessionId: string
+  hasMore: boolean
+  loadError: boolean
+  loadErrorMessage: string
+  observerRef: RefObject<HTMLDivElement | null>
+  onOpenChange: (open: boolean) => void
+  onSwitchSession: (sessionId: string) => void
+  onDeleteSession: (sessionId: string) => void
+}
+
+export function SessionHistoryMenu({
+  sessions,
+  activeSessionId,
+  hasMore,
+  loadError,
+  loadErrorMessage,
+  observerRef,
+  onOpenChange,
+  onSwitchSession,
+  onDeleteSession,
+}: SessionHistoryMenuProps) {
+  const { t } = useTranslation()
+
+  return (
+    <DropdownMenu onOpenChange={onOpenChange}>
+      <DropdownMenuTrigger asChild>
+        <Button variant="secondary" size="sm" className="h-9 gap-2">
+          <IconHistory className="size-4" />
+          <span className="hidden sm:inline">{t("chat.history")}</span>
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-72">
+        <ScrollArea className="max-h-[300px]">
+          {loadError && (
+            <DropdownMenuItem disabled>
+              <span className="text-destructive text-xs">
+                {loadErrorMessage}
+              </span>
+            </DropdownMenuItem>
+          )}
+          {sessions.length === 0 && !loadError ? (
+            <DropdownMenuItem disabled>
+              <span className="text-muted-foreground text-xs">
+                {t("chat.noHistory")}
+              </span>
+            </DropdownMenuItem>
+          ) : (
+            sessions.map((session) => (
+              <DropdownMenuItem
+                key={session.id}
+                className={`group relative my-0.5 flex flex-col items-start gap-0.5 pr-8 ${
+                  session.id === activeSessionId ? "bg-accent" : ""
+                }`}
+                onClick={() => onSwitchSession(session.id)}
+              >
+                <span className="line-clamp-1 text-sm font-medium">
+                  {session.title || session.preview}
+                </span>
+                <span className="text-muted-foreground text-xs">
+                  {t("chat.messagesCount", {
+                    count: session.message_count,
+                  })}{" "}
+                  · {dayjs(session.updated).fromNow()}
+                </span>
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  aria-label={t("chat.deleteSession")}
+                  className="text-muted-foreground hover:bg-destructive/10 hover:text-destructive absolute top-1/2 right-2 h-6 w-6 -translate-y-1/2 opacity-0 transition-opacity group-hover:opacity-100"
+                  onClick={(e) => {
+                    e.preventDefault()
+                    e.stopPropagation()
+                    onDeleteSession(session.id)
+                  }}
+                >
+                  <IconTrash className="h-4 w-4" />
+                </Button>
+              </DropdownMenuItem>
+            ))
+          )}
+          {hasMore && sessions.length > 0 && (
+            <div ref={observerRef} className="py-2 text-center">
+              <span className="text-muted-foreground animate-pulse text-xs">
+                {t("chat.loadingMore")}
+              </span>
+            </div>
+          )}
+        </ScrollArea>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
diff --git a/web/frontend/src/components/chat/typing-indicator.tsx b/web/frontend/src/components/chat/typing-indicator.tsx
new file mode 100644
index 000000000..98580963d
--- /dev/null
+++ b/web/frontend/src/components/chat/typing-indicator.tsx
@@ -0,0 +1,47 @@
+import { useEffect, useState } from "react"
+import { useTranslation } from "react-i18next"
+
+export function TypingIndicator() {
+  const { t } = useTranslation()
+  const thinkingSteps = [
+    t("chat.thinking.step1"),
+    t("chat.thinking.step2"),
+    t("chat.thinking.step3"),
+    t("chat.thinking.step4"),
+  ]
+  const [stepIndex, setStepIndex] = useState(0)
+
+  useEffect(() => {
+    const stepsCount = thinkingSteps.length
+    const interval = setInterval(() => {
+      setStepIndex((prev) => (prev + 1) % stepsCount)
+    }, 3000)
+    return () => clearInterval(interval)
+  }, [thinkingSteps.length])
+
+  return (
+    <div className="flex w-full flex-col gap-1.5">
+      <div className="text-muted-foreground flex items-center gap-2 px-1 text-xs opacity-70">
+        <span>PicoClaw</span>
+      </div>
+      <div className="bg-card inline-flex w-fit max-w-xs flex-col gap-3 rounded-xl border px-5 py-4">
+        <div className="flex items-center gap-1.5">
+          <span className="size-2 animate-bounce rounded-full bg-violet-400/70 [animation-delay:-0.3s]" />
+          <span className="size-2 animate-bounce rounded-full bg-violet-400/70 [animation-delay:-0.15s]" />
+          <span className="size-2 animate-bounce rounded-full bg-violet-400/70" />
+        </div>
+
+        <div className="bg-muted relative h-1 w-36 overflow-hidden rounded-full">
+          <div className="absolute inset-0 animate-[shimmer_2s_infinite] rounded-full bg-gradient-to-r from-violet-500/60 via-violet-400/80 to-violet-500/60 bg-[length:200%_100%]" />
+        </div>
+
+        <p
+          key={stepIndex}
+          className="text-muted-foreground animate-[fadeSlideIn_0.4s_ease-out] text-xs"
+        >
+          {thinkingSteps[stepIndex]}
+        </p>
+      </div>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/chat/user-message.tsx b/web/frontend/src/components/chat/user-message.tsx
new file mode 100644
index 000000000..0035f14fa
--- /dev/null
+++ b/web/frontend/src/components/chat/user-message.tsx
@@ -0,0 +1,13 @@
+interface UserMessageProps {
+  content: string
+}
+
+export function UserMessage({ content }: UserMessageProps) {
+  return (
+    <div className="flex w-full flex-col items-end gap-1.5">
+      <div className="max-w-[70%] rounded-2xl rounded-tr-sm bg-violet-500 px-5 py-3 text-[15px] leading-relaxed whitespace-pre-wrap text-white shadow-sm">
+        {content}
+      </div>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/config/config-page.tsx b/web/frontend/src/components/config/config-page.tsx
new file mode 100644
index 000000000..24a719d86
--- /dev/null
+++ b/web/frontend/src/components/config/config-page.tsx
@@ -0,0 +1,370 @@
+import { IconCode, IconDeviceFloppy } from "@tabler/icons-react"
+import { useQuery, useQueryClient } from "@tanstack/react-query"
+import { Link } from "@tanstack/react-router"
+import { useEffect, useState } from "react"
+import { useTranslation } from "react-i18next"
+import { toast } from "sonner"
+
+import { patchAppConfig } from "@/api/channels"
+import {
+  getAutoStartStatus,
+  getLauncherConfig,
+  setAutoStartEnabled as updateAutoStartEnabled,
+  setLauncherConfig as updateLauncherConfig,
+} from "@/api/system"
+import {
+  AgentDefaultsSection,
+  CronSection,
+  DevicesSection,
+  ExecSection,
+  LauncherSection,
+  RuntimeSection,
+} from "@/components/config/config-sections"
+import {
+  type CoreConfigForm,
+  EMPTY_FORM,
+  EMPTY_LAUNCHER_FORM,
+  type LauncherForm,
+  buildFormFromConfig,
+  parseCIDRText,
+  parseIntField,
+  parseMultilineList,
+} from "@/components/config/form-model"
+import { PageHeader } from "@/components/page-header"
+import { Button } from "@/components/ui/button"
+
+export function ConfigPage() {
+  const { t } = useTranslation()
+  const queryClient = useQueryClient()
+  const [form, setForm] = useState<CoreConfigForm>(EMPTY_FORM)
+  const [baseline, setBaseline] = useState<CoreConfigForm>(EMPTY_FORM)
+  const [launcherForm, setLauncherForm] =
+    useState<LauncherForm>(EMPTY_LAUNCHER_FORM)
+  const [launcherBaseline, setLauncherBaseline] =
+    useState<LauncherForm>(EMPTY_LAUNCHER_FORM)
+  const [autoStartEnabled, setAutoStartEnabled] = useState(false)
+  const [autoStartBaseline, setAutoStartBaseline] = useState(false)
+  const [saving, setSaving] = useState(false)
+
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["config"],
+    queryFn: async () => {
+      const res = await fetch("/api/config")
+      if (!res.ok) {
+        throw new Error("Failed to load config")
+      }
+      return res.json()
+    },
+  })
+
+  const { data: launcherConfig, isLoading: isLauncherLoading } = useQuery({
+    queryKey: ["system", "launcher-config"],
+    queryFn: getLauncherConfig,
+  })
+
+  const {
+    data: autoStartStatus,
+    isLoading: isAutoStartLoading,
+    error: autoStartError,
+  } = useQuery({
+    queryKey: ["system", "autostart"],
+    queryFn: getAutoStartStatus,
+  })
+
+  useEffect(() => {
+    if (!data) return
+    const parsed = buildFormFromConfig(data)
+    setForm(parsed)
+    setBaseline(parsed)
+  }, [data])
+
+  useEffect(() => {
+    if (!launcherConfig) return
+    const parsed: LauncherForm = {
+      port: String(launcherConfig.port),
+      publicAccess: launcherConfig.public,
+      allowedCIDRsText: (launcherConfig.allowed_cidrs ?? []).join("\n"),
+    }
+    setLauncherForm(parsed)
+    setLauncherBaseline(parsed)
+  }, [launcherConfig])
+
+  useEffect(() => {
+    if (!autoStartStatus) return
+    setAutoStartEnabled(autoStartStatus.enabled)
+    setAutoStartBaseline(autoStartStatus.enabled)
+  }, [autoStartStatus])
+
+  const configDirty = JSON.stringify(form) !== JSON.stringify(baseline)
+  const launcherDirty =
+    JSON.stringify(launcherForm) !== JSON.stringify(launcherBaseline)
+  const autoStartDirty = autoStartEnabled !== autoStartBaseline
+  const isDirty = configDirty || launcherDirty || autoStartDirty
+
+  const autoStartSupported = autoStartStatus?.supported !== false
+  const autoStartHint = autoStartError
+    ? t("pages.config.autostart_load_error")
+    : !autoStartSupported
+      ? t("pages.config.autostart_unsupported")
+      : t("pages.config.autostart_hint")
+
+  const updateField = <K extends keyof CoreConfigForm>(
+    key: K,
+    value: CoreConfigForm[K],
+  ) => {
+    setForm((prev) => ({ ...prev, [key]: value }))
+  }
+
+  const updateLauncherField = <K extends keyof LauncherForm>(
+    key: K,
+    value: LauncherForm[K],
+  ) => {
+    setLauncherForm((prev) => ({ ...prev, [key]: value }))
+  }
+
+  const handleReset = () => {
+    setForm(baseline)
+    setLauncherForm(launcherBaseline)
+    setAutoStartEnabled(autoStartBaseline)
+    toast.info(t("pages.config.reset_success"))
+  }
+
+  const handleSave = async () => {
+    try {
+      setSaving(true)
+
+      if (configDirty) {
+        const workspace = form.workspace.trim()
+        const dmScope = form.dmScope.trim()
+
+        if (!workspace) {
+          throw new Error("Workspace path is required.")
+        }
+        if (!dmScope) {
+          throw new Error("Session scope is required.")
+        }
+
+        const maxTokens = parseIntField(form.maxTokens, "Max tokens", {
+          min: 1,
+        })
+        const contextWindow = form.contextWindow.trim()
+          ? parseIntField(form.contextWindow, "Context window", { min: 1 })
+          : undefined
+        const maxToolIterations = parseIntField(
+          form.maxToolIterations,
+          "Max tool iterations",
+          { min: 1 },
+        )
+        const toolFeedbackMaxArgsLength = parseIntField(
+          form.toolFeedbackMaxArgsLength,
+          "Tool feedback max args length",
+          { min: 0 },
+        )
+        const summarizeMessageThreshold = parseIntField(
+          form.summarizeMessageThreshold,
+          "Summarize message threshold",
+          { min: 1 },
+        )
+        const summarizeTokenPercent = parseIntField(
+          form.summarizeTokenPercent,
+          "Summarize token percent",
+          { min: 1, max: 100 },
+        )
+        const heartbeatInterval = parseIntField(
+          form.heartbeatInterval,
+          "Heartbeat interval",
+          { min: 1 },
+        )
+        const cronExecTimeoutMinutes = parseIntField(
+          form.cronExecTimeoutMinutes,
+          "Cron exec timeout",
+          { min: 0 },
+        )
+        const execConfigPatch: Record<string, unknown> = {
+          enabled: form.execEnabled,
+        }
+
+        if (form.execEnabled) {
+          execConfigPatch.allow_remote = form.allowRemote
+          execConfigPatch.enable_deny_patterns = form.enableDenyPatterns
+          execConfigPatch.custom_allow_patterns = parseMultilineList(
+            form.customAllowPatternsText,
+          )
+          execConfigPatch.timeout_seconds = parseIntField(
+            form.execTimeoutSeconds,
+            "Exec timeout",
+            { min: 0 },
+          )
+
+          if (form.enableDenyPatterns) {
+            execConfigPatch.custom_deny_patterns = parseMultilineList(
+              form.customDenyPatternsText,
+            )
+          }
+        }
+
+        await patchAppConfig({
+          agents: {
+            defaults: {
+              workspace,
+              restrict_to_workspace: form.restrictToWorkspace,
+              tool_feedback: {
+                enabled: form.toolFeedbackEnabled,
+                max_args_length: toolFeedbackMaxArgsLength,
+              },
+              max_tokens: maxTokens,
+              context_window: contextWindow,
+              max_tool_iterations: maxToolIterations,
+              summarize_message_threshold: summarizeMessageThreshold,
+              summarize_token_percent: summarizeTokenPercent,
+            },
+          },
+          session: {
+            dm_scope: dmScope,
+          },
+          tools: {
+            cron: {
+              allow_command: form.allowCommand,
+              exec_timeout_minutes: cronExecTimeoutMinutes,
+            },
+            exec: execConfigPatch,
+          },
+          heartbeat: {
+            enabled: form.heartbeatEnabled,
+            interval: heartbeatInterval,
+          },
+          devices: {
+            enabled: form.devicesEnabled,
+            monitor_usb: form.monitorUSB,
+          },
+        })
+
+        setBaseline(form)
+        queryClient.invalidateQueries({ queryKey: ["config"] })
+      }
+
+      if (launcherDirty) {
+        const port = parseIntField(launcherForm.port, "Service port", {
+          min: 1,
+          max: 65535,
+        })
+        const allowedCIDRs = parseCIDRText(launcherForm.allowedCIDRsText)
+        const savedLauncherConfig = await updateLauncherConfig({
+          port,
+          public: launcherForm.publicAccess,
+          allowed_cidrs: allowedCIDRs,
+        })
+        const parsedLauncher: LauncherForm = {
+          port: String(savedLauncherConfig.port),
+          publicAccess: savedLauncherConfig.public,
+          allowedCIDRsText: (savedLauncherConfig.allowed_cidrs ?? []).join(
+            "\n",
+          ),
+        }
+        setLauncherForm(parsedLauncher)
+        setLauncherBaseline(parsedLauncher)
+        queryClient.setQueryData(
+          ["system", "launcher-config"],
+          savedLauncherConfig,
+        )
+      }
+
+      if (autoStartDirty) {
+        if (!autoStartSupported) {
+          throw new Error(t("pages.config.autostart_unsupported"))
+        }
+        const status = await updateAutoStartEnabled(autoStartEnabled)
+        setAutoStartEnabled(status.enabled)
+        setAutoStartBaseline(status.enabled)
+        queryClient.setQueryData(["system", "autostart"], status)
+      }
+
+      toast.success(t("pages.config.save_success"))
+    } catch (err) {
+      toast.error(
+        err instanceof Error ? err.message : t("pages.config.save_error"),
+      )
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  return (
+    <div className="flex h-full flex-col">
+      <PageHeader
+        title={t("navigation.config")}
+        children={
+          <Button variant="outline" asChild>
+            <Link to="/config/raw">
+              <IconCode className="size-4" />
+              {t("pages.config.open_raw")}
+            </Link>
+          </Button>
+        }
+      />
+      <div className="flex-1 overflow-auto p-3 lg:p-6">
+        <div className="mx-auto w-full max-w-[1000px] space-y-6">
+          {isLoading ? (
+            <div className="text-muted-foreground py-6 text-sm">
+              {t("labels.loading")}
+            </div>
+          ) : error ? (
+            <div className="text-destructive py-6 text-sm">
+              {t("pages.config.load_error")}
+            </div>
+          ) : (
+            <div className="space-y-6">
+              {isDirty && (
+                <div className="bg-yellow-50 px-3 py-2 text-sm text-yellow-700">
+                  {t("pages.config.unsaved_changes")}
+                </div>
+              )}
+
+              <AgentDefaultsSection form={form} onFieldChange={updateField} />
+
+              <RuntimeSection form={form} onFieldChange={updateField} />
+
+              <ExecSection form={form} onFieldChange={updateField} />
+
+              <CronSection form={form} onFieldChange={updateField} />
+
+              <LauncherSection
+                launcherForm={launcherForm}
+                onFieldChange={updateLauncherField}
+                disabled={saving || isLauncherLoading}
+              />
+
+              <DevicesSection
+                form={form}
+                onFieldChange={updateField}
+                autoStartEnabled={autoStartEnabled}
+                autoStartHint={autoStartHint}
+                autoStartDisabled={
+                  isAutoStartLoading ||
+                  Boolean(autoStartError) ||
+                  !autoStartSupported ||
+                  saving
+                }
+                onAutoStartChange={setAutoStartEnabled}
+              />
+
+              <div className="flex justify-end gap-2">
+                <Button
+                  variant="outline"
+                  onClick={handleReset}
+                  disabled={!isDirty || saving}
+                >
+                  {t("common.reset")}
+                </Button>
+                <Button onClick={handleSave} disabled={!isDirty || saving}>
+                  <IconDeviceFloppy className="size-4" />
+                  {saving ? t("common.saving") : t("common.save")}
+                </Button>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/config/config-sections.tsx b/web/frontend/src/components/config/config-sections.tsx
new file mode 100644
index 000000000..5482b0a35
--- /dev/null
+++ b/web/frontend/src/components/config/config-sections.tsx
@@ -0,0 +1,506 @@
+import type { ReactNode } from "react"
+import { useTranslation } from "react-i18next"
+
+import {
+  type CoreConfigForm,
+  DM_SCOPE_OPTIONS,
+  type LauncherForm,
+} from "@/components/config/form-model"
+import { Field, SwitchCardField } from "@/components/shared-form"
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card"
+import { Input } from "@/components/ui/input"
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select"
+import { Textarea } from "@/components/ui/textarea"
+
+type UpdateCoreField = <K extends keyof CoreConfigForm>(
+  key: K,
+  value: CoreConfigForm[K],
+) => void
+
+type UpdateLauncherField = <K extends keyof LauncherForm>(
+  key: K,
+  value: LauncherForm[K],
+) => void
+
+interface ConfigSectionCardProps {
+  title: string
+  description?: string
+  children: ReactNode
+}
+
+function ConfigSectionCard({
+  title,
+  description,
+  children,
+}: ConfigSectionCardProps) {
+  return (
+    <Card size="sm">
+      <CardHeader className="border-border border-b">
+        <CardTitle>{title}</CardTitle>
+        {description && <CardDescription>{description}</CardDescription>}
+      </CardHeader>
+      <CardContent className="pt-0">
+        <div className="divide-border/70 divide-y">{children}</div>
+      </CardContent>
+    </Card>
+  )
+}
+
+interface AgentDefaultsSectionProps {
+  form: CoreConfigForm
+  onFieldChange: UpdateCoreField
+}
+
+export function AgentDefaultsSection({
+  form,
+  onFieldChange,
+}: AgentDefaultsSectionProps) {
+  const { t } = useTranslation()
+
+  return (
+    <ConfigSectionCard title={t("pages.config.sections.agent")}>
+      <Field
+        label={t("pages.config.workspace")}
+        hint={t("pages.config.workspace_hint")}
+        layout="setting-row"
+      >
+        <Input
+          value={form.workspace}
+          onChange={(e) => onFieldChange("workspace", e.target.value)}
+          placeholder="~/.picoclaw/workspace"
+        />
+      </Field>
+
+      <SwitchCardField
+        label={t("pages.config.restrict_workspace")}
+        hint={t("pages.config.restrict_workspace_hint")}
+        layout="setting-row"
+        checked={form.restrictToWorkspace}
+        onCheckedChange={(checked) =>
+          onFieldChange("restrictToWorkspace", checked)
+        }
+      />
+
+      <SwitchCardField
+        label={t("pages.config.tool_feedback_enabled")}
+        hint={t("pages.config.tool_feedback_enabled_hint")}
+        layout="setting-row"
+        checked={form.toolFeedbackEnabled}
+        onCheckedChange={(checked) =>
+          onFieldChange("toolFeedbackEnabled", checked)
+        }
+      />
+
+      {form.toolFeedbackEnabled && (
+        <Field
+          label={t("pages.config.tool_feedback_max_args_length")}
+          hint={t("pages.config.tool_feedback_max_args_length_hint")}
+          layout="setting-row"
+        >
+          <Input
+            type="number"
+            min={0}
+            value={form.toolFeedbackMaxArgsLength}
+            onChange={(e) =>
+              onFieldChange("toolFeedbackMaxArgsLength", e.target.value)
+            }
+          />
+        </Field>
+      )}
+
+      <Field
+        label={t("pages.config.max_tokens")}
+        hint={t("pages.config.max_tokens_hint")}
+        layout="setting-row"
+      >
+        <Input
+          type="number"
+          min={1}
+          value={form.maxTokens}
+          onChange={(e) => onFieldChange("maxTokens", e.target.value)}
+        />
+      </Field>
+
+      <Field
+        label={t("pages.config.context_window")}
+        hint={t("pages.config.context_window_hint")}
+        layout="setting-row"
+      >
+        <Input
+          type="number"
+          min={1}
+          value={form.contextWindow}
+          onChange={(e) => onFieldChange("contextWindow", e.target.value)}
+          placeholder="131072"
+        />
+      </Field>
+
+      <Field
+        label={t("pages.config.max_tool_iterations")}
+        hint={t("pages.config.max_tool_iterations_hint")}
+        layout="setting-row"
+      >
+        <Input
+          type="number"
+          min={1}
+          value={form.maxToolIterations}
+          onChange={(e) => onFieldChange("maxToolIterations", e.target.value)}
+        />
+      </Field>
+
+      <Field
+        label={t("pages.config.summarize_threshold")}
+        hint={t("pages.config.summarize_threshold_hint")}
+        layout="setting-row"
+      >
+        <Input
+          type="number"
+          min={1}
+          value={form.summarizeMessageThreshold}
+          onChange={(e) =>
+            onFieldChange("summarizeMessageThreshold", e.target.value)
+          }
+        />
+      </Field>
+
+      <Field
+        label={t("pages.config.summarize_token_percent")}
+        hint={t("pages.config.summarize_token_percent_hint")}
+        layout="setting-row"
+      >
+        <Input
+          type="number"
+          min={1}
+          max={100}
+          value={form.summarizeTokenPercent}
+          onChange={(e) =>
+            onFieldChange("summarizeTokenPercent", e.target.value)
+          }
+        />
+      </Field>
+    </ConfigSectionCard>
+  )
+}
+
+interface ExecSectionProps {
+  form: CoreConfigForm
+  onFieldChange: UpdateCoreField
+}
+
+export function ExecSection({ form, onFieldChange }: ExecSectionProps) {
+  const { t } = useTranslation()
+
+  return (
+    <ConfigSectionCard title={t("pages.config.sections.exec")}>
+      <SwitchCardField
+        label={t("pages.config.exec_enabled")}
+        hint={t("pages.config.exec_enabled_hint")}
+        layout="setting-row"
+        checked={form.execEnabled}
+        onCheckedChange={(checked) => onFieldChange("execEnabled", checked)}
+      />
+
+      {form.execEnabled && (
+        <>
+          <SwitchCardField
+            label={t("pages.config.allow_remote")}
+            hint={t("pages.config.allow_remote_hint")}
+            layout="setting-row"
+            checked={form.allowRemote}
+            onCheckedChange={(checked) => onFieldChange("allowRemote", checked)}
+          />
+
+          <SwitchCardField
+            label={t("pages.config.enable_deny_patterns")}
+            hint={t("pages.config.enable_deny_patterns_hint")}
+            layout="setting-row"
+            checked={form.enableDenyPatterns}
+            onCheckedChange={(checked) =>
+              onFieldChange("enableDenyPatterns", checked)
+            }
+          />
+
+          {form.enableDenyPatterns && (
+            <Field
+              label={t("pages.config.custom_deny_patterns")}
+              hint={t("pages.config.custom_deny_patterns_hint")}
+              layout="setting-row"
+              controlClassName="md:max-w-md"
+            >
+              <Textarea
+                value={form.customDenyPatternsText}
+                placeholder={t("pages.config.custom_patterns_placeholder")}
+                className="min-h-[88px]"
+                onChange={(e) =>
+                  onFieldChange("customDenyPatternsText", e.target.value)
+                }
+              />
+            </Field>
+          )}
+
+          <Field
+            label={t("pages.config.custom_allow_patterns")}
+            hint={t("pages.config.custom_allow_patterns_hint")}
+            layout="setting-row"
+            controlClassName="md:max-w-md"
+          >
+            <Textarea
+              value={form.customAllowPatternsText}
+              placeholder={t("pages.config.custom_patterns_placeholder")}
+              className="min-h-[88px]"
+              onChange={(e) =>
+                onFieldChange("customAllowPatternsText", e.target.value)
+              }
+            />
+          </Field>
+
+          <Field
+            label={t("pages.config.exec_timeout_seconds")}
+            hint={t("pages.config.exec_timeout_seconds_hint")}
+            layout="setting-row"
+          >
+            <Input
+              type="number"
+              min={0}
+              value={form.execTimeoutSeconds}
+              onChange={(e) =>
+                onFieldChange("execTimeoutSeconds", e.target.value)
+              }
+            />
+          </Field>
+        </>
+      )}
+    </ConfigSectionCard>
+  )
+}
+
+interface RuntimeSectionProps {
+  form: CoreConfigForm
+  onFieldChange: UpdateCoreField
+}
+
+export function RuntimeSection({ form, onFieldChange }: RuntimeSectionProps) {
+  const { t } = useTranslation()
+  const selectedDmScopeOption = DM_SCOPE_OPTIONS.find(
+    (scope) => scope.value === form.dmScope,
+  )
+
+  return (
+    <ConfigSectionCard title={t("pages.config.sections.runtime")}>
+      <Field
+        label={t("pages.config.session_scope")}
+        hint={t("pages.config.session_scope_hint")}
+        layout="setting-row"
+      >
+        <Select
+          value={form.dmScope}
+          onValueChange={(value) => onFieldChange("dmScope", value)}
+        >
+          <SelectTrigger className="w-full">
+            <SelectValue>
+              {selectedDmScopeOption
+                ? t(
+                    selectedDmScopeOption.labelKey,
+                    selectedDmScopeOption.labelDefault,
+                  )
+                : form.dmScope}
+            </SelectValue>
+          </SelectTrigger>
+          <SelectContent>
+            {DM_SCOPE_OPTIONS.map((scope) => (
+              <SelectItem key={scope.value} value={scope.value}>
+                <div className="flex flex-col gap-0.5">
+                  <span className="font-medium">{t(scope.labelKey)}</span>
+                  <span className="text-muted-foreground text-xs">
+                    {t(scope.descKey)}
+                  </span>
+                </div>
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </Field>
+
+      <SwitchCardField
+        label={t("pages.config.heartbeat_enabled")}
+        hint={t("pages.config.heartbeat_enabled_hint")}
+        layout="setting-row"
+        checked={form.heartbeatEnabled}
+        onCheckedChange={(checked) =>
+          onFieldChange("heartbeatEnabled", checked)
+        }
+      />
+
+      {form.heartbeatEnabled && (
+        <Field
+          label={t("pages.config.heartbeat_interval")}
+          hint={t("pages.config.heartbeat_interval_hint")}
+          layout="setting-row"
+        >
+          <Input
+            type="number"
+            min={1}
+            value={form.heartbeatInterval}
+            onChange={(e) => onFieldChange("heartbeatInterval", e.target.value)}
+          />
+        </Field>
+      )}
+    </ConfigSectionCard>
+  )
+}
+
+interface CronSectionProps {
+  form: CoreConfigForm
+  onFieldChange: UpdateCoreField
+}
+
+export function CronSection({ form, onFieldChange }: CronSectionProps) {
+  const { t } = useTranslation()
+
+  return (
+    <ConfigSectionCard title={t("pages.config.sections.cron")}>
+      <SwitchCardField
+        label={t("pages.config.allow_shell_execution")}
+        hint={t("pages.config.allow_shell_execution_hint")}
+        layout="setting-row"
+        checked={form.allowCommand}
+        disabled={!form.execEnabled}
+        onCheckedChange={(checked) => onFieldChange("allowCommand", checked)}
+      />
+
+      <Field
+        label={t("pages.config.cron_exec_timeout")}
+        hint={t("pages.config.cron_exec_timeout_hint")}
+        layout="setting-row"
+      >
+        <Input
+          type="number"
+          min={0}
+          disabled={!form.execEnabled}
+          value={form.cronExecTimeoutMinutes}
+          onChange={(e) =>
+            onFieldChange("cronExecTimeoutMinutes", e.target.value)
+          }
+        />
+      </Field>
+    </ConfigSectionCard>
+  )
+}
+
+interface LauncherSectionProps {
+  launcherForm: LauncherForm
+  onFieldChange: UpdateLauncherField
+  disabled: boolean
+}
+
+export function LauncherSection({
+  launcherForm,
+  onFieldChange,
+  disabled,
+}: LauncherSectionProps) {
+  const { t } = useTranslation()
+
+  return (
+    <ConfigSectionCard title={t("pages.config.sections.launcher")}>
+      <SwitchCardField
+        label={t("pages.config.lan_access")}
+        hint={t("pages.config.lan_access_hint")}
+        layout="setting-row"
+        checked={launcherForm.publicAccess}
+        disabled={disabled}
+        onCheckedChange={(checked) => onFieldChange("publicAccess", checked)}
+      />
+
+      <Field
+        label={t("pages.config.server_port")}
+        hint={t("pages.config.server_port_hint")}
+        layout="setting-row"
+      >
+        <Input
+          type="number"
+          min={1}
+          max={65535}
+          value={launcherForm.port}
+          disabled={disabled}
+          onChange={(e) => onFieldChange("port", e.target.value)}
+        />
+      </Field>
+
+      <Field
+        label={t("pages.config.allowed_cidrs")}
+        hint={t("pages.config.allowed_cidrs_hint")}
+        layout="setting-row"
+        controlClassName="md:max-w-md"
+      >
+        <Textarea
+          value={launcherForm.allowedCIDRsText}
+          disabled={disabled}
+          placeholder={t("pages.config.allowed_cidrs_placeholder")}
+          className="min-h-[88px]"
+          onChange={(e) => onFieldChange("allowedCIDRsText", e.target.value)}
+        />
+      </Field>
+    </ConfigSectionCard>
+  )
+}
+
+interface DevicesSectionProps {
+  form: CoreConfigForm
+  onFieldChange: UpdateCoreField
+  autoStartEnabled: boolean
+  autoStartHint: string
+  autoStartDisabled: boolean
+  onAutoStartChange: (checked: boolean) => void
+}
+
+export function DevicesSection({
+  form,
+  onFieldChange,
+  autoStartEnabled,
+  autoStartHint,
+  autoStartDisabled,
+  onAutoStartChange,
+}: DevicesSectionProps) {
+  const { t } = useTranslation()
+
+  return (
+    <ConfigSectionCard title={t("pages.config.sections.devices")}>
+      <SwitchCardField
+        label={t("pages.config.devices_enabled")}
+        hint={t("pages.config.devices_enabled_hint")}
+        layout="setting-row"
+        checked={form.devicesEnabled}
+        onCheckedChange={(checked) => onFieldChange("devicesEnabled", checked)}
+      />
+
+      <SwitchCardField
+        label={t("pages.config.monitor_usb")}
+        hint={t("pages.config.monitor_usb_hint")}
+        layout="setting-row"
+        checked={form.monitorUSB}
+        onCheckedChange={(checked) => onFieldChange("monitorUSB", checked)}
+      />
+
+      <SwitchCardField
+        label={t("pages.config.autostart_label")}
+        hint={autoStartHint}
+        layout="setting-row"
+        checked={autoStartEnabled}
+        disabled={autoStartDisabled}
+        onCheckedChange={onAutoStartChange}
+      />
+    </ConfigSectionCard>
+  )
+}
diff --git a/web/frontend/src/components/config/form-model.ts b/web/frontend/src/components/config/form-model.ts
new file mode 100644
index 000000000..10c5c71bb
--- /dev/null
+++ b/web/frontend/src/components/config/form-model.ts
@@ -0,0 +1,254 @@
+export type JsonRecord = Record<string, unknown>
+
+export interface CoreConfigForm {
+  workspace: string
+  restrictToWorkspace: boolean
+  toolFeedbackEnabled: boolean
+  toolFeedbackMaxArgsLength: string
+  execEnabled: boolean
+  allowRemote: boolean
+  enableDenyPatterns: boolean
+  customDenyPatternsText: string
+  customAllowPatternsText: string
+  execTimeoutSeconds: string
+  allowCommand: boolean
+  cronExecTimeoutMinutes: string
+  maxTokens: string
+  contextWindow: string
+  maxToolIterations: string
+  summarizeMessageThreshold: string
+  summarizeTokenPercent: string
+  dmScope: string
+  heartbeatEnabled: boolean
+  heartbeatInterval: string
+  devicesEnabled: boolean
+  monitorUSB: boolean
+}
+
+export interface LauncherForm {
+  port: string
+  publicAccess: boolean
+  allowedCIDRsText: string
+}
+
+export const DM_SCOPE_OPTIONS = [
+  {
+    value: "per-channel-peer",
+    labelKey: "pages.config.session_scope_per_channel_peer",
+    labelDefault: "Per Channel + Peer",
+    descKey: "pages.config.session_scope_per_channel_peer_desc",
+    descDefault: "Separate context for each user in each channel.",
+  },
+  {
+    value: "per-channel",
+    labelKey: "pages.config.session_scope_per_channel",
+    labelDefault: "Per Channel",
+    descKey: "pages.config.session_scope_per_channel_desc",
+    descDefault: "One shared context per channel.",
+  },
+  {
+    value: "per-peer",
+    labelKey: "pages.config.session_scope_per_peer",
+    labelDefault: "Per Peer",
+    descKey: "pages.config.session_scope_per_peer_desc",
+    descDefault: "One context per user across channels.",
+  },
+  {
+    value: "global",
+    labelKey: "pages.config.session_scope_global",
+    labelDefault: "Global",
+    descKey: "pages.config.session_scope_global_desc",
+    descDefault: "All messages share one global context.",
+  },
+] as const
+
+export const EMPTY_FORM: CoreConfigForm = {
+  workspace: "",
+  restrictToWorkspace: true,
+  toolFeedbackEnabled: true,
+  toolFeedbackMaxArgsLength: "300",
+  execEnabled: true,
+  allowRemote: true,
+  enableDenyPatterns: true,
+  customDenyPatternsText: "",
+  customAllowPatternsText: "",
+  execTimeoutSeconds: "0",
+  allowCommand: true,
+  cronExecTimeoutMinutes: "5",
+  maxTokens: "32768",
+  contextWindow: "",
+  maxToolIterations: "50",
+  summarizeMessageThreshold: "20",
+  summarizeTokenPercent: "75",
+  dmScope: "per-channel-peer",
+  heartbeatEnabled: true,
+  heartbeatInterval: "30",
+  devicesEnabled: false,
+  monitorUSB: true,
+}
+
+export const EMPTY_LAUNCHER_FORM: LauncherForm = {
+  port: "18800",
+  publicAccess: false,
+  allowedCIDRsText: "",
+}
+
+function asRecord(value: unknown): JsonRecord {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as JsonRecord
+  }
+  return {}
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : ""
+}
+
+function asBool(value: unknown): boolean {
+  return value === true
+}
+
+function asNumberString(value: unknown, fallback: string): string {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value)
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    return value
+  }
+  return fallback
+}
+
+export function buildFormFromConfig(config: unknown): CoreConfigForm {
+  const root = asRecord(config)
+  const agents = asRecord(root.agents)
+  const defaults = asRecord(agents.defaults)
+  const session = asRecord(root.session)
+  const heartbeat = asRecord(root.heartbeat)
+  const devices = asRecord(root.devices)
+  const tools = asRecord(root.tools)
+  const cron = asRecord(tools.cron)
+  const exec = asRecord(tools.exec)
+  const toolFeedback = asRecord(defaults.tool_feedback)
+
+  return {
+    workspace: asString(defaults.workspace) || EMPTY_FORM.workspace,
+    restrictToWorkspace:
+      defaults.restrict_to_workspace === undefined
+        ? EMPTY_FORM.restrictToWorkspace
+        : asBool(defaults.restrict_to_workspace),
+    toolFeedbackEnabled:
+      toolFeedback.enabled === undefined
+        ? EMPTY_FORM.toolFeedbackEnabled
+        : asBool(toolFeedback.enabled),
+    toolFeedbackMaxArgsLength: asNumberString(
+      toolFeedback.max_args_length,
+      EMPTY_FORM.toolFeedbackMaxArgsLength,
+    ),
+    execEnabled:
+      exec.enabled === undefined
+        ? EMPTY_FORM.execEnabled
+        : asBool(exec.enabled),
+    allowRemote:
+      exec.allow_remote === undefined
+        ? EMPTY_FORM.allowRemote
+        : asBool(exec.allow_remote),
+    enableDenyPatterns:
+      exec.enable_deny_patterns === undefined
+        ? EMPTY_FORM.enableDenyPatterns
+        : asBool(exec.enable_deny_patterns),
+    customDenyPatternsText: Array.isArray(exec.custom_deny_patterns)
+      ? exec.custom_deny_patterns
+          .filter((value): value is string => typeof value === "string")
+          .join("\n")
+      : EMPTY_FORM.customDenyPatternsText,
+    customAllowPatternsText: Array.isArray(exec.custom_allow_patterns)
+      ? exec.custom_allow_patterns
+          .filter((value): value is string => typeof value === "string")
+          .join("\n")
+      : EMPTY_FORM.customAllowPatternsText,
+    execTimeoutSeconds: asNumberString(
+      exec.timeout_seconds,
+      EMPTY_FORM.execTimeoutSeconds,
+    ),
+    allowCommand:
+      cron.allow_command === undefined
+        ? EMPTY_FORM.allowCommand
+        : asBool(cron.allow_command),
+    cronExecTimeoutMinutes: asNumberString(
+      cron.exec_timeout_minutes,
+      EMPTY_FORM.cronExecTimeoutMinutes,
+    ),
+    maxTokens: asNumberString(defaults.max_tokens, EMPTY_FORM.maxTokens),
+    contextWindow: asNumberString(
+      defaults.context_window,
+      EMPTY_FORM.contextWindow,
+    ),
+    maxToolIterations: asNumberString(
+      defaults.max_tool_iterations,
+      EMPTY_FORM.maxToolIterations,
+    ),
+    summarizeMessageThreshold: asNumberString(
+      defaults.summarize_message_threshold,
+      EMPTY_FORM.summarizeMessageThreshold,
+    ),
+    summarizeTokenPercent: asNumberString(
+      defaults.summarize_token_percent,
+      EMPTY_FORM.summarizeTokenPercent,
+    ),
+    dmScope: asString(session.dm_scope) || EMPTY_FORM.dmScope,
+    heartbeatEnabled:
+      heartbeat.enabled === undefined
+        ? EMPTY_FORM.heartbeatEnabled
+        : asBool(heartbeat.enabled),
+    heartbeatInterval: asNumberString(
+      heartbeat.interval,
+      EMPTY_FORM.heartbeatInterval,
+    ),
+    devicesEnabled:
+      devices.enabled === undefined
+        ? EMPTY_FORM.devicesEnabled
+        : asBool(devices.enabled),
+    monitorUSB:
+      devices.monitor_usb === undefined
+        ? EMPTY_FORM.monitorUSB
+        : asBool(devices.monitor_usb),
+  }
+}
+
+export function parseIntField(
+  rawValue: string,
+  label: string,
+  options: { min?: number; max?: number } = {},
+): number {
+  const value = Number(rawValue)
+  if (!Number.isInteger(value)) {
+    throw new Error(`${label} must be an integer.`)
+  }
+  if (options.min !== undefined && value < options.min) {
+    throw new Error(`${label} must be >= ${options.min}.`)
+  }
+  if (options.max !== undefined && value > options.max) {
+    throw new Error(`${label} must be <= ${options.max}.`)
+  }
+  return value
+}
+
+export function parseCIDRText(raw: string): string[] {
+  if (!raw.trim()) {
+    return []
+  }
+  return raw
+    .split(/[\n,]/)
+    .map((v) => v.trim())
+    .filter((v) => v.length > 0)
+}
+
+export function parseMultilineList(raw: string): string[] {
+  if (!raw.trim()) {
+    return []
+  }
+  return raw
+    .split("\n")
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0)
+}
diff --git a/web/frontend/src/components/config/raw-config-page.tsx b/web/frontend/src/components/config/raw-config-page.tsx
new file mode 100644
index 000000000..e40cc7301
--- /dev/null
+++ b/web/frontend/src/components/config/raw-config-page.tsx
@@ -0,0 +1,207 @@
+import { IconAdjustments } from "@tabler/icons-react"
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
+import { Link } from "@tanstack/react-router"
+import { useState } from "react"
+import { useTranslation } from "react-i18next"
+import { toast } from "sonner"
+
+import { PageHeader } from "@/components/page-header"
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from "@/components/ui/alert-dialog"
+import { Button } from "@/components/ui/button"
+import { Textarea } from "@/components/ui/textarea"
+
+export function RawConfigPage() {
+  const { t } = useTranslation()
+  const queryClient = useQueryClient()
+
+  const { data: config, isLoading } = useQuery({
+    queryKey: ["config"],
+    queryFn: async () => {
+      const res = await fetch("/api/config")
+      if (!res.ok) {
+        throw new Error("Failed to fetch config")
+      }
+      return res.json()
+    },
+  })
+
+  const mutation = useMutation({
+    mutationFn: async (newConfig: string) => {
+      const res = await fetch("/api/config", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: newConfig,
+      })
+      if (!res.ok) {
+        throw new Error("Failed to save config")
+      }
+    },
+    onSuccess: (_, submittedConfig) => {
+      toast.success(t("pages.config.save_success"))
+      try {
+        const savedConfig = JSON.parse(submittedConfig)
+        setLastSavedConfig(savedConfig)
+        setIsDirty(false)
+        queryClient.invalidateQueries({ queryKey: ["config"] })
+      } catch {
+        queryClient.invalidateQueries({ queryKey: ["config"] })
+      }
+    },
+    onError: () => {
+      toast.error(t("pages.config.save_error"))
+    },
+  })
+
+  const [editorValue, setEditorValue] = useState("")
+  const [isDirty, setIsDirty] = useState(false)
+  const [lastSavedConfig, setLastSavedConfig] = useState<Record<
+    string,
+    unknown
+  > | null>(null)
+
+  const effectiveEditorValue =
+    editorValue || (config ? JSON.stringify(config, null, 2) : "")
+
+  const handleSave = () => {
+    try {
+      JSON.parse(effectiveEditorValue)
+      mutation.mutate(effectiveEditorValue)
+    } catch (error) {
+      toast.error(
+        t(
+          "pages.config.invalid_json",
+          error instanceof Error ? error.message : "Invalid JSON format.",
+        ),
+      )
+    }
+  }
+
+  const handleFormat = () => {
+    try {
+      const formatted = JSON.stringify(
+        JSON.parse(effectiveEditorValue),
+        null,
+        2,
+      )
+      setEditorValue(formatted)
+      toast.success(t("pages.config.format_success"))
+    } catch (error) {
+      toast.error(
+        t(
+          "pages.config.format_error",
+          error instanceof Error ? error.message : "Invalid JSON format.",
+        ),
+      )
+    }
+  }
+
+  const [showResetDialog, setShowResetDialog] = useState(false)
+
+  const confirmReset = () => {
+    if (lastSavedConfig) {
+      setEditorValue(JSON.stringify(lastSavedConfig, null, 2))
+    } else if (config) {
+      setEditorValue(JSON.stringify(config, null, 2))
+    }
+    setIsDirty(false)
+    toast.info(t("pages.config.reset_success"))
+    setShowResetDialog(false)
+  }
+
+  return (
+    <div className="flex h-full flex-col">
+      <PageHeader title={t("pages.config.raw_json_title")}>
+        <Button variant="outline" asChild>
+          <Link to="/config">
+            <IconAdjustments className="size-4" />
+            {t("pages.config.back_to_visual")}
+          </Link>
+        </Button>
+      </PageHeader>
+
+      <div className="flex min-h-0 flex-1 flex-col p-1 lg:p-3 lg:p-6">
+        <div className="mx-auto flex h-full min-h-0 w-full max-w-[1000px] flex-col">
+          {isLoading ? (
+            <div className="flex flex-1 items-center justify-center">
+              <p>{t("labels.loading")}</p>
+            </div>
+          ) : (
+            <div className="flex min-h-0 flex-1 flex-col gap-3">
+              {isDirty && (
+                <div className="shrink-0 rounded-lg border border-yellow-200 bg-yellow-50 p-2 text-sm text-yellow-700">
+                  {t("pages.config.unsaved_changes")}
+                </div>
+              )}
+              <div className="relative min-h-0 flex-1 overflow-hidden rounded-lg border shadow-sm">
+                <Textarea
+                  value={effectiveEditorValue}
+                  onChange={(e) => {
+                    setEditorValue(e.target.value)
+                    setIsDirty(true)
+                  }}
+                  wrap="off"
+                  className="h-full min-h-0 resize-none overflow-auto border-0 bg-transparent px-4 py-3 font-mono text-sm [overflow-wrap:normal] whitespace-pre shadow-none focus-visible:ring-0"
+                  placeholder={t("pages.config.json_placeholder")}
+                />
+              </div>
+              <div className="flex shrink-0 justify-end gap-2">
+                <Button
+                  variant="outline"
+                  onClick={handleFormat}
+                  disabled={mutation.isPending}
+                >
+                  {t("pages.config.format")}
+                </Button>
+                <AlertDialog
+                  open={showResetDialog}
+                  onOpenChange={setShowResetDialog}
+                >
+                  <AlertDialogTrigger asChild>
+                    <Button
+                      variant="outline"
+                      disabled={!isDirty}
+                      onClick={() => setShowResetDialog(true)}
+                    >
+                      {t("common.reset")}
+                    </Button>
+                  </AlertDialogTrigger>
+                  <AlertDialogContent>
+                    <AlertDialogHeader>
+                      <AlertDialogTitle>
+                        {t("pages.config.reset_confirm_title")}
+                      </AlertDialogTitle>
+                      <AlertDialogDescription>
+                        {t("pages.config.reset_confirm_desc")}
+                      </AlertDialogDescription>
+                    </AlertDialogHeader>
+                    <AlertDialogFooter>
+                      <AlertDialogCancel>
+                        {t("common.cancel")}
+                      </AlertDialogCancel>
+                      <AlertDialogAction onClick={confirmReset}>
+                        {t("common.confirm")}
+                      </AlertDialogAction>
+                    </AlertDialogFooter>
+                  </AlertDialogContent>
+                </AlertDialog>
+                <Button onClick={handleSave} disabled={mutation.isPending}>
+                  {mutation.isPending ? t("common.saving") : t("common.save")}
+                </Button>
+              </div>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/credentials/anthropic-credential-card.tsx b/web/frontend/src/components/credentials/anthropic-credential-card.tsx
new file mode 100644
index 000000000..c7e968646
--- /dev/null
+++ b/web/frontend/src/components/credentials/anthropic-credential-card.tsx
@@ -0,0 +1,108 @@
+import {
+  IconKey,
+  IconLoader2,
+  IconPlayerStopFilled,
+  IconSparkles,
+} from "@tabler/icons-react"
+import { useTranslation } from "react-i18next"
+
+import type { OAuthProviderStatus } from "@/api/oauth"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+
+import { CredentialCard } from "./credential-card"
+
+interface AnthropicCredentialCardProps {
+  status?: OAuthProviderStatus
+  activeAction: string
+  token: string
+  onTokenChange: (value: string) => void
+  onStopLoading: () => void
+  onSaveToken: () => void
+  onAskLogout: () => void
+}
+
+export function AnthropicCredentialCard({
+  status,
+  activeAction,
+  token,
+  onTokenChange,
+  onStopLoading,
+  onSaveToken,
+  onAskLogout,
+}: AnthropicCredentialCardProps) {
+  const { t } = useTranslation()
+  const actionBusy = activeAction !== ""
+  const tokenLoading = activeAction === "anthropic:token"
+  const stopLabel = t("credentials.actions.stopLoading")
+
+  return (
+    <CredentialCard
+      title={
+        <span className="inline-flex items-center gap-2">
+          <span className="border-muted inline-flex size-6 items-center justify-center rounded-full border">
+            <IconSparkles className="size-3.5" />
+          </span>
+          <span>Anthropic</span>
+        </span>
+      }
+      description={t("credentials.providers.anthropic.description")}
+      status={status?.status ?? "not_logged_in"}
+      authMethod={status?.auth_method}
+      actions={
+        <div className="border-muted flex h-[120px] flex-col justify-center rounded-lg border p-3">
+          <div className="flex h-full flex-col gap-3">
+            <div className="flex h-full items-center gap-2">
+              <Input
+                value={token}
+                onChange={(e) => onTokenChange(e.target.value)}
+                type="password"
+                placeholder={t("credentials.fields.anthropicToken")}
+              />
+              <Button
+                size="sm"
+                className="w-fit"
+                disabled={actionBusy || !token.trim()}
+                onClick={onSaveToken}
+              >
+                {tokenLoading && (
+                  <IconLoader2 className="size-4 animate-spin" />
+                )}
+                <IconKey className="size-4" />
+                {t("credentials.actions.saveToken")}
+              </Button>
+              {tokenLoading && (
+                <Button
+                  size="icon-sm"
+                  variant="ghost"
+                  onClick={onStopLoading}
+                  aria-label={stopLabel}
+                  title={stopLabel}
+                  className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+                >
+                  <IconPlayerStopFilled className="size-4" />
+                </Button>
+              )}
+            </div>
+          </div>
+        </div>
+      }
+      footer={
+        status?.logged_in ? (
+          <Button
+            variant="ghost"
+            size="sm"
+            disabled={actionBusy}
+            onClick={onAskLogout}
+            className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+          >
+            {activeAction === "anthropic:logout" && (
+              <IconLoader2 className="size-4 animate-spin" />
+            )}
+            {t("credentials.actions.logout")}
+          </Button>
+        ) : null
+      }
+    />
+  )
+}
diff --git a/web/frontend/src/components/credentials/antigravity-credential-card.tsx b/web/frontend/src/components/credentials/antigravity-credential-card.tsx
new file mode 100644
index 000000000..62a19145b
--- /dev/null
+++ b/web/frontend/src/components/credentials/antigravity-credential-card.tsx
@@ -0,0 +1,106 @@
+import {
+  IconBrandGoogle,
+  IconLoader2,
+  IconLockOpen,
+  IconPlayerStopFilled,
+} from "@tabler/icons-react"
+import { useTranslation } from "react-i18next"
+
+import type { OAuthProviderStatus } from "@/api/oauth"
+import { Button } from "@/components/ui/button"
+
+import { CredentialCard } from "./credential-card"
+
+interface AntigravityCredentialCardProps {
+  status?: OAuthProviderStatus
+  activeAction: string
+  onStopLoading: () => void
+  onStartBrowserOAuth: () => void
+  onAskLogout: () => void
+}
+
+export function AntigravityCredentialCard({
+  status,
+  activeAction,
+  onStopLoading,
+  onStartBrowserOAuth,
+  onAskLogout,
+}: AntigravityCredentialCardProps) {
+  const { t } = useTranslation()
+  const actionBusy = activeAction !== ""
+  const browserLoading = activeAction === "google-antigravity:browser"
+
+  return (
+    <CredentialCard
+      title={
+        <span className="inline-flex items-center gap-2">
+          <span className="border-muted inline-flex size-6 items-center justify-center rounded-full border">
+            <IconBrandGoogle className="size-3.5" />
+          </span>
+          <span>Google Antigravity</span>
+        </span>
+      }
+      description={t("credentials.providers.antigravity.description")}
+      status={status?.status ?? "not_logged_in"}
+      authMethod={status?.auth_method}
+      details={
+        <div className="space-y-1">
+          {status?.email && (
+            <p>
+              {t("credentials.labels.email")}: {status.email}
+            </p>
+          )}
+          {status?.project_id && (
+            <p>
+              {t("credentials.labels.project")}: {status.project_id}
+            </p>
+          )}
+        </div>
+      }
+      actions={
+        <div className="border-muted flex h-[120px] flex-col justify-center rounded-lg border p-3">
+          <div className="flex flex-wrap items-center gap-2">
+            <Button
+              size="sm"
+              variant="outline"
+              disabled={actionBusy}
+              onClick={onStartBrowserOAuth}
+            >
+              {browserLoading && (
+                <IconLoader2 className="size-4 animate-spin" />
+              )}
+              <IconLockOpen className="size-4" />
+              {t("credentials.actions.browser")}
+            </Button>
+            {browserLoading && (
+              <Button
+                size="icon-xs"
+                variant="secondary"
+                onClick={onStopLoading}
+                className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+              >
+                <IconPlayerStopFilled className="size-3" />
+              </Button>
+            )}
+          </div>
+        </div>
+      }
+      footer={
+        status?.logged_in ? (
+          <Button
+            variant="ghost"
+            size="sm"
+            disabled={actionBusy}
+            onClick={onAskLogout}
+            className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+          >
+            {activeAction === "google-antigravity:logout" && (
+              <IconLoader2 className="size-4 animate-spin" />
+            )}
+            {t("credentials.actions.logout")}
+          </Button>
+        ) : null
+      }
+    />
+  )
+}
diff --git a/web/frontend/src/components/credentials/credential-card.tsx b/web/frontend/src/components/credentials/credential-card.tsx
new file mode 100644
index 000000000..60e849972
--- /dev/null
+++ b/web/frontend/src/components/credentials/credential-card.tsx
@@ -0,0 +1,44 @@
+import type { ReactNode } from "react"
+
+import type { OAuthProviderStatus } from "@/api/oauth"
+
+import { ProviderStatusLine } from "./provider-status-line"
+
+interface CredentialCardProps {
+  title: ReactNode
+  description: string
+  status: OAuthProviderStatus["status"]
+  authMethod?: string
+  details?: ReactNode
+  actions: ReactNode
+  footer?: ReactNode
+}
+
+export function CredentialCard({
+  title,
+  description,
+  status,
+  authMethod,
+  details,
+  actions,
+  footer,
+}: CredentialCardProps) {
+  return (
+    <section className="bg-card flex h-full flex-col rounded-xl border p-4">
+      <div className="min-h-16">
+        <h3 className="text-base font-semibold">{title}</h3>
+        <p className="text-muted-foreground mt-1 text-xs">{description}</p>
+      </div>
+
+      <ProviderStatusLine status={status} authMethod={authMethod} />
+      <div className="text-muted-foreground mt-3 min-h-11 text-xs leading-5">
+        {details}
+      </div>
+
+      <div className="mt-auto flex flex-col gap-4 pt-4">
+        <div className="min-h-[112px]">{actions}</div>
+        <div className="min-h-8">{footer}</div>
+      </div>
+    </section>
+  )
+}
diff --git a/web/frontend/src/components/credentials/credentials-page.tsx b/web/frontend/src/components/credentials/credentials-page.tsx
new file mode 100644
index 000000000..04aceb002
--- /dev/null
+++ b/web/frontend/src/components/credentials/credentials-page.tsx
@@ -0,0 +1,127 @@
+import { IconLoader2 } from "@tabler/icons-react"
+import { useTranslation } from "react-i18next"
+
+import { PageHeader } from "@/components/page-header"
+import { useCredentialsPage } from "@/hooks/use-credentials-page"
+
+import { AnthropicCredentialCard } from "./anthropic-credential-card"
+import { AntigravityCredentialCard } from "./antigravity-credential-card"
+import { DeviceCodeSheet } from "./device-code-sheet"
+import { LogoutConfirmDialog } from "./logout-confirm-dialog"
+import { OpenAICredentialCard } from "./openai-credential-card"
+
+export function CredentialsPage() {
+  const { t } = useTranslation()
+  const {
+    loading,
+    error,
+    activeAction,
+    activeFlow,
+    flowHint,
+    openAIToken,
+    anthropicToken,
+    openaiStatus,
+    anthropicStatus,
+    antigravityStatus,
+    logoutDialogOpen,
+    logoutConfirmProvider,
+    logoutProviderLabel,
+    deviceSheetOpen,
+    deviceFlow,
+    setOpenAIToken,
+    setAnthropicToken,
+    startBrowserOAuth,
+    startOpenAIDeviceCode,
+    stopLoading,
+    saveToken,
+    askLogout,
+    handleConfirmLogout,
+    handleLogoutDialogOpenChange,
+    handleDeviceSheetOpenChange,
+  } = useCredentialsPage()
+
+  return (
+    <div className="flex h-full flex-col">
+      <PageHeader title={t("navigation.credentials")} />
+
+      <div className="min-h-0 flex-1 overflow-y-auto px-4 sm:px-6">
+        <div className="pt-2">
+          <p className="text-muted-foreground text-sm">
+            {t("credentials.description")}
+          </p>
+        </div>
+
+        {error && (
+          <div className="text-destructive bg-destructive/10 mt-4 rounded-lg px-4 py-3 text-sm">
+            {error}
+          </div>
+        )}
+
+        {activeFlow && (
+          <div className="bg-muted mt-4 rounded-lg border px-4 py-3 text-sm">
+            <p className="font-medium">{t("credentials.flow.current")}</p>
+            <p className="text-muted-foreground mt-1">{flowHint}</p>
+          </div>
+        )}
+
+        {loading ? (
+          <div className="text-muted-foreground flex items-center gap-2 py-10 text-sm">
+            <IconLoader2 className="size-4 animate-spin" />
+            {t("credentials.loading")}
+          </div>
+        ) : (
+          <div className="grid grid-cols-1 gap-4 py-5 lg:auto-rows-fr lg:grid-cols-3">
+            <OpenAICredentialCard
+              status={openaiStatus}
+              activeAction={activeAction}
+              token={openAIToken}
+              onTokenChange={setOpenAIToken}
+              onStartBrowserOAuth={() => void startBrowserOAuth("openai")}
+              onStartDeviceCode={() => void startOpenAIDeviceCode()}
+              onStopLoading={stopLoading}
+              onSaveToken={() => void saveToken("openai", openAIToken.trim())}
+              onAskLogout={() => askLogout("openai")}
+            />
+
+            <AnthropicCredentialCard
+              status={anthropicStatus}
+              activeAction={activeAction}
+              token={anthropicToken}
+              onTokenChange={setAnthropicToken}
+              onStopLoading={stopLoading}
+              onSaveToken={() =>
+                void saveToken("anthropic", anthropicToken.trim())
+              }
+              onAskLogout={() => askLogout("anthropic")}
+            />
+
+            <AntigravityCredentialCard
+              status={antigravityStatus}
+              activeAction={activeAction}
+              onStopLoading={stopLoading}
+              onStartBrowserOAuth={() =>
+                void startBrowserOAuth("google-antigravity")
+              }
+              onAskLogout={() => askLogout("google-antigravity")}
+            />
+          </div>
+        )}
+      </div>
+
+      <LogoutConfirmDialog
+        open={logoutDialogOpen}
+        providerLabel={logoutProviderLabel}
+        isSubmitting={activeAction === `${logoutConfirmProvider}:logout`}
+        onOpenChange={handleLogoutDialogOpenChange}
+        onConfirm={handleConfirmLogout}
+      />
+
+      <DeviceCodeSheet
+        open={deviceSheetOpen}
+        flow={deviceFlow}
+        flowHint={flowHint}
+        onOpenChange={handleDeviceSheetOpenChange}
+      />
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/credentials/device-code-sheet.tsx b/web/frontend/src/components/credentials/device-code-sheet.tsx
new file mode 100644
index 000000000..c6d2a754f
--- /dev/null
+++ b/web/frontend/src/components/credentials/device-code-sheet.tsx
@@ -0,0 +1,92 @@
+import { IconRefresh } from "@tabler/icons-react"
+import { useTranslation } from "react-i18next"
+
+import type { OAuthFlowState } from "@/api/oauth"
+import { Button } from "@/components/ui/button"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet"
+
+interface DeviceCodeSheetProps {
+  open: boolean
+  flow: OAuthFlowState | null
+  flowHint: string
+  onOpenChange: (open: boolean) => void
+}
+
+export function DeviceCodeSheet({
+  open,
+  flow,
+  flowHint,
+  onOpenChange,
+}: DeviceCodeSheetProps) {
+  const { t } = useTranslation()
+
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent
+        side="right"
+        className="data-[side=right]:!w-full data-[side=right]:sm:!w-[480px] data-[side=right]:sm:!max-w-[480px]"
+      >
+        <SheetHeader className="border-b-muted border-b px-6 py-5">
+          <SheetTitle>{t("credentials.device.title")}</SheetTitle>
+          <SheetDescription>
+            {t("credentials.device.description")}
+          </SheetDescription>
+        </SheetHeader>
+
+        <div className="space-y-4 px-6 py-5">
+          <div>
+            <p className="text-muted-foreground text-xs uppercase">
+              {t("credentials.device.code")}
+            </p>
+            <p className="mt-1 rounded-md border px-3 py-2 font-mono text-lg font-semibold tracking-wide">
+              {flow?.user_code || "-"}
+            </p>
+          </div>
+
+          <div>
+            <p className="text-muted-foreground text-xs uppercase">
+              {t("credentials.device.url")}
+            </p>
+            <a
+              href={flow?.verify_url || "#"}
+              target="_blank"
+              rel="noreferrer"
+              className="text-primary mt-1 block text-sm break-all underline"
+            >
+              {flow?.verify_url || "-"}
+            </a>
+          </div>
+
+          <div className="text-muted-foreground flex items-center gap-2 text-sm">
+            <IconRefresh className="size-4" />
+            {t("credentials.device.polling")}
+          </div>
+
+          {flow && (
+            <div className="bg-muted rounded-md border px-3 py-2 text-sm">
+              {flowHint}
+            </div>
+          )}
+        </div>
+
+        <SheetFooter className="border-t-muted border-t px-6 py-4">
+          <Button variant="ghost" onClick={() => onOpenChange(false)}>
+            {t("common.cancel")}
+          </Button>
+          <Button asChild disabled={!flow?.verify_url}>
+            <a href={flow?.verify_url || "#"} target="_blank" rel="noreferrer">
+              {t("credentials.device.open")}
+            </a>
+          </Button>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  )
+}
diff --git a/web/frontend/src/components/credentials/logout-confirm-dialog.tsx b/web/frontend/src/components/credentials/logout-confirm-dialog.tsx
new file mode 100644
index 000000000..1a9eebffd
--- /dev/null
+++ b/web/frontend/src/components/credentials/logout-confirm-dialog.tsx
@@ -0,0 +1,57 @@
+import { IconLoader2 } from "@tabler/icons-react"
+import { useTranslation } from "react-i18next"
+
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog"
+
+interface LogoutConfirmDialogProps {
+  open: boolean
+  providerLabel: string
+  isSubmitting: boolean
+  onOpenChange: (open: boolean) => void
+  onConfirm: () => void | Promise<void>
+}
+
+export function LogoutConfirmDialog({
+  open,
+  providerLabel,
+  isSubmitting,
+  onOpenChange,
+  onConfirm,
+}: LogoutConfirmDialogProps) {
+  const { t } = useTranslation()
+
+  return (
+    <AlertDialog open={open} onOpenChange={onOpenChange}>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>
+            {t("credentials.logoutDialog.title")}
+          </AlertDialogTitle>
+          <AlertDialogDescription>
+            {t(
+              "credentials.logoutDialog.description",
+              "This will remove your saved credential for {{provider}}.",
+              { provider: providerLabel },
+            )}
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>{t("common.cancel")}</AlertDialogCancel>
+          <AlertDialogAction onClick={onConfirm} variant="destructive">
+            {isSubmitting && <IconLoader2 className="size-4 animate-spin" />}
+            {t("credentials.actions.logout")}
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
diff --git a/web/frontend/src/components/credentials/openai-credential-card.tsx b/web/frontend/src/components/credentials/openai-credential-card.tsx
new file mode 100644
index 000000000..925508191
--- /dev/null
+++ b/web/frontend/src/components/credentials/openai-credential-card.tsx
@@ -0,0 +1,162 @@
+import {
+  IconBrandOpenai,
+  IconClockHour4,
+  IconKey,
+  IconLoader2,
+  IconPlayerStopFilled,
+} from "@tabler/icons-react"
+import { useTranslation } from "react-i18next"
+
+import type { OAuthProviderStatus } from "@/api/oauth"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+
+import { CredentialCard } from "./credential-card"
+
+interface OpenAICredentialCardProps {
+  status?: OAuthProviderStatus
+  activeAction: string
+  token: string
+  onTokenChange: (value: string) => void
+  onStartBrowserOAuth: () => void
+  onStartDeviceCode: () => void
+  onStopLoading: () => void
+  onSaveToken: () => void
+  onAskLogout: () => void
+}
+
+export function OpenAICredentialCard({
+  status,
+  activeAction,
+  token,
+  onTokenChange,
+  onStartBrowserOAuth,
+  onStartDeviceCode,
+  onStopLoading,
+  onSaveToken,
+  onAskLogout,
+}: OpenAICredentialCardProps) {
+  const { t } = useTranslation()
+  const actionBusy = activeAction !== ""
+  const browserLoading = activeAction === "openai:browser"
+  const deviceLoading = activeAction === "openai:device"
+  const oauthLoading = browserLoading || deviceLoading
+  const tokenLoading = activeAction === "openai:token"
+
+  return (
+    <CredentialCard
+      title={
+        <span className="inline-flex items-center gap-2">
+          <span className="border-muted inline-flex size-6 items-center justify-center rounded-full border">
+            <IconBrandOpenai className="size-3.5" />
+          </span>
+          <span>OpenAI</span>
+        </span>
+      }
+      description={t("credentials.providers.openai.description")}
+      status={status?.status ?? "not_logged_in"}
+      authMethod={status?.auth_method}
+      details={
+        status?.account_id ? (
+          <p>
+            {t("credentials.labels.account")}: {status.account_id}
+          </p>
+        ) : null
+      }
+      actions={
+        <div className="border-muted flex h-[120px] flex-col rounded-lg border p-3">
+          <div className="flex h-full flex-col gap-3">
+            <div className="min-h-8">
+              <div className="flex flex-nowrap items-center gap-2 overflow-x-auto">
+                <Button
+                  size="sm"
+                  variant="outline"
+                  disabled={actionBusy}
+                  onClick={onStartBrowserOAuth}
+                >
+                  {browserLoading && (
+                    <IconLoader2 className="size-4 animate-spin" />
+                  )}
+                  <IconBrandOpenai className="size-4" />
+                  {t("credentials.actions.browser")}
+                </Button>
+
+                {oauthLoading && !deviceLoading && (
+                  <Button
+                    size="icon-xs"
+                    variant="secondary"
+                    onClick={onStopLoading}
+                    className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+                  >
+                    <IconPlayerStopFilled className="size-4" />
+                  </Button>
+                )}
+
+                <Button
+                  size="sm"
+                  variant="outline"
+                  disabled={actionBusy}
+                  onClick={onStartDeviceCode}
+                >
+                  {deviceLoading && (
+                    <IconLoader2 className="size-4 animate-spin" />
+                  )}
+                  <IconClockHour4 className="size-4" />
+                  {t("credentials.actions.deviceCode")}
+                </Button>
+              </div>
+            </div>
+
+            <div className="min-h-9 flex-1">
+              <div className="flex h-full items-center gap-2">
+                <Input
+                  value={token}
+                  onChange={(e) => onTokenChange(e.target.value)}
+                  type="password"
+                  placeholder={t("credentials.fields.openaiToken")}
+                />
+                <Button
+                  size="sm"
+                  disabled={actionBusy || !token.trim()}
+                  onClick={onSaveToken}
+                >
+                  {tokenLoading && (
+                    <IconLoader2 className="size-4 animate-spin" />
+                  )}
+                  <IconKey className="size-4" />
+                  {t("credentials.actions.saveToken")}
+                </Button>
+                {tokenLoading && (
+                  <Button
+                    size="icon-sm"
+                    variant="ghost"
+                    onClick={onStopLoading}
+                    className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+                  >
+                    <IconPlayerStopFilled className="size-4" />
+                  </Button>
+                )}
+              </div>
+            </div>
+          </div>
+        </div>
+      }
+      footer={
+        status?.logged_in ? (
+          <Button
+            variant="ghost"
+            size="sm"
+            disabled={actionBusy}
+            onClick={onAskLogout}
+            className="text-destructive hover:bg-destructive/10 hover:text-destructive"
+          >
+            {activeAction === "openai:logout" && (
+              <IconLoader2 className="size-4 animate-spin" />
+            )}
+            {t("credentials.actions.logout")}
+          </Button>
+        ) : null
+      }
+    />
+  )
+}
diff --git a/web/frontend/src/components/credentials/provider-status-line.tsx b/web/frontend/src/components/credentials/provider-status-line.tsx
new file mode 100644
index 000000000..d891d18df
--- /dev/null
+++ b/web/frontend/src/components/credentials/provider-status-line.tsx
@@ -0,0 +1,43 @@
+import { useTranslation } from "react-i18next"
+
+import type { OAuthProviderStatus } from "@/api/oauth"
+
+interface ProviderStatusLineProps {
+  status: OAuthProviderStatus["status"]
+  authMethod?: string
+}
+
+export function ProviderStatusLine({
+  status,
+  authMethod,
+}: ProviderStatusLineProps) {
+  const { t } = useTranslation()
+
+  const style =
+    status === "connected"
+      ? "bg-green-500/10 text-green-700 dark:text-green-300"
+      : status === "needs_refresh"
+        ? "bg-amber-500/10 text-amber-700 dark:text-amber-300"
+        : status === "expired"
+          ? "bg-red-500/10 text-red-700 dark:text-red-300"
+          : "bg-muted text-muted-foreground"
+
+  return (
+    <div className="flex items-center justify-between gap-2">
+      <span className={`rounded px-2 py-1 text-xs font-medium ${style}`}>
+        {status === "connected"
+          ? t("credentials.status.connected")
+          : status === "needs_refresh"
+            ? t("credentials.status.needsRefresh")
+            : status === "expired"
+              ? t("credentials.status.expired")
+              : t("credentials.status.notLoggedIn")}
+      </span>
+      {authMethod && (
+        <span className="text-muted-foreground text-xs uppercase">
+          {authMethod}
+        </span>
+      )}
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/logs/ansi-log-line.tsx b/web/frontend/src/components/logs/ansi-log-line.tsx
new file mode 100644
index 000000000..db078efd2
--- /dev/null
+++ b/web/frontend/src/components/logs/ansi-log-line.tsx
@@ -0,0 +1,24 @@
+import { Fragment, useMemo } from "react"
+
+import { parseAnsiSegments, wrapLogLine } from "@/lib/ansi-log"
+
+type AnsiLogLineProps = {
+  line: string
+  wrapColumns: number
+}
+
+export function AnsiLogLine({ line, wrapColumns }: AnsiLogLineProps) {
+  const segments = useMemo(() => {
+    return parseAnsiSegments(wrapLogLine(line, wrapColumns))
+  }, [line, wrapColumns])
+
+  return (
+    <div className="break-normal whitespace-pre-wrap">
+      {segments.map((segment, index) => (
+        <Fragment key={`${index}-${segment.text.length}`}>
+          <span style={segment.style}>{segment.text}</span>
+        </Fragment>
+      ))}
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/logs/logs-page.tsx b/web/frontend/src/components/logs/logs-page.tsx
new file mode 100644
index 000000000..a4c458fa2
--- /dev/null
+++ b/web/frontend/src/components/logs/logs-page.tsx
@@ -0,0 +1,42 @@
+import { IconTrash } from "@tabler/icons-react"
+import { useTranslation } from "react-i18next"
+
+import { LogsPanel } from "@/components/logs/logs-panel"
+import { PageHeader } from "@/components/page-header"
+import { Button } from "@/components/ui/button"
+import { useGatewayLogs } from "@/hooks/use-gateway-logs"
+import { useLogWrapColumns } from "@/hooks/use-log-wrap-columns"
+
+export function LogsPage() {
+  const { t } = useTranslation()
+  const { clearLogs, clearing, logs } = useGatewayLogs()
+  const { contentRef, measureRef, wrapColumns } = useLogWrapColumns()
+
+  return (
+    <div className="flex h-full flex-col">
+      <PageHeader
+        title={t("navigation.logs")}
+        children={
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={clearLogs}
+            disabled={logs.length === 0 || clearing}
+          >
+            <IconTrash className="size-4" />
+            {t("pages.logs.clear")}
+          </Button>
+        }
+      />
+
+      <div className="flex flex-1 flex-col gap-4 overflow-hidden p-4 sm:p-8">
+        <LogsPanel
+          logs={logs}
+          wrapColumns={wrapColumns}
+          contentRef={contentRef}
+          measureRef={measureRef}
+        />
+      </div>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/logs/logs-panel.tsx b/web/frontend/src/components/logs/logs-panel.tsx
new file mode 100644
index 000000000..083fb74d8
--- /dev/null
+++ b/web/frontend/src/components/logs/logs-panel.tsx
@@ -0,0 +1,55 @@
+import { type RefObject, useEffect, useRef } from "react"
+import { useTranslation } from "react-i18next"
+
+import { AnsiLogLine } from "@/components/logs/ansi-log-line"
+import { ScrollArea } from "@/components/ui/scroll-area"
+
+type LogsPanelProps = {
+  logs: string[]
+  wrapColumns: number
+  contentRef: RefObject<HTMLDivElement | null>
+  measureRef: RefObject<HTMLSpanElement | null>
+}
+
+export function LogsPanel({
+  logs,
+  wrapColumns,
+  contentRef,
+  measureRef,
+}: LogsPanelProps) {
+  const { t } = useTranslation()
+  const scrollRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (scrollRef.current) {
+      scrollRef.current.scrollIntoView({ behavior: "smooth" })
+    }
+  }, [logs])
+
+  return (
+    <div className="relative flex-1 overflow-hidden rounded-lg border border-zinc-800 bg-zinc-950 text-zinc-100">
+      <ScrollArea className="h-full">
+        <div
+          ref={contentRef}
+          className="relative p-4 font-mono text-sm leading-relaxed"
+        >
+          <span
+            ref={measureRef}
+            aria-hidden
+            className="pointer-events-none invisible absolute font-mono text-sm"
+          >
+            0
+          </span>
+          {logs.length === 0 ? (
+            <div className="text-zinc-500 italic">{t("pages.logs.empty")}</div>
+          ) : (
+            logs.map((log, index) => (
+              <AnsiLogLine key={index} line={log} wrapColumns={wrapColumns} />
+            ))
+          )}
+          <div ref={scrollRef} />
+        </div>
+      </ScrollArea>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/models/add-model-sheet.tsx b/web/frontend/src/components/models/add-model-sheet.tsx
new file mode 100644
index 000000000..c760bc672
--- /dev/null
+++ b/web/frontend/src/components/models/add-model-sheet.tsx
@@ -0,0 +1,330 @@
+import { IconLoader2 } from "@tabler/icons-react"
+import { useEffect, useState } from "react"
+import { useTranslation } from "react-i18next"
+
+import { addModel, setDefaultModel } from "@/api/models"
+import { maskedSecretPlaceholder } from "@/components/secret-placeholder"
+import {
+  AdvancedSection,
+  Field,
+  KeyInput,
+  SwitchCardField,
+} from "@/components/shared-form"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet"
+
+interface AddForm {
+  modelName: string
+  model: string
+  apiBase: string
+  apiKey: string
+  proxy: string
+  authMethod: string
+  connectMode: string
+  workspace: string
+  rpm: string
+  maxTokensField: string
+  requestTimeout: string
+  thinkingLevel: string
+}
+
+const EMPTY_ADD_FORM: AddForm = {
+  modelName: "",
+  model: "",
+  apiBase: "",
+  apiKey: "",
+  proxy: "",
+  authMethod: "",
+  connectMode: "",
+  workspace: "",
+  rpm: "",
+  maxTokensField: "",
+  requestTimeout: "",
+  thinkingLevel: "",
+}
+
+interface AddModelSheetProps {
+  open: boolean
+  onClose: () => void
+  onSaved: () => void
+  existingModelNames: string[]
+}
+
+export function AddModelSheet({
+  open,
+  onClose,
+  onSaved,
+  existingModelNames,
+}: AddModelSheetProps) {
+  const { t } = useTranslation()
+  const [form, setForm] = useState<AddForm>(EMPTY_ADD_FORM)
+  const [saving, setSaving] = useState(false)
+  const [setAsDefault, setSetAsDefault] = useState(false)
+  const [fieldErrors, setFieldErrors] = useState<
+    Partial<Record<keyof AddForm, string>>
+  >({})
+  const [serverError, setServerError] = useState("")
+  const apiKeyPlaceholder = maskedSecretPlaceholder(
+    form.apiKey,
+    t("models.field.apiKeyPlaceholder"),
+  )
+
+  useEffect(() => {
+    if (open) {
+      setForm(EMPTY_ADD_FORM)
+      setSetAsDefault(false)
+      setFieldErrors({})
+      setServerError("")
+    }
+  }, [open])
+
+  const validate = (): boolean => {
+    const errors: Partial<Record<keyof AddForm, string>> = {}
+    const modelName = form.modelName.trim()
+    if (!modelName) {
+      errors.modelName = t("models.add.errorRequired")
+    } else if (existingModelNames.some((name) => name.trim() === modelName)) {
+      errors.modelName = t("models.add.errorDuplicateModelName")
+    }
+    if (!form.model.trim()) errors.model = t("models.add.errorRequired")
+    setFieldErrors(errors)
+    return Object.keys(errors).length === 0
+  }
+
+  const setField =
+    (key: keyof AddForm) => (e: React.ChangeEvent<HTMLInputElement>) => {
+      setForm((f) => ({ ...f, [key]: e.target.value }))
+      if (fieldErrors[key]) {
+        setFieldErrors((prev) => ({ ...prev, [key]: undefined }))
+      }
+    }
+
+  const handleSave = async () => {
+    if (!validate()) return
+    setSaving(true)
+    setServerError("")
+    try {
+      const modelName = form.modelName.trim()
+      const modelId = form.model.trim()
+      await addModel({
+        model_name: modelName,
+        model: modelId,
+        api_base: form.apiBase.trim() || undefined,
+        api_key: form.apiKey.trim() || undefined,
+        proxy: form.proxy.trim() || undefined,
+        auth_method: form.authMethod.trim() || undefined,
+        connect_mode: form.connectMode.trim() || undefined,
+        workspace: form.workspace.trim() || undefined,
+        rpm: form.rpm ? Number(form.rpm) : undefined,
+        max_tokens_field: form.maxTokensField.trim() || undefined,
+        request_timeout: form.requestTimeout
+          ? Number(form.requestTimeout)
+          : undefined,
+        thinking_level: form.thinkingLevel.trim() || undefined,
+      })
+      if (setAsDefault) {
+        await setDefaultModel(modelName)
+      }
+      onSaved()
+      onClose()
+    } catch (e) {
+      setServerError(e instanceof Error ? e.message : t("models.add.saveError"))
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  return (
+    <Sheet open={open} onOpenChange={(v) => !v && onClose()}>
+      <SheetContent
+        side="right"
+        className="flex flex-col gap-0 p-0 data-[side=right]:!w-full data-[side=right]:sm:!w-[560px] data-[side=right]:sm:!max-w-[560px]"
+      >
+        <SheetHeader className="border-b-muted border-b px-6 py-5">
+          <SheetTitle className="text-base">{t("models.add.title")}</SheetTitle>
+          <SheetDescription className="text-xs">
+            {t("models.add.description")}
+          </SheetDescription>
+        </SheetHeader>
+
+        <div className="min-h-0 flex-1 overflow-y-auto">
+          <div className="space-y-5 px-6 py-5">
+            <Field
+              label={t("models.add.modelName")}
+              hint={t("models.add.modelNameHint")}
+            >
+              <Input
+                value={form.modelName}
+                onChange={setField("modelName")}
+                placeholder={t("models.add.modelNamePlaceholder")}
+                aria-invalid={!!fieldErrors.modelName}
+              />
+              {fieldErrors.modelName && (
+                <p className="text-destructive text-xs">
+                  {fieldErrors.modelName}
+                </p>
+              )}
+            </Field>
+
+            <Field
+              label={t("models.add.modelId")}
+              hint={t("models.add.modelIdHint")}
+            >
+              <Input
+                value={form.model}
+                onChange={setField("model")}
+                placeholder={t("models.add.modelIdPlaceholder")}
+                className="font-mono text-sm"
+                aria-invalid={!!fieldErrors.model}
+              />
+              {fieldErrors.model && (
+                <p className="text-destructive text-xs">{fieldErrors.model}</p>
+              )}
+            </Field>
+
+            <Field label={t("models.field.apiKey")}>
+              <KeyInput
+                value={form.apiKey}
+                onChange={(v) => setForm((f) => ({ ...f, apiKey: v }))}
+                placeholder={apiKeyPlaceholder}
+              />
+            </Field>
+
+            <Field label={t("models.field.apiBase")}>
+              <Input
+                value={form.apiBase}
+                onChange={setField("apiBase")}
+                placeholder="https://api.example.com/v1"
+              />
+            </Field>
+
+            <SwitchCardField
+              label={t("models.defaultOnSave.label")}
+              hint={t("models.defaultOnSave.description")}
+              checked={setAsDefault}
+              onCheckedChange={setSetAsDefault}
+            />
+
+            <AdvancedSection>
+              <Field
+                label={t("models.field.proxy")}
+                hint={t("models.field.proxyHint")}
+              >
+                <Input
+                  value={form.proxy}
+                  onChange={setField("proxy")}
+                  placeholder="http://127.0.0.1:7890"
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.authMethod")}
+                hint={t("models.field.authMethodHint")}
+              >
+                <Input
+                  value={form.authMethod}
+                  onChange={setField("authMethod")}
+                  placeholder="oauth"
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.connectMode")}
+                hint={t("models.field.connectModeHint")}
+              >
+                <Input
+                  value={form.connectMode}
+                  onChange={setField("connectMode")}
+                  placeholder="stdio"
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.workspace")}
+                hint={t("models.field.workspaceHint")}
+              >
+                <Input
+                  value={form.workspace}
+                  onChange={setField("workspace")}
+                  placeholder="/path/to/workspace"
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.requestTimeout")}
+                hint={t("models.field.requestTimeoutHint")}
+              >
+                <Input
+                  value={form.requestTimeout}
+                  onChange={setField("requestTimeout")}
+                  placeholder="60"
+                  type="number"
+                  min={0}
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.rpm")}
+                hint={t("models.field.rpmHint")}
+              >
+                <Input
+                  value={form.rpm}
+                  onChange={setField("rpm")}
+                  placeholder="60"
+                  type="number"
+                  min={0}
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.thinkingLevel")}
+                hint={t("models.field.thinkingLevelHint")}
+              >
+                <Input
+                  value={form.thinkingLevel}
+                  onChange={setField("thinkingLevel")}
+                  placeholder="off"
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.maxTokensField")}
+                hint={t("models.field.maxTokensFieldHint")}
+              >
+                <Input
+                  value={form.maxTokensField}
+                  onChange={setField("maxTokensField")}
+                  placeholder="max_completion_tokens"
+                />
+              </Field>
+            </AdvancedSection>
+
+            {serverError && (
+              <p className="text-destructive bg-destructive/10 rounded-md px-3 py-2 text-sm">
+                {serverError}
+              </p>
+            )}
+          </div>
+        </div>
+
+        <SheetFooter className="border-t-muted border-t px-6 py-4">
+          <Button variant="ghost" onClick={onClose} disabled={saving}>
+            {t("common.cancel")}
+          </Button>
+          <Button onClick={handleSave} disabled={saving}>
+            {saving && <IconLoader2 className="size-4 animate-spin" />}
+            {t("models.add.confirm")}
+          </Button>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  )
+}
diff --git a/web/frontend/src/components/models/delete-model-dialog.tsx b/web/frontend/src/components/models/delete-model-dialog.tsx
new file mode 100644
index 000000000..72b8df002
--- /dev/null
+++ b/web/frontend/src/components/models/delete-model-dialog.tsx
@@ -0,0 +1,74 @@
+import { IconLoader2 } from "@tabler/icons-react"
+import { useState } from "react"
+import { useTranslation } from "react-i18next"
+
+import { type ModelInfo, deleteModel } from "@/api/models"
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog"
+
+interface DeleteModelDialogProps {
+  model: ModelInfo | null
+  onClose: () => void
+  onDeleted: () => void
+}
+
+export function DeleteModelDialog({
+  model,
+  onClose,
+  onDeleted,
+}: DeleteModelDialogProps) {
+  const { t } = useTranslation()
+  const [deleting, setDeleting] = useState(false)
+
+  const handleConfirm = async () => {
+    if (!model) return
+    if (model.is_default) {
+      onClose()
+      return
+    }
+    setDeleting(true)
+    try {
+      await deleteModel(model.index)
+      onDeleted()
+    } catch {
+      // ignore, user can retry from list
+    } finally {
+      setDeleting(false)
+      onClose()
+    }
+  }
+
+  return (
+    <AlertDialog open={model !== null} onOpenChange={(v) => !v && onClose()}>
+      <AlertDialogContent size="sm">
+        <AlertDialogHeader>
+          <AlertDialogTitle>{t("models.delete.title")}</AlertDialogTitle>
+          <AlertDialogDescription>
+            {t("models.delete.description", { name: model?.model_name })}
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel onClick={onClose} disabled={deleting}>
+            {t("common.cancel")}
+          </AlertDialogCancel>
+          <AlertDialogAction
+            variant="destructive"
+            onClick={handleConfirm}
+            disabled={deleting}
+          >
+            {deleting && <IconLoader2 className="size-4 animate-spin" />}
+            {t("models.delete.confirm")}
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  )
+}
diff --git a/web/frontend/src/components/models/edit-model-sheet.tsx b/web/frontend/src/components/models/edit-model-sheet.tsx
new file mode 100644
index 000000000..237991a9f
--- /dev/null
+++ b/web/frontend/src/components/models/edit-model-sheet.tsx
@@ -0,0 +1,298 @@
+import { IconLoader2 } from "@tabler/icons-react"
+import { useEffect, useState } from "react"
+import { useTranslation } from "react-i18next"
+
+import { type ModelInfo, setDefaultModel, updateModel } from "@/api/models"
+import { maskedSecretPlaceholder } from "@/components/secret-placeholder"
+import {
+  AdvancedSection,
+  Field,
+  KeyInput,
+  SwitchCardField,
+} from "@/components/shared-form"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet"
+
+interface EditForm {
+  apiKey: string
+  apiBase: string
+  proxy: string
+  authMethod: string
+  connectMode: string
+  workspace: string
+  rpm: string
+  maxTokensField: string
+  requestTimeout: string
+  thinkingLevel: string
+}
+
+interface EditModelSheetProps {
+  model: ModelInfo | null
+  open: boolean
+  onClose: () => void
+  onSaved: () => void
+}
+
+export function EditModelSheet({
+  model,
+  open,
+  onClose,
+  onSaved,
+}: EditModelSheetProps) {
+  const { t } = useTranslation()
+  const [form, setForm] = useState<EditForm>({
+    apiKey: "",
+    apiBase: "",
+    proxy: "",
+    authMethod: "",
+    connectMode: "",
+    workspace: "",
+    rpm: "",
+    maxTokensField: "",
+    requestTimeout: "",
+    thinkingLevel: "",
+  })
+  const [saving, setSaving] = useState(false)
+  const [setAsDefault, setSetAsDefault] = useState(false)
+  const [error, setError] = useState("")
+
+  useEffect(() => {
+    if (model) {
+      setForm({
+        apiKey: "",
+        apiBase: model.api_base ?? "",
+        proxy: model.proxy ?? "",
+        authMethod: model.auth_method ?? "",
+        connectMode: model.connect_mode ?? "",
+        workspace: model.workspace ?? "",
+        rpm: model.rpm ? String(model.rpm) : "",
+        maxTokensField: model.max_tokens_field ?? "",
+        requestTimeout: model.request_timeout
+          ? String(model.request_timeout)
+          : "",
+        thinkingLevel: model.thinking_level ?? "",
+      })
+      setSetAsDefault(model.is_default)
+      setError("")
+    }
+  }, [model])
+
+  const setField =
+    (key: keyof EditForm) => (e: React.ChangeEvent<HTMLInputElement>) =>
+      setForm((f) => ({ ...f, [key]: e.target.value }))
+
+  const handleSave = async () => {
+    if (!model) return
+    setSaving(true)
+    setError("")
+    try {
+      await updateModel(model.index, {
+        model_name: model.model_name,
+        model: model.model,
+        api_base: form.apiBase || undefined,
+        api_key: form.apiKey || undefined,
+        proxy: form.proxy || undefined,
+        auth_method: form.authMethod || undefined,
+        connect_mode: form.connectMode || undefined,
+        workspace: form.workspace || undefined,
+        rpm: form.rpm ? Number(form.rpm) : undefined,
+        max_tokens_field: form.maxTokensField || undefined,
+        request_timeout: form.requestTimeout
+          ? Number(form.requestTimeout)
+          : undefined,
+        thinking_level: form.thinkingLevel || undefined,
+      })
+      if (setAsDefault && !model.is_default) {
+        await setDefaultModel(model.model_name)
+      }
+      onSaved()
+      onClose()
+    } catch (e) {
+      setError(e instanceof Error ? e.message : t("models.edit.saveError"))
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const isOAuth = model?.auth_method === "oauth"
+  const apiKeyPlaceholder = model?.configured
+    ? maskedSecretPlaceholder(
+        model.api_key,
+        t("models.field.apiKeyPlaceholderSet"),
+      )
+    : t("models.field.apiKeyPlaceholder")
+
+  return (
+    <Sheet open={open} onOpenChange={(v) => !v && onClose()}>
+      <SheetContent
+        side="right"
+        className="flex flex-col gap-0 p-0 data-[side=right]:!w-full data-[side=right]:sm:!w-[560px] data-[side=right]:sm:!max-w-[560px]"
+      >
+        <SheetHeader className="border-b-muted border-b px-6 py-5">
+          <SheetTitle className="text-base">
+            {t("models.edit.title", { name: model?.model_name })}
+          </SheetTitle>
+          <SheetDescription className="font-mono text-xs">
+            {model?.model}
+          </SheetDescription>
+        </SheetHeader>
+
+        <div className="min-h-0 flex-1 overflow-y-auto">
+          <div className="space-y-5 px-6 py-5">
+            {!isOAuth && (
+              <Field
+                label={t("models.field.apiKey")}
+                hint={
+                  model?.configured ? t("models.edit.apiKeyHint") : undefined
+                }
+              >
+                <KeyInput
+                  value={form.apiKey}
+                  onChange={(v) => setForm((f) => ({ ...f, apiKey: v }))}
+                  placeholder={apiKeyPlaceholder}
+                />
+              </Field>
+            )}
+
+            <Field
+              label={t("models.field.apiBase")}
+              hint={isOAuth ? t("models.edit.oauthNote") : undefined}
+            >
+              <Input
+                value={form.apiBase}
+                onChange={setField("apiBase")}
+                placeholder="https://api.example.com/v1"
+                disabled={isOAuth}
+              />
+            </Field>
+
+            <SwitchCardField
+              label={t("models.defaultOnSave.label")}
+              hint={t("models.defaultOnSave.description")}
+              checked={setAsDefault}
+              onCheckedChange={setSetAsDefault}
+            />
+
+            <AdvancedSection>
+              <Field
+                label={t("models.field.proxy")}
+                hint={t("models.field.proxyHint")}
+              >
+                <Input
+                  value={form.proxy}
+                  onChange={setField("proxy")}
+                  placeholder="http://127.0.0.1:7890"
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.authMethod")}
+                hint={t("models.field.authMethodHint")}
+              >
+                <Input
+                  value={form.authMethod}
+                  onChange={setField("authMethod")}
+                  placeholder="oauth"
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.connectMode")}
+                hint={t("models.field.connectModeHint")}
+              >
+                <Input
+                  value={form.connectMode}
+                  onChange={setField("connectMode")}
+                  placeholder="stdio"
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.workspace")}
+                hint={t("models.field.workspaceHint")}
+              >
+                <Input
+                  value={form.workspace}
+                  onChange={setField("workspace")}
+                  placeholder="/path/to/workspace"
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.requestTimeout")}
+                hint={t("models.field.requestTimeoutHint")}
+              >
+                <Input
+                  value={form.requestTimeout}
+                  onChange={setField("requestTimeout")}
+                  placeholder="60"
+                  type="number"
+                  min={0}
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.rpm")}
+                hint={t("models.field.rpmHint")}
+              >
+                <Input
+                  value={form.rpm}
+                  onChange={setField("rpm")}
+                  placeholder="60"
+                  type="number"
+                  min={0}
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.thinkingLevel")}
+                hint={t("models.field.thinkingLevelHint")}
+              >
+                <Input
+                  value={form.thinkingLevel}
+                  onChange={setField("thinkingLevel")}
+                  placeholder="off"
+                />
+              </Field>
+
+              <Field
+                label={t("models.field.maxTokensField")}
+                hint={t("models.field.maxTokensFieldHint")}
+              >
+                <Input
+                  value={form.maxTokensField}
+                  onChange={setField("maxTokensField")}
+                  placeholder="max_completion_tokens"
+                />
+              </Field>
+            </AdvancedSection>
+
+            {error && (
+              <p className="text-destructive bg-destructive/10 rounded-md px-3 py-2 text-sm">
+                {error}
+              </p>
+            )}
+          </div>
+        </div>
+
+        <SheetFooter className="border-t-muted border-t px-6 py-4">
+          <Button variant="ghost" onClick={onClose} disabled={saving}>
+            {t("common.cancel")}
+          </Button>
+          <Button onClick={handleSave} disabled={saving}>
+            {saving && <IconLoader2 className="size-4 animate-spin" />}
+            {t("common.save")}
+          </Button>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  )
+}
diff --git a/web/frontend/src/components/models/model-card.tsx b/web/frontend/src/components/models/model-card.tsx
new file mode 100644
index 000000000..319cb11a3
--- /dev/null
+++ b/web/frontend/src/components/models/model-card.tsx
@@ -0,0 +1,142 @@
+import {
+  IconEdit,
+  IconKey,
+  IconLoader2,
+  IconStar,
+  IconStarFilled,
+  IconTrash,
+} from "@tabler/icons-react"
+import { useTranslation } from "react-i18next"
+
+import type { ModelInfo } from "@/api/models"
+import { Button } from "@/components/ui/button"
+
+interface ModelCardProps {
+  model: ModelInfo
+  onEdit: (model: ModelInfo) => void
+  onSetDefault: (model: ModelInfo) => void
+  onDelete: (model: ModelInfo) => void
+  settingDefault: boolean
+}
+
+export function ModelCard({
+  model,
+  onEdit,
+  onSetDefault,
+  onDelete,
+  settingDefault,
+}: ModelCardProps) {
+  const { t } = useTranslation()
+  const isOAuth = model.auth_method === "oauth"
+  const canSetDefault = model.configured && !model.is_default && !model.is_virtual
+
+  return (
+    <div
+      className={[
+        "group/card hover:bg-muted/30 relative flex w-full max-w-[36rem] flex-col gap-3 justify-self-start rounded-xl border p-4 transition-colors hover:shadow-xs",
+        model.configured
+          ? "border-border/60 bg-card"
+          : "border-border/50 bg-card/60",
+      ].join(" ")}
+    >
+      <div className="flex items-start justify-between gap-2">
+        <div className="flex min-w-0 items-center gap-2">
+          <span
+            className={[
+              "mt-0.5 h-2 w-2 shrink-0 rounded-full",
+              model.is_default
+                ? "bg-green-400 shadow-[0_0_0_2px_rgba(74,222,128,0.35)]"
+                : model.configured
+                  ? "bg-green-500"
+                  : "bg-muted-foreground/25",
+            ].join(" ")}
+            title={
+              model.configured
+                ? t("models.status.configured")
+                : t("models.status.unconfigured")
+            }
+          />
+          <span className="text-foreground truncate text-sm font-semibold">
+            {model.model_name}
+          </span>
+          {model.is_default && (
+            <span className="bg-primary/10 text-primary shrink-0 rounded px-1.5 py-0.5 text-[10px] leading-none font-medium">
+              {t("models.badge.default")}
+            </span>
+          )}
+          {model.is_virtual && (
+            <span className="bg-muted text-muted-foreground shrink-0 rounded px-1.5 py-0.5 text-[10px] leading-none font-medium">
+              {t("models.badge.virtual")}
+            </span>
+          )}
+        </div>
+
+        <div className="flex shrink-0 items-center gap-0.5">
+          {model.is_default ? (
+            <span
+              className="text-primary p-1"
+              title={t("models.badge.default")}
+            >
+              <IconStarFilled className="size-3.5" />
+            </span>
+          ) : (
+            <Button
+              variant="ghost"
+              size="icon-sm"
+              onClick={() => onSetDefault(model)}
+              disabled={settingDefault || !canSetDefault}
+              title={t("models.action.setDefault")}
+            >
+              {settingDefault ? (
+                <IconLoader2 className="size-3.5 animate-spin" />
+              ) : (
+                <IconStar className="size-3.5" />
+              )}
+            </Button>
+          )}
+
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            onClick={() => onEdit(model)}
+            title={t("models.action.edit")}
+          >
+            <IconEdit className="size-3.5" />
+          </Button>
+
+          <Button
+            variant="ghost"
+            size="icon-sm"
+            onClick={() => onDelete(model)}
+            disabled={model.is_default}
+            title={t("models.action.delete")}
+            className="text-muted-foreground hover:text-destructive hover:bg-destructive/10"
+          >
+            <IconTrash className="size-3.5" />
+          </Button>
+        </div>
+      </div>
+
+      <p className="text-muted-foreground truncate font-mono text-xs leading-snug">
+        {model.model}
+      </p>
+
+      <div className="flex items-center gap-2">
+        {isOAuth ? (
+          <span className="text-muted-foreground bg-muted rounded px-1.5 py-0.5 text-[10px] font-medium">
+            OAuth
+          </span>
+        ) : model.configured && model.api_key ? (
+          <span className="text-muted-foreground/70 flex items-center gap-1 font-mono text-[11px]">
+            <IconKey className="size-3" />
+            {model.api_key}
+          </span>
+        ) : (
+          <span className="text-muted-foreground/50 text-[11px]">
+            {t("models.status.unconfigured")}
+          </span>
+        )}
+      </div>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/models/models-page.tsx b/web/frontend/src/components/models/models-page.tsx
new file mode 100644
index 000000000..6776e5ca8
--- /dev/null
+++ b/web/frontend/src/components/models/models-page.tsx
@@ -0,0 +1,215 @@
+import { IconLoader2, IconPlus, IconStar } from "@tabler/icons-react"
+import { useCallback, useEffect, useState } from "react"
+import { useTranslation } from "react-i18next"
+
+import { type ModelInfo, getModels, setDefaultModel } from "@/api/models"
+import { PageHeader } from "@/components/page-header"
+import { Button } from "@/components/ui/button"
+
+import { AddModelSheet } from "./add-model-sheet"
+import { DeleteModelDialog } from "./delete-model-dialog"
+import { EditModelSheet } from "./edit-model-sheet"
+import { getProviderKey, getProviderLabel } from "./provider-label"
+import { ProviderSection } from "./provider-section"
+
+const PROVIDER_PRIORITY: Record<string, number> = {
+  volcengine: 0,
+  openai: 1,
+  gemini: 2,
+  anthropic: 3,
+  zhipu: 4,
+  deepseek: 5,
+  openrouter: 6,
+  qwen: 7,
+  moonshot: 8,
+  groq: 9,
+  "github-copilot": 10,
+  antigravity: 11,
+  nvidia: 12,
+  cerebras: 13,
+  shengsuanyun: 14,
+  ollama: 15,
+  vllm: 16,
+  mistral: 17,
+  avian: 18,
+}
+
+interface ProviderGroup {
+  key: string
+  label: string
+  models: ModelInfo[]
+  hasDefault: boolean
+  configuredCount: number
+}
+
+export function ModelsPage() {
+  const { t } = useTranslation()
+  const [models, setModels] = useState<ModelInfo[]>([])
+  const [loading, setLoading] = useState(true)
+  const [fetchError, setFetchError] = useState("")
+
+  const [editingModel, setEditingModel] = useState<ModelInfo | null>(null)
+  const [deletingModel, setDeletingModel] = useState<ModelInfo | null>(null)
+  const [addOpen, setAddOpen] = useState(false)
+  const [settingDefaultIndex, setSettingDefaultIndex] = useState<number | null>(
+    null,
+  )
+
+  const fetchModels = useCallback(async () => {
+    try {
+      const data = await getModels()
+      const sorted = [...data.models].sort((a, b) => {
+        if (a.is_default && !b.is_default) return -1
+        if (!a.is_default && b.is_default) return 1
+        if (a.configured && !b.configured) return -1
+        if (!a.configured && b.configured) return 1
+        return a.model_name.localeCompare(b.model_name)
+      })
+      setModels(sorted)
+      setFetchError("")
+    } catch (e) {
+      setFetchError(e instanceof Error ? e.message : t("models.loadError"))
+    } finally {
+      setLoading(false)
+    }
+  }, [t])
+
+  useEffect(() => {
+    fetchModels()
+  }, [fetchModels])
+
+  const handleSetDefault = async (model: ModelInfo) => {
+    if (model.is_default) return
+
+    setSettingDefaultIndex(model.index)
+    try {
+      await setDefaultModel(model.model_name)
+      await fetchModels()
+    } catch {
+      // ignore
+    } finally {
+      setSettingDefaultIndex(null)
+    }
+  }
+
+  const grouped: Record<string, { label: string; models: ModelInfo[] }> = {}
+  for (const model of models) {
+    const providerKey = getProviderKey(model.model)
+    if (!grouped[providerKey]) {
+      grouped[providerKey] = {
+        label: getProviderLabel(model.model),
+        models: [],
+      }
+    }
+    grouped[providerKey].models.push(model)
+  }
+
+  const providerGroups: ProviderGroup[] = Object.entries(grouped)
+    .map(([key, group]) => {
+      const configuredCount = group.models.filter(
+        (model) => model.configured,
+      ).length
+      return {
+        key,
+        label: group.label,
+        models: group.models,
+        hasDefault: group.models.some((model) => model.is_default),
+        configuredCount,
+      }
+    })
+    .sort((a, b) => {
+      if (a.hasDefault && !b.hasDefault) return -1
+      if (!a.hasDefault && b.hasDefault) return 1
+
+      if (a.configuredCount !== b.configuredCount) {
+        return b.configuredCount - a.configuredCount
+      }
+
+      const aPriority = PROVIDER_PRIORITY[a.key] ?? Number.MAX_SAFE_INTEGER
+      const bPriority = PROVIDER_PRIORITY[b.key] ?? Number.MAX_SAFE_INTEGER
+      if (aPriority !== bPriority) {
+        return aPriority - bPriority
+      }
+
+      return a.label.localeCompare(b.label)
+    })
+
+  const defaultModel = models.find((model) => model.is_default)
+
+  return (
+    <div className="flex h-full flex-col">
+      <PageHeader title={t("navigation.models")}>
+        <div className="flex items-center gap-3">
+          <Button size="sm" variant="outline" onClick={() => setAddOpen(true)}>
+            <IconPlus className="size-4" />
+            {t("models.add.button")}
+          </Button>
+        </div>
+      </PageHeader>
+
+      <div className="min-h-0 flex-1 overflow-y-auto px-4 sm:px-6">
+        <div className="pt-2">
+          {!defaultModel && (
+            <div className="text-muted-foreground flex items-center gap-1.5 text-sm">
+              <span>{t("models.noDefaultHintPrefix")}</span>
+              <IconStar className="size-3.5 shrink-0" />
+              <span>{t("models.noDefaultHintSuffix")}</span>
+            </div>
+          )}
+          <p className="text-muted-foreground mt-1 text-sm">
+            {t("models.description")}
+          </p>
+        </div>
+
+        {loading && (
+          <div className="flex items-center justify-center py-20">
+            <IconLoader2 className="text-muted-foreground size-6 animate-spin" />
+          </div>
+        )}
+
+        {fetchError && (
+          <div className="text-destructive bg-destructive/10 rounded-lg px-4 py-3 text-sm">
+            {fetchError}
+          </div>
+        )}
+
+        {!loading && !fetchError && (
+          <div className="pb-8">
+            {providerGroups.map((providerGroup) => (
+              <ProviderSection
+                key={providerGroup.key}
+                provider={providerGroup.label}
+                providerKey={providerGroup.key}
+                models={providerGroup.models}
+                onEdit={setEditingModel}
+                onSetDefault={handleSetDefault}
+                onDelete={setDeletingModel}
+                settingDefaultIndex={settingDefaultIndex}
+              />
+            ))}
+          </div>
+        )}
+      </div>
+
+      <EditModelSheet
+        model={editingModel}
+        open={editingModel !== null}
+        onClose={() => setEditingModel(null)}
+        onSaved={fetchModels}
+      />
+
+      <AddModelSheet
+        open={addOpen}
+        onClose={() => setAddOpen(false)}
+        onSaved={fetchModels}
+        existingModelNames={models.map((model) => model.model_name)}
+      />
+
+      <DeleteModelDialog
+        model={deletingModel}
+        onClose={() => setDeletingModel(null)}
+        onDeleted={fetchModels}
+      />
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/models/provider-icon.tsx b/web/frontend/src/components/models/provider-icon.tsx
new file mode 100644
index 000000000..5e2151e2d
--- /dev/null
+++ b/web/frontend/src/components/models/provider-icon.tsx
@@ -0,0 +1,95 @@
+import { useMemo, useState } from "react"
+
+const PROVIDER_ICON_SLUGS: Record<string, string> = {
+  openai: "openai",
+  anthropic: "anthropic",
+  gemini: "googlegemini",
+  deepseek: "deepseek",
+  qwen: "alibabacloud",
+  groq: "groq",
+  openrouter: "openrouter",
+  nvidia: "nvidia",
+  cerebras: "cerebras",
+  volcengine: "bytedance",
+  "github-copilot": "githubcopilot",
+  ollama: "ollama",
+  mistral: "mistralai",
+  zhipu: "zhipu",
+}
+
+const PROVIDER_DOMAINS: Record<string, string> = {
+  openai: "openai.com",
+  anthropic: "anthropic.com",
+  gemini: "gemini.google.com",
+  deepseek: "deepseek.com",
+  qwen: "qwenlm.ai",
+  moonshot: "moonshot.ai",
+  groq: "groq.com",
+  openrouter: "openrouter.ai",
+  nvidia: "nvidia.com",
+  cerebras: "cerebras.ai",
+  volcengine: "volcengine.com",
+  shengsuanyun: "shengsuanyun.com",
+  antigravity: "antigravity.google",
+  "github-copilot": "github.com",
+  ollama: "ollama.com",
+  mistral: "mistral.ai",
+  avian: "avian.io",
+  vllm: "vllm.ai",
+  zhipu: "zhipuai.cn",
+}
+
+interface ProviderIconProps {
+  providerKey: string
+  providerLabel: string
+}
+
+export function ProviderIcon({
+  providerKey,
+  providerLabel,
+}: ProviderIconProps) {
+  const [sourceIndex, setSourceIndex] = useState(0)
+  const [loadFailed, setLoadFailed] = useState(false)
+  const initial = providerLabel.trim().charAt(0).toUpperCase() || "?"
+  const iconUrls = useMemo(() => {
+    const slug = PROVIDER_ICON_SLUGS[providerKey]
+    const domain = PROVIDER_DOMAINS[providerKey]
+    const urls: string[] = []
+    if (slug) {
+      urls.push(`https://cdn.simpleicons.org/${slug}`)
+    }
+    if (domain) {
+      urls.push(`https://www.google.com/s2/favicons?domain=${domain}&sz=64`)
+    }
+    return urls
+  }, [providerKey])
+
+  const iconUrl = iconUrls[sourceIndex]
+
+  if (!iconUrl || loadFailed) {
+    return (
+      <span className="inline-flex size-4 shrink-0 items-center justify-center rounded-sm border border-black/10 bg-white text-[9px] font-semibold text-black/70 dark:border-white/20 dark:text-black/70">
+        {initial}
+      </span>
+    )
+  }
+
+  return (
+    <span className="inline-flex size-4 shrink-0 items-center justify-center overflow-hidden rounded-sm border border-black/10 bg-white p-0.5 dark:border-white/20">
+      <img
+        src={iconUrl}
+        alt={`${providerLabel} logo`}
+        className="size-full object-contain"
+        loading="lazy"
+        referrerPolicy="no-referrer"
+        onError={() => {
+          if (sourceIndex < iconUrls.length - 1) {
+            setSourceIndex((idx) => idx + 1)
+            return
+          }
+          setLoadFailed(true)
+        }}
+      />
+    </span>
+  )
+}
diff --git a/web/frontend/src/components/models/provider-label.ts b/web/frontend/src/components/models/provider-label.ts
new file mode 100644
index 000000000..923cd9506
--- /dev/null
+++ b/web/frontend/src/components/models/provider-label.ts
@@ -0,0 +1,33 @@
+const PROVIDER_LABELS: Record<string, string> = {
+  openai: "OpenAI",
+  anthropic: "Anthropic",
+  gemini: "Google Gemini",
+  deepseek: "DeepSeek",
+  qwen: "Qwen (阿里云)",
+  moonshot: "Moonshot (月之暗面)",
+  groq: "Groq",
+  openrouter: "OpenRouter",
+  nvidia: "NVIDIA",
+  cerebras: "Cerebras",
+  volcengine: "Volcengine (火山引擎)",
+  shengsuanyun: "ShengsuanYun (神算云)",
+  antigravity: "Google Code Assist",
+  "github-copilot": "GitHub Copilot",
+  ollama: "Ollama (local)",
+  mistral: "Mistral AI",
+  avian: "Avian",
+  vllm: "VLLM (local)",
+  zhipu: "Zhipu AI (智谱)",
+}
+
+export function getProviderKey(model: string): string {
+  return model.split("/")[0]
+}
+
+export function getProviderLabel(model: string): string {
+  const prefix = getProviderKey(model)
+  const labels: Record<string, string> = {
+    ...PROVIDER_LABELS,
+  }
+  return labels[prefix] ?? prefix
+}
diff --git a/web/frontend/src/components/models/provider-section.tsx b/web/frontend/src/components/models/provider-section.tsx
new file mode 100644
index 000000000..613364f0f
--- /dev/null
+++ b/web/frontend/src/components/models/provider-section.tsx
@@ -0,0 +1,72 @@
+import { IconChevronDown } from "@tabler/icons-react"
+import { useState } from "react"
+
+import type { ModelInfo } from "@/api/models"
+
+import { ModelCard } from "./model-card"
+import { ProviderIcon } from "./provider-icon"
+
+interface ProviderSectionProps {
+  provider: string
+  providerKey: string
+  models: ModelInfo[]
+  onEdit: (model: ModelInfo) => void
+  onSetDefault: (model: ModelInfo) => void
+  onDelete: (model: ModelInfo) => void
+  settingDefaultIndex: number | null
+}
+
+export function ProviderSection({
+  provider,
+  providerKey,
+  models,
+  onEdit,
+  onSetDefault,
+  onDelete,
+  settingDefaultIndex,
+}: ProviderSectionProps) {
+  const [open, setOpen] = useState(true)
+
+  return (
+    <section className="my-8">
+      <button
+        type="button"
+        onClick={() => setOpen((v) => !v)}
+        className="mb-3 grid w-full grid-cols-[1fr_auto_1fr_auto] items-center gap-2 px-1 py-1.5 text-left"
+        aria-expanded={open}
+      >
+        <div className="border-border/40 border-t" />
+        <span className="text-foreground/80 text-center text-xs font-semibold tracking-wide uppercase">
+          <span className="bg-background inline-flex items-center gap-1.5 px-2">
+            <ProviderIcon providerKey={providerKey} providerLabel={provider} />
+            {provider}
+          </span>
+        </span>
+        <div className="border-border/40 border-t" />
+        <span className="flex justify-end">
+          <IconChevronDown
+            className={[
+              "text-muted-foreground size-4 transition-transform",
+              open ? "rotate-180" : "",
+            ].join(" ")}
+          />
+        </span>
+      </button>
+
+      {open && (
+        <div className="grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3">
+          {models.map((model) => (
+            <ModelCard
+              key={model.index}
+              model={model}
+              onEdit={onEdit}
+              onSetDefault={onSetDefault}
+              onDelete={onDelete}
+              settingDefault={settingDefaultIndex === model.index}
+            />
+          ))}
+        </div>
+      )}
+    </section>
+  )
+}
diff --git a/web/frontend/src/components/page-header.tsx b/web/frontend/src/components/page-header.tsx
new file mode 100644
index 000000000..656551f39
--- /dev/null
+++ b/web/frontend/src/components/page-header.tsx
@@ -0,0 +1,39 @@
+import { IconMenu2 } from "@tabler/icons-react"
+import type { ReactNode } from "react"
+
+import { SidebarTrigger } from "@/components/ui/sidebar"
+import { cn } from "@/lib/utils"
+
+interface PageHeaderProps {
+  title: string
+  titleExtra?: ReactNode
+  children?: ReactNode
+  className?: string
+}
+
+export function PageHeader({
+  title,
+  titleExtra,
+  children,
+  className,
+}: PageHeaderProps) {
+  return (
+    <div
+      className={cn(
+        "z-40 flex h-14 shrink-0 items-center justify-between px-6 pt-2",
+        className,
+      )}
+    >
+      <div className="flex items-center gap-4">
+        <SidebarTrigger className="border-border/60 bg-background text-muted-foreground hover:bg-accent hover:text-foreground hidden h-9 w-9 rounded-lg border sm:flex [&>svg]:size-5">
+          <IconMenu2 />
+        </SidebarTrigger>
+        <h2 className="text-foreground/90 text-xl font-medium tracking-tight">
+          {title}
+        </h2>
+        {titleExtra}
+      </div>
+      {children && <div className="flex items-center gap-2">{children}</div>}
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/secret-placeholder.ts b/web/frontend/src/components/secret-placeholder.ts
new file mode 100644
index 000000000..88d4cb311
--- /dev/null
+++ b/web/frontend/src/components/secret-placeholder.ts
@@ -0,0 +1,23 @@
+export function maskedSecretPlaceholder(value: unknown, fallback = ""): string {
+  const secret = typeof value === "string" ? value.trim() : ""
+  if (!secret) {
+    return fallback
+  }
+
+  // ensure at least 40% of the characters are masked for secrets of length 4 or more
+  if (secret.length <= 6) {
+    const first = secret[0]
+    const last = secret[secret.length - 1]
+    return `${first}***${last}`
+  }
+
+  if (secret.length <= 12) {
+    const firstTwo = secret.slice(0, 2)
+    const lastTwo = secret.slice(-2)
+    return `${firstTwo}****${lastTwo}`
+  }
+
+  const prefix = secret.slice(0, 3)
+  const suffix = secret.slice(-4)
+  return `${prefix}*****${suffix}`
+}
diff --git a/web/frontend/src/components/shared-form.tsx b/web/frontend/src/components/shared-form.tsx
new file mode 100644
index 000000000..14da8e1f1
--- /dev/null
+++ b/web/frontend/src/components/shared-form.tsx
@@ -0,0 +1,228 @@
+import { IconChevronDown, IconEye, IconEyeOff } from "@tabler/icons-react"
+import { type ReactNode, useState } from "react"
+import { useTranslation } from "react-i18next"
+
+import {
+  FieldDescription,
+  FieldLabel,
+  Field as UiField,
+} from "@/components/ui/field"
+import { Input } from "@/components/ui/input"
+import { Switch } from "@/components/ui/switch"
+import { cn } from "@/lib/utils"
+
+type FieldLayout = "default" | "setting-row"
+
+interface FieldProps {
+  label: string
+  hint?: string
+  error?: string
+  required?: boolean
+  children: ReactNode
+  layout?: FieldLayout
+  controlClassName?: string
+}
+
+export function Field({
+  label,
+  hint,
+  error,
+  required,
+  children,
+  layout = "default",
+  controlClassName,
+}: FieldProps) {
+  if (layout === "setting-row") {
+    return (
+      <div className="flex flex-col gap-4 py-4 md:grid md:grid-cols-[minmax(0,1fr)_minmax(240px,320px)] md:items-center md:gap-6">
+        <div className="max-w-full space-y-1 md:max-w-[clamp(18rem,42vw,28rem)]">
+          <FieldLabel>
+            {label}
+            {required && <span className="text-destructive ml-1">*</span>}
+          </FieldLabel>
+          {hint && (
+            <FieldDescription className="text-xs leading-normal break-words">
+              {hint}
+            </FieldDescription>
+          )}
+        </div>
+        <div className={cn("w-full md:justify-self-center", controlClassName)}>
+          {children}
+        </div>
+        {error && (
+          <FieldDescription className="text-destructive text-xs leading-normal md:col-start-2">
+            {error}
+          </FieldDescription>
+        )}
+      </div>
+    )
+  }
+
+  return (
+    <UiField className="gap-2.5">
+      <div className="space-y-1">
+        <FieldLabel>
+          {label}
+          {required && <span className="text-destructive ml-1">*</span>}
+        </FieldLabel>
+        {hint && (
+          <FieldDescription className="text-xs leading-normal">
+            {hint}
+          </FieldDescription>
+        )}
+      </div>
+      {children}
+      {error && (
+        <FieldDescription className="text-destructive text-xs leading-normal">
+          {error}
+        </FieldDescription>
+      )}
+    </UiField>
+  )
+}
+
+interface KeyInputProps {
+  value: string
+  onChange: (v: string) => void
+  placeholder?: string
+}
+
+export function KeyInput({ value, onChange, placeholder }: KeyInputProps) {
+  const [show, setShow] = useState(false)
+
+  return (
+    <div className="relative">
+      <Input
+        type={show ? "text" : "password"}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder}
+        className="pr-10"
+      />
+      <button
+        type="button"
+        onClick={() => setShow((v) => !v)}
+        tabIndex={-1}
+        className="text-muted-foreground hover:text-foreground absolute top-1/2 right-3 -translate-y-1/2 transition-colors"
+      >
+        {show ? (
+          <IconEyeOff className="size-4" />
+        ) : (
+          <IconEye className="size-4" />
+        )}
+      </button>
+    </div>
+  )
+}
+
+interface SwitchCardFieldProps {
+  label: string
+  hint?: string
+  error?: string
+  checked: boolean
+  onCheckedChange: (checked: boolean) => void
+  ariaLabel?: string
+  disabled?: boolean
+  children?: ReactNode
+  layout?: FieldLayout
+}
+
+export function SwitchCardField({
+  label,
+  hint,
+  error,
+  checked,
+  onCheckedChange,
+  ariaLabel,
+  disabled,
+  children,
+  layout = "default",
+}: SwitchCardFieldProps) {
+  if (layout === "setting-row") {
+    return (
+      <div className="flex flex-col gap-4 py-4 md:grid md:grid-cols-[minmax(0,1fr)_auto] md:items-center md:gap-6">
+        <div className="max-w-full min-w-0 md:max-w-[clamp(18rem,42vw,28rem)]">
+          <p className="text-sm font-medium">{label}</p>
+          {hint && (
+            <p className="text-muted-foreground mt-0.5 text-xs leading-normal break-words">
+              {hint}
+            </p>
+          )}
+        </div>
+        <div className="flex items-center md:justify-self-center">
+          <Switch
+            checked={checked}
+            onCheckedChange={onCheckedChange}
+            disabled={disabled}
+            aria-label={ariaLabel ?? label}
+          />
+        </div>
+        {children && <div className="md:col-start-2">{children}</div>}
+        {error && (
+          <p className="text-destructive text-xs leading-normal md:col-start-2">
+            {error}
+          </p>
+        )}
+      </div>
+    )
+  }
+
+  return (
+    <div className="border-border/60 bg-background rounded-lg border px-4 py-3">
+      <div className="flex items-start justify-between gap-3">
+        <div className="min-w-0">
+          <p className="text-sm font-medium">{label}</p>
+          {hint && (
+            <p className="text-muted-foreground mt-0.5 text-xs leading-normal">
+              {hint}
+            </p>
+          )}
+        </div>
+        <Switch
+          checked={checked}
+          onCheckedChange={onCheckedChange}
+          disabled={disabled}
+          aria-label={ariaLabel ?? label}
+        />
+      </div>
+      {children && <div className="mt-3">{children}</div>}
+      {error && (
+        <p className="text-destructive mt-2 text-xs leading-normal">{error}</p>
+      )}
+    </div>
+  )
+}
+
+interface AdvancedSectionProps {
+  children: ReactNode
+}
+
+export function AdvancedSection({ children }: AdvancedSectionProps) {
+  const { t } = useTranslation()
+  const [open, setOpen] = useState(false)
+
+  return (
+    <div className="border-border/50 rounded-lg border">
+      <button
+        type="button"
+        onClick={() => setOpen((v) => !v)}
+        className="hover:bg-muted/40 flex w-full items-center justify-between rounded-lg px-4 py-3 transition-colors"
+      >
+        <span className="text-muted-foreground text-sm">
+          {t("models.advanced.toggle")}
+        </span>
+        <IconChevronDown
+          className={[
+            "text-muted-foreground size-4 transition-transform duration-200",
+            open ? "rotate-180" : "",
+          ].join(" ")}
+        />
+      </button>
+      {open && (
+        <div className="border-border/30 space-y-5 border-t px-4 pt-4 pb-4">
+          {children}
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/skills/skills-page.tsx b/web/frontend/src/components/skills/skills-page.tsx
new file mode 100644
index 000000000..d8eeb1d93
--- /dev/null
+++ b/web/frontend/src/components/skills/skills-page.tsx
@@ -0,0 +1,319 @@
+import {
+  IconFileInfo,
+  IconLoader2,
+  IconPlus,
+  IconTrash,
+} from "@tabler/icons-react"
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
+import { type ChangeEvent, useRef, useState } from "react"
+import { useTranslation } from "react-i18next"
+import ReactMarkdown from "react-markdown"
+import rehypeRaw from "rehype-raw"
+import rehypeSanitize from "rehype-sanitize"
+import remarkGfm from "remark-gfm"
+import { toast } from "sonner"
+
+import {
+  type SkillSupportItem,
+  deleteSkill,
+  getSkill,
+  getSkills,
+  importSkill,
+} from "@/api/skills"
+import { PageHeader } from "@/components/page-header"
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog"
+import { Button } from "@/components/ui/button"
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet"
+
+export function SkillsPage() {
+  const { t } = useTranslation()
+  const queryClient = useQueryClient()
+  const importInputRef = useRef<HTMLInputElement | null>(null)
+  const [selectedSkill, setSelectedSkill] = useState<SkillSupportItem | null>(
+    null,
+  )
+  const [skillPendingDelete, setSkillPendingDelete] =
+    useState<SkillSupportItem | null>(null)
+
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["skills"],
+    queryFn: getSkills,
+  })
+  const {
+    data: selectedSkillDetail,
+    isLoading: isSkillDetailLoading,
+    error: skillDetailError,
+  } = useQuery({
+    queryKey: ["skills", selectedSkill?.name],
+    queryFn: () => getSkill(selectedSkill!.name),
+    enabled: selectedSkill !== null,
+  })
+
+  const importMutation = useMutation({
+    mutationFn: async (file: File) => importSkill(file),
+    onSuccess: () => {
+      toast.success(t("pages.agent.skills.import_success"))
+      void queryClient.invalidateQueries({ queryKey: ["skills"] })
+    },
+    onError: (err) => {
+      toast.error(
+        err instanceof Error
+          ? err.message
+          : t("pages.agent.skills.import_error"),
+      )
+    },
+  })
+
+  const deleteMutation = useMutation({
+    mutationFn: async (name: string) => deleteSkill(name),
+    onSuccess: (_, deletedName) => {
+      toast.success(t("pages.agent.skills.delete_success"))
+      setSkillPendingDelete(null)
+      if (
+        selectedSkill?.name === deletedName &&
+        selectedSkill.source === "workspace"
+      ) {
+        setSelectedSkill(null)
+      }
+      void queryClient.invalidateQueries({ queryKey: ["skills"] })
+    },
+    onError: (err) => {
+      toast.error(
+        err instanceof Error
+          ? err.message
+          : t("pages.agent.skills.delete_error"),
+      )
+    },
+  })
+
+  const handleImportClick = () => {
+    importInputRef.current?.click()
+  }
+
+  const handleImportFileChange = (event: ChangeEvent<HTMLInputElement>) => {
+    const file = event.target.files?.[0]
+    if (!file) return
+    importMutation.mutate(file)
+    event.target.value = ""
+  }
+
+  return (
+    <div className="flex h-full flex-col">
+      <PageHeader
+        title={t("navigation.skills")}
+        children={
+          <>
+            <input
+              ref={importInputRef}
+              type="file"
+              accept=".md,text/markdown,text/plain"
+              className="hidden"
+              onChange={handleImportFileChange}
+            />
+            <Button
+              variant="outline"
+              onClick={handleImportClick}
+              disabled={importMutation.isPending}
+            >
+              {importMutation.isPending ? (
+                <IconLoader2 className="size-4 animate-spin" />
+              ) : (
+                <IconPlus className="size-4" />
+              )}
+              {t("pages.agent.skills.import")}
+            </Button>
+          </>
+        }
+      />
+
+      <div className="flex-1 overflow-auto px-6 py-3">
+        <div className="w-full max-w-6xl space-y-6">
+          {isLoading ? (
+            <div className="text-muted-foreground py-6 text-sm">
+              {t("labels.loading")}
+            </div>
+          ) : error ? (
+            <div className="text-destructive py-6 text-sm">
+              {t("pages.agent.load_error")}
+            </div>
+          ) : (
+            <section className="space-y-5">
+              <p className="text-muted-foreground text-sm">
+                {t("pages.agent.skills.description")}
+              </p>
+
+              {data?.skills.length ? (
+                <div className="grid gap-4 lg:grid-cols-2">
+                  {data.skills.map((skill) => (
+                    <Card
+                      key={`${skill.source}:${skill.name}`}
+                      className="border-border/60 gap-4 bg-white/80"
+                      size="sm"
+                    >
+                      <CardHeader>
+                        <div className="flex items-start justify-between gap-3">
+                          <div>
+                            <CardTitle className="font-semibold">
+                              {skill.name}
+                            </CardTitle>
+                            <CardDescription className="mt-3">
+                              {skill.description ||
+                                t("pages.agent.skills.no_description")}
+                            </CardDescription>
+                          </div>
+                          <div className="flex items-center gap-1">
+                            <Button
+                              variant="ghost"
+                              size="icon-sm"
+                              className="text-muted-foreground hover:text-foreground"
+                              onClick={() => setSelectedSkill(skill)}
+                              title={t("pages.agent.skills.view")}
+                            >
+                              <IconFileInfo className="size-4" />
+                            </Button>
+                            {skill.source === "workspace" ? (
+                              <Button
+                                variant="ghost"
+                                size="icon-sm"
+                                className="text-muted-foreground hover:text-destructive"
+                                onClick={() => setSkillPendingDelete(skill)}
+                                title={t("pages.agent.skills.delete")}
+                              >
+                                <IconTrash className="size-4" />
+                              </Button>
+                            ) : null}
+                          </div>
+                        </div>
+                      </CardHeader>
+                      <CardContent className="space-y-2">
+                        <div className="text-muted-foreground text-[11px] tracking-[0.18em] uppercase">
+                          {t("pages.agent.skills.path")}
+                        </div>
+                        <div className="bg-muted/60 overflow-x-auto rounded-lg px-3 py-2 font-mono text-xs leading-relaxed">
+                          {skill.path}
+                        </div>
+                      </CardContent>
+                    </Card>
+                  ))}
+                </div>
+              ) : (
+                <Card className="border-dashed">
+                  <CardContent className="text-muted-foreground py-10 text-center text-sm">
+                    {t("pages.agent.skills.empty")}
+                  </CardContent>
+                </Card>
+              )}
+            </section>
+          )}
+        </div>
+      </div>
+
+      <Sheet
+        open={selectedSkill !== null}
+        onOpenChange={(open) => {
+          if (!open) setSelectedSkill(null)
+        }}
+      >
+        <SheetContent
+          side="right"
+          className="w-full gap-0 p-0 data-[side=right]:!w-full data-[side=right]:sm:!w-[560px] data-[side=right]:sm:!max-w-[560px]"
+        >
+          <SheetHeader className="border-b px-6 py-5">
+            <SheetTitle>
+              {selectedSkill?.name || t("pages.agent.skills.viewer_title")}
+            </SheetTitle>
+            <SheetDescription>
+              {selectedSkill?.description ||
+                t("pages.agent.skills.viewer_description")}
+            </SheetDescription>
+          </SheetHeader>
+
+          <div className="flex-1 overflow-auto px-6 py-5">
+            {isSkillDetailLoading ? (
+              <div className="text-muted-foreground text-sm">
+                {t("pages.agent.skills.loading_detail")}
+              </div>
+            ) : skillDetailError ? (
+              <div className="text-destructive text-sm">
+                {t("pages.agent.skills.load_detail_error")}
+              </div>
+            ) : selectedSkillDetail ? (
+              <div className="space-y-5">
+                <div className="prose prose-sm dark:prose-invert prose-pre:rounded-lg prose-pre:border prose-pre:bg-zinc-950 prose-pre:p-3 max-w-none">
+                  <ReactMarkdown
+                    remarkPlugins={[remarkGfm]}
+                    rehypePlugins={[rehypeRaw, rehypeSanitize]}
+                  >
+                    {selectedSkillDetail.content}
+                  </ReactMarkdown>
+                </div>
+              </div>
+            ) : null}
+          </div>
+        </SheetContent>
+      </Sheet>
+
+      <AlertDialog
+        open={skillPendingDelete !== null}
+        onOpenChange={(open) => {
+          if (!open) setSkillPendingDelete(null)
+        }}
+      >
+        <AlertDialogContent size="sm">
+          <AlertDialogHeader>
+            <AlertDialogTitle>
+              {t("pages.agent.skills.delete_title")}
+            </AlertDialogTitle>
+            <AlertDialogDescription>
+              {t("pages.agent.skills.delete_description", {
+                name: skillPendingDelete?.name,
+              })}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={deleteMutation.isPending}>
+              {t("common.cancel")}
+            </AlertDialogCancel>
+            <AlertDialogAction
+              variant="destructive"
+              disabled={deleteMutation.isPending || !skillPendingDelete}
+              onClick={() => {
+                if (skillPendingDelete)
+                  deleteMutation.mutate(skillPendingDelete.name)
+              }}
+            >
+              {deleteMutation.isPending ? (
+                <IconLoader2 className="size-4 animate-spin" />
+              ) : (
+                <IconTrash className="size-4" />
+              )}
+              {t("pages.agent.skills.delete_confirm")}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </div>
+  )
+}
diff --git a/web/frontend/src/components/tools/tools-page.tsx b/web/frontend/src/components/tools/tools-page.tsx
new file mode 100644
index 000000000..05aa42122
--- /dev/null
+++ b/web/frontend/src/components/tools/tools-page.tsx
@@ -0,0 +1,190 @@
+import { IconLoader2 } from "@tabler/icons-react"
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
+import { useTranslation } from "react-i18next"
+import { toast } from "sonner"
+
+import { type ToolSupportItem, getTools, setToolEnabled } from "@/api/tools"
+import { PageHeader } from "@/components/page-header"
+import { Button } from "@/components/ui/button"
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card"
+import { cn } from "@/lib/utils"
+
+export function ToolsPage() {
+  const { t } = useTranslation()
+  const queryClient = useQueryClient()
+  const { data, isLoading, error } = useQuery({
+    queryKey: ["tools"],
+    queryFn: getTools,
+  })
+
+  const toggleMutation = useMutation({
+    mutationFn: async ({ name, enabled }: { name: string; enabled: boolean }) =>
+      setToolEnabled(name, enabled),
+    onSuccess: (_, variables) => {
+      toast.success(
+        variables.enabled
+          ? t("pages.agent.tools.enable_success")
+          : t("pages.agent.tools.disable_success"),
+      )
+      void queryClient.invalidateQueries({ queryKey: ["tools"] })
+    },
+    onError: (err) => {
+      toast.error(
+        err instanceof Error
+          ? err.message
+          : t("pages.agent.tools.toggle_error"),
+      )
+    },
+  })
+
+  const groupedTools = (() => {
+    if (!data) return [] as Array<[string, ToolSupportItem[]]>
+    const buckets = new Map<string, ToolSupportItem[]>()
+    for (const item of data.tools) {
+      const list = buckets.get(item.category) ?? []
+      list.push(item)
+      buckets.set(item.category, list)
+    }
+    return Array.from(buckets.entries())
+  })()
+
+  return (
+    <div className="flex h-full flex-col">
+      <PageHeader title={t("navigation.tools")} />
+
+      <div className="flex-1 overflow-auto px-6 py-3">
+        <div className="w-full max-w-6xl space-y-6">
+          {isLoading ? (
+            <div className="text-muted-foreground py-6 text-sm">
+              {t("labels.loading")}
+            </div>
+          ) : error ? (
+            <div className="text-destructive py-6 text-sm">
+              {t("pages.agent.load_error")}
+            </div>
+          ) : (
+            <section className="space-y-5">
+              <p className="text-muted-foreground mt-1 text-sm">
+                {t("pages.agent.tools.description")}
+              </p>
+
+              {data?.tools.length ? (
+                groupedTools.map(([category, items]) => (
+                  <div key={category} className="space-y-3">
+                    <div className="text-foreground/85 text-sm font-semibold tracking-wide">
+                      {t(`pages.agent.tools.categories.${category}`)}
+                    </div>
+                    <div className="grid gap-4 lg:grid-cols-2">
+                      {items.map((tool) => {
+                        const reasonText = tool.reason_code
+                          ? t(`pages.agent.tools.reasons.${tool.reason_code}`)
+                          : ""
+                        const isPending =
+                          toggleMutation.isPending &&
+                          toggleMutation.variables?.name === tool.name
+                        const nextEnabled = tool.status !== "enabled"
+
+                        return (
+                          <Card
+                            key={tool.name}
+                            className={cn(
+                              "gap-4 border transition-colors",
+                              tool.status === "enabled" &&
+                                "border-emerald-200/70 bg-emerald-50/50",
+                              tool.status === "blocked" &&
+                                "border-amber-200/80 bg-amber-50/60",
+                              tool.status === "disabled" &&
+                                "border-border/60 bg-card/70",
+                            )}
+                            size="sm"
+                          >
+                            <CardHeader>
+                              <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+                                <div className="min-w-0 flex-1">
+                                  <CardTitle className="font-mono text-sm break-all">
+                                    {tool.name}
+                                  </CardTitle>
+                                  <CardDescription className="mt-1 break-words">
+                                    {tool.description}
+                                  </CardDescription>
+                                </div>
+                                <div className="flex shrink-0 items-center gap-2 self-start">
+                                  <ToolStatusBadge status={tool.status} />
+                                  <Button
+                                    variant={
+                                      nextEnabled ? "default" : "outline"
+                                    }
+                                    size="sm"
+                                    disabled={isPending}
+                                    onClick={() =>
+                                      toggleMutation.mutate({
+                                        name: tool.name,
+                                        enabled: nextEnabled,
+                                      })
+                                    }
+                                  >
+                                    {isPending ? (
+                                      <IconLoader2 className="size-4 animate-spin" />
+                                    ) : null}
+                                    {nextEnabled
+                                      ? t("pages.agent.tools.enable")
+                                      : t("pages.agent.tools.disable")}
+                                  </Button>
+                                </div>
+                              </div>
+                            </CardHeader>
+                            <CardContent className="space-y-2">
+                              <div className="text-muted-foreground text-xs">
+                                {t("pages.agent.tools.config_key", {
+                                  key: tool.config_key,
+                                })}
+                              </div>
+                              {reasonText ? (
+                                <div className="text-sm text-amber-800">
+                                  {reasonText}
+                                </div>
+                              ) : null}
+                            </CardContent>
+                          </Card>
+                        )
+                      })}
+                    </div>
+                  </div>
+                ))
+              ) : (
+                <Card className="border-dashed">
+                  <CardContent className="text-muted-foreground py-10 text-center text-sm">
+                    {t("pages.agent.tools.empty")}
+                  </CardContent>
+                </Card>
+              )}
+            </section>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function ToolStatusBadge({ status }: { status: ToolSupportItem["status"] }) {
+  const { t } = useTranslation()
+
+  return (
+    <span
+      className={cn(
+        "shrink-0 rounded-md px-2 py-1 text-[11px] font-semibold",
+        status === "enabled" && "bg-emerald-100 text-emerald-700",
+        status === "blocked" && "bg-amber-100 text-amber-700",
+        status === "disabled" && "bg-muted text-muted-foreground",
+      )}
+    >
+      {t(`pages.agent.tools.status.${status}`)}
+    </span>
+  )
+}
diff --git a/web/frontend/src/components/ui/alert-dialog.tsx b/web/frontend/src/components/ui/alert-dialog.tsx
new file mode 100644
index 000000000..d20de09a3
--- /dev/null
+++ b/web/frontend/src/components/ui/alert-dialog.tsx
@@ -0,0 +1,197 @@
+import * as React from "react"
+import { AlertDialog as AlertDialogPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+
+function AlertDialog({
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Root>) {
+  return <AlertDialogPrimitive.Root data-slot="alert-dialog" {...props} />
+}
+
+function AlertDialogTrigger({
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Trigger>) {
+  return (
+    <AlertDialogPrimitive.Trigger data-slot="alert-dialog-trigger" {...props} />
+  )
+}
+
+function AlertDialogPortal({
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Portal>) {
+  return (
+    <AlertDialogPrimitive.Portal data-slot="alert-dialog-portal" {...props} />
+  )
+}
+
+function AlertDialogOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Overlay>) {
+  return (
+    <AlertDialogPrimitive.Overlay
+      data-slot="alert-dialog-overlay"
+      className={cn(
+        "fixed inset-0 z-50 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogContent({
+  className,
+  size = "default",
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Content> & {
+  size?: "default" | "sm"
+}) {
+  return (
+    <AlertDialogPortal>
+      <AlertDialogOverlay />
+      <AlertDialogPrimitive.Content
+        data-slot="alert-dialog-content"
+        data-size={size}
+        className={cn(
+          "group/alert-dialog-content fixed top-1/2 left-1/2 z-50 grid w-full -translate-x-1/2 -translate-y-1/2 gap-6 rounded-xl bg-background p-6 ring-1 ring-foreground/10 duration-100 outline-none data-[size=default]:max-w-xs data-[size=sm]:max-w-xs data-[size=default]:sm:max-w-lg data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+          className
+        )}
+        {...props}
+      />
+    </AlertDialogPortal>
+  )
+}
+
+function AlertDialogHeader({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-dialog-header"
+      className={cn(
+        "grid grid-rows-[auto_1fr] place-items-center gap-1.5 text-center has-data-[slot=alert-dialog-media]:grid-rows-[auto_auto_1fr] has-data-[slot=alert-dialog-media]:gap-x-6 sm:group-data-[size=default]/alert-dialog-content:place-items-start sm:group-data-[size=default]/alert-dialog-content:text-left sm:group-data-[size=default]/alert-dialog-content:has-data-[slot=alert-dialog-media]:grid-rows-[auto_1fr]",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogFooter({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-dialog-footer"
+      className={cn(
+        "flex flex-col-reverse gap-2 group-data-[size=sm]/alert-dialog-content:grid group-data-[size=sm]/alert-dialog-content:grid-cols-2 sm:flex-row sm:justify-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogMedia({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="alert-dialog-media"
+      className={cn(
+        "mb-2 inline-flex size-16 items-center justify-center rounded-md bg-muted sm:group-data-[size=default]/alert-dialog-content:row-span-2 *:[svg:not([class*='size-'])]:size-8",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Title>) {
+  return (
+    <AlertDialogPrimitive.Title
+      data-slot="alert-dialog-title"
+      className={cn(
+        "text-lg font-medium sm:group-data-[size=default]/alert-dialog-content:group-has-data-[slot=alert-dialog-media]/alert-dialog-content:col-start-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Description>) {
+  return (
+    <AlertDialogPrimitive.Description
+      data-slot="alert-dialog-description"
+      className={cn(
+        "text-sm text-balance text-muted-foreground md:text-pretty *:[a]:underline *:[a]:underline-offset-3 *:[a]:hover:text-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function AlertDialogAction({
+  className,
+  variant = "default",
+  size = "default",
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Action> &
+  Pick<React.ComponentProps<typeof Button>, "variant" | "size">) {
+  return (
+    <Button variant={variant} size={size} asChild>
+      <AlertDialogPrimitive.Action
+        data-slot="alert-dialog-action"
+        className={cn(className)}
+        {...props}
+      />
+    </Button>
+  )
+}
+
+function AlertDialogCancel({
+  className,
+  variant = "outline",
+  size = "default",
+  ...props
+}: React.ComponentProps<typeof AlertDialogPrimitive.Cancel> &
+  Pick<React.ComponentProps<typeof Button>, "variant" | "size">) {
+  return (
+    <Button variant={variant} size={size} asChild>
+      <AlertDialogPrimitive.Cancel
+        data-slot="alert-dialog-cancel"
+        className={cn(className)}
+        {...props}
+      />
+    </Button>
+  )
+}
+
+export {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogMedia,
+  AlertDialogOverlay,
+  AlertDialogPortal,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+}
diff --git a/web/frontend/src/components/ui/button.tsx b/web/frontend/src/components/ui/button.tsx
new file mode 100644
index 000000000..b9b702292
--- /dev/null
+++ b/web/frontend/src/components/ui/button.tsx
@@ -0,0 +1,67 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { Slot } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+const buttonVariants = cva(
+  "group/button inline-flex shrink-0 items-center justify-center rounded-md border border-transparent bg-clip-padding text-sm font-medium whitespace-nowrap transition-all outline-none select-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/80",
+        outline:
+          "border-border bg-background shadow-xs hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80 aria-expanded:bg-secondary aria-expanded:text-secondary-foreground",
+        ghost:
+          "hover:bg-muted hover:text-foreground aria-expanded:bg-muted aria-expanded:text-foreground dark:hover:bg-muted/50",
+        destructive:
+          "bg-destructive/10 text-destructive hover:bg-destructive/20 focus-visible:border-destructive/40 focus-visible:ring-destructive/20 dark:bg-destructive/20 dark:hover:bg-destructive/30 dark:focus-visible:ring-destructive/40",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default:
+          "h-9 gap-1.5 px-2.5 in-data-[slot=button-group]:rounded-md has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        xs: "h-6 gap-1 rounded-[min(var(--radius-md),8px)] px-2 text-xs in-data-[slot=button-group]:rounded-md has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
+        sm: "h-8 gap-1 rounded-[min(var(--radius-md),10px)] px-2.5 in-data-[slot=button-group]:rounded-md has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5",
+        lg: "h-10 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3",
+        icon: "size-9",
+        "icon-xs":
+          "size-6 rounded-[min(var(--radius-md),8px)] in-data-[slot=button-group]:rounded-md [&_svg:not([class*='size-'])]:size-3",
+        "icon-sm":
+          "size-8 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-md",
+        "icon-lg": "size-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function Button({
+  className,
+  variant = "default",
+  size = "default",
+  asChild = false,
+  ...props
+}: React.ComponentProps<"button"> &
+  VariantProps<typeof buttonVariants> & {
+    asChild?: boolean
+  }) {
+  const Comp = asChild ? Slot.Root : "button"
+
+  return (
+    <Comp
+      data-slot="button"
+      data-variant={variant}
+      data-size={size}
+      className={cn(buttonVariants({ variant, size, className }))}
+      {...props}
+    />
+  )
+}
+
+export { Button, buttonVariants }
diff --git a/web/frontend/src/components/ui/card.tsx b/web/frontend/src/components/ui/card.tsx
new file mode 100644
index 000000000..13610b23d
--- /dev/null
+++ b/web/frontend/src/components/ui/card.tsx
@@ -0,0 +1,103 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Card({
+  className,
+  size = "default",
+  ...props
+}: React.ComponentProps<"div"> & { size?: "default" | "sm" }) {
+  return (
+    <div
+      data-slot="card"
+      data-size={size}
+      className={cn(
+        "group/card flex flex-col gap-6 overflow-hidden rounded-xl bg-card py-6 text-sm text-card-foreground shadow-xs ring-1 ring-foreground/10 has-[>img:first-child]:pt-0 data-[size=sm]:gap-4 data-[size=sm]:py-4 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-6 group-data-[size=sm]/card:px-4 has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-6 group-data-[size=sm]/card:[.border-b]:pb-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn(
+        "text-base leading-normal font-medium group-data-[size=sm]/card:text-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn(
+        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-6 group-data-[size=sm]/card:px-4", className)}
+      {...props}
+    />
+  )
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn(
+        "flex items-center rounded-b-xl px-6 group-data-[size=sm]/card:px-4 [.border-t]:pt-6 group-data-[size=sm]/card:[.border-t]:pt-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardAction,
+  CardDescription,
+  CardContent,
+}
diff --git a/web/frontend/src/components/ui/collapsible.tsx b/web/frontend/src/components/ui/collapsible.tsx
new file mode 100644
index 000000000..63fc8eff3
--- /dev/null
+++ b/web/frontend/src/components/ui/collapsible.tsx
@@ -0,0 +1,31 @@
+import { Collapsible as CollapsiblePrimitive } from "radix-ui"
+
+function Collapsible({
+  ...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.Root>) {
+  return <CollapsiblePrimitive.Root data-slot="collapsible" {...props} />
+}
+
+function CollapsibleTrigger({
+  ...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleTrigger>) {
+  return (
+    <CollapsiblePrimitive.CollapsibleTrigger
+      data-slot="collapsible-trigger"
+      {...props}
+    />
+  )
+}
+
+function CollapsibleContent({
+  ...props
+}: React.ComponentProps<typeof CollapsiblePrimitive.CollapsibleContent>) {
+  return (
+    <CollapsiblePrimitive.CollapsibleContent
+      data-slot="collapsible-content"
+      {...props}
+    />
+  )
+}
+
+export { Collapsible, CollapsibleTrigger, CollapsibleContent }
diff --git a/web/frontend/src/components/ui/dropdown-menu.tsx b/web/frontend/src/components/ui/dropdown-menu.tsx
new file mode 100644
index 000000000..566e2c861
--- /dev/null
+++ b/web/frontend/src/components/ui/dropdown-menu.tsx
@@ -0,0 +1,269 @@
+"use client"
+
+import * as React from "react"
+import { DropdownMenu as DropdownMenuPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+import { IconCheck, IconChevronRight } from "@tabler/icons-react"
+
+function DropdownMenu({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Root>) {
+  return <DropdownMenuPrimitive.Root data-slot="dropdown-menu" {...props} />
+}
+
+function DropdownMenuPortal({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>) {
+  return (
+    <DropdownMenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />
+  )
+}
+
+function DropdownMenuTrigger({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>) {
+  return (
+    <DropdownMenuPrimitive.Trigger
+      data-slot="dropdown-menu-trigger"
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuContent({
+  className,
+  align = "start",
+  sideOffset = 4,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+  return (
+    <DropdownMenuPrimitive.Portal>
+      <DropdownMenuPrimitive.Content
+        data-slot="dropdown-menu-content"
+        sideOffset={sideOffset}
+        align={align}
+        className={cn("z-50 max-h-(--radix-dropdown-menu-content-available-height) w-(--radix-dropdown-menu-trigger-width) min-w-32 origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md bg-popover p-1 text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:overflow-hidden data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className )}
+        {...props}
+      />
+    </DropdownMenuPrimitive.Portal>
+  )
+}
+
+function DropdownMenuGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Group>) {
+  return (
+    <DropdownMenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />
+  )
+}
+
+function DropdownMenuItem({
+  className,
+  inset,
+  variant = "default",
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+  inset?: boolean
+  variant?: "default" | "destructive"
+}) {
+  return (
+    <DropdownMenuPrimitive.Item
+      data-slot="dropdown-menu-item"
+      data-inset={inset}
+      data-variant={variant}
+      className={cn(
+        "group/dropdown-menu-item relative flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-8 data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 data-[variant=destructive]:focus:text-destructive dark:data-[variant=destructive]:focus:bg-destructive/20 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 data-[variant=destructive]:*:[svg]:text-destructive",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuCheckboxItem({
+  className,
+  children,
+  checked,
+  inset,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem> & {
+  inset?: boolean
+}) {
+  return (
+    <DropdownMenuPrimitive.CheckboxItem
+      data-slot="dropdown-menu-checkbox-item"
+      data-inset={inset}
+      className={cn(
+        "relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-8 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      checked={checked}
+      {...props}
+    >
+      <span
+        className="pointer-events-none absolute right-2 flex items-center justify-center"
+        data-slot="dropdown-menu-checkbox-item-indicator"
+      >
+        <DropdownMenuPrimitive.ItemIndicator>
+          <IconCheck
+          />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.CheckboxItem>
+  )
+}
+
+function DropdownMenuRadioGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>) {
+  return (
+    <DropdownMenuPrimitive.RadioGroup
+      data-slot="dropdown-menu-radio-group"
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuRadioItem({
+  className,
+  children,
+  inset,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem> & {
+  inset?: boolean
+}) {
+  return (
+    <DropdownMenuPrimitive.RadioItem
+      data-slot="dropdown-menu-radio-item"
+      data-inset={inset}
+      className={cn(
+        "relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground focus:**:text-accent-foreground data-inset:pl-8 data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <span
+        className="pointer-events-none absolute right-2 flex items-center justify-center"
+        data-slot="dropdown-menu-radio-item-indicator"
+      >
+        <DropdownMenuPrimitive.ItemIndicator>
+          <IconCheck
+          />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.RadioItem>
+  )
+}
+
+function DropdownMenuLabel({
+  className,
+  inset,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
+  inset?: boolean
+}) {
+  return (
+    <DropdownMenuPrimitive.Label
+      data-slot="dropdown-menu-label"
+      data-inset={inset}
+      className={cn(
+        "px-2 py-1.5 text-xs font-medium text-muted-foreground data-inset:pl-8",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>) {
+  return (
+    <DropdownMenuPrimitive.Separator
+      data-slot="dropdown-menu-separator"
+      className={cn("-mx-1 my-1 h-px bg-border", className)}
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuShortcut({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="dropdown-menu-shortcut"
+      className={cn(
+        "ml-auto text-xs tracking-widest text-muted-foreground group-focus/dropdown-menu-item:text-accent-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function DropdownMenuSub({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>) {
+  return <DropdownMenuPrimitive.Sub data-slot="dropdown-menu-sub" {...props} />
+}
+
+function DropdownMenuSubTrigger({
+  className,
+  inset,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+  inset?: boolean
+}) {
+  return (
+    <DropdownMenuPrimitive.SubTrigger
+      data-slot="dropdown-menu-sub-trigger"
+      data-inset={inset}
+      className={cn(
+        "flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-inset:pl-8 data-open:bg-accent data-open:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <IconChevronRight className="ml-auto" />
+    </DropdownMenuPrimitive.SubTrigger>
+  )
+}
+
+function DropdownMenuSubContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
+  return (
+    <DropdownMenuPrimitive.SubContent
+      data-slot="dropdown-menu-sub-content"
+      className={cn("z-50 min-w-[96px] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-lg ring-1 ring-foreground/10 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", className )}
+      {...props}
+    />
+  )
+}
+
+export {
+  DropdownMenu,
+  DropdownMenuPortal,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+}
diff --git a/web/frontend/src/components/ui/field.tsx b/web/frontend/src/components/ui/field.tsx
new file mode 100644
index 000000000..7cf58a8b4
--- /dev/null
+++ b/web/frontend/src/components/ui/field.tsx
@@ -0,0 +1,236 @@
+import { useMemo } from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { Label } from "@/components/ui/label"
+import { Separator } from "@/components/ui/separator"
+
+function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
+  return (
+    <fieldset
+      data-slot="field-set"
+      className={cn(
+        "flex flex-col gap-6 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldLegend({
+  className,
+  variant = "legend",
+  ...props
+}: React.ComponentProps<"legend"> & { variant?: "legend" | "label" }) {
+  return (
+    <legend
+      data-slot="field-legend"
+      data-variant={variant}
+      className={cn(
+        "mb-3 font-medium data-[variant=label]:text-sm data-[variant=legend]:text-base",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="field-group"
+      className={cn(
+        "group/field-group @container/field-group flex w-full flex-col gap-7 data-[slot=checkbox-group]:gap-3 *:data-[slot=field-group]:gap-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const fieldVariants = cva(
+  "group/field flex w-full gap-3 data-[invalid=true]:text-destructive",
+  {
+    variants: {
+      orientation: {
+        vertical: "flex-col *:w-full [&>.sr-only]:w-auto",
+        horizontal:
+          "flex-row items-center has-[>[data-slot=field-content]]:items-start *:data-[slot=field-label]:flex-auto has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
+        responsive:
+          "flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:*:data-[slot=field-label]:flex-auto [&>.sr-only]:w-auto @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
+      },
+    },
+    defaultVariants: {
+      orientation: "vertical",
+    },
+  }
+)
+
+function Field({
+  className,
+  orientation = "vertical",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="field"
+      data-orientation={orientation}
+      className={cn(fieldVariants({ orientation }), className)}
+      {...props}
+    />
+  )
+}
+
+function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="field-content"
+      className={cn(
+        "group/field-content flex flex-1 flex-col gap-1 leading-snug",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldLabel({
+  className,
+  ...props
+}: React.ComponentProps<typeof Label>) {
+  return (
+    <Label
+      data-slot="field-label"
+      className={cn(
+        "group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50 has-data-checked:border-primary/30 has-data-checked:bg-primary/5 has-[>[data-slot=field]]:rounded-md has-[>[data-slot=field]]:border *:data-[slot=field]:p-3 dark:has-data-checked:border-primary/20 dark:has-data-checked:bg-primary/10",
+        "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="field-label"
+      className={cn(
+        "flex w-fit items-center gap-2 text-sm leading-snug font-medium group-data-[disabled=true]/field:opacity-50",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
+  return (
+    <p
+      data-slot="field-description"
+      className={cn(
+        "text-left text-sm leading-normal font-normal text-muted-foreground group-has-data-horizontal/field:text-balance [[data-variant=legend]+&]:-mt-1.5",
+        "last:mt-0 nth-last-2:-mt-1",
+        "[&>a]:underline [&>a]:underline-offset-4 [&>a:hover]:text-primary",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldSeparator({
+  children,
+  className,
+  ...props
+}: React.ComponentProps<"div"> & {
+  children?: React.ReactNode
+}) {
+  return (
+    <div
+      data-slot="field-separator"
+      data-content={!!children}
+      className={cn(
+        "relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2",
+        className
+      )}
+      {...props}
+    >
+      <Separator className="absolute inset-0 top-1/2" />
+      {children && (
+        <span
+          className="relative mx-auto block w-fit bg-background px-2 text-muted-foreground"
+          data-slot="field-separator-content"
+        >
+          {children}
+        </span>
+      )}
+    </div>
+  )
+}
+
+function FieldError({
+  className,
+  children,
+  errors,
+  ...props
+}: React.ComponentProps<"div"> & {
+  errors?: Array<{ message?: string } | undefined>
+}) {
+  const content = useMemo(() => {
+    if (children) {
+      return children
+    }
+
+    if (!errors?.length) {
+      return null
+    }
+
+    const uniqueErrors = [
+      ...new Map(errors.map((error) => [error?.message, error])).values(),
+    ]
+
+    if (uniqueErrors?.length == 1) {
+      return uniqueErrors[0]?.message
+    }
+
+    return (
+      <ul className="ml-4 flex list-disc flex-col gap-1">
+        {uniqueErrors.map(
+          (error, index) =>
+            error?.message && <li key={index}>{error.message}</li>
+        )}
+      </ul>
+    )
+  }, [children, errors])
+
+  if (!content) {
+    return null
+  }
+
+  return (
+    <div
+      role="alert"
+      data-slot="field-error"
+      className={cn("text-sm font-normal text-destructive", className)}
+      {...props}
+    >
+      {content}
+    </div>
+  )
+}
+
+export {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLegend,
+  FieldSeparator,
+  FieldSet,
+  FieldContent,
+  FieldTitle,
+}
diff --git a/web/frontend/src/components/ui/input.tsx b/web/frontend/src/components/ui/input.tsx
new file mode 100644
index 000000000..17beb1e93
--- /dev/null
+++ b/web/frontend/src/components/ui/input.tsx
@@ -0,0 +1,19 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        "h-9 w-full min-w-0 rounded-md border border-input bg-transparent px-2.5 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Input }
diff --git a/web/frontend/src/components/ui/label.tsx b/web/frontend/src/components/ui/label.tsx
new file mode 100644
index 000000000..f752f82ba
--- /dev/null
+++ b/web/frontend/src/components/ui/label.tsx
@@ -0,0 +1,22 @@
+import * as React from "react"
+import { Label as LabelPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Label({
+  className,
+  ...props
+}: React.ComponentProps<typeof LabelPrimitive.Root>) {
+  return (
+    <LabelPrimitive.Root
+      data-slot="label"
+      className={cn(
+        "flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Label }
diff --git a/web/frontend/src/components/ui/scroll-area.tsx b/web/frontend/src/components/ui/scroll-area.tsx
new file mode 100644
index 000000000..f49b0a81c
--- /dev/null
+++ b/web/frontend/src/components/ui/scroll-area.tsx
@@ -0,0 +1,53 @@
+import * as React from "react"
+import { ScrollArea as ScrollAreaPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function ScrollArea({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof ScrollAreaPrimitive.Root>) {
+  return (
+    <ScrollAreaPrimitive.Root
+      data-slot="scroll-area"
+      className={cn("relative", className)}
+      {...props}
+    >
+      <ScrollAreaPrimitive.Viewport
+        data-slot="scroll-area-viewport"
+        className="size-full rounded-[inherit] transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-1"
+      >
+        {children}
+      </ScrollAreaPrimitive.Viewport>
+      <ScrollBar />
+      <ScrollAreaPrimitive.Corner />
+    </ScrollAreaPrimitive.Root>
+  )
+}
+
+function ScrollBar({
+  className,
+  orientation = "vertical",
+  ...props
+}: React.ComponentProps<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>) {
+  return (
+    <ScrollAreaPrimitive.ScrollAreaScrollbar
+      data-slot="scroll-area-scrollbar"
+      data-orientation={orientation}
+      orientation={orientation}
+      className={cn(
+        "flex touch-none p-px transition-colors select-none data-horizontal:h-2.5 data-horizontal:flex-col data-horizontal:border-t data-horizontal:border-t-transparent data-vertical:h-full data-vertical:w-2.5 data-vertical:border-l data-vertical:border-l-transparent",
+        className
+      )}
+      {...props}
+    >
+      <ScrollAreaPrimitive.ScrollAreaThumb
+        data-slot="scroll-area-thumb"
+        className="relative flex-1 rounded-full bg-border"
+      />
+    </ScrollAreaPrimitive.ScrollAreaScrollbar>
+  )
+}
+
+export { ScrollArea, ScrollBar }
diff --git a/web/frontend/src/components/ui/select.tsx b/web/frontend/src/components/ui/select.tsx
new file mode 100644
index 000000000..86427f351
--- /dev/null
+++ b/web/frontend/src/components/ui/select.tsx
@@ -0,0 +1,190 @@
+import * as React from "react"
+import { Select as SelectPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+import { IconSelector, IconCheck, IconChevronUp, IconChevronDown } from "@tabler/icons-react"
+
+function Select({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Root>) {
+  return <SelectPrimitive.Root data-slot="select" {...props} />
+}
+
+function SelectGroup({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Group>) {
+  return (
+    <SelectPrimitive.Group
+      data-slot="select-group"
+      className={cn("scroll-my-1 p-1", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectValue({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Value>) {
+  return <SelectPrimitive.Value data-slot="select-value" {...props} />
+}
+
+function SelectTrigger({
+  className,
+  size = "default",
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
+  size?: "sm" | "default"
+}) {
+  return (
+    <SelectPrimitive.Trigger
+      data-slot="select-trigger"
+      data-size={size}
+      className={cn(
+        "flex w-fit items-center justify-between gap-1.5 rounded-md border border-input bg-transparent py-2 pr-2 pl-2.5 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-placeholder:text-muted-foreground data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-1.5 dark:bg-input/30 dark:hover:bg-input/50 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <SelectPrimitive.Icon asChild>
+        <IconSelector className="pointer-events-none size-4 text-muted-foreground" />
+      </SelectPrimitive.Icon>
+    </SelectPrimitive.Trigger>
+  )
+}
+
+function SelectContent({
+  className,
+  children,
+  position = "item-aligned",
+  align = "center",
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Content>) {
+  return (
+    <SelectPrimitive.Portal>
+      <SelectPrimitive.Content
+        data-slot="select-content"
+        data-align-trigger={position === "item-aligned"}
+        className={cn("relative z-50 max-h-(--radix-select-content-available-height) min-w-36 origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md bg-popover text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[align-trigger=true]:animate-none data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95", position ==="popper"&&"data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1", className )}
+        position={position}
+        align={align}
+        {...props}
+      >
+        <SelectScrollUpButton />
+        <SelectPrimitive.Viewport
+          data-position={position}
+          className={cn(
+            "data-[position=popper]:h-(--radix-select-trigger-height) data-[position=popper]:w-full data-[position=popper]:min-w-(--radix-select-trigger-width)",
+            position === "popper" && ""
+          )}
+        >
+          {children}
+        </SelectPrimitive.Viewport>
+        <SelectScrollDownButton />
+      </SelectPrimitive.Content>
+    </SelectPrimitive.Portal>
+  )
+}
+
+function SelectLabel({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Label>) {
+  return (
+    <SelectPrimitive.Label
+      data-slot="select-label"
+      className={cn("px-2 py-1.5 text-xs text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Item>) {
+  return (
+    <SelectPrimitive.Item
+      data-slot="select-item"
+      className={cn(
+        "relative flex w-full cursor-default items-center gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none focus:bg-accent focus:text-accent-foreground not-data-[variant=destructive]:focus:**:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        className
+      )}
+      {...props}
+    >
+      <span className="pointer-events-none absolute right-2 flex size-4 items-center justify-center">
+        <SelectPrimitive.ItemIndicator>
+          <IconCheck className="pointer-events-none" />
+        </SelectPrimitive.ItemIndicator>
+      </span>
+      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+    </SelectPrimitive.Item>
+  )
+}
+
+function SelectSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Separator>) {
+  return (
+    <SelectPrimitive.Separator
+      data-slot="select-separator"
+      className={cn("pointer-events-none -mx-1 my-1 h-px bg-border", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectScrollUpButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>) {
+  return (
+    <SelectPrimitive.ScrollUpButton
+      data-slot="select-scroll-up-button"
+      className={cn(
+        "z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <IconChevronUp
+      />
+    </SelectPrimitive.ScrollUpButton>
+  )
+}
+
+function SelectScrollDownButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>) {
+  return (
+    <SelectPrimitive.ScrollDownButton
+      data-slot="select-scroll-down-button"
+      className={cn(
+        "z-10 flex cursor-default items-center justify-center bg-popover py-1 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <IconChevronDown
+      />
+    </SelectPrimitive.ScrollDownButton>
+  )
+}
+
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+}
diff --git a/web/frontend/src/components/ui/separator.tsx b/web/frontend/src/components/ui/separator.tsx
new file mode 100644
index 000000000..d4570908d
--- /dev/null
+++ b/web/frontend/src/components/ui/separator.tsx
@@ -0,0 +1,28 @@
+"use client"
+
+import * as React from "react"
+import { Separator as SeparatorPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Separator({
+  className,
+  orientation = "horizontal",
+  decorative = true,
+  ...props
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>) {
+  return (
+    <SeparatorPrimitive.Root
+      data-slot="separator"
+      decorative={decorative}
+      orientation={orientation}
+      className={cn(
+        "shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Separator }
diff --git a/web/frontend/src/components/ui/sheet.tsx b/web/frontend/src/components/ui/sheet.tsx
new file mode 100644
index 000000000..a438ca69d
--- /dev/null
+++ b/web/frontend/src/components/ui/sheet.tsx
@@ -0,0 +1,144 @@
+"use client"
+
+import * as React from "react"
+import { Dialog as SheetPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { IconX } from "@tabler/icons-react"
+
+function Sheet({ ...props }: React.ComponentProps<typeof SheetPrimitive.Root>) {
+  return <SheetPrimitive.Root data-slot="sheet" {...props} />
+}
+
+function SheetTrigger({
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Trigger>) {
+  return <SheetPrimitive.Trigger data-slot="sheet-trigger" {...props} />
+}
+
+function SheetClose({
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Close>) {
+  return <SheetPrimitive.Close data-slot="sheet-close" {...props} />
+}
+
+function SheetPortal({
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Portal>) {
+  return <SheetPrimitive.Portal data-slot="sheet-portal" {...props} />
+}
+
+function SheetOverlay({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Overlay>) {
+  return (
+    <SheetPrimitive.Overlay
+      data-slot="sheet-overlay"
+      className={cn(
+        "fixed inset-0 z-50 bg-black/10 duration-100 data-ending-style:opacity-0 data-starting-style:opacity-0 supports-backdrop-filter:backdrop-blur-xs data-open:animate-in data-open:fade-in-0 data-closed:animate-out data-closed:fade-out-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SheetContent({
+  className,
+  children,
+  side = "right",
+  showCloseButton = true,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Content> & {
+  side?: "top" | "right" | "bottom" | "left"
+  showCloseButton?: boolean
+}) {
+  return (
+    <SheetPortal>
+      <SheetOverlay />
+      <SheetPrimitive.Content
+        data-slot="sheet-content"
+        data-side={side}
+        className={cn(
+          "fixed z-50 flex flex-col gap-4 bg-background bg-clip-padding text-sm shadow-lg transition duration-200 ease-in-out data-[side=bottom]:inset-x-0 data-[side=bottom]:bottom-0 data-[side=bottom]:h-auto data-[side=bottom]:border-t data-[side=left]:inset-y-0 data-[side=left]:left-0 data-[side=left]:h-full data-[side=left]:w-3/4 data-[side=left]:border-r data-[side=right]:inset-y-0 data-[side=right]:right-0 data-[side=right]:h-full data-[side=right]:w-3/4 data-[side=right]:border-l data-[side=top]:inset-x-0 data-[side=top]:top-0 data-[side=top]:h-auto data-[side=top]:border-b data-[side=left]:sm:max-w-sm data-[side=right]:sm:max-w-sm data-open:animate-in data-open:fade-in-0 data-[side=bottom]:data-open:slide-in-from-bottom-10 data-[side=left]:data-open:slide-in-from-left-10 data-[side=right]:data-open:slide-in-from-right-10 data-[side=top]:data-open:slide-in-from-top-10 data-closed:animate-out data-closed:fade-out-0 data-[side=bottom]:data-closed:slide-out-to-bottom-10 data-[side=left]:data-closed:slide-out-to-left-10 data-[side=right]:data-closed:slide-out-to-right-10 data-[side=top]:data-closed:slide-out-to-top-10",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        {showCloseButton && (
+          <SheetPrimitive.Close data-slot="sheet-close" asChild>
+            <Button
+              variant="ghost"
+              className="absolute top-4 right-4"
+              size="icon-sm"
+            >
+              <IconX
+              />
+              <span className="sr-only">Close</span>
+            </Button>
+          </SheetPrimitive.Close>
+        )}
+      </SheetPrimitive.Content>
+    </SheetPortal>
+  )
+}
+
+function SheetHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sheet-header"
+      className={cn("flex flex-col gap-1.5 p-4", className)}
+      {...props}
+    />
+  )
+}
+
+function SheetFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sheet-footer"
+      className={cn("mt-auto flex flex-col gap-2 p-4", className)}
+      {...props}
+    />
+  )
+}
+
+function SheetTitle({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Title>) {
+  return (
+    <SheetPrimitive.Title
+      data-slot="sheet-title"
+      className={cn("font-medium text-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function SheetDescription({
+  className,
+  ...props
+}: React.ComponentProps<typeof SheetPrimitive.Description>) {
+  return (
+    <SheetPrimitive.Description
+      data-slot="sheet-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Sheet,
+  SheetTrigger,
+  SheetClose,
+  SheetContent,
+  SheetHeader,
+  SheetFooter,
+  SheetTitle,
+  SheetDescription,
+}
diff --git a/web/frontend/src/components/ui/sidebar.tsx b/web/frontend/src/components/ui/sidebar.tsx
new file mode 100644
index 000000000..06dab36ef
--- /dev/null
+++ b/web/frontend/src/components/ui/sidebar.tsx
@@ -0,0 +1,700 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { Slot } from "radix-ui"
+
+import { useIsMobile } from "@/hooks/use-mobile"
+import { cn } from "@/lib/utils"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+import { Separator } from "@/components/ui/separator"
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from "@/components/ui/sheet"
+import { Skeleton } from "@/components/ui/skeleton"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
+import { IconLayoutSidebar } from "@tabler/icons-react"
+
+const SIDEBAR_COOKIE_NAME = "sidebar_state"
+const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7
+const SIDEBAR_WIDTH = "16rem"
+const SIDEBAR_WIDTH_MOBILE = "18rem"
+const SIDEBAR_WIDTH_ICON = "3rem"
+const SIDEBAR_KEYBOARD_SHORTCUT = "b"
+
+type SidebarContextProps = {
+  state: "expanded" | "collapsed"
+  open: boolean
+  setOpen: (open: boolean) => void
+  openMobile: boolean
+  setOpenMobile: (open: boolean) => void
+  isMobile: boolean
+  toggleSidebar: () => void
+}
+
+const SidebarContext = React.createContext<SidebarContextProps | null>(null)
+
+function useSidebar() {
+  const context = React.useContext(SidebarContext)
+  if (!context) {
+    throw new Error("useSidebar must be used within a SidebarProvider.")
+  }
+
+  return context
+}
+
+function SidebarProvider({
+  defaultOpen = true,
+  open: openProp,
+  onOpenChange: setOpenProp,
+  className,
+  style,
+  children,
+  ...props
+}: React.ComponentProps<"div"> & {
+  defaultOpen?: boolean
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+}) {
+  const isMobile = useIsMobile()
+  const [openMobile, setOpenMobile] = React.useState(false)
+
+  // This is the internal state of the sidebar.
+  // We use openProp and setOpenProp for control from outside the component.
+  const [_open, _setOpen] = React.useState(defaultOpen)
+  const open = openProp ?? _open
+  const setOpen = React.useCallback(
+    (value: boolean | ((value: boolean) => boolean)) => {
+      const openState = typeof value === "function" ? value(open) : value
+      if (setOpenProp) {
+        setOpenProp(openState)
+      } else {
+        _setOpen(openState)
+      }
+
+      // This sets the cookie to keep the sidebar state.
+      document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`
+    },
+    [setOpenProp, open]
+  )
+
+  // Helper to toggle the sidebar.
+  const toggleSidebar = React.useCallback(() => {
+    return isMobile ? setOpenMobile((open) => !open) : setOpen((open) => !open)
+  }, [isMobile, setOpen, setOpenMobile])
+
+  // Adds a keyboard shortcut to toggle the sidebar.
+  React.useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (
+        event.key === SIDEBAR_KEYBOARD_SHORTCUT &&
+        (event.metaKey || event.ctrlKey)
+      ) {
+        event.preventDefault()
+        toggleSidebar()
+      }
+    }
+
+    window.addEventListener("keydown", handleKeyDown)
+    return () => window.removeEventListener("keydown", handleKeyDown)
+  }, [toggleSidebar])
+
+  // We add a state so that we can do data-state="expanded" or "collapsed".
+  // This makes it easier to style the sidebar with Tailwind classes.
+  const state = open ? "expanded" : "collapsed"
+
+  const contextValue = React.useMemo<SidebarContextProps>(
+    () => ({
+      state,
+      open,
+      setOpen,
+      isMobile,
+      openMobile,
+      setOpenMobile,
+      toggleSidebar,
+    }),
+    [state, open, setOpen, isMobile, openMobile, setOpenMobile, toggleSidebar]
+  )
+
+  return (
+    <SidebarContext.Provider value={contextValue}>
+      <div
+        data-slot="sidebar-wrapper"
+        style={
+          {
+            "--sidebar-width": SIDEBAR_WIDTH,
+            "--sidebar-width-icon": SIDEBAR_WIDTH_ICON,
+            ...style,
+          } as React.CSSProperties
+        }
+        className={cn(
+          "group/sidebar-wrapper flex min-h-svh w-full has-data-[variant=inset]:bg-sidebar",
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    </SidebarContext.Provider>
+  )
+}
+
+function Sidebar({
+  side = "left",
+  variant = "sidebar",
+  collapsible = "offcanvas",
+  className,
+  children,
+  dir,
+  ...props
+}: React.ComponentProps<"div"> & {
+  side?: "left" | "right"
+  variant?: "sidebar" | "floating" | "inset"
+  collapsible?: "offcanvas" | "icon" | "none"
+}) {
+  const { isMobile, state, openMobile, setOpenMobile } = useSidebar()
+
+  if (collapsible === "none") {
+    return (
+      <div
+        data-slot="sidebar"
+        className={cn(
+          "flex h-full w-(--sidebar-width) flex-col bg-sidebar text-sidebar-foreground",
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    )
+  }
+
+  if (isMobile) {
+    return (
+      <Sheet open={openMobile} onOpenChange={setOpenMobile} {...props}>
+        <SheetContent
+          dir={dir}
+          data-sidebar="sidebar"
+          data-slot="sidebar"
+          data-mobile="true"
+          className="w-(--sidebar-width) bg-sidebar p-0 text-sidebar-foreground [&>button]:hidden"
+          style={
+            {
+              "--sidebar-width": SIDEBAR_WIDTH_MOBILE,
+            } as React.CSSProperties
+          }
+          side={side}
+        >
+          <SheetHeader className="sr-only">
+            <SheetTitle>Sidebar</SheetTitle>
+            <SheetDescription>Displays the mobile sidebar.</SheetDescription>
+          </SheetHeader>
+          <div className="flex h-full w-full flex-col">{children}</div>
+        </SheetContent>
+      </Sheet>
+    )
+  }
+
+  return (
+    <div
+      className="group peer hidden text-sidebar-foreground md:block"
+      data-state={state}
+      data-collapsible={state === "collapsed" ? collapsible : ""}
+      data-variant={variant}
+      data-side={side}
+      data-slot="sidebar"
+    >
+      {/* This is what handles the sidebar gap on desktop */}
+      <div
+        data-slot="sidebar-gap"
+        className={cn(
+          "relative w-(--sidebar-width) bg-transparent transition-[width] duration-200 ease-linear",
+          "group-data-[collapsible=offcanvas]:w-0",
+          "group-data-[side=right]:rotate-180",
+          variant === "floating" || variant === "inset"
+            ? "group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4)))]"
+            : "group-data-[collapsible=icon]:w-(--sidebar-width-icon)"
+        )}
+      />
+      <div
+        data-slot="sidebar-container"
+        data-side={side}
+        className={cn(
+          "fixed inset-y-0 z-10 hidden h-svh w-(--sidebar-width) transition-[left,right,width] duration-200 ease-linear data-[side=left]:left-0 data-[side=left]:group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)] data-[side=right]:right-0 data-[side=right]:group-data-[collapsible=offcanvas]:right-[calc(var(--sidebar-width)*-1)] md:flex",
+          // Adjust the padding for floating and inset variants.
+          variant === "floating" || variant === "inset"
+            ? "p-2 group-data-[collapsible=icon]:w-[calc(var(--sidebar-width-icon)+(--spacing(4))+2px)]"
+            : "group-data-[collapsible=icon]:w-(--sidebar-width-icon)",
+          className
+        )}
+        {...props}
+      >
+        <div
+          data-sidebar="sidebar"
+          data-slot="sidebar-inner"
+          className="flex size-full flex-col bg-sidebar group-data-[variant=floating]:rounded-lg group-data-[variant=floating]:shadow-sm group-data-[variant=floating]:ring-1 group-data-[variant=floating]:ring-sidebar-border"
+        >
+          {children}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+function SidebarTrigger({
+  className,
+  onClick,
+  ...props
+}: React.ComponentProps<typeof Button>) {
+  const { toggleSidebar } = useSidebar()
+
+  return (
+    <Button
+      data-sidebar="trigger"
+      data-slot="sidebar-trigger"
+      variant="ghost"
+      size="icon-sm"
+      className={cn(className)}
+      onClick={(event) => {
+        onClick?.(event)
+        toggleSidebar()
+      }}
+      {...props}
+    >
+      <IconLayoutSidebar />
+      <span className="sr-only">Toggle Sidebar</span>
+    </Button>
+  )
+}
+
+function SidebarRail({ className, ...props }: React.ComponentProps<"button">) {
+  const { toggleSidebar } = useSidebar()
+
+  return (
+    <button
+      data-sidebar="rail"
+      data-slot="sidebar-rail"
+      aria-label="Toggle Sidebar"
+      tabIndex={-1}
+      onClick={toggleSidebar}
+      title="Toggle Sidebar"
+      className={cn(
+        "absolute inset-y-0 z-20 hidden w-4 transition-all ease-linear group-data-[side=left]:-right-4 group-data-[side=right]:left-0 after:absolute after:inset-y-0 after:start-1/2 after:w-[2px] hover:after:bg-sidebar-border sm:flex ltr:-translate-x-1/2 rtl:-translate-x-1/2",
+        "in-data-[side=left]:cursor-w-resize in-data-[side=right]:cursor-e-resize",
+        "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize",
+        "group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full hover:group-data-[collapsible=offcanvas]:bg-sidebar",
+        "[[data-side=left][data-collapsible=offcanvas]_&]:-right-2",
+        "[[data-side=right][data-collapsible=offcanvas]_&]:-left-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarInset({ className, ...props }: React.ComponentProps<"main">) {
+  return (
+    <main
+      data-slot="sidebar-inset"
+      className={cn(
+        "relative flex w-full flex-1 flex-col bg-background md:peer-data-[variant=inset]:m-2 md:peer-data-[variant=inset]:ml-0 md:peer-data-[variant=inset]:rounded-xl md:peer-data-[variant=inset]:shadow-sm md:peer-data-[variant=inset]:peer-data-[state=collapsed]:ml-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarInput({
+  className,
+  ...props
+}: React.ComponentProps<typeof Input>) {
+  return (
+    <Input
+      data-slot="sidebar-input"
+      data-sidebar="input"
+      className={cn("h-8 w-full bg-background shadow-none", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-header"
+      data-sidebar="header"
+      className={cn("flex flex-col gap-2 p-2", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-footer"
+      data-sidebar="footer"
+      className={cn("flex flex-col gap-2 p-2", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof Separator>) {
+  return (
+    <Separator
+      data-slot="sidebar-separator"
+      data-sidebar="separator"
+      className={cn("mx-2 w-auto bg-sidebar-border", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-content"
+      data-sidebar="content"
+      className={cn(
+        "no-scrollbar flex min-h-0 flex-1 flex-col gap-2 overflow-auto group-data-[collapsible=icon]:overflow-hidden",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-group"
+      data-sidebar="group"
+      className={cn("relative flex w-full min-w-0 flex-col p-2", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarGroupLabel({
+  className,
+  asChild = false,
+  ...props
+}: React.ComponentProps<"div"> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot.Root : "div"
+
+  return (
+    <Comp
+      data-slot="sidebar-group-label"
+      data-sidebar="group-label"
+      className={cn(
+        "flex h-8 shrink-0 items-center rounded-md px-2 text-xs font-medium text-sidebar-foreground/70 ring-sidebar-ring outline-hidden transition-[margin,opacity] duration-200 ease-linear group-data-[collapsible=icon]:-mt-8 group-data-[collapsible=icon]:opacity-0 focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarGroupAction({
+  className,
+  asChild = false,
+  ...props
+}: React.ComponentProps<"button"> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot.Root : "button"
+
+  return (
+    <Comp
+      data-slot="sidebar-group-action"
+      data-sidebar="group-action"
+      className={cn(
+        "absolute top-3.5 right-3 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground ring-sidebar-ring outline-hidden transition-transform group-data-[collapsible=icon]:hidden after:absolute after:-inset-2 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 md:after:hidden [&>svg]:size-4 [&>svg]:shrink-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarGroupContent({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-group-content"
+      data-sidebar="group-content"
+      className={cn("w-full text-sm", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenu({ className, ...props }: React.ComponentProps<"ul">) {
+  return (
+    <ul
+      data-slot="sidebar-menu"
+      data-sidebar="menu"
+      className={cn("flex w-full min-w-0 flex-col gap-1", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="sidebar-menu-item"
+      data-sidebar="menu-item"
+      className={cn("group/menu-item relative", className)}
+      {...props}
+    />
+  )
+}
+
+const sidebarMenuButtonVariants = cva(
+  "peer/menu-button group/menu-button flex w-full items-center gap-2 overflow-hidden rounded-md p-2 text-left text-sm ring-sidebar-ring outline-hidden transition-[width,height,padding] group-has-data-[sidebar=menu-action]/menu-item:pr-8 group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground data-active:bg-sidebar-accent data-active:font-medium data-active:text-sidebar-accent-foreground [&_svg]:size-4 [&_svg]:shrink-0 [&>span:last-child]:truncate",
+  {
+    variants: {
+      variant: {
+        default: "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
+        outline:
+          "bg-background shadow-[0_0_0_1px_hsl(var(--sidebar-border))] hover:bg-sidebar-accent hover:text-sidebar-accent-foreground hover:shadow-[0_0_0_1px_hsl(var(--sidebar-accent))]",
+      },
+      size: {
+        default: "h-8 text-sm",
+        sm: "h-7 text-xs",
+        lg: "h-12 text-sm group-data-[collapsible=icon]:p-0!",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+function SidebarMenuButton({
+  asChild = false,
+  isActive = false,
+  variant = "default",
+  size = "default",
+  tooltip,
+  className,
+  ...props
+}: React.ComponentProps<"button"> & {
+  asChild?: boolean
+  isActive?: boolean
+  tooltip?: string | React.ComponentProps<typeof TooltipContent>
+} & VariantProps<typeof sidebarMenuButtonVariants>) {
+  const Comp = asChild ? Slot.Root : "button"
+  const { isMobile, state } = useSidebar()
+
+  const button = (
+    <Comp
+      data-slot="sidebar-menu-button"
+      data-sidebar="menu-button"
+      data-size={size}
+      data-active={isActive}
+      className={cn(sidebarMenuButtonVariants({ variant, size }), className)}
+      {...props}
+    />
+  )
+
+  if (!tooltip) {
+    return button
+  }
+
+  if (typeof tooltip === "string") {
+    tooltip = {
+      children: tooltip,
+    }
+  }
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{button}</TooltipTrigger>
+      <TooltipContent
+        side="right"
+        align="center"
+        hidden={state !== "collapsed" || isMobile}
+        {...tooltip}
+      />
+    </Tooltip>
+  )
+}
+
+function SidebarMenuAction({
+  className,
+  asChild = false,
+  showOnHover = false,
+  ...props
+}: React.ComponentProps<"button"> & {
+  asChild?: boolean
+  showOnHover?: boolean
+}) {
+  const Comp = asChild ? Slot.Root : "button"
+
+  return (
+    <Comp
+      data-slot="sidebar-menu-action"
+      data-sidebar="menu-action"
+      className={cn(
+        "absolute top-1.5 right-1 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-sidebar-foreground ring-sidebar-ring outline-hidden transition-transform group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 after:absolute after:-inset-2 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 md:after:hidden [&>svg]:size-4 [&>svg]:shrink-0",
+        showOnHover &&
+        "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 peer-data-active/menu-button:text-sidebar-accent-foreground aria-expanded:opacity-100 md:opacity-0",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuBadge({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="sidebar-menu-badge"
+      data-sidebar="menu-badge"
+      className={cn(
+        "pointer-events-none absolute right-1 flex h-5 min-w-5 items-center justify-center rounded-md px-1 text-xs font-medium text-sidebar-foreground tabular-nums select-none group-data-[collapsible=icon]:hidden peer-hover/menu-button:text-sidebar-accent-foreground peer-data-[size=default]/menu-button:top-1.5 peer-data-[size=lg]/menu-button:top-2.5 peer-data-[size=sm]/menu-button:top-1 peer-data-active/menu-button:text-sidebar-accent-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuSkeleton({
+  className,
+  showIcon = false,
+  ...props
+}: React.ComponentProps<"div"> & {
+  showIcon?: boolean
+}) {
+  // Random width between 50 to 90%.
+  const [width] = React.useState(() => {
+    return `${Math.floor(Math.random() * 40) + 50}%`
+  })
+
+  return (
+    <div
+      data-slot="sidebar-menu-skeleton"
+      data-sidebar="menu-skeleton"
+      className={cn("flex h-8 items-center gap-2 rounded-md px-2", className)}
+      {...props}
+    >
+      {showIcon && (
+        <Skeleton
+          className="size-4 rounded-md"
+          data-sidebar="menu-skeleton-icon"
+        />
+      )}
+      <Skeleton
+        className="h-4 max-w-(--skeleton-width) flex-1"
+        data-sidebar="menu-skeleton-text"
+        style={
+          {
+            "--skeleton-width": width,
+          } as React.CSSProperties
+        }
+      />
+    </div>
+  )
+}
+
+function SidebarMenuSub({ className, ...props }: React.ComponentProps<"ul">) {
+  return (
+    <ul
+      data-slot="sidebar-menu-sub"
+      data-sidebar="menu-sub"
+      className={cn(
+        "mx-3.5 flex min-w-0 translate-x-px flex-col gap-1 border-l border-sidebar-border px-2.5 py-0.5 group-data-[collapsible=icon]:hidden",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuSubItem({
+  className,
+  ...props
+}: React.ComponentProps<"li">) {
+  return (
+    <li
+      data-slot="sidebar-menu-sub-item"
+      data-sidebar="menu-sub-item"
+      className={cn("group/menu-sub-item relative", className)}
+      {...props}
+    />
+  )
+}
+
+function SidebarMenuSubButton({
+  asChild = false,
+  size = "md",
+  isActive = false,
+  className,
+  ...props
+}: React.ComponentProps<"a"> & {
+  asChild?: boolean
+  size?: "sm" | "md"
+  isActive?: boolean
+}) {
+  const Comp = asChild ? Slot.Root : "a"
+
+  return (
+    <Comp
+      data-slot="sidebar-menu-sub-button"
+      data-sidebar="menu-sub-button"
+      data-size={size}
+      data-active={isActive}
+      className={cn(
+        "flex h-7 min-w-0 -translate-x-px items-center gap-2 overflow-hidden rounded-md px-2 text-sidebar-foreground ring-sidebar-ring outline-hidden group-data-[collapsible=icon]:hidden hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-[size=md]:text-sm data-[size=sm]:text-xs data-active:bg-sidebar-accent data-active:text-sidebar-accent-foreground [&>span:last-child]:truncate [&>svg]:size-4 [&>svg]:shrink-0 [&>svg]:text-sidebar-accent-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupAction,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarInput,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuAction,
+  SidebarMenuBadge,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSkeleton,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  SidebarProvider,
+  SidebarRail,
+  SidebarSeparator,
+  SidebarTrigger,
+  useSidebar,
+}
diff --git a/web/frontend/src/components/ui/skeleton.tsx b/web/frontend/src/components/ui/skeleton.tsx
new file mode 100644
index 000000000..0118624f6
--- /dev/null
+++ b/web/frontend/src/components/ui/skeleton.tsx
@@ -0,0 +1,13 @@
+import { cn } from "@/lib/utils"
+
+function Skeleton({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="skeleton"
+      className={cn("animate-pulse rounded-md bg-muted", className)}
+      {...props}
+    />
+  )
+}
+
+export { Skeleton }
diff --git a/web/frontend/src/components/ui/switch.tsx b/web/frontend/src/components/ui/switch.tsx
new file mode 100644
index 000000000..df3522f90
--- /dev/null
+++ b/web/frontend/src/components/ui/switch.tsx
@@ -0,0 +1,31 @@
+import * as React from "react"
+import { Switch as SwitchPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Switch({
+  className,
+  size = "default",
+  ...props
+}: React.ComponentProps<typeof SwitchPrimitive.Root> & {
+  size?: "sm" | "default"
+}) {
+  return (
+    <SwitchPrimitive.Root
+      data-slot="switch"
+      data-size={size}
+      className={cn(
+        "peer group/switch relative inline-flex shrink-0 items-center rounded-full border border-transparent shadow-xs transition-all outline-none after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 data-[size=default]:h-[18.4px] data-[size=default]:w-[32px] data-[size=sm]:h-[14px] data-[size=sm]:w-[24px] dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-checked:bg-primary data-unchecked:bg-input dark:data-unchecked:bg-input/80 data-disabled:cursor-not-allowed data-disabled:opacity-50",
+        className
+      )}
+      {...props}
+    >
+      <SwitchPrimitive.Thumb
+        data-slot="switch-thumb"
+        className="pointer-events-none block rounded-full bg-background ring-0 transition-transform group-data-[size=default]/switch:size-4 group-data-[size=sm]/switch:size-3 group-data-[size=default]/switch:data-checked:translate-x-[calc(100%-2px)] group-data-[size=sm]/switch:data-checked:translate-x-[calc(100%-2px)] dark:data-checked:bg-primary-foreground group-data-[size=default]/switch:data-unchecked:translate-x-0 group-data-[size=sm]/switch:data-unchecked:translate-x-0 dark:data-unchecked:bg-foreground"
+      />
+    </SwitchPrimitive.Root>
+  )
+}
+
+export { Switch }
diff --git a/web/frontend/src/components/ui/textarea.tsx b/web/frontend/src/components/ui/textarea.tsx
new file mode 100644
index 000000000..95ed1c44c
--- /dev/null
+++ b/web/frontend/src/components/ui/textarea.tsx
@@ -0,0 +1,18 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
+  return (
+    <textarea
+      data-slot="textarea"
+      className={cn(
+        "flex field-sizing-content min-h-16 w-full rounded-md border border-input bg-transparent px-2.5 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:cursor-not-allowed disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Textarea }
diff --git a/web/frontend/src/components/ui/tooltip.tsx b/web/frontend/src/components/ui/tooltip.tsx
new file mode 100644
index 000000000..757f05b03
--- /dev/null
+++ b/web/frontend/src/components/ui/tooltip.tsx
@@ -0,0 +1,55 @@
+import * as React from "react"
+import { Tooltip as TooltipPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delayDuration={delayDuration}
+      {...props}
+    />
+  )
+}
+
+function Tooltip({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+}
+
+function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content>) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        sideOffset={sideOffset}
+        className={cn(
+          "z-50 w-fit max-w-xs origin-(--radix-tooltip-content-transform-origin) rounded-md bg-foreground px-3 py-1.5 text-xs text-background data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow className="z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground" />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  )
+}
+
+export { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger }
diff --git a/web/frontend/src/features/chat/controller.ts b/web/frontend/src/features/chat/controller.ts
new file mode 100644
index 000000000..5e6eb2229
--- /dev/null
+++ b/web/frontend/src/features/chat/controller.ts
@@ -0,0 +1,459 @@
+import { getDefaultStore } from "jotai"
+import { toast } from "sonner"
+
+import { getPicoToken } from "@/api/pico"
+import {
+  loadSessionMessages,
+  mergeHistoryMessages,
+} from "@/features/chat/history"
+import { type PicoMessage, handlePicoMessage } from "@/features/chat/protocol"
+import {
+  clearStoredSessionId,
+  generateSessionId,
+  readStoredSessionId,
+} from "@/features/chat/state"
+import {
+  invalidateSocket,
+  isCurrentSocket,
+  normalizeWsUrlForBrowser,
+} from "@/features/chat/websocket"
+import i18n from "@/i18n"
+import { getChatState, updateChatStore } from "@/store/chat"
+import { type GatewayState, gatewayAtom } from "@/store/gateway"
+
+const store = getDefaultStore()
+
+let wsRef: WebSocket | null = null
+let isConnecting = false
+let msgIdCounter = 0
+let activeSessionIdRef = getChatState().activeSessionId
+let initialized = false
+let unsubscribeGateway: (() => void) | null = null
+let hydratePromise: Promise<void> | null = null
+let connectionGeneration = 0
+let reconnectTimer: number | null = null
+let reconnectAttempts = 0
+let shouldMaintainConnection = false
+
+function clearReconnectTimer() {
+  if (reconnectTimer !== null) {
+    window.clearTimeout(reconnectTimer)
+    reconnectTimer = null
+  }
+}
+
+function shouldReconnectFor(generation: number, sessionId: string): boolean {
+  return (
+    shouldMaintainConnection &&
+    generation === connectionGeneration &&
+    sessionId === activeSessionIdRef &&
+    store.get(gatewayAtom).status === "running"
+  )
+}
+
+function scheduleReconnect(generation: number, sessionId: string) {
+  if (!shouldReconnectFor(generation, sessionId) || reconnectTimer !== null) {
+    return
+  }
+
+  const delay = Math.min(1000 * 2 ** reconnectAttempts, 5000)
+  reconnectAttempts += 1
+  reconnectTimer = window.setTimeout(() => {
+    reconnectTimer = null
+    if (!shouldReconnectFor(generation, sessionId)) {
+      return
+    }
+    void connectChat()
+  }, delay)
+}
+
+function needsActiveSessionHydration(): boolean {
+  const state = getChatState()
+  const storedSessionId = readStoredSessionId()
+
+  return Boolean(
+    storedSessionId &&
+    storedSessionId === state.activeSessionId &&
+    !state.hasHydratedActiveSession,
+  )
+}
+
+function setActiveSessionId(sessionId: string) {
+  activeSessionIdRef = sessionId
+  updateChatStore({ activeSessionId: sessionId })
+}
+
+function disconnectChatInternal({
+  clearDesiredConnection,
+}: {
+  clearDesiredConnection: boolean
+}) {
+  connectionGeneration += 1
+  clearReconnectTimer()
+
+  if (clearDesiredConnection) {
+    shouldMaintainConnection = false
+  }
+
+  const socket = wsRef
+  wsRef = null
+  isConnecting = false
+
+  invalidateSocket(socket)
+
+  updateChatStore({
+    connectionState: "disconnected",
+    isTyping: false,
+  })
+}
+
+export async function connectChat() {
+  if (
+    store.get(gatewayAtom).status !== "running" ||
+    needsActiveSessionHydration()
+  ) {
+    return
+  }
+
+  if (
+    isConnecting ||
+    (wsRef &&
+      (wsRef.readyState === WebSocket.OPEN ||
+        wsRef.readyState === WebSocket.CONNECTING))
+  ) {
+    return
+  }
+
+  const generation = connectionGeneration + 1
+  connectionGeneration = generation
+  isConnecting = true
+  clearReconnectTimer()
+  updateChatStore({ connectionState: "connecting" })
+
+  try {
+    const { token, ws_url } = await getPicoToken()
+    const sessionId = activeSessionIdRef
+
+    if (generation !== connectionGeneration) {
+      isConnecting = false
+      return
+    }
+
+    if (!token) {
+      console.error("No pico token available")
+      updateChatStore({ connectionState: "error" })
+      isConnecting = false
+      scheduleReconnect(generation, sessionId)
+      return
+    }
+
+    const finalWsUrl = normalizeWsUrlForBrowser(ws_url)
+    const url = `${finalWsUrl}?session_id=${encodeURIComponent(sessionId)}`
+    const socket = new WebSocket(url, [`token.${token}`])
+
+    if (generation !== connectionGeneration) {
+      isConnecting = false
+      invalidateSocket(socket)
+      return
+    }
+
+    socket.onopen = () => {
+      if (
+        !isCurrentSocket({
+          socket,
+          currentSocket: wsRef,
+          generation,
+          currentGeneration: connectionGeneration,
+          sessionId,
+          currentSessionId: activeSessionIdRef,
+        })
+      ) {
+        return
+      }
+      updateChatStore({ connectionState: "connected" })
+      isConnecting = false
+      reconnectAttempts = 0
+    }
+
+    socket.onmessage = (event) => {
+      if (
+        !isCurrentSocket({
+          socket,
+          currentSocket: wsRef,
+          generation,
+          currentGeneration: connectionGeneration,
+          sessionId,
+          currentSessionId: activeSessionIdRef,
+        })
+      ) {
+        return
+      }
+
+      try {
+        const message = JSON.parse(event.data) as PicoMessage
+        handlePicoMessage(message, sessionId)
+      } catch {
+        console.warn("Non-JSON message from pico:", event.data)
+      }
+    }
+
+    socket.onclose = () => {
+      if (
+        !isCurrentSocket({
+          socket,
+          currentSocket: wsRef,
+          generation,
+          currentGeneration: connectionGeneration,
+          sessionId,
+          currentSessionId: activeSessionIdRef,
+        })
+      ) {
+        return
+      }
+      wsRef = null
+      isConnecting = false
+      updateChatStore({
+        connectionState: "disconnected",
+        isTyping: false,
+      })
+      scheduleReconnect(generation, sessionId)
+    }
+
+    socket.onerror = () => {
+      if (
+        !isCurrentSocket({
+          socket,
+          currentSocket: wsRef,
+          generation,
+          currentGeneration: connectionGeneration,
+          sessionId,
+          currentSessionId: activeSessionIdRef,
+        })
+      ) {
+        return
+      }
+      isConnecting = false
+      updateChatStore({ connectionState: "error" })
+      scheduleReconnect(generation, sessionId)
+    }
+
+    wsRef = socket
+  } catch (error) {
+    if (generation !== connectionGeneration) {
+      isConnecting = false
+      return
+    }
+    console.error("Failed to connect to pico:", error)
+    updateChatStore({ connectionState: "error" })
+    isConnecting = false
+    scheduleReconnect(generation, activeSessionIdRef)
+  }
+}
+
+export function disconnectChat() {
+  disconnectChatInternal({ clearDesiredConnection: true })
+}
+
+export async function hydrateActiveSession() {
+  if (hydratePromise) {
+    return hydratePromise
+  }
+
+  const state = getChatState()
+  const storedSessionId = readStoredSessionId()
+
+  if (
+    !storedSessionId ||
+    state.hasHydratedActiveSession ||
+    storedSessionId !== state.activeSessionId
+  ) {
+    if (!state.hasHydratedActiveSession) {
+      updateChatStore({ hasHydratedActiveSession: true })
+    }
+    return
+  }
+
+  hydratePromise = loadSessionMessages(storedSessionId)
+    .then((historyMessages) => {
+      const currentState = getChatState()
+      if (currentState.activeSessionId !== storedSessionId) {
+        return
+      }
+
+      if (currentState.messages.length > 0) {
+        updateChatStore({
+          messages: mergeHistoryMessages(
+            historyMessages,
+            currentState.messages,
+          ),
+          hasHydratedActiveSession: true,
+        })
+        return
+      }
+
+      updateChatStore({
+        messages: historyMessages,
+        isTyping: false,
+        hasHydratedActiveSession: true,
+      })
+    })
+    .catch((error) => {
+      console.error("Failed to restore last session history:", error)
+
+      const currentState = getChatState()
+      if (currentState.activeSessionId !== storedSessionId) {
+        return
+      }
+
+      if (currentState.messages.length > 0) {
+        updateChatStore({ hasHydratedActiveSession: true })
+        return
+      }
+
+      clearStoredSessionId()
+      updateChatStore({
+        messages: [],
+        isTyping: false,
+        hasHydratedActiveSession: true,
+      })
+    })
+    .finally(() => {
+      hydratePromise = null
+    })
+
+  return hydratePromise
+}
+
+export function sendChatMessage(content: string) {
+  if (!wsRef || wsRef.readyState !== WebSocket.OPEN) {
+    console.warn("WebSocket not connected")
+    return false
+  }
+
+  const socket = wsRef
+  const id = `msg-${++msgIdCounter}-${Date.now()}`
+
+  updateChatStore((prev) => ({
+    messages: [
+      ...prev.messages,
+      { id, role: "user", content, timestamp: Date.now() },
+    ],
+    isTyping: true,
+  }))
+
+  try {
+    socket.send(
+      JSON.stringify({
+        type: "message.send",
+        id,
+        payload: { content },
+      }),
+    )
+    return true
+  } catch (error) {
+    console.error("Failed to send pico message:", error)
+    updateChatStore((prev) => ({
+      messages: prev.messages.filter((message) => message.id !== id),
+      isTyping: false,
+    }))
+    return false
+  }
+}
+
+export async function switchChatSession(sessionId: string) {
+  if (sessionId === activeSessionIdRef) {
+    return
+  }
+
+  try {
+    const historyMessages = await loadSessionMessages(sessionId)
+
+    disconnectChatInternal({ clearDesiredConnection: false })
+    setActiveSessionId(sessionId)
+    updateChatStore({
+      messages: historyMessages,
+      isTyping: false,
+      hasHydratedActiveSession: true,
+    })
+
+    if (store.get(gatewayAtom).status === "running") {
+      shouldMaintainConnection = true
+      await connectChat()
+    }
+  } catch (error) {
+    console.error("Failed to load session history:", error)
+    toast.error(i18n.t("chat.historyOpenFailed"))
+  }
+}
+
+export async function newChatSession() {
+  if (getChatState().messages.length === 0) {
+    return
+  }
+
+  disconnectChatInternal({ clearDesiredConnection: false })
+  setActiveSessionId(generateSessionId())
+  updateChatStore({
+    messages: [],
+    isTyping: false,
+    hasHydratedActiveSession: true,
+  })
+
+  if (store.get(gatewayAtom).status === "running") {
+    shouldMaintainConnection = true
+    await connectChat()
+  }
+}
+
+export function initializeChatStore() {
+  if (initialized) {
+    return
+  }
+
+  initialized = true
+  activeSessionIdRef = getChatState().activeSessionId
+  let lastGatewayStatus: GatewayState | null = null
+
+  const syncConnectionWithGateway = (force: boolean = false) => {
+    const gatewayStatus = store.get(gatewayAtom).status
+    if (!force && gatewayStatus === lastGatewayStatus) {
+      return
+    }
+    lastGatewayStatus = gatewayStatus
+
+    if (gatewayStatus === "running") {
+      shouldMaintainConnection = true
+      if (needsActiveSessionHydration()) {
+        return
+      }
+      void connectChat()
+      return
+    }
+
+    if (gatewayStatus === "stopped" || gatewayStatus === "error") {
+      disconnectChatInternal({ clearDesiredConnection: true })
+    }
+  }
+
+  unsubscribeGateway = store.sub(gatewayAtom, syncConnectionWithGateway)
+
+  if (!readStoredSessionId()) {
+    updateChatStore({ hasHydratedActiveSession: true })
+    syncConnectionWithGateway(true)
+    return
+  }
+
+  void hydrateActiveSession().finally(() => {
+    if (!initialized) {
+      return
+    }
+    syncConnectionWithGateway(true)
+  })
+}
+
+export function teardownChatStore() {
+  unsubscribeGateway?.()
+  unsubscribeGateway = null
+  initialized = false
+  disconnectChat()
+}
diff --git a/web/frontend/src/features/chat/history.ts b/web/frontend/src/features/chat/history.ts
new file mode 100644
index 000000000..886148184
--- /dev/null
+++ b/web/frontend/src/features/chat/history.ts
@@ -0,0 +1,68 @@
+import { getSessionHistory } from "@/api/sessions"
+import { normalizeUnixTimestamp } from "@/features/chat/state"
+import type { ChatMessage } from "@/store/chat"
+
+export async function loadSessionMessages(
+  sessionId: string,
+): Promise<ChatMessage[]> {
+  const detail = await getSessionHistory(sessionId)
+  const fallbackTime = detail.updated
+
+  return detail.messages.map((message, index) => ({
+    id: `hist-${index}-${Date.now()}`,
+    role: message.role,
+    content: message.content,
+    timestamp: fallbackTime,
+  }))
+}
+
+function normalizeMessageTimestamp(timestamp: number | string): string {
+  if (typeof timestamp === "number") {
+    return String(normalizeUnixTimestamp(timestamp))
+  }
+
+  const trimmed = timestamp.trim()
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+    return String(normalizeUnixTimestamp(Number(trimmed)))
+  }
+
+  const parsed = Date.parse(trimmed)
+  return Number.isNaN(parsed) ? trimmed : String(parsed)
+}
+
+function messageSignature(message: ChatMessage): string {
+  return `${message.role}\u0000${message.content}\u0000${normalizeMessageTimestamp(
+    message.timestamp,
+  )}`
+}
+
+function comparableTimestamp(timestamp: number | string): number {
+  const normalized = normalizeMessageTimestamp(timestamp)
+  const numeric = Number(normalized)
+  return Number.isFinite(numeric) ? numeric : 0
+}
+
+export function mergeHistoryMessages(
+  historyMessages: ChatMessage[],
+  currentMessages: ChatMessage[],
+): ChatMessage[] {
+  const currentIds = new Set(currentMessages.map((message) => message.id))
+  const currentSignatures = new Set(
+    currentMessages.map((message) => messageSignature(message)),
+  )
+
+  const merged = [
+    ...historyMessages.filter(
+      (message) =>
+        !currentIds.has(message.id) &&
+        !currentSignatures.has(messageSignature(message)),
+    ),
+    ...currentMessages,
+  ]
+
+  return merged.sort(
+    (left, right) =>
+      comparableTimestamp(left.timestamp) -
+      comparableTimestamp(right.timestamp),
+  )
+}
diff --git a/web/frontend/src/features/chat/protocol.ts b/web/frontend/src/features/chat/protocol.ts
new file mode 100644
index 000000000..5e5220c77
--- /dev/null
+++ b/web/frontend/src/features/chat/protocol.ts
@@ -0,0 +1,81 @@
+import { normalizeUnixTimestamp } from "@/features/chat/state"
+import { updateChatStore } from "@/store/chat"
+
+export interface PicoMessage {
+  type: string
+  id?: string
+  session_id?: string
+  timestamp?: number | string
+  payload?: Record<string, unknown>
+}
+
+export function handlePicoMessage(
+  message: PicoMessage,
+  expectedSessionId: string,
+) {
+  if (message.session_id && message.session_id !== expectedSessionId) {
+    return
+  }
+
+  const payload = message.payload || {}
+
+  switch (message.type) {
+    case "message.create": {
+      const content = (payload.content as string) || ""
+      const messageId = (payload.message_id as string) || `pico-${Date.now()}`
+      const timestamp =
+        message.timestamp !== undefined &&
+        Number.isFinite(Number(message.timestamp))
+          ? normalizeUnixTimestamp(Number(message.timestamp))
+          : Date.now()
+
+      updateChatStore((prev) => ({
+        messages: [
+          ...prev.messages,
+          {
+            id: messageId,
+            role: "assistant",
+            content,
+            timestamp,
+          },
+        ],
+        isTyping: false,
+      }))
+      break
+    }
+
+    case "message.update": {
+      const content = (payload.content as string) || ""
+      const messageId = payload.message_id as string
+      if (!messageId) {
+        break
+      }
+
+      updateChatStore((prev) => ({
+        messages: prev.messages.map((msg) =>
+          msg.id === messageId ? { ...msg, content } : msg,
+        ),
+      }))
+      break
+    }
+
+    case "typing.start":
+      updateChatStore({ isTyping: true })
+      break
+
+    case "typing.stop":
+      updateChatStore({ isTyping: false })
+      break
+
+    case "error":
+      console.error("Pico error:", payload)
+      updateChatStore({ isTyping: false })
+      break
+
+    case "pong":
+      break
+
+    default:
+      console.log("Unknown pico message type:", message.type)
+  }
+}
diff --git a/web/frontend/src/features/chat/state.ts b/web/frontend/src/features/chat/state.ts
new file mode 100644
index 000000000..5b7d6c6cd
--- /dev/null
+++ b/web/frontend/src/features/chat/state.ts
@@ -0,0 +1,59 @@
+const LAST_SESSION_STORAGE_KEY = "picoclaw:last-session-id"
+const UNIX_MS_THRESHOLD = 1e12
+
+function readStorageValue() {
+  return (
+    globalThis.localStorage?.getItem(LAST_SESSION_STORAGE_KEY)?.trim() || ""
+  )
+}
+
+export function readStoredSessionId(): string {
+  return readStorageValue()
+}
+
+export function writeStoredSessionId(sessionId: string) {
+  if (sessionId) {
+    globalThis.localStorage?.setItem(LAST_SESSION_STORAGE_KEY, sessionId)
+    return
+  }
+
+  globalThis.localStorage?.removeItem(LAST_SESSION_STORAGE_KEY)
+}
+
+export function clearStoredSessionId() {
+  globalThis.localStorage?.removeItem(LAST_SESSION_STORAGE_KEY)
+}
+
+export function generateSessionId(): string {
+  const webCrypto = globalThis.crypto
+  if (webCrypto && typeof webCrypto.randomUUID === "function") {
+    return webCrypto.randomUUID()
+  }
+
+  if (webCrypto && typeof webCrypto.getRandomValues === "function") {
+    const bytes = new Uint8Array(16)
+    webCrypto.getRandomValues(bytes)
+
+    bytes[6] = (bytes[6] & 0x0f) | 0x40
+    bytes[8] = (bytes[8] & 0x3f) | 0x80
+
+    const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0"))
+    return (
+      `${hex[0]}${hex[1]}${hex[2]}${hex[3]}-` +
+      `${hex[4]}${hex[5]}-` +
+      `${hex[6]}${hex[7]}-` +
+      `${hex[8]}${hex[9]}-` +
+      `${hex[10]}${hex[11]}${hex[12]}${hex[13]}${hex[14]}${hex[15]}`
+    )
+  }
+
+  return `session-${Date.now()}-${Math.random().toString(16).slice(2, 10)}`
+}
+
+export function getInitialActiveSessionId(): string {
+  return readStorageValue() || generateSessionId()
+}
+
+export function normalizeUnixTimestamp(timestamp: number): number {
+  return timestamp < UNIX_MS_THRESHOLD ? timestamp * 1000 : timestamp
+}
diff --git a/web/frontend/src/features/chat/websocket.ts b/web/frontend/src/features/chat/websocket.ts
new file mode 100644
index 000000000..6b132e9a6
--- /dev/null
+++ b/web/frontend/src/features/chat/websocket.ts
@@ -0,0 +1,57 @@
+export function normalizeWsUrlForBrowser(wsUrl: string): string {
+  let finalWsUrl = wsUrl
+
+  try {
+    const parsedUrl = new URL(wsUrl)
+    const isLocalHost =
+      parsedUrl.hostname === "localhost" ||
+      parsedUrl.hostname === "127.0.0.1" ||
+      parsedUrl.hostname === "0.0.0.0"
+    const isBrowserLocal =
+      window.location.hostname === "localhost" ||
+      window.location.hostname === "127.0.0.1"
+
+    if (isLocalHost && !isBrowserLocal) {
+      parsedUrl.hostname = window.location.hostname
+      finalWsUrl = parsedUrl.toString()
+    }
+  } catch (error) {
+    console.warn("Could not parse ws_url:", error)
+  }
+
+  return finalWsUrl
+}
+
+export function invalidateSocket(socket: WebSocket | null) {
+  if (!socket) {
+    return
+  }
+
+  socket.onopen = null
+  socket.onmessage = null
+  socket.onclose = null
+  socket.onerror = null
+  socket.close()
+}
+
+export function isCurrentSocket({
+  socket,
+  currentSocket,
+  generation,
+  currentGeneration,
+  sessionId,
+  currentSessionId,
+}: {
+  socket: WebSocket
+  currentSocket: WebSocket | null
+  generation: number
+  currentGeneration: number
+  sessionId: string
+  currentSessionId: string
+}): boolean {
+  return (
+    currentSocket === socket &&
+    generation === currentGeneration &&
+    sessionId === currentSessionId
+  )
+}
diff --git a/web/frontend/src/hooks/use-chat-models.ts b/web/frontend/src/hooks/use-chat-models.ts
new file mode 100644
index 000000000..9afa882db
--- /dev/null
+++ b/web/frontend/src/hooks/use-chat-models.ts
@@ -0,0 +1,99 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+
+import { type ModelInfo, getModels, setDefaultModel } from "@/api/models"
+
+interface UseChatModelsOptions {
+  isConnected: boolean
+}
+
+function isLocalModel(model: ModelInfo): boolean {
+  const isLocalHostBase = Boolean(
+    model.api_base?.includes("localhost") ||
+    model.api_base?.includes("127.0.0.1"),
+  )
+
+  return (
+    model.auth_method === "local" || (!model.auth_method && isLocalHostBase)
+  )
+}
+
+export function useChatModels({ isConnected }: UseChatModelsOptions) {
+  const [modelList, setModelList] = useState<ModelInfo[]>([])
+  const [defaultModelName, setDefaultModelName] = useState("")
+  const setDefaultRequestIdRef = useRef(0)
+
+  const loadModels = useCallback(async () => {
+    try {
+      const data = await getModels()
+      setModelList(data.models)
+      if (data.models.some((m) => m.model_name === data.default_model)) {
+        setDefaultModelName(data.default_model)
+      }
+    } catch {
+      // silently fail
+    }
+  }, [])
+
+  useEffect(() => {
+    const timerId = setTimeout(() => {
+      void loadModels()
+    }, 0)
+
+    return () => clearTimeout(timerId)
+  }, [isConnected, loadModels])
+
+  const handleSetDefault = useCallback(
+    async (modelName: string) => {
+      if (modelName === defaultModelName) return
+      const requestId = ++setDefaultRequestIdRef.current
+
+      try {
+        await setDefaultModel(modelName)
+        const data = await getModels()
+        if (requestId !== setDefaultRequestIdRef.current) {
+          return
+        }
+
+        setModelList(data.models)
+        if (data.models.some((m) => m.model_name === data.default_model)) {
+          setDefaultModelName(data.default_model)
+        }
+      } catch (err) {
+        console.error("Failed to set default model:", err)
+      }
+    },
+    [defaultModelName],
+  )
+
+  const hasConfiguredModels = useMemo(
+    () => modelList.some((m) => m.configured),
+    [modelList],
+  )
+
+  const oauthModels = useMemo(
+    () => modelList.filter((m) => m.configured && m.auth_method === "oauth"),
+    [modelList],
+  )
+
+  const localModels = useMemo(
+    () => modelList.filter((m) => m.configured && isLocalModel(m)),
+    [modelList],
+  )
+
+  const apiKeyModels = useMemo(
+    () =>
+      modelList.filter(
+        (m) => m.configured && m.auth_method !== "oauth" && !isLocalModel(m),
+      ),
+    [modelList],
+  )
+
+  return {
+    defaultModelName,
+    hasConfiguredModels,
+    apiKeyModels,
+    oauthModels,
+    localModels,
+    handleSetDefault,
+  }
+}
diff --git a/web/frontend/src/hooks/use-credentials-page.ts b/web/frontend/src/hooks/use-credentials-page.ts
new file mode 100644
index 000000000..354065b23
--- /dev/null
+++ b/web/frontend/src/hooks/use-credentials-page.ts
@@ -0,0 +1,436 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import { useTranslation } from "react-i18next"
+
+import {
+  type OAuthFlowState,
+  type OAuthProvider,
+  type OAuthProviderStatus,
+  getOAuthFlow,
+  getOAuthProviders,
+  loginOAuth,
+  logoutOAuth,
+  pollOAuthFlow,
+} from "@/api/oauth"
+
+type FlowWatchMode = "" | "status" | "poll"
+
+function getProviderLabel(provider: OAuthProvider | ""): string {
+  if (provider === "openai") return "OpenAI"
+  if (provider === "anthropic") return "Anthropic"
+  if (provider === "google-antigravity") return "Google Antigravity"
+  return ""
+}
+
+export function useCredentialsPage() {
+  const { t } = useTranslation()
+  const [providers, setProviders] = useState<OAuthProviderStatus[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState("")
+
+  const [activeAction, setActiveAction] = useState("")
+  const [activeFlow, setActiveFlow] = useState<OAuthFlowState | null>(null)
+  const actionTokenRef = useRef(0)
+
+  const [watchFlowID, setWatchFlowID] = useState("")
+  const [watchMode, setWatchMode] = useState<FlowWatchMode>("")
+  const [pollIntervalMs, setPollIntervalMs] = useState(2000)
+
+  const [openAIToken, setOpenAIToken] = useState("")
+  const [anthropicToken, setAnthropicToken] = useState("")
+
+  const [logoutDialogOpen, setLogoutDialogOpen] = useState(false)
+  const [logoutConfirmProvider, setLogoutConfirmProvider] = useState<
+    OAuthProvider | ""
+  >("")
+
+  const [deviceSheetOpen, setDeviceSheetOpen] = useState(false)
+  const [deviceFlow, setDeviceFlow] = useState<OAuthFlowState | null>(null)
+
+  const loadProviders = useCallback(async () => {
+    try {
+      const data = await getOAuthProviders()
+      setProviders(data.providers)
+      setError("")
+    } catch (err) {
+      setError(
+        err instanceof Error ? err.message : t("credentials.errors.loadFailed"),
+      )
+    } finally {
+      setLoading(false)
+    }
+  }, [t])
+
+  useEffect(() => {
+    void loadProviders()
+  }, [loadProviders])
+
+  useEffect(() => {
+    if (!watchFlowID || !watchMode) {
+      return
+    }
+
+    let canceled = false
+    let timer: ReturnType<typeof setTimeout> | null = null
+
+    const step = async () => {
+      try {
+        const flow =
+          watchMode === "poll"
+            ? await pollOAuthFlow(watchFlowID)
+            : await getOAuthFlow(watchFlowID)
+
+        if (canceled) {
+          return
+        }
+
+        setActiveFlow(flow)
+        setDeviceFlow((prev) =>
+          prev?.flow_id === flow.flow_id ? { ...prev, ...flow } : prev,
+        )
+
+        if (flow.status === "pending") {
+          timer = setTimeout(step, pollIntervalMs)
+          return
+        }
+
+        if (watchMode === "poll") {
+          setDeviceSheetOpen(false)
+        }
+
+        setWatchFlowID("")
+        setWatchMode("")
+        setActiveAction("")
+        await loadProviders()
+      } catch (err) {
+        if (canceled) {
+          return
+        }
+        setWatchFlowID("")
+        setWatchMode("")
+        setActiveAction("")
+        setError(
+          err instanceof Error
+            ? err.message
+            : t("credentials.errors.flowFailed"),
+        )
+      }
+    }
+
+    void step()
+
+    return () => {
+      canceled = true
+      if (timer) {
+        clearTimeout(timer)
+      }
+    }
+  }, [loadProviders, pollIntervalMs, t, watchFlowID, watchMode])
+
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search)
+    const flowID = params.get("oauth_flow_id")
+    if (!flowID) {
+      return
+    }
+
+    setWatchFlowID(flowID)
+    setWatchMode("status")
+    setPollIntervalMs(700)
+
+    window.history.replaceState({}, "", window.location.pathname)
+  }, [])
+
+  useEffect(() => {
+    const onMessage = (event: MessageEvent) => {
+      const data = event.data as
+        | { type?: string; flowId?: string; status?: string }
+        | undefined
+      if (!data || data.type !== "picoclaw-oauth-result" || !data.flowId) {
+        return
+      }
+
+      setWatchFlowID(data.flowId)
+      setWatchMode("status")
+      setPollIntervalMs(700)
+    }
+
+    window.addEventListener("message", onMessage)
+    return () => window.removeEventListener("message", onMessage)
+  }, [])
+
+  const providersMap = useMemo(() => {
+    const map = new Map<OAuthProvider, OAuthProviderStatus>()
+    for (const item of providers) {
+      map.set(item.provider, item)
+    }
+    return map
+  }, [providers])
+
+  const openaiStatus = providersMap.get("openai")
+  const anthropicStatus = providersMap.get("anthropic")
+  const antigravityStatus = providersMap.get("google-antigravity")
+
+  const bumpActionToken = useCallback(() => {
+    actionTokenRef.current += 1
+    return actionTokenRef.current
+  }, [])
+
+  const isActionTokenCurrent = useCallback((token: number) => {
+    return actionTokenRef.current === token
+  }, [])
+
+  const startBrowserOAuth = useCallback(
+    async (provider: OAuthProvider) => {
+      const actionToken = bumpActionToken()
+      setActiveAction(`${provider}:browser`)
+      setError("")
+
+      const authTab = window.open("", "_blank")
+      if (!authTab) {
+        if (!isActionTokenCurrent(actionToken)) {
+          return
+        }
+        setActiveAction("")
+        setError(t("credentials.errors.popupBlocked"))
+        return
+      }
+
+      try {
+        const resp = await loginOAuth({ provider, method: "browser" })
+        if (!isActionTokenCurrent(actionToken)) {
+          authTab.close()
+          return
+        }
+        if (!resp.auth_url || !resp.flow_id) {
+          throw new Error(t("credentials.errors.invalidBrowserResponse"))
+        }
+
+        authTab.location.href = resp.auth_url
+
+        setActiveFlow({
+          flow_id: resp.flow_id,
+          provider,
+          method: "browser",
+          status: "pending",
+          expires_at: resp.expires_at,
+        })
+        setWatchFlowID(resp.flow_id)
+        setWatchMode("status")
+        setPollIntervalMs(2000)
+      } catch (err) {
+        if (!isActionTokenCurrent(actionToken)) {
+          authTab.close()
+          return
+        }
+        authTab.close()
+        setActiveAction("")
+        setError(
+          err instanceof Error
+            ? err.message
+            : t("credentials.errors.loginFailed"),
+        )
+      }
+    },
+    [bumpActionToken, isActionTokenCurrent, t],
+  )
+
+  const startOpenAIDeviceCode = useCallback(async () => {
+    const actionToken = bumpActionToken()
+    setActiveAction("openai:device")
+    setError("")
+
+    try {
+      const resp = await loginOAuth({
+        provider: "openai",
+        method: "device_code",
+      })
+      if (!isActionTokenCurrent(actionToken)) {
+        return
+      }
+      if (!resp.flow_id || !resp.user_code || !resp.verify_url) {
+        throw new Error(t("credentials.errors.invalidDeviceResponse"))
+      }
+
+      const flow: OAuthFlowState = {
+        flow_id: resp.flow_id,
+        provider: "openai",
+        method: "device_code",
+        status: "pending",
+        user_code: resp.user_code,
+        verify_url: resp.verify_url,
+        interval: resp.interval,
+        expires_at: resp.expires_at,
+      }
+
+      setDeviceFlow(flow)
+      setDeviceSheetOpen(true)
+      setActiveFlow(flow)
+      setWatchFlowID(resp.flow_id)
+      setWatchMode("poll")
+      setPollIntervalMs(Math.max(1000, (resp.interval ?? 5) * 1000))
+    } catch (err) {
+      if (!isActionTokenCurrent(actionToken)) {
+        return
+      }
+      setActiveAction("")
+      setError(
+        err instanceof Error
+          ? err.message
+          : t("credentials.errors.loginFailed"),
+      )
+    }
+  }, [bumpActionToken, isActionTokenCurrent, t])
+
+  const saveToken = useCallback(
+    async (provider: OAuthProvider, token: string) => {
+      const actionID = `${provider}:token`
+      setActiveAction(actionID)
+      setError("")
+
+      try {
+        await loginOAuth({ provider, method: "token", token })
+        if (provider === "openai") {
+          setOpenAIToken("")
+        }
+        if (provider === "anthropic") {
+          setAnthropicToken("")
+        }
+        await loadProviders()
+      } catch (err) {
+        setError(
+          err instanceof Error
+            ? err.message
+            : t("credentials.errors.loginFailed"),
+        )
+      } finally {
+        setActiveAction("")
+      }
+    },
+    [loadProviders, t],
+  )
+
+  const doLogout = useCallback(
+    async (provider: OAuthProvider) => {
+      const actionID = `${provider}:logout`
+      setActiveAction(actionID)
+      setError("")
+
+      try {
+        await logoutOAuth(provider)
+        await loadProviders()
+      } catch (err) {
+        setError(
+          err instanceof Error
+            ? err.message
+            : t("credentials.errors.logoutFailed"),
+        )
+      } finally {
+        setActiveAction("")
+      }
+    },
+    [loadProviders, t],
+  )
+
+  const askLogout = useCallback((provider: OAuthProvider) => {
+    setLogoutConfirmProvider(provider)
+    setLogoutDialogOpen(true)
+  }, [])
+
+  const handleConfirmLogout = useCallback(async () => {
+    if (!logoutConfirmProvider) {
+      return
+    }
+    await doLogout(logoutConfirmProvider)
+    setLogoutDialogOpen(false)
+    setLogoutConfirmProvider("")
+  }, [doLogout, logoutConfirmProvider])
+
+  const handleLogoutDialogOpenChange = useCallback((open: boolean) => {
+    setLogoutDialogOpen(open)
+    if (!open) {
+      setLogoutConfirmProvider("")
+    }
+  }, [])
+
+  const handleDeviceSheetOpenChange = useCallback(
+    (open: boolean) => {
+      setDeviceSheetOpen(open)
+      if (open) {
+        return
+      }
+
+      if (watchMode === "poll") {
+        setWatchFlowID("")
+        setWatchMode("")
+        if (activeAction === "openai:device") {
+          setActiveAction("")
+        }
+      }
+
+      setDeviceFlow(null)
+      if (
+        activeFlow?.method === "device_code" &&
+        activeFlow.status === "pending"
+      ) {
+        setActiveFlow(null)
+      }
+    },
+    [activeAction, activeFlow, watchMode],
+  )
+
+  const stopLoading = useCallback(() => {
+    bumpActionToken()
+    setWatchFlowID("")
+    setWatchMode("")
+    setActiveAction("")
+    setDeviceSheetOpen(false)
+    setDeviceFlow(null)
+    setActiveFlow((prev) => (prev?.status === "pending" ? null : prev))
+  }, [bumpActionToken])
+
+  const logoutProviderLabel = getProviderLabel(logoutConfirmProvider)
+
+  const flowHint = useMemo(() => {
+    if (!activeFlow) {
+      return ""
+    }
+    if (activeFlow.status === "pending") {
+      return t("credentials.flow.pending")
+    }
+    if (activeFlow.status === "success") {
+      return t("credentials.flow.success")
+    }
+    if (activeFlow.status === "expired") {
+      return t("credentials.flow.expired")
+    }
+    return activeFlow.error || t("credentials.flow.error")
+  }, [activeFlow, t])
+
+  return {
+    loading,
+    error,
+    activeAction,
+    activeFlow,
+    flowHint,
+    openAIToken,
+    anthropicToken,
+    openaiStatus,
+    anthropicStatus,
+    antigravityStatus,
+    logoutDialogOpen,
+    logoutConfirmProvider,
+    logoutProviderLabel,
+    deviceSheetOpen,
+    deviceFlow,
+    setOpenAIToken,
+    setAnthropicToken,
+    startBrowserOAuth,
+    startOpenAIDeviceCode,
+    stopLoading,
+    saveToken,
+    askLogout,
+    handleConfirmLogout,
+    handleLogoutDialogOpenChange,
+    handleDeviceSheetOpenChange,
+  }
+}
diff --git a/web/frontend/src/hooks/use-gateway-logs.ts b/web/frontend/src/hooks/use-gateway-logs.ts
new file mode 100644
index 000000000..1de361124
--- /dev/null
+++ b/web/frontend/src/hooks/use-gateway-logs.ts
@@ -0,0 +1,98 @@
+import { useAtomValue } from "jotai"
+import { useEffect, useRef, useState } from "react"
+
+import { clearGatewayLogs, getGatewayLogs } from "@/api/gateway"
+import { gatewayAtom } from "@/store/gateway"
+
+export function useGatewayLogs() {
+  const [logs, setLogs] = useState<string[]>([])
+  const [clearing, setClearing] = useState(false)
+  const logOffsetRef = useRef(0)
+  const logRunIdRef = useRef(-1)
+  const syncTokenRef = useRef(0)
+
+  const gateway = useAtomValue(gatewayAtom)
+
+  const clearLogs = async () => {
+    setClearing(true)
+    try {
+      const data = await clearGatewayLogs()
+      syncTokenRef.current += 1
+      setLogs([])
+      logOffsetRef.current = data.log_total ?? 0
+      if (data.log_run_id !== undefined) {
+        logRunIdRef.current = data.log_run_id
+      }
+    } catch {
+      // Ignore clear failures silently to avoid noisy transient errors.
+    } finally {
+      setClearing(false)
+    }
+  }
+
+  useEffect(() => {
+    let mounted = true
+    let timeout: ReturnType<typeof setTimeout>
+
+    const fetchLogs = async () => {
+      if (
+        !mounted ||
+        !["running", "starting", "restarting", "stopping"].includes(
+          gateway.status,
+        )
+      ) {
+        if (mounted) {
+          timeout = setTimeout(fetchLogs, 1000)
+        }
+        return
+      }
+
+      try {
+        const requestToken = syncTokenRef.current
+        const requestOffset = logOffsetRef.current
+        const requestRunId = logRunIdRef.current
+        const data = await getGatewayLogs({
+          log_offset: requestOffset,
+          log_run_id: requestRunId,
+        })
+
+        if (!mounted || requestToken !== syncTokenRef.current) {
+          return
+        }
+
+        if (data.log_run_id !== undefined && data.log_run_id !== requestRunId) {
+          logRunIdRef.current = data.log_run_id
+          logOffsetRef.current = 0
+          if (data.logs) {
+            setLogs(data.logs)
+            logOffsetRef.current = data.log_total || data.logs.length
+          }
+        } else if (data.logs && data.logs.length > 0) {
+          const nextLogs = data.logs
+          setLogs((prev) => [...prev, ...nextLogs])
+          logOffsetRef.current =
+            data.log_total || logOffsetRef.current + nextLogs.length
+        }
+      } catch {
+        // Ignore simple fetch errors during polling.
+      } finally {
+        if (mounted) {
+          timeout = setTimeout(fetchLogs, 1000)
+        }
+      }
+    }
+
+    fetchLogs()
+
+    return () => {
+      mounted = false
+      clearTimeout(timeout)
+    }
+  }, [gateway.status])
+
+  return {
+    clearLogs,
+    clearing,
+    logs,
+  }
+}
diff --git a/web/frontend/src/hooks/use-gateway.ts b/web/frontend/src/hooks/use-gateway.ts
new file mode 100644
index 000000000..b118b43da
--- /dev/null
+++ b/web/frontend/src/hooks/use-gateway.ts
@@ -0,0 +1,74 @@
+import { useAtomValue } from "jotai"
+import { useCallback, useEffect, useState } from "react"
+
+import { restartGateway, startGateway, stopGateway } from "@/api/gateway"
+import {
+  beginGatewayStoppingTransition,
+  cancelGatewayStoppingTransition,
+  gatewayAtom,
+  refreshGatewayState,
+  subscribeGatewayPolling,
+  updateGatewayStore,
+} from "@/store"
+
+export function useGateway() {
+  const gateway = useAtomValue(gatewayAtom)
+  const { status: state, canStart, restartRequired } = gateway
+  const [loading, setLoading] = useState(false)
+
+  useEffect(() => {
+    return subscribeGatewayPolling()
+  }, [])
+
+  const start = useCallback(async () => {
+    if (!canStart) return
+
+    setLoading(true)
+    try {
+      await startGateway()
+      updateGatewayStore({
+        status: "starting",
+        restartRequired: false,
+      })
+    } catch (err) {
+      console.error("Failed to start gateway:", err)
+    } finally {
+      await refreshGatewayState({ force: true })
+      setLoading(false)
+    }
+  }, [canStart])
+
+  const stop = useCallback(async () => {
+    setLoading(true)
+    beginGatewayStoppingTransition()
+    try {
+      await stopGateway()
+    } catch (err) {
+      console.error("Failed to stop gateway:", err)
+      cancelGatewayStoppingTransition()
+    } finally {
+      await refreshGatewayState({ force: true })
+      setLoading(false)
+    }
+  }, [])
+
+  const restart = useCallback(async () => {
+    if (state !== "running") return
+
+    setLoading(true)
+    try {
+      await restartGateway()
+      updateGatewayStore({
+        status: "restarting",
+        restartRequired: false,
+      })
+    } catch (err) {
+      console.error("Failed to restart gateway:", err)
+    } finally {
+      await refreshGatewayState({ force: true })
+      setLoading(false)
+    }
+  }, [state])
+
+  return { state, loading, canStart, restartRequired, start, stop, restart }
+}
diff --git a/web/frontend/src/hooks/use-log-wrap-columns.ts b/web/frontend/src/hooks/use-log-wrap-columns.ts
new file mode 100644
index 000000000..9a07e019c
--- /dev/null
+++ b/web/frontend/src/hooks/use-log-wrap-columns.ts
@@ -0,0 +1,52 @@
+import { useEffect, useRef, useState } from "react"
+
+const DEFAULT_WRAP_COLUMNS = 120
+const MIN_WRAP_COLUMNS = 20
+
+export function useLogWrapColumns() {
+  const [wrapColumns, setWrapColumns] = useState(DEFAULT_WRAP_COLUMNS)
+  const contentRef = useRef<HTMLDivElement>(null)
+  const measureRef = useRef<HTMLSpanElement>(null)
+
+  useEffect(() => {
+    const content = contentRef.current
+    const measure = measureRef.current
+
+    if (!content || !measure) {
+      return
+    }
+
+    const updateWrapColumns = () => {
+      const contentWidth = content.clientWidth
+      const charWidth = measure.getBoundingClientRect().width
+
+      if (!contentWidth || !charWidth) {
+        return
+      }
+
+      const nextColumns = Math.max(
+        Math.floor(contentWidth / charWidth) - 1,
+        MIN_WRAP_COLUMNS,
+      )
+
+      setWrapColumns((current) =>
+        current === nextColumns ? current : nextColumns,
+      )
+    }
+
+    updateWrapColumns()
+
+    const observer = new ResizeObserver(updateWrapColumns)
+    observer.observe(content)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [])
+
+  return {
+    contentRef,
+    measureRef,
+    wrapColumns,
+  }
+}
diff --git a/web/frontend/src/hooks/use-mobile.ts b/web/frontend/src/hooks/use-mobile.ts
new file mode 100644
index 000000000..2b0fe1dfe
--- /dev/null
+++ b/web/frontend/src/hooks/use-mobile.ts
@@ -0,0 +1,19 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isMobile
+}
diff --git a/web/frontend/src/hooks/use-pico-chat.ts b/web/frontend/src/hooks/use-pico-chat.ts
new file mode 100644
index 000000000..3ac2e1613
--- /dev/null
+++ b/web/frontend/src/hooks/use-pico-chat.ts
@@ -0,0 +1,70 @@
+import dayjs from "dayjs"
+import { useAtomValue } from "jotai"
+
+import {
+  newChatSession,
+  sendChatMessage,
+  switchChatSession,
+} from "@/features/chat/controller"
+import { chatAtom } from "@/store/chat"
+
+const UNIX_MS_THRESHOLD = 1e12
+
+function normalizeUnixTimestamp(timestamp: number): number {
+  return timestamp < UNIX_MS_THRESHOLD ? timestamp * 1000 : timestamp
+}
+
+function parseTimestamp(dateRaw: number | string | Date) {
+  if (typeof dateRaw === "number") {
+    return dayjs(normalizeUnixTimestamp(dateRaw))
+  }
+
+  if (typeof dateRaw === "string") {
+    const trimmed = dateRaw.trim()
+    if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+      const numeric = Number(trimmed)
+      if (Number.isFinite(numeric)) {
+        return dayjs(normalizeUnixTimestamp(numeric))
+      }
+    }
+    return dayjs(trimmed)
+  }
+
+  return dayjs(dateRaw)
+}
+
+export function formatMessageTime(dateRaw: number | string | Date): string {
+  const date = parseTimestamp(dateRaw)
+  if (!date.isValid()) {
+    return ""
+  }
+  const now = dayjs()
+
+  const isToday = date.isSame(now, "day")
+  const isThisYear = date.isSame(now, "year")
+
+  if (isToday) {
+    return date.format("LT")
+  }
+
+  if (isThisYear) {
+    return date.format("MMM D LT")
+  }
+
+  return date.format("ll LT")
+}
+
+export function usePicoChat() {
+  const { messages, connectionState, isTyping, activeSessionId } =
+    useAtomValue(chatAtom)
+
+  return {
+    messages,
+    connectionState,
+    isTyping,
+    activeSessionId,
+    sendMessage: sendChatMessage,
+    switchSession: switchChatSession,
+    newChat: newChatSession,
+  }
+}
diff --git a/web/frontend/src/hooks/use-session-history.ts b/web/frontend/src/hooks/use-session-history.ts
new file mode 100644
index 000000000..790339dba
--- /dev/null
+++ b/web/frontend/src/hooks/use-session-history.ts
@@ -0,0 +1,112 @@
+import { useCallback, useEffect, useRef, useState } from "react"
+import { useTranslation } from "react-i18next"
+
+import { type SessionSummary, deleteSession, getSessions } from "@/api/sessions"
+
+const LIMIT = 20
+
+interface UseSessionHistoryOptions {
+  activeSessionId: string
+  onDeletedActiveSession: () => void
+}
+
+export function useSessionHistory({
+  activeSessionId,
+  onDeletedActiveSession,
+}: UseSessionHistoryOptions) {
+  const { t } = useTranslation()
+  const observerRef = useRef<HTMLDivElement>(null)
+  const [sessions, setSessions] = useState<SessionSummary[]>([])
+  const [offset, setOffset] = useState(0)
+  const [hasMore, setHasMore] = useState(true)
+  const [isLoadingMore, setIsLoadingMore] = useState(false)
+  const [loadError, setLoadError] = useState(false)
+
+  const loadSessions = useCallback(
+    async (reset = true) => {
+      try {
+        const currentOffset = reset ? 0 : offset
+        if (reset) {
+          setLoadError(false)
+          setHasMore(true)
+          setOffset(0)
+        }
+
+        const data = await getSessions(currentOffset, LIMIT)
+        setLoadError(false)
+
+        if (data.length < LIMIT) {
+          setHasMore(false)
+        }
+
+        if (reset) {
+          setSessions(data)
+        } else {
+          setSessions((prev) => {
+            const existingIds = new Set(prev.map((s) => s.id))
+            const newItems = data.filter((s) => !existingIds.has(s.id))
+            return [...prev, ...newItems]
+          })
+        }
+
+        setOffset(currentOffset + data.length)
+      } catch (err) {
+        console.error("Failed to fetch session history:", err)
+        setLoadError(true)
+        if (!reset) {
+          setHasMore(false)
+        }
+      } finally {
+        setIsLoadingMore(false)
+      }
+    },
+    [offset],
+  )
+
+  useEffect(() => {
+    if (!observerRef.current || !hasMore || isLoadingMore || loadError) return
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (
+          entries[0].isIntersecting &&
+          hasMore &&
+          !isLoadingMore &&
+          !loadError
+        ) {
+          setIsLoadingMore(true)
+          void loadSessions(false)
+        }
+      },
+      { threshold: 0.1 },
+    )
+
+    observer.observe(observerRef.current)
+    return () => observer.disconnect()
+  }, [hasMore, isLoadingMore, loadError, loadSessions])
+
+  const handleDeleteSession = useCallback(
+    async (id: string) => {
+      try {
+        await deleteSession(id)
+        setSessions((prev) => prev.filter((s) => s.id !== id))
+        if (id === activeSessionId) {
+          onDeletedActiveSession()
+        }
+      } catch (err) {
+        console.error("Failed to delete session:", err)
+      }
+    },
+    [activeSessionId, onDeletedActiveSession],
+  )
+
+  return {
+    sessions,
+    hasMore,
+    loadError,
+    loadErrorMessage: t("chat.historyLoadFailed"),
+    observerRef,
+    loadSessions,
+    handleDeleteSession,
+  }
+}
diff --git a/web/frontend/src/hooks/use-sidebar-channels.ts b/web/frontend/src/hooks/use-sidebar-channels.ts
new file mode 100644
index 000000000..22fc24e57
--- /dev/null
+++ b/web/frontend/src/hooks/use-sidebar-channels.ts
@@ -0,0 +1,241 @@
+import {
+  IconBrandChrome,
+  IconBrandDingtalk,
+  IconBrandDiscord,
+  IconBrandLine,
+  IconBrandMatrix,
+  IconBrandQq,
+  IconBrandSlack,
+  IconBrandTelegram,
+  IconBrandWechat,
+  IconBrandWhatsapp,
+  IconCamera,
+  IconMessages,
+  IconPlug,
+  IconRobot,
+} from "@tabler/icons-react"
+import type { TFunction } from "i18next"
+import { useAtomValue } from "jotai"
+import * as React from "react"
+
+import {
+  type AppConfig,
+  type SupportedChannel,
+  getAppConfig,
+  getChannelsCatalog,
+} from "@/api/channels"
+import { getChannelDisplayName } from "@/components/channels/channel-display-name"
+import { gatewayAtom } from "@/store/gateway"
+
+const DEFAULT_VISIBLE_CHANNELS = 4
+const CHANNEL_IMPORTANCE_TAIL = [
+  "slack",
+  "line",
+  "wecom",
+  "dingtalk",
+  "qq",
+  "onebot",
+  "matrix",
+  "pico",
+  "maixcam",
+  "irc",
+  "whatsapp",
+  "whatsapp_native",
+]
+
+function getChannelImportanceOrder(language: string): string[] {
+  const priority = language.startsWith("zh")
+    ? ["feishu", "weixin", "discord", "telegram"]
+    : ["discord", "telegram", "feishu", "weixin"]
+  return [...priority, ...CHANNEL_IMPORTANCE_TAIL]
+}
+
+function IconLark({ className }: { className?: string }) {
+  return React.createElement("span", {
+    className,
+    "aria-hidden": "true",
+    style: {
+      display: "inline-block",
+      backgroundColor: "currentColor",
+      mask: "url(/lark.svg) center / contain no-repeat",
+      WebkitMask: "url(/lark.svg) center / contain no-repeat",
+    } as React.CSSProperties,
+  })
+}
+
+const CHANNEL_ICON_MAP: Record<
+  string,
+  React.ComponentType<{ className?: string }>
+> = {
+  telegram: IconBrandTelegram,
+  discord: IconBrandDiscord,
+  slack: IconBrandSlack,
+  feishu: IconLark,
+  dingtalk: IconBrandDingtalk,
+  line: IconBrandLine,
+  qq: IconBrandQq,
+  weixin: IconBrandWechat,
+  wecom: IconBrandWechat,
+  whatsapp: IconBrandWhatsapp,
+  whatsapp_native: IconBrandWhatsapp,
+  matrix: IconBrandMatrix,
+  maixcam: IconCamera,
+  onebot: IconRobot,
+  pico: IconBrandChrome,
+  irc: IconMessages,
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>
+  }
+  return {}
+}
+
+function isChannelEnabled(
+  channel: SupportedChannel,
+  channelsConfig: Record<string, unknown>,
+): boolean {
+  const channelConfig = asRecord(channelsConfig[channel.config_key])
+  if (channelConfig.enabled !== true) {
+    return false
+  }
+
+  // whatsapp / whatsapp_native share one config block and are split by use_native.
+  if (channel.name === "whatsapp_native") {
+    return channelConfig.use_native === true
+  }
+  if (channel.name === "whatsapp") {
+    return channelConfig.use_native !== true
+  }
+
+  return true
+}
+
+function buildChannelEnabledMap(
+  channels: SupportedChannel[],
+  appConfig: AppConfig,
+): Record<string, boolean> {
+  const channelsConfig = asRecord(asRecord(appConfig).channels)
+  const result: Record<string, boolean> = {}
+  for (const channel of channels) {
+    result[channel.name] = isChannelEnabled(channel, channelsConfig)
+  }
+  return result
+}
+
+export interface SidebarChannelNavItem {
+  key: string
+  title: string
+  url: string
+  icon: React.ComponentType<{ className?: string }>
+}
+
+interface UseSidebarChannelsOptions {
+  language: string
+  t: TFunction
+}
+
+export function useSidebarChannels({ language, t }: UseSidebarChannelsOptions) {
+  const gateway = useAtomValue(gatewayAtom)
+  const [channels, setChannels] = React.useState<SupportedChannel[]>([])
+  const [enabledMap, setEnabledMap] = React.useState<Record<string, boolean>>(
+    {},
+  )
+  const [showAllChannels, setShowAllChannels] = React.useState(false)
+
+  const reloadChannels = React.useCallback((shouldApply?: () => boolean) => {
+    Promise.all([
+      getChannelsCatalog(),
+      getAppConfig().catch(() => ({}) as AppConfig),
+    ])
+      .then(([catalog, appConfig]) => {
+        if (shouldApply && !shouldApply()) {
+          return
+        }
+        setChannels(catalog.channels)
+        setEnabledMap(buildChannelEnabledMap(catalog.channels, appConfig))
+      })
+      .catch(() => {
+        if (shouldApply && !shouldApply()) {
+          return
+        }
+        setChannels([])
+        setEnabledMap({})
+      })
+  }, [])
+
+  React.useEffect(() => {
+    let active = true
+    reloadChannels(() => active)
+    return () => {
+      active = false
+    }
+  }, [reloadChannels])
+
+  const previousGatewayStatusRef = React.useRef(gateway.status)
+  React.useEffect(() => {
+    const previousStatus = previousGatewayStatusRef.current
+    if (previousStatus !== "running" && gateway.status === "running") {
+      reloadChannels()
+    }
+    previousGatewayStatusRef.current = gateway.status
+  }, [gateway.status, reloadChannels])
+
+  const channelImportanceIndex = React.useMemo(() => {
+    return new Map(
+      getChannelImportanceOrder(language).map((name, index) => [name, index]),
+    )
+  }, [language])
+
+  const sortedChannels = React.useMemo(() => {
+    const list = [...channels]
+    list.sort((a, b) => {
+      const aEnabled = enabledMap[a.name] === true
+      const bEnabled = enabledMap[b.name] === true
+      if (aEnabled !== bEnabled) {
+        return aEnabled ? -1 : 1
+      }
+
+      const aImportance =
+        channelImportanceIndex.get(a.name) ?? Number.MAX_SAFE_INTEGER
+      const bImportance =
+        channelImportanceIndex.get(b.name) ?? Number.MAX_SAFE_INTEGER
+      if (aImportance !== bImportance) {
+        return aImportance - bImportance
+      }
+
+      return getChannelDisplayName(a, t).localeCompare(
+        getChannelDisplayName(b, t),
+      )
+    })
+    return list
+  }, [channelImportanceIndex, channels, enabledMap, t])
+
+  const hasMoreChannels = sortedChannels.length > DEFAULT_VISIBLE_CHANNELS
+  const visibleChannels = showAllChannels
+    ? sortedChannels
+    : sortedChannels.slice(0, DEFAULT_VISIBLE_CHANNELS)
+
+  const channelItems = React.useMemo<SidebarChannelNavItem[]>(
+    () =>
+      visibleChannels.map((channel) => ({
+        key: channel.name,
+        title: getChannelDisplayName(channel, t),
+        url: `/channels/${channel.name}`,
+        icon: CHANNEL_ICON_MAP[channel.name] ?? IconPlug,
+      })),
+    [t, visibleChannels],
+  )
+
+  const toggleShowAllChannels = React.useCallback(() => {
+    setShowAllChannels((prev) => !prev)
+  }, [])
+
+  return {
+    channelItems,
+    hasMoreChannels,
+    showAllChannels,
+    toggleShowAllChannels,
+  }
+}
diff --git a/web/frontend/src/hooks/use-theme.ts b/web/frontend/src/hooks/use-theme.ts
new file mode 100644
index 000000000..b0f5ea18d
--- /dev/null
+++ b/web/frontend/src/hooks/use-theme.ts
@@ -0,0 +1,28 @@
+import { useCallback, useEffect, useState } from "react"
+
+type Theme = "light" | "dark"
+
+function getStoredTheme(): Theme {
+  if (typeof window === "undefined") return "dark"
+  return (localStorage.getItem("theme") as Theme) || "dark"
+}
+
+export function useTheme() {
+  const [theme, setThemeState] = useState<Theme>(getStoredTheme)
+
+  useEffect(() => {
+    const root = document.documentElement
+    if (theme === "dark") {
+      root.classList.add("dark")
+    } else {
+      root.classList.remove("dark")
+    }
+    localStorage.setItem("theme", theme)
+  }, [theme])
+
+  const toggleTheme = useCallback(() => {
+    setThemeState((prev) => (prev === "dark" ? "light" : "dark"))
+  }, [])
+
+  return { theme, toggleTheme }
+}
diff --git a/web/frontend/src/i18n/index.ts b/web/frontend/src/i18n/index.ts
new file mode 100644
index 000000000..bdc1fe917
--- /dev/null
+++ b/web/frontend/src/i18n/index.ts
@@ -0,0 +1,49 @@
+import dayjs from "dayjs"
+import "dayjs/locale/en"
+import "dayjs/locale/zh-cn"
+import localizedFormat from "dayjs/plugin/localizedFormat"
+import relativeTime from "dayjs/plugin/relativeTime"
+import i18n from "i18next"
+import LanguageDetector from "i18next-browser-languagedetector"
+import { initReactI18next } from "react-i18next"
+
+import en from "./locales/en.json"
+import zh from "./locales/zh.json"
+
+dayjs.extend(relativeTime)
+dayjs.extend(localizedFormat)
+
+i18n
+  // detect user language
+  // learn more: https://github.com/i18next/i18next-browser-languageDetector
+  .use(LanguageDetector)
+  // pass the i18n instance to react-i18next.
+  .use(initReactI18next)
+  // init i18next
+  // for all options read: https://www.i18next.com/overview/configuration-options
+  .init({
+    resources: {
+      en: {
+        translation: en,
+      },
+      zh: {
+        translation: zh,
+      },
+    },
+    fallbackLng: "en",
+    debug: false,
+
+    interpolation: {
+      escapeValue: false, // not needed for react as it escapes by default
+    },
+  })
+
+i18n.on("languageChanged", (lng) => {
+  if (lng.startsWith("zh")) {
+    dayjs.locale("zh-cn")
+  } else {
+    dayjs.locale("en")
+  }
+})
+
+export default i18n
diff --git a/web/frontend/src/i18n/locales/en.json b/web/frontend/src/i18n/locales/en.json
new file mode 100644
index 000000000..e966219e6
--- /dev/null
+++ b/web/frontend/src/i18n/locales/en.json
@@ -0,0 +1,507 @@
+{
+  "navigation": {
+    "chat": "Chat",
+    "model_group": "Models",
+    "models": "Models",
+    "credentials": "Credentials",
+    "agent_group": "Agent",
+    "skills": "Skills",
+    "tools": "Tools",
+    "services": "Services",
+    "channels_group": "Channels",
+    "show_more_channels": "More",
+    "show_less_channels": "Less",
+    "config": "Config",
+    "logs": "Logs"
+  },
+  "chat": {
+    "welcome": "How can I help you today?",
+    "welcomeDesc": "Ask me about weather, settings, or any other tasks. I'm here to assist you.",
+    "placeholder": "Start a new message...\nPress Enter to send, Shift + Enter for a new line",
+    "newChat": "New Chat",
+    "notConnected": "Gateway is not running. Start it to chat.",
+    "thinking": {
+      "step1": "Thinking...",
+      "step2": "Analyzing your request...",
+      "step3": "Preparing response...",
+      "step4": "Almost there..."
+    },
+    "history": "History",
+    "noHistory": "No chat history yet",
+    "historyLoadFailed": "Failed to load chat history",
+    "historyOpenFailed": "Failed to open this chat history",
+    "loadingMore": "Loading more...",
+    "deleteSession": "Delete session",
+    "messagesCount": "{{count}} messages",
+    "noModel": "Select model",
+    "empty": {
+      "noConfiguredModel": "No Model Configured",
+      "noConfiguredModelDescription": "You need to configure at least one AI model with an API key before you can start chatting.",
+      "goToModels": "Go to Models",
+      "noSelectedModel": "No Model Selected",
+      "noSelectedModelDescription": "You have configured models, but none is set as default. Select a model before starting chat.",
+      "notRunning": "Gateway Not Running",
+      "notRunningDescription": "Start the gateway service to begin chatting. Use the Start Gateway button in the top bar."
+    },
+    "modelGroup": {
+      "apikey": "API Key",
+      "oauth": "OAuth",
+      "local": "Local"
+    }
+  },
+  "header": {
+    "gateway": {
+      "stopDialog": {
+        "title": "Stop Gateway Service?",
+        "description": "Are you sure you want to stop the gateway? This will disconnect your active chat sessions and halt inference.",
+        "confirm": "Stop Gateway"
+      },
+      "action": {
+        "start": "Start Gateway",
+        "stop": "Stop Gateway",
+        "restart": "Restart Gateway"
+      },
+      "status": {
+        "starting": "Starting Gateway...",
+        "restarting": "Restarting Gateway...",
+        "stopping": "Stopping Gateway..."
+      },
+      "restartRequired": "Model changes require a gateway restart to take effect."
+    }
+  },
+  "common": {
+    "cancel": "Cancel",
+    "save": "Save",
+    "saving": "Saving...",
+    "reset": "Reset",
+    "confirm": "Confirm"
+  },
+  "labels": {
+    "loading": "Loading..."
+  },
+  "credentials": {
+    "description": "Manage OAuth and token-based credentials for supported providers.",
+    "loading": "Loading credentials...",
+    "providers": {
+      "openai": {
+        "description": "Supports browser OAuth, device code, and token login."
+      },
+      "anthropic": {
+        "description": "Uses token login for Claude access."
+      },
+      "antigravity": {
+        "description": "Uses browser OAuth for Google Cloud Code Assist."
+      }
+    },
+    "status": {
+      "connected": "Connected",
+      "needsRefresh": "Needs refresh",
+      "expired": "Expired",
+      "notLoggedIn": "Not logged in"
+    },
+    "actions": {
+      "browser": "Browser OAuth",
+      "deviceCode": "Device Code",
+      "stopLoading": "Stop Loading",
+      "saveToken": "Save",
+      "logout": "Logout"
+    },
+    "logoutDialog": {
+      "title": "Logout provider?",
+      "description": "This will remove your saved credential for {{provider}}."
+    },
+    "fields": {
+      "openaiToken": "OpenAI token",
+      "anthropicToken": "Anthropic token"
+    },
+    "labels": {
+      "account": "Account",
+      "email": "Email",
+      "project": "Project"
+    },
+    "errors": {
+      "loadFailed": "Failed to load credentials",
+      "flowFailed": "Failed to check authentication flow",
+      "loginFailed": "Login failed",
+      "logoutFailed": "Logout failed",
+      "invalidBrowserResponse": "Invalid browser login response",
+      "invalidDeviceResponse": "Invalid device code response",
+      "popupBlocked": "Unable to open a new tab. Please allow popups and try again."
+    },
+    "flow": {
+      "current": "Current authentication status",
+      "pending": "Waiting for authorization...",
+      "success": "Authentication successful",
+      "error": "Authentication failed",
+      "expired": "Authentication session expired"
+    },
+    "device": {
+      "title": "OpenAI Device Login",
+      "description": "Open the verification page and enter the code below. This page will refresh automatically.",
+      "code": "User Code",
+      "url": "Verification URL",
+      "polling": "Polling login status...",
+      "open": "Open Verification Page"
+    }
+  },
+  "models": {
+    "description": "Configure API keys for AI providers. Only configured models are available for chat.",
+    "loadError": "Failed to load models",
+    "noDefaultHintPrefix": "No default model set yet. Click",
+    "noDefaultHintSuffix": "to set one.",
+    "status": {
+      "configured": "Configured",
+      "unconfigured": "Not configured"
+    },
+    "badge": {
+      "default": "Default",
+      "virtual": "Virtual"
+    },
+    "action": {
+      "edit": "Edit API key",
+      "setDefault": "Set as default",
+      "delete": "Delete model"
+    },
+    "defaultOnSave": {
+      "label": "Default Model",
+      "description": "Automatically set this model as default after saving."
+    },
+    "add": {
+      "button": "Add Model",
+      "title": "Add Custom Model",
+      "description": "Add an OpenAI-compatible or native model endpoint.",
+      "modelName": "Model Alias",
+      "modelNamePlaceholder": "e.g. my-gpt4",
+      "modelNameHint": "A short name used to identify this model in conversations.",
+      "modelId": "Model Identifier",
+      "modelIdPlaceholder": "e.g. openai/gpt-4o",
+      "modelIdHint": "Format: protocol/model-id. Supported: openai, anthropic, gemini, groq, …",
+      "errorRequired": "This field is required.",
+      "errorDuplicateModelName": "Model alias already exists. Please use a different name.",
+      "saveError": "Failed to add model",
+      "confirm": "Add Model"
+    },
+    "delete": {
+      "title": "Delete Model?",
+      "description": "\"{{name}}\" will be permanently removed from your model list. This cannot be undone.",
+      "confirm": "Delete"
+    },
+    "advanced": {
+      "toggle": "Advanced options"
+    },
+    "field": {
+      "apiBase": "API Base URL",
+      "apiKey": "API Key",
+      "apiKeyPlaceholder": "Enter your API key",
+      "apiKeyPlaceholderSet": "Leave blank to keep existing key",
+      "proxy": "HTTP Proxy",
+      "proxyHint": "Optional. e.g. http://127.0.0.1:7890",
+      "authMethod": "Auth Method",
+      "authMethodHint": "Authentication method: oauth, token. Leave blank for API key auth.",
+      "connectMode": "Connect Mode",
+      "connectModeHint": "Connection mode for CLI-based providers: stdio or grpc.",
+      "workspace": "Workspace Path",
+      "workspaceHint": "Working directory for CLI-based providers (e.g. GitHub Copilot).",
+      "requestTimeout": "Request Timeout (s)",
+      "requestTimeoutHint": "Maximum seconds to wait for a response. 0 = use default.",
+      "rpm": "Rate Limit (RPM)",
+      "rpmHint": "Maximum requests per minute. 0 = no limit.",
+      "thinkingLevel": "Thinking Level",
+      "thinkingLevelHint": "Extended thinking budget: off, low, medium, high, xhigh, adaptive.",
+      "maxTokensField": "Max Tokens Field",
+      "maxTokensFieldHint": "Override the request field name for max tokens, e.g. max_completion_tokens."
+    },
+    "edit": {
+      "title": "Configure {{name}}",
+      "apiKeyHint": "A key is already set. Leave blank to keep it unchanged.",
+      "oauthNote": "This provider uses OAuth — no API key required.",
+      "saveError": "Failed to save"
+    }
+  },
+  "channels": {
+    "loadError": "Failed to load channels",
+    "edit": "Configure {{name}}",
+    "status": {
+      "configured": "Configured"
+    },
+    "name": {
+      "telegram": "Telegram",
+      "discord": "Discord",
+      "slack": "Slack",
+      "feishu": "Feishu",
+      "dingtalk": "DingTalk",
+      "line": "LINE",
+      "qq": "QQ",
+      "onebot": "OneBot",
+      "wecom": "WeCom",
+      "whatsapp": "WhatsApp",
+      "whatsapp_native": "WhatsApp Native",
+      "pico": "Web",
+      "maixcam": "MaixCam",
+      "matrix": "Matrix",
+      "irc": "IRC",
+      "weixin": "WeChat"
+    },
+    "weixin": {
+      "warningTitle": "Testing phase, use with caution",
+      "warningDesc": "The WeChat channel is still experimental and may carry a risk of account suspension. Use it only if you understand and accept the risk.",
+      "bindEnableSuccess": "WeChat connected and the channel has been enabled automatically.",
+      "bindTitle": "WeChat Account Binding",
+      "bindDesc": "Scan the QR code with WeChat to bind your personal account.",
+      "bind": "Bind WeChat",
+      "rebind": "Re-bind",
+      "bound": "WeChat Bound",
+      "notBound": "WeChat account not bound yet.",
+      "generating": "Generating QR code...",
+      "scanHint": "Open WeChat and scan the QR code",
+      "scanned": "Scanned — please confirm in WeChat",
+      "expired": "QR code expired",
+      "retry": "Try Again",
+      "refresh": "Refresh QR",
+      "errorGeneric": "An error occurred. Please try again."
+    },
+    "field": {
+      "token": "Bot Token",
+      "tokenPlaceholder": "Enter bot token",
+      "botToken": "Bot Token",
+      "appToken": "App Token",
+      "appId": "App ID",
+      "appSecret": "App Secret",
+      "verificationToken": "Verification Token",
+      "encryptKey": "Encrypt Key",
+      "baseUrl": "API Base URL",
+      "proxy": "HTTP Proxy",
+      "mentionOnly": "Mention Only",
+      "typingEnabled": "Typing Indicator",
+      "placeholderEnabled": "Placeholder Message",
+      "placeholderText": "Placeholder Text",
+      "groupTriggerMentionOnly": "Group Mention Only",
+      "groupTriggerPrefixes": "Group Trigger Prefixes",
+      "isLark": "Lark (International)",
+      "allowFrom": "Allow From",
+      "allowFromPlaceholder": "e.g. 123456, 789012",
+      "allowOrigins": "Allow Origins",
+      "allowOriginsPlaceholder": "e.g. https://example.com, http://localhost:5173",
+      "secretPlaceholder": "Enter secret",
+      "secretHintSet": "A value is already set. Leave blank to keep it unchanged."
+    },
+    "page": {
+      "notFound": "Channel \"{{name}}\" is not supported.",
+      "saveSuccess": "Channel configuration saved.",
+      "saveError": "Failed to save channel configuration",
+      "enabled": "enabled",
+      "docLink": "Documentation",
+      "enableLabel": "Enable channel",
+      "restartRequiredTitle": "Gateway restart required",
+      "restartRequiredDesc": "The latest {{name}} configuration has been saved. Restart the gateway for it to take effect."
+    },
+    "form": {
+      "desc": {
+        "token": "Bot access token used to connect to the platform API.",
+        "botToken": "Bot token used to send and receive messages.",
+        "appToken": "App token used for Socket Mode connections.",
+        "appId": "Unique application ID used for authentication.",
+        "appSecret": "Application secret used for signing and authentication.",
+        "verificationToken": "Verification token for event callbacks.",
+        "encryptKey": "Encryption key used to decrypt callback payloads.",
+        "baseUrl": "Platform API base URL. Official endpoint is used by default.",
+        "proxy": "HTTP proxy address for outbound network access.",
+        "mentionOnly": "Only respond when the bot is explicitly mentioned in group chats.",
+        "typingEnabled": "Display typing status while the assistant is generating a response.",
+        "placeholderEnabled": "Enable temporary placeholder messages before the final reply is sent.",
+        "groupTriggerMentionOnly": "In group chats, respond only when the bot is mentioned.",
+        "groupTriggerPrefixes": "Custom group-chat trigger prefixes, separated by commas.",
+        "isLark": "Use Lark international domain (open.larksuite.com) instead of Feishu domain (open.feishu.cn).",
+        "allowFrom": "Allowed user or group IDs, separated by commas.",
+        "allowOrigins": "Allowed origin domains, separated by commas.",
+        "wsUrl": "WebSocket service URL.",
+        "reconnectInterval": "Reconnect interval after disconnection (seconds).",
+        "bridgeUrl": "Bridge service URL.",
+        "sessionStorePath": "Local path for session storage.",
+        "useNative": "Whether to use native client mode.",
+        "host": "Service host address.",
+        "port": "Service port.",
+        "homeserver": "Matrix homeserver URL.",
+        "userId": "Account user ID.",
+        "deviceId": "Device ID.",
+        "joinOnInvite": "Automatically join rooms when invited.",
+        "clientId": "Client ID used for platform authentication.",
+        "corpId": "Enterprise Corp ID.",
+        "agentId": "Enterprise application Agent ID.",
+        "webhookUrl": "Full webhook URL.",
+        "webhookHost": "Webhook listening host.",
+        "webhookPort": "Webhook listening port.",
+        "webhookPath": "Webhook route path.",
+        "replyTimeout": "Reply timeout in seconds.",
+        "maxSteps": "Maximum number of processing steps.",
+        "welcomeMessage": "Welcome message content for new sessions.",
+        "allowTokenQuery": "Allow token in URL query parameters.",
+        "pingInterval": "Connection heartbeat interval in seconds.",
+        "readTimeout": "Read timeout in seconds.",
+        "writeTimeout": "Write timeout in seconds.",
+        "maxConnections": "Maximum number of concurrent connections.",
+        "server": "IRC server address.",
+        "tls": "Whether to enable TLS.",
+        "nick": "Bot nickname.",
+        "user": "IRC username.",
+        "realName": "Displayed real name.",
+        "channels": "IRC channels to join.",
+        "requestCaps": "IRC capability list requested on connect.",
+        "maxBase64FileSizeMiB": "Maximum size in MiB for converting local files to base64 before upload. 0 means unlimited. Applies only to local files, not URL uploads.",
+        "genericField": "Used to configure {{field}}."
+      }
+    },
+    "validation": {
+      "requiredField": "This field is required."
+    }
+  },
+  "pages": {
+    "agent": {
+      "load_error": "Failed to load agent support information.",
+      "skills": {
+        "description": "Skills are loaded from the workspace, global PicoClaw home, and builtin directories.",
+        "empty": "No skills are currently available.",
+        "import": "Import Skill",
+        "import_success": "Skill imported.",
+        "import_error": "Failed to import skill.",
+        "view": "View",
+        "delete": "Delete",
+        "delete_title": "Delete Skill?",
+        "delete_description": "\"{{name}}\" will be removed from workspace skills.",
+        "delete_confirm": "Delete",
+        "delete_success": "Skill deleted.",
+        "delete_error": "Failed to delete skill.",
+        "viewer_title": "Skill Content",
+        "viewer_description": "Read the current effective SKILL.md content here.",
+        "loading_detail": "Loading skill content...",
+        "load_detail_error": "Failed to load skill content.",
+        "path": "Skill Path",
+        "no_description": "No description provided."
+      },
+      "tools": {
+        "description": "This view reflects whether each agent tool is enabled, disabled, or blocked by a missing prerequisite.",
+        "empty": "No tools are available.",
+        "enable": "Enable",
+        "disable": "Disable",
+        "enable_success": "Tool enabled.",
+        "disable_success": "Tool disabled.",
+        "toggle_error": "Failed to update tool state.",
+        "config_key": "Controlled by tools.{{key}}",
+        "status": {
+          "enabled": "Enabled",
+          "disabled": "Disabled",
+          "blocked": "Blocked"
+        },
+        "categories": {
+          "automation": "Automation",
+          "filesystem": "Filesystem",
+          "web": "Web",
+          "communication": "Communication",
+          "skills": "Skills",
+          "agents": "Agents",
+          "hardware": "Hardware",
+          "discovery": "Discovery"
+        },
+        "reasons": {
+          "requires_linux": "This tool only works on Linux hosts with the required device files exposed.",
+          "requires_skills": "Enable `tools.skills` before this skill-registry tool can be used.",
+          "requires_subagent": "Enable `tools.subagent` before the spawn tool can delegate work.",
+          "requires_mcp_discovery": "Enable `tools.mcp.discovery` before MCP discovery tools become available."
+        }
+      }
+    },
+    "config": {
+      "load_error": "Failed to load configuration. Please refresh and try again.",
+      "workspace": "Workspace Directory",
+      "workspace_hint": "Base directory for agent file operations.",
+      "restrict_workspace": "Restrict to Workspace",
+      "restrict_workspace_hint": "Only allow file operations inside workspace.",
+      "tool_feedback_enabled": "Tool Feedback",
+      "tool_feedback_enabled_hint": "Send a short tool-call preview into the current chat before each tool execution.",
+      "tool_feedback_max_args_length": "Tool Feedback Args Preview Length",
+      "tool_feedback_max_args_length_hint": "Maximum number of argument characters shown in each tool feedback message. Set to 0 to use the default.",
+      "exec_enabled": "Allow Commands",
+      "exec_enabled_hint": "Enable or disable command execution for the app. When disabled, no command requests will run.",
+      "allow_remote": "Allow Remote Commands",
+      "allow_remote_hint": "When enabled, remote sessions or non-local contexts can also run commands. When disabled, command execution stays limited to local safe contexts.",
+      "enable_deny_patterns": "Enable Blacklist",
+      "enable_deny_patterns_hint": "When enabled, the app blocks commands that match its built-in dangerous patterns and the custom command blacklist below.",
+      "exec_timeout_seconds": "Command Timeout (seconds)",
+      "exec_timeout_seconds_hint": "Maximum runtime for command requests. Set to 0 to use the default timeout.",
+      "custom_deny_patterns": "Command Blacklist",
+      "custom_deny_patterns_hint": "Add extra command-blocking rules, one regular expression per line. A command matching any rule here will be blocked.",
+      "custom_allow_patterns": "Command Whitelist",
+      "custom_allow_patterns_hint": "Add extra command-allow rules, one regular expression per line. A command matching any rule here skips blacklist matching, but other safety limits still apply.",
+      "custom_patterns_placeholder": "^rm\\s+-rf\\b\n^git\\s+push\\b",
+      "allow_shell_execution": "Allow Scheduled Commands",
+      "allow_shell_execution_hint": "Allow scheduled tasks to run commands by default. When disabled, users must pass command_confirm=true to schedule a command task.",
+      "cron_exec_timeout": "Scheduled Command Timeout (minutes)",
+      "cron_exec_timeout_hint": "Maximum runtime for scheduled commands. Set to 0 to disable the timeout.",
+      "max_tokens": "Max Tokens",
+      "max_tokens_hint": "Upper token limit per model response.",
+      "context_window": "Context Window",
+      "context_window_hint": "Model input context capacity in tokens. Leave empty to use the default (4x max tokens).",
+      "max_tool_iterations": "Max Tool Iterations",
+      "max_tool_iterations_hint": "Maximum tool-call loops in a single task.",
+      "summarize_threshold": "Summarize Message Threshold",
+      "summarize_threshold_hint": "Start summarization after this many messages.",
+      "summarize_token_percent": "Summarize Token Percent",
+      "summarize_token_percent_hint": "Used when conversation summary is triggered.",
+      "session_scope": "Session Scope",
+      "session_scope_hint": "How chat context is isolated across peers/channels.",
+      "session_scope_per_channel_peer": "Per Channel + Peer",
+      "session_scope_per_channel_peer_desc": "Separate context for each user in each channel.",
+      "session_scope_per_channel": "Per Channel",
+      "session_scope_per_channel_desc": "One shared context per channel.",
+      "session_scope_per_peer": "Per Peer",
+      "session_scope_per_peer_desc": "One context per user across channels.",
+      "session_scope_global": "Global",
+      "session_scope_global_desc": "All messages share one global context.",
+      "heartbeat_enabled": "Heartbeat",
+      "heartbeat_enabled_hint": "Send periodic heartbeat messages.",
+      "heartbeat_interval": "Heartbeat Interval (minutes)",
+      "heartbeat_interval_hint": "Interval in minutes between heartbeat signals.",
+      "devices_enabled": "Enable Devices",
+      "devices_enabled_hint": "Enable hardware-device integrations.",
+      "monitor_usb": "Monitor USB",
+      "monitor_usb_hint": "Watch USB plug/unplug events when devices are enabled.",
+      "autostart_label": "Launch at Login",
+      "autostart_hint": "Start PicoClaw Web automatically when you log in.",
+      "autostart_unsupported": "Launch at login is not supported on this platform.",
+      "autostart_load_error": "Failed to load launch-at-login status.",
+      "server_port": "Service Port",
+      "server_port_hint": "HTTP port used by PicoClaw Web.",
+      "lan_access": "Enable LAN Access",
+      "lan_access_hint": "Allow access from other devices on your local network.",
+      "allowed_cidrs": "Allowed Network CIDRs",
+      "allowed_cidrs_hint": "Only clients from these CIDR ranges can access the service. One per line or comma-separated. Leave empty to allow all.",
+      "allowed_cidrs_placeholder": "192.168.1.0/24\n10.0.0.0/8",
+      "sections": {
+        "agent": "Agent",
+        "runtime": "Runtime",
+        "exec": "Run Commands",
+        "cron": "Cron Tasks",
+        "launcher": "Service",
+        "devices": "Devices"
+      },
+      "open_raw": "Raw Config",
+      "back_to_visual": "Visual Config",
+      "raw_json_title": "Raw JSON Configuration",
+      "json_placeholder": "Enter valid JSON configuration...",
+      "save_success": "Configuration saved successfully.",
+      "save_error": "Failed to save configuration.",
+      "reset_confirm_title": "Reset Changes",
+      "reset_confirm_desc": "Are you sure you want to reset your unsaved changes back to the last saved state?",
+      "reset_success": "Changes have been reset to the last saved state.",
+      "invalid_json": "Invalid JSON format.",
+      "format_success": "JSON formatted successfully.",
+      "format_error": "Invalid JSON format.",
+      "format": "Format",
+      "unsaved_changes": "You have unsaved changes."
+    },
+    "logs": {
+      "clear": "Clear logs",
+      "empty": "Waiting for logs..."
+    }
+  }
+}
diff --git a/web/frontend/src/i18n/locales/zh.json b/web/frontend/src/i18n/locales/zh.json
new file mode 100644
index 000000000..9657d78b1
--- /dev/null
+++ b/web/frontend/src/i18n/locales/zh.json
@@ -0,0 +1,507 @@
+{
+  "navigation": {
+    "chat": "对话",
+    "model_group": "模型",
+    "models": "模型",
+    "credentials": "凭据",
+    "agent_group": "智能体",
+    "skills": "技能",
+    "tools": "工具",
+    "services": "服务",
+    "channels_group": "频道",
+    "show_more_channels": "更多",
+    "show_less_channels": "收起",
+    "config": "配置",
+    "logs": "日志"
+  },
+  "chat": {
+    "welcome": "今天我能为您做些什么？",
+    "welcomeDesc": "您可以询问我天气、设置或其他任何任务，我随时为您效劳。",
+    "placeholder": "输入新消息...\n按 Enter 发送，Shift + Enter 换行",
+    "newChat": "新建对话",
+    "notConnected": "服务未运行，请先启动以进行对话。",
+    "thinking": {
+      "step1": "思考中...",
+      "step2": "分析您的请求...",
+      "step3": "准备回复...",
+      "step4": "马上就好..."
+    },
+    "history": "历史记录",
+    "noHistory": "暂无对话历史",
+    "historyLoadFailed": "加载历史记录失败",
+    "historyOpenFailed": "打开该历史会话失败",
+    "loadingMore": "加载更多...",
+    "deleteSession": "删除会话",
+    "messagesCount": "{{count}} 条消息",
+    "noModel": "选择模型",
+    "empty": {
+      "noConfiguredModel": "尚未配置模型",
+      "noConfiguredModelDescription": "请先配置至少一个带有 API Key 的 AI 模型，才能开始对话。",
+      "goToModels": "去模型页配置",
+      "noSelectedModel": "尚未设置模型",
+      "noSelectedModelDescription": "您已配置模型，但尚未设置默认模型。请选择一个模型后开始对话",
+      "notRunning": "服务尚未运行",
+      "notRunningDescription": "请先启动网关服务后再开始对话，可点击顶部栏中的「启动服务」按钮。"
+    },
+    "modelGroup": {
+      "apikey": "API Key",
+      "oauth": "OAuth",
+      "local": "本地模型"
+    }
+  },
+  "header": {
+    "gateway": {
+      "stopDialog": {
+        "title": "停止服务？",
+        "description": "您确定要停止服务吗？这将断开您当前活动的聊天会话并停止推理。",
+        "confirm": "停止服务"
+      },
+      "action": {
+        "start": "启动服务",
+        "stop": "停止服务",
+        "restart": "重启服务"
+      },
+      "status": {
+        "starting": "服务启动中...",
+        "restarting": "服务重启中...",
+        "stopping": "服务停止中..."
+      },
+      "restartRequired": "切换默认模型后需要重启服务才能生效。"
+    }
+  },
+  "common": {
+    "cancel": "取消",
+    "save": "保存",
+    "saving": "保存中...",
+    "reset": "重置",
+    "confirm": "确认"
+  },
+  "labels": {
+    "loading": "加载中..."
+  },
+  "credentials": {
+    "description": "管理已支持服务商的 OAuth 与 Token 凭据。",
+    "loading": "正在加载凭据...",
+    "providers": {
+      "openai": {
+        "description": "支持浏览器 OAuth、设备码和 Token 登录。"
+      },
+      "anthropic": {
+        "description": "使用 Token 登录 Claude。"
+      },
+      "antigravity": {
+        "description": "使用浏览器 OAuth 登录 Google Cloud Code Assist。"
+      }
+    },
+    "status": {
+      "connected": "已连接",
+      "needsRefresh": "即将过期",
+      "expired": "已过期",
+      "notLoggedIn": "未登录"
+    },
+    "actions": {
+      "browser": "浏览器 OAuth",
+      "deviceCode": "设备码",
+      "stopLoading": "停止加载",
+      "saveToken": "保存",
+      "logout": "退出登录"
+    },
+    "logoutDialog": {
+      "title": "确认退出登录？",
+      "description": "这将删除 {{provider}} 的已保存凭据。"
+    },
+    "fields": {
+      "openaiToken": "OpenAI Token",
+      "anthropicToken": "Anthropic Token"
+    },
+    "labels": {
+      "account": "账号",
+      "email": "邮箱",
+      "project": "项目"
+    },
+    "errors": {
+      "loadFailed": "加载凭据失败",
+      "flowFailed": "查询授权流程失败",
+      "loginFailed": "登录失败",
+      "logoutFailed": "退出登录失败",
+      "invalidBrowserResponse": "浏览器登录响应无效",
+      "invalidDeviceResponse": "设备码响应无效",
+      "popupBlocked": "无法打开新标签页，请允许弹窗后重试。"
+    },
+    "flow": {
+      "current": "当前授权状态",
+      "pending": "等待授权中...",
+      "success": "认证成功",
+      "error": "认证失败",
+      "expired": "授权会话已过期"
+    },
+    "device": {
+      "title": "OpenAI 设备码登录",
+      "description": "请打开验证页面并输入下方代码，此页面会自动刷新授权状态。",
+      "code": "用户代码",
+      "url": "验证地址",
+      "polling": "正在轮询登录状态...",
+      "open": "打开验证页面"
+    }
+  },
+  "models": {
+    "description": "为 AI 服务商配置 API Key。只有已配置的模型可用于对话。",
+    "loadError": "加载模型列表失败",
+    "noDefaultHintPrefix": "尚未设置默认模型，点击",
+    "noDefaultHintSuffix": "设为默认。",
+    "status": {
+      "configured": "已配置",
+      "unconfigured": "未配置"
+    },
+    "badge": {
+      "default": "默认",
+      "virtual": "虚拟"
+    },
+    "action": {
+      "edit": "编辑 API Key",
+      "setDefault": "设为默认",
+      "delete": "删除模型"
+    },
+    "defaultOnSave": {
+      "label": "默认模型",
+      "description": "保存后自动将该模型设置为默认模型。"
+    },
+    "add": {
+      "button": "添加模型",
+      "title": "添加自定义模型",
+      "description": "添加兼容 OpenAI 或原生协议的模型端点。",
+      "modelName": "模型别名",
+      "modelNamePlaceholder": "例如 my-gpt4",
+      "modelNameHint": "用于在对话中识别此模型的简短名称。",
+      "modelId": "模型标识符",
+      "modelIdPlaceholder": "例如 openai/gpt-4o",
+      "modelIdHint": "格式：协议/模型ID。支持：openai、anthropic、gemini、groq 等。",
+      "errorRequired": "此字段为必填项。",
+      "errorDuplicateModelName": "模型别名已存在，请使用其他名称。",
+      "saveError": "添加模型失败",
+      "confirm": "添加模型"
+    },
+    "delete": {
+      "title": "确认删除模型？",
+      "description": "「{{name}}」将从模型列表中永久移除，此操作不可撤销。",
+      "confirm": "删除"
+    },
+    "advanced": {
+      "toggle": "高级选项"
+    },
+    "field": {
+      "apiBase": "API Base URL",
+      "apiKey": "API Key",
+      "apiKeyPlaceholder": "请输入 API Key",
+      "apiKeyPlaceholderSet": "留空保持原有 Key 不变",
+      "proxy": "HTTP 代理",
+      "proxyHint": "可选。例如 http://127.0.0.1:7890",
+      "authMethod": "认证方式",
+      "authMethodHint": "认证方式：oauth、token。留空表示使用 API Key 认证。",
+      "connectMode": "连接模式",
+      "connectModeHint": "CLI 型服务商的连接模式：stdio 或 grpc。",
+      "workspace": "工作目录",
+      "workspaceHint": "CLI 型服务商的工作目录路径（如 GitHub Copilot）。",
+      "requestTimeout": "请求超时（秒）",
+      "requestTimeoutHint": "等待响应的最大秒数，0 表示使用默认值。",
+      "rpm": "速率限制（RPM）",
+      "rpmHint": "每分钟最大请求数，0 表示不限制。",
+      "thinkingLevel": "思考级别",
+      "thinkingLevelHint": "扩展思考预算：off、low、medium、high、xhigh、adaptive。",
+      "maxTokensField": "Max Tokens 字段名",
+      "maxTokensFieldHint": "覆盖请求中 max_tokens 的字段名，例如 max_completion_tokens。"
+    },
+    "edit": {
+      "title": "配置 {{name}}",
+      "apiKeyHint": "已设置 API Key，留空表示不修改。",
+      "oauthNote": "该服务商使用 OAuth 认证，无需 API Key。",
+      "saveError": "保存失败"
+    }
+  },
+  "channels": {
+    "loadError": "加载频道列表失败",
+    "edit": "配置 {{name}}",
+    "status": {
+      "configured": "已配置"
+    },
+    "name": {
+      "telegram": "Telegram",
+      "discord": "Discord",
+      "slack": "Slack",
+      "feishu": "飞书",
+      "dingtalk": "钉钉",
+      "line": "LINE",
+      "qq": "QQ",
+      "onebot": "OneBot",
+      "wecom": "企业微信",
+      "whatsapp": "WhatsApp",
+      "whatsapp_native": "WhatsApp Native",
+      "pico": "Web",
+      "maixcam": "MaixCam",
+      "matrix": "Matrix",
+      "irc": "IRC",
+      "weixin": "微信"
+    },
+    "weixin": {
+      "warningTitle": "测试阶段，请谨慎使用",
+      "warningDesc": "微信 Channel 当前仍处于测试阶段，存在封号风险。请仅在充分了解风险的前提下使用。",
+      "bindEnableSuccess": "微信已连接，频道已自动启用。",
+      "bindTitle": "微信账号绑定",
+      "bindDesc": "使用微信扫描二维码以绑定您的个人微信账号。",
+      "bind": "绑定微信",
+      "rebind": "重新绑定",
+      "bound": "微信已绑定",
+      "notBound": "尚未绑定微信账号。",
+      "generating": "正在生成二维码...",
+      "scanHint": "打开微信，扫描二维码",
+      "scanned": "已扫码 — 请在微信中确认",
+      "expired": "二维码已过期",
+      "retry": "重试",
+      "refresh": "刷新二维码",
+      "errorGeneric": "发生错误，请重试。"
+    },
+    "field": {
+      "token": "Bot Token",
+      "tokenPlaceholder": "输入 Bot Token",
+      "botToken": "Bot Token",
+      "appToken": "App Token",
+      "appId": "App ID",
+      "appSecret": "App Secret",
+      "verificationToken": "Verification Token",
+      "encryptKey": "Encrypt Key",
+      "baseUrl": "API Base URL",
+      "proxy": "HTTP 代理",
+      "mentionOnly": "仅提及时响应",
+      "typingEnabled": "输入中提示",
+      "placeholderEnabled": "占位消息",
+      "placeholderText": "占位文案",
+      "groupTriggerMentionOnly": "群聊仅提及时响应",
+      "groupTriggerPrefixes": "群聊触发前缀",
+      "isLark": "Lark（国际版）",
+      "allowFrom": "允许来源",
+      "allowFromPlaceholder": "例如 123456, 789012",
+      "allowOrigins": "允许来源域名",
+      "allowOriginsPlaceholder": "例如 https://example.com, http://localhost:5173",
+      "secretPlaceholder": "输入密钥",
+      "secretHintSet": "已设置密钥，留空表示不修改。"
+    },
+    "page": {
+      "notFound": "不支持频道“{{name}}”。",
+      "saveSuccess": "频道配置已保存。",
+      "saveError": "保存频道配置失败",
+      "enabled": "已启用",
+      "docLink": "配置文档",
+      "enableLabel": "启用频道",
+      "restartRequiredTitle": "需要重启服务",
+      "restartRequiredDesc": "{{name}} 的最新配置已保存。重启服务后才能正式生效。"
+    },
+    "form": {
+      "desc": {
+        "token": "机器人访问令牌，用于连接平台 API。",
+        "botToken": "Bot Token，用于发送与接收消息。",
+        "appToken": "App Token，用于 Socket 模式连接。",
+        "appId": "应用唯一标识，用于平台鉴权。",
+        "appSecret": "应用密钥，用于请求签名和鉴权。",
+        "verificationToken": "事件回调验证令牌。",
+        "encryptKey": "消息加密密钥，用于解密回调内容。",
+        "baseUrl": "平台 API 地址，默认使用官方地址。",
+        "proxy": "HTTP 代理地址，用于网络访问。",
+        "mentionOnly": "在群聊中仅当明确提及时才响应。",
+        "typingEnabled": "在生成回复时显示“正在输入”状态。",
+        "placeholderEnabled": "在最终回复发送前，先发送临时占位消息。",
+        "groupTriggerMentionOnly": "在群聊中仅当提及机器人时才响应。",
+        "groupTriggerPrefixes": "群聊触发前缀，多个值用逗号分隔。",
+        "isLark": "使用 Lark 国际版域名（open.larksuite.com）替代飞书域名（open.feishu.cn）。",
+        "allowFrom": "允许访问的用户或群组 ID，多个值用逗号分隔。",
+        "allowOrigins": "允许访问的来源域名，多个值用逗号分隔。",
+        "wsUrl": "WebSocket 服务地址。",
+        "reconnectInterval": "断线后的重连间隔（秒）。",
+        "bridgeUrl": "桥接服务地址。",
+        "sessionStorePath": "本地会话存储目录路径。",
+        "useNative": "是否使用原生客户端模式连接。",
+        "host": "服务监听主机地址。",
+        "port": "服务监听端口。",
+        "homeserver": "Matrix homeserver 地址。",
+        "userId": "账号 ID。",
+        "deviceId": "设备 ID。",
+        "joinOnInvite": "收到邀请时是否自动加入房间。",
+        "clientId": "应用客户端 ID，用于平台鉴权。",
+        "corpId": "企业 ID。",
+        "agentId": "企业应用 Agent ID。",
+        "webhookUrl": "Webhook 完整地址。",
+        "webhookHost": "Webhook 监听主机。",
+        "webhookPort": "Webhook 监听端口。",
+        "webhookPath": "Webhook 路径。",
+        "replyTimeout": "回复超时时间（秒）。",
+        "maxSteps": "最大步骤数。",
+        "welcomeMessage": "新会话欢迎语内容。",
+        "allowTokenQuery": "是否允许 URL Query 方式传递 Token。",
+        "pingInterval": "连接心跳间隔（秒）。",
+        "readTimeout": "读取超时时间（秒）。",
+        "writeTimeout": "写入超时时间（秒）。",
+        "maxConnections": "最大并发连接数。",
+        "server": "IRC 服务器地址。",
+        "tls": "是否启用 TLS 连接。",
+        "nick": "机器人昵称。",
+        "user": "IRC 用户名。",
+        "realName": "显示名称。",
+        "channels": "要加入的 IRC 频道列表。",
+        "requestCaps": "连接时请求的 IRC 扩展能力列表。",
+        "maxBase64FileSizeMiB": "本地文件转为 base64 上传的最大体积，单位 MiB；0 表示不限制，仅影响本地文件，不影响 URL 直传。",
+        "genericField": "用于配置{{field}}。"
+      }
+    },
+    "validation": {
+      "requiredField": "请填写该字段"
+    }
+  },
+  "pages": {
+    "agent": {
+      "load_error": "加载 Agent 支持信息失败。",
+      "skills": {
+        "description": "技能会从工作区、PicoClaw 全局目录和内置目录中加载。",
+        "empty": "当前没有可用技能。",
+        "import": "导入技能",
+        "import_success": "技能导入成功。",
+        "import_error": "导入技能失败。",
+        "view": "查看",
+        "delete": "删除",
+        "delete_title": "删除技能？",
+        "delete_description": "将从工作区技能中移除「{{name}}」。",
+        "delete_confirm": "删除",
+        "delete_success": "技能已删除。",
+        "delete_error": "删除技能失败。",
+        "viewer_title": "技能内容",
+        "viewer_description": "这里展示当前生效的 SKILL.md 内容。",
+        "loading_detail": "正在加载技能内容...",
+        "load_detail_error": "加载技能内容失败。",
+        "path": "技能路径",
+        "no_description": "未提供描述。"
+      },
+      "tools": {
+        "description": "这里展示每个 Agent 工具当前是已启用、已禁用，还是被依赖条件阻塞。",
+        "empty": "当前没有可用工具。",
+        "enable": "启用",
+        "disable": "禁用",
+        "enable_success": "工具已启用。",
+        "disable_success": "工具已禁用。",
+        "toggle_error": "更新工具状态失败。",
+        "config_key": "由 tools.{{key}} 控制",
+        "status": {
+          "enabled": "已启用",
+          "disabled": "已禁用",
+          "blocked": "被阻塞"
+        },
+        "categories": {
+          "automation": "自动化",
+          "filesystem": "文件系统",
+          "web": "网页",
+          "communication": "通信",
+          "skills": "技能",
+          "agents": "Agent",
+          "hardware": "硬件",
+          "discovery": "发现"
+        },
+        "reasons": {
+          "requires_linux": "该工具仅在 Linux 主机上可用，并且需要暴露对应的设备文件。",
+          "requires_skills": "需要先启用 `tools.skills`，该技能注册表工具才能使用。",
+          "requires_subagent": "需要先启用 `tools.subagent`，`spawn` 才能委派任务。",
+          "requires_mcp_discovery": "需要先启用 `tools.mcp.discovery`，MCP 发现工具才会可用。"
+        }
+      }
+    },
+    "config": {
+      "load_error": "加载配置失败，请刷新后重试。",
+      "workspace": "工作目录",
+      "workspace_hint": "智能体执行文件读写操作时使用的基础目录。",
+      "restrict_workspace": "限制工作目录访问",
+      "restrict_workspace_hint": "仅允许在工作目录内执行文件操作。",
+      "tool_feedback_enabled": "工具反馈",
+      "tool_feedback_enabled_hint": "在每次执行工具前，先向当前会话发送一条简短的工具调用预览。",
+      "tool_feedback_max_args_length": "工具反馈参数预览长度",
+      "tool_feedback_max_args_length_hint": "每条工具反馈消息中展示的参数字符上限。设为 0 时使用默认值。",
+      "exec_enabled": "允许命令执行",
+      "exec_enabled_hint": "控制应用是否允许执行命令。关闭后，所有命令请求都不会执行。",
+      "allow_remote": "允许远程命令执行",
+      "allow_remote_hint": "开启后，来自远程会话或非本地上下文的请求也可以执行命令；关闭后，仅允许本地安全上下文执行命令。",
+      "enable_deny_patterns": "启用黑名单",
+      "enable_deny_patterns_hint": "开启后，应用会拦截匹配内置危险模式以及下方自定义命令黑名单的命令。",
+      "exec_timeout_seconds": "命令超时（秒）",
+      "exec_timeout_seconds_hint": "命令请求的最长运行时间。设置为 0 表示使用默认超时。",
+      "custom_deny_patterns": "命令黑名单",
+      "custom_deny_patterns_hint": "用于补充额外的命令拦截规则，每行一个正则表达式。命中任意一条规则的命令都会被阻止。",
+      "custom_allow_patterns": "命令白名单",
+      "custom_allow_patterns_hint": "用于补充额外的命令放行规则，每行一个正则表达式。命中任意一条规则的命令会跳过黑名单检查，但仍受其他安全限制约束。",
+      "custom_patterns_placeholder": "^rm\\s+-rf\\b\n^git\\s+push\\b",
+      "allow_shell_execution": "允许定时任务运行命令",
+      "allow_shell_execution_hint": "开启后，定时任务默认允许运行命令。关闭后，必须显式传入 command_confirm=true 才能创建运行命令的定时任务。",
+      "cron_exec_timeout": "定时命令超时（分钟）",
+      "cron_exec_timeout_hint": "定时任务中命令的最长运行时间。设置为 0 表示不限制超时。",
+      "max_tokens": "最大 Token 数",
+      "max_tokens_hint": "单次模型响应允许的最大 Token 数。",
+      "context_window": "上下文窗口",
+      "context_window_hint": "模型输入上下文容量（Token 数）。留空使用默认值（最大 Token 数的 4 倍）。",
+      "max_tool_iterations": "最大工具迭代次数",
+      "max_tool_iterations_hint": "单个任务中允许的工具调用循环上限。",
+      "summarize_threshold": "触发摘要的消息阈值",
+      "summarize_threshold_hint": "消息数量达到该值后开始触发摘要。",
+      "summarize_token_percent": "摘要目标 Token 百分比",
+      "summarize_token_percent_hint": "在触发会话摘要时使用。",
+      "session_scope": "会话隔离范围",
+      "session_scope_hint": "定义不同用户/频道之间如何隔离会话上下文。",
+      "session_scope_per_channel_peer": "按频道+用户隔离",
+      "session_scope_per_channel_peer_desc": "同一频道内不同用户使用独立上下文。",
+      "session_scope_per_channel": "按频道隔离",
+      "session_scope_per_channel_desc": "同一频道内共享一个上下文。",
+      "session_scope_per_peer": "按用户隔离",
+      "session_scope_per_peer_desc": "同一用户跨频道共享一个上下文。",
+      "session_scope_global": "全局共享",
+      "session_scope_global_desc": "所有消息共用一个全局上下文。",
+      "heartbeat_enabled": "心跳开关",
+      "heartbeat_enabled_hint": "按间隔发送系统心跳。",
+      "heartbeat_interval": "心跳间隔（分钟）",
+      "heartbeat_interval_hint": "两次心跳发送之间的分钟间隔。",
+      "devices_enabled": "启用设备功能",
+      "devices_enabled_hint": "启用与本机硬件设备相关的能力。",
+      "monitor_usb": "监听 USB",
+      "monitor_usb_hint": "在启用设备功能时，监听 USB 插拔事件。",
+      "autostart_label": "开机自启",
+      "autostart_hint": "登录系统后自动启动 PicoClaw Web。",
+      "autostart_unsupported": "当前平台不支持开机自启。",
+      "autostart_load_error": "加载开机自启状态失败。",
+      "server_port": "服务端口",
+      "server_port_hint": "PicoClaw Web 的 HTTP 监听端口。",
+      "lan_access": "启用局域网访问",
+      "lan_access_hint": "允许局域网中的其他设备访问当前服务。",
+      "allowed_cidrs": "允许访问网段",
+      "allowed_cidrs_hint": "仅允许这些 CIDR 网段的客户端访问服务。可按行或逗号分隔；留空表示允许所有来源。",
+      "allowed_cidrs_placeholder": "192.168.1.0/24\n10.0.0.0/8",
+      "sections": {
+        "agent": "智能体",
+        "runtime": "运行时",
+        "exec": "运行命令",
+        "cron": "定时任务",
+        "launcher": "服务参数",
+        "devices": "设备"
+      },
+      "open_raw": "原始配置",
+      "back_to_visual": "可视化配置",
+      "raw_json_title": "原始 JSON 配置",
+      "json_placeholder": "请输入有效的 JSON 配置...",
+      "save_success": "配置保存成功。",
+      "save_error": "配置保存失败。",
+      "reset_confirm_title": "重置更改",
+      "reset_confirm_desc": "您确定要重置回上次保存的状态吗？",
+      "reset_success": "更改已重置为上次保存的状态。",
+      "invalid_json": "JSON 格式无效。",
+      "format_success": "JSON 格式化成功。",
+      "format_error": "JSON 格式无效。",
+      "format": "格式化",
+      "unsaved_changes": "您有未保存的更改。"
+    },
+    "logs": {
+      "clear": "清空日志",
+      "empty": "等待日志中..."
+    }
+  }
+}
diff --git a/web/frontend/src/index.css b/web/frontend/src/index.css
new file mode 100644
index 000000000..fc55a3a32
--- /dev/null
+++ b/web/frontend/src/index.css
@@ -0,0 +1,181 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "@fontsource-variable/inter";
+@plugin "@tailwindcss/typography";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) + 8px);
+  --radius-3xl: calc(var(--radius) + 12px);
+  --radius-4xl: calc(var(--radius) + 16px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+}
+
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.646 0.222 41.116);
+  --chart-2: oklch(0.6 0.118 184.704);
+  --chart-3: oklch(0.398 0.07 227.392);
+  --chart-4: oklch(0.828 0.189 84.429);
+  --chart-5: oklch(0.769 0.188 70.08);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.556 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+    scrollbar-width: thin;
+    scrollbar-color: var(--border) transparent;
+  }
+
+  body {
+    @apply bg-background text-foreground;
+  }
+
+  /* WebKit Custom Scrollbar */
+  ::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+
+  ::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  ::-webkit-scrollbar-thumb {
+    background: var(--border);
+    border-radius: 4px;
+  }
+
+  ::-webkit-scrollbar-thumb:hover {
+    background: var(--muted-foreground);
+  }
+}
+
+/* Offset sidebar below the full-width header */
+[data-slot="sidebar-container"] {
+  top: 3.5rem !important;
+  height: calc(100svh - 3.5rem) !important;
+}
+
+[data-slot="sidebar-gap"] {
+  height: calc(100svh - 3.5rem);
+}
+
+/* Typing indicator animations */
+@keyframes shimmer {
+  0% {
+    background-position: 200% 0;
+  }
+
+  100% {
+    background-position: -200% 0;
+  }
+}
+
+@keyframes fadeSlideIn {
+  0% {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+
+  100% {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
diff --git a/web/frontend/src/lib/ansi-log.ts b/web/frontend/src/lib/ansi-log.ts
new file mode 100644
index 000000000..39561fb98
--- /dev/null
+++ b/web/frontend/src/lib/ansi-log.ts
@@ -0,0 +1,290 @@
+import type { CSSProperties } from "react"
+import wrapAnsi from "wrap-ansi"
+
+export type AnsiSegment = {
+  style: CSSProperties
+  text: string
+}
+
+type AnsiState = {
+  background?: string
+  bold?: boolean
+  dim?: boolean
+  foreground?: string
+  italic?: boolean
+  strikethrough?: boolean
+  underline?: boolean
+  underlineColor?: string
+}
+
+const ANSI_PATTERN = new RegExp(String.raw`\u001B\[([0-9;]*)m`, "g")
+
+const ANSI_COLORS = [
+  "#4b5563",
+  "#f87171",
+  "#4ade80",
+  "#facc15",
+  "#60a5fa",
+  "#c084fc",
+  "#22d3ee",
+  "#f3f4f6",
+]
+
+const ANSI_BRIGHT_COLORS = [
+  "#6b7280",
+  "#fb7185",
+  "#86efac",
+  "#fde047",
+  "#93c5fd",
+  "#e879f9",
+  "#67e8f9",
+  "#ffffff",
+]
+
+function cloneAnsiState(state: AnsiState): AnsiState {
+  return { ...state }
+}
+
+function ansi256ToHex(code: number): string {
+  if (code < 0 || code > 255) {
+    return "inherit"
+  }
+
+  if (code < 8) {
+    return ANSI_COLORS[code]
+  }
+
+  if (code < 16) {
+    return ANSI_BRIGHT_COLORS[code - 8]
+  }
+
+  if (code < 232) {
+    const index = code - 16
+    const red = Math.floor(index / 36)
+    const green = Math.floor((index % 36) / 6)
+    const blue = index % 6
+    const scale = [0, 95, 135, 175, 215, 255]
+    return `rgb(${scale[red]}, ${scale[green]}, ${scale[blue]})`
+  }
+
+  const gray = 8 + (code - 232) * 10
+  return `rgb(${gray}, ${gray}, ${gray})`
+}
+
+function codeToColor(code: number): string | undefined {
+  if (code >= 30 && code <= 37) {
+    return ANSI_COLORS[code - 30]
+  }
+
+  if (code >= 40 && code <= 47) {
+    return ANSI_COLORS[code - 40]
+  }
+
+  if (code >= 90 && code <= 97) {
+    return ANSI_BRIGHT_COLORS[code - 90]
+  }
+
+  if (code >= 100 && code <= 107) {
+    return ANSI_BRIGHT_COLORS[code - 100]
+  }
+
+  if (code === 39 || code === 49) {
+    return undefined
+  }
+}
+
+function applyExtendedColor(
+  state: AnsiState,
+  codes: number[],
+  index: number,
+  target: "foreground" | "background" | "underlineColor",
+): number {
+  const mode = codes[index + 1]
+
+  if (mode === 5) {
+    const colorCode = codes[index + 2]
+    if (colorCode !== undefined) {
+      state[target] = ansi256ToHex(colorCode)
+      return index + 2
+    }
+  }
+
+  if (mode === 2) {
+    const red = codes[index + 2]
+    const green = codes[index + 3]
+    const blue = codes[index + 4]
+    if (red !== undefined && green !== undefined && blue !== undefined) {
+      state[target] = `rgb(${red}, ${green}, ${blue})`
+      return index + 4
+    }
+  }
+
+  return index
+}
+
+function styleToCss(style: AnsiState): CSSProperties {
+  return {
+    backgroundColor: style.background,
+    color: style.foreground,
+    fontStyle: style.italic ? "italic" : undefined,
+    fontWeight: style.bold ? 700 : undefined,
+    opacity: style.dim ? 0.7 : undefined,
+    textDecorationColor: style.underlineColor,
+    textDecorationLine:
+      [
+        style.underline ? "underline" : "",
+        style.strikethrough ? "line-through" : "",
+      ]
+        .filter(Boolean)
+        .join(" ") || undefined,
+  }
+}
+
+export function parseAnsiSegments(input: string): AnsiSegment[] {
+  const segments: AnsiSegment[] = []
+  const state: AnsiState = {}
+  let lastIndex = 0
+  let match: RegExpExecArray | null
+
+  const pushText = (text: string) => {
+    if (!text) {
+      return
+    }
+
+    segments.push({
+      style: styleToCss(cloneAnsiState(state)),
+      text,
+    })
+  }
+
+  ANSI_PATTERN.lastIndex = 0
+
+  while ((match = ANSI_PATTERN.exec(input)) !== null) {
+    pushText(input.slice(lastIndex, match.index))
+
+    const codes = (match[1] || "0")
+      .split(";")
+      .map((value) => (value === "" ? 0 : Number.parseInt(value, 10)))
+      .filter((value) => Number.isFinite(value))
+
+    for (let index = 0; index < codes.length; index += 1) {
+      const code = codes[index]
+
+      if (code === 0) {
+        Object.keys(state).forEach((key) => {
+          delete state[key as keyof AnsiState]
+        })
+        continue
+      }
+
+      if (code === 1) {
+        state.bold = true
+        continue
+      }
+
+      if (code === 2) {
+        state.dim = true
+        continue
+      }
+
+      if (code === 3) {
+        state.italic = true
+        continue
+      }
+
+      if (code === 4) {
+        state.underline = true
+        continue
+      }
+
+      if (code === 9) {
+        state.strikethrough = true
+        continue
+      }
+
+      if (code === 21 || code === 22) {
+        delete state.bold
+        delete state.dim
+        continue
+      }
+
+      if (code === 23) {
+        delete state.italic
+        continue
+      }
+
+      if (code === 24) {
+        delete state.underline
+        continue
+      }
+
+      if (code === 29) {
+        delete state.strikethrough
+        continue
+      }
+
+      if (code === 39) {
+        delete state.foreground
+        continue
+      }
+
+      if (code === 49) {
+        delete state.background
+        continue
+      }
+
+      if (code === 59) {
+        delete state.underlineColor
+        continue
+      }
+
+      if (code === 38) {
+        index = applyExtendedColor(state, codes, index, "foreground")
+        continue
+      }
+
+      if (code === 48) {
+        index = applyExtendedColor(state, codes, index, "background")
+        continue
+      }
+
+      if (code === 58) {
+        index = applyExtendedColor(state, codes, index, "underlineColor")
+        continue
+      }
+
+      if ((code >= 30 && code <= 37) || (code >= 90 && code <= 97)) {
+        state.foreground = codeToColor(code)
+        continue
+      }
+
+      if ((code >= 40 && code <= 47) || (code >= 100 && code <= 107)) {
+        state.background = codeToColor(code)
+      }
+    }
+
+    lastIndex = ANSI_PATTERN.lastIndex
+  }
+
+  pushText(input.slice(lastIndex))
+
+  if (segments.length === 0) {
+    return [{ style: {}, text: input }]
+  }
+
+  return segments
+}
+
+export function wrapLogLine(line: string, columns: number): string {
+  const normalized = line.replaceAll("\r\n", "\n").replaceAll("\r", "\n")
+
+  if (columns < 20) {
+    return normalized
+  }
+
+  return wrapAnsi(normalized, columns, {
+    hard: true,
+    trim: false,
+    wordWrap: false,
+  })
+}
diff --git a/web/frontend/src/lib/utils.ts b/web/frontend/src/lib/utils.ts
new file mode 100644
index 000000000..d084ccade
--- /dev/null
+++ b/web/frontend/src/lib/utils.ts
@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
diff --git a/web/frontend/src/main.tsx b/web/frontend/src/main.tsx
new file mode 100644
index 000000000..81e72c29f
--- /dev/null
+++ b/web/frontend/src/main.tsx
@@ -0,0 +1,35 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query"
+import { RouterProvider, createRouter } from "@tanstack/react-router"
+import { StrictMode } from "react"
+import ReactDOM from "react-dom/client"
+
+import "./i18n"
+import "./index.css"
+import { routeTree } from "./routeTree.gen"
+
+const queryClient = new QueryClient()
+
+const router = createRouter({
+  routeTree,
+  context: {
+    queryClient,
+  },
+})
+
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: typeof router
+  }
+}
+
+const rootElement = document.getElementById("root")!
+if (!rootElement.innerHTML) {
+  const root = ReactDOM.createRoot(rootElement)
+  root.render(
+    <StrictMode>
+      <QueryClientProvider client={queryClient}>
+        <RouterProvider router={router} />
+      </QueryClientProvider>
+    </StrictMode>,
+  )
+}
diff --git a/web/frontend/src/routeTree.gen.ts b/web/frontend/src/routeTree.gen.ts
new file mode 100644
index 000000000..60f19ab53
--- /dev/null
+++ b/web/frontend/src/routeTree.gen.ts
@@ -0,0 +1,300 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as ModelsRouteImport } from './routes/models'
+import { Route as LogsRouteImport } from './routes/logs'
+import { Route as CredentialsRouteImport } from './routes/credentials'
+import { Route as ConfigRouteImport } from './routes/config'
+import { Route as AgentRouteImport } from './routes/agent'
+import { Route as ChannelsRouteRouteImport } from './routes/channels/route'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as ConfigRawRouteImport } from './routes/config.raw'
+import { Route as ChannelsNameRouteImport } from './routes/channels/$name'
+import { Route as AgentToolsRouteImport } from './routes/agent/tools'
+import { Route as AgentSkillsRouteImport } from './routes/agent/skills'
+
+const ModelsRoute = ModelsRouteImport.update({
+  id: '/models',
+  path: '/models',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const LogsRoute = LogsRouteImport.update({
+  id: '/logs',
+  path: '/logs',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const CredentialsRoute = CredentialsRouteImport.update({
+  id: '/credentials',
+  path: '/credentials',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ConfigRoute = ConfigRouteImport.update({
+  id: '/config',
+  path: '/config',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const AgentRoute = AgentRouteImport.update({
+  id: '/agent',
+  path: '/agent',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ChannelsRouteRoute = ChannelsRouteRouteImport.update({
+  id: '/channels',
+  path: '/channels',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ConfigRawRoute = ConfigRawRouteImport.update({
+  id: '/raw',
+  path: '/raw',
+  getParentRoute: () => ConfigRoute,
+} as any)
+const ChannelsNameRoute = ChannelsNameRouteImport.update({
+  id: '/$name',
+  path: '/$name',
+  getParentRoute: () => ChannelsRouteRoute,
+} as any)
+const AgentToolsRoute = AgentToolsRouteImport.update({
+  id: '/tools',
+  path: '/tools',
+  getParentRoute: () => AgentRoute,
+} as any)
+const AgentSkillsRoute = AgentSkillsRouteImport.update({
+  id: '/skills',
+  path: '/skills',
+  getParentRoute: () => AgentRoute,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/channels': typeof ChannelsRouteRouteWithChildren
+  '/agent': typeof AgentRouteWithChildren
+  '/config': typeof ConfigRouteWithChildren
+  '/credentials': typeof CredentialsRoute
+  '/logs': typeof LogsRoute
+  '/models': typeof ModelsRoute
+  '/agent/skills': typeof AgentSkillsRoute
+  '/agent/tools': typeof AgentToolsRoute
+  '/channels/$name': typeof ChannelsNameRoute
+  '/config/raw': typeof ConfigRawRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/channels': typeof ChannelsRouteRouteWithChildren
+  '/agent': typeof AgentRouteWithChildren
+  '/config': typeof ConfigRouteWithChildren
+  '/credentials': typeof CredentialsRoute
+  '/logs': typeof LogsRoute
+  '/models': typeof ModelsRoute
+  '/agent/skills': typeof AgentSkillsRoute
+  '/agent/tools': typeof AgentToolsRoute
+  '/channels/$name': typeof ChannelsNameRoute
+  '/config/raw': typeof ConfigRawRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/channels': typeof ChannelsRouteRouteWithChildren
+  '/agent': typeof AgentRouteWithChildren
+  '/config': typeof ConfigRouteWithChildren
+  '/credentials': typeof CredentialsRoute
+  '/logs': typeof LogsRoute
+  '/models': typeof ModelsRoute
+  '/agent/skills': typeof AgentSkillsRoute
+  '/agent/tools': typeof AgentToolsRoute
+  '/channels/$name': typeof ChannelsNameRoute
+  '/config/raw': typeof ConfigRawRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths:
+    | '/'
+    | '/channels'
+    | '/agent'
+    | '/config'
+    | '/credentials'
+    | '/logs'
+    | '/models'
+    | '/agent/skills'
+    | '/agent/tools'
+    | '/channels/$name'
+    | '/config/raw'
+  fileRoutesByTo: FileRoutesByTo
+  to:
+    | '/'
+    | '/channels'
+    | '/agent'
+    | '/config'
+    | '/credentials'
+    | '/logs'
+    | '/models'
+    | '/agent/skills'
+    | '/agent/tools'
+    | '/channels/$name'
+    | '/config/raw'
+  id:
+    | '__root__'
+    | '/'
+    | '/channels'
+    | '/agent'
+    | '/config'
+    | '/credentials'
+    | '/logs'
+    | '/models'
+    | '/agent/skills'
+    | '/agent/tools'
+    | '/channels/$name'
+    | '/config/raw'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  ChannelsRouteRoute: typeof ChannelsRouteRouteWithChildren
+  AgentRoute: typeof AgentRouteWithChildren
+  ConfigRoute: typeof ConfigRouteWithChildren
+  CredentialsRoute: typeof CredentialsRoute
+  LogsRoute: typeof LogsRoute
+  ModelsRoute: typeof ModelsRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/models': {
+      id: '/models'
+      path: '/models'
+      fullPath: '/models'
+      preLoaderRoute: typeof ModelsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/logs': {
+      id: '/logs'
+      path: '/logs'
+      fullPath: '/logs'
+      preLoaderRoute: typeof LogsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/credentials': {
+      id: '/credentials'
+      path: '/credentials'
+      fullPath: '/credentials'
+      preLoaderRoute: typeof CredentialsRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/config': {
+      id: '/config'
+      path: '/config'
+      fullPath: '/config'
+      preLoaderRoute: typeof ConfigRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/agent': {
+      id: '/agent'
+      path: '/agent'
+      fullPath: '/agent'
+      preLoaderRoute: typeof AgentRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/channels': {
+      id: '/channels'
+      path: '/channels'
+      fullPath: '/channels'
+      preLoaderRoute: typeof ChannelsRouteRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/config/raw': {
+      id: '/config/raw'
+      path: '/raw'
+      fullPath: '/config/raw'
+      preLoaderRoute: typeof ConfigRawRouteImport
+      parentRoute: typeof ConfigRoute
+    }
+    '/channels/$name': {
+      id: '/channels/$name'
+      path: '/$name'
+      fullPath: '/channels/$name'
+      preLoaderRoute: typeof ChannelsNameRouteImport
+      parentRoute: typeof ChannelsRouteRoute
+    }
+    '/agent/tools': {
+      id: '/agent/tools'
+      path: '/tools'
+      fullPath: '/agent/tools'
+      preLoaderRoute: typeof AgentToolsRouteImport
+      parentRoute: typeof AgentRoute
+    }
+    '/agent/skills': {
+      id: '/agent/skills'
+      path: '/skills'
+      fullPath: '/agent/skills'
+      preLoaderRoute: typeof AgentSkillsRouteImport
+      parentRoute: typeof AgentRoute
+    }
+  }
+}
+
+interface ChannelsRouteRouteChildren {
+  ChannelsNameRoute: typeof ChannelsNameRoute
+}
+
+const ChannelsRouteRouteChildren: ChannelsRouteRouteChildren = {
+  ChannelsNameRoute: ChannelsNameRoute,
+}
+
+const ChannelsRouteRouteWithChildren = ChannelsRouteRoute._addFileChildren(
+  ChannelsRouteRouteChildren,
+)
+
+interface AgentRouteChildren {
+  AgentSkillsRoute: typeof AgentSkillsRoute
+  AgentToolsRoute: typeof AgentToolsRoute
+}
+
+const AgentRouteChildren: AgentRouteChildren = {
+  AgentSkillsRoute: AgentSkillsRoute,
+  AgentToolsRoute: AgentToolsRoute,
+}
+
+const AgentRouteWithChildren = AgentRoute._addFileChildren(AgentRouteChildren)
+
+interface ConfigRouteChildren {
+  ConfigRawRoute: typeof ConfigRawRoute
+}
+
+const ConfigRouteChildren: ConfigRouteChildren = {
+  ConfigRawRoute: ConfigRawRoute,
+}
+
+const ConfigRouteWithChildren =
+  ConfigRoute._addFileChildren(ConfigRouteChildren)
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  ChannelsRouteRoute: ChannelsRouteRouteWithChildren,
+  AgentRoute: AgentRouteWithChildren,
+  ConfigRoute: ConfigRouteWithChildren,
+  CredentialsRoute: CredentialsRoute,
+  LogsRoute: LogsRoute,
+  ModelsRoute: ModelsRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
diff --git a/web/frontend/src/routes/__root.tsx b/web/frontend/src/routes/__root.tsx
new file mode 100644
index 000000000..31fdb7804
--- /dev/null
+++ b/web/frontend/src/routes/__root.tsx
@@ -0,0 +1,21 @@
+import { Outlet, createRootRoute } from "@tanstack/react-router"
+import { TanStackRouterDevtools } from "@tanstack/react-router-devtools"
+import { useEffect } from "react"
+
+import { AppLayout } from "@/components/app-layout"
+import { initializeChatStore } from "@/features/chat/controller"
+
+const RootLayout = () => {
+  useEffect(() => {
+    initializeChatStore()
+  }, [])
+
+  return (
+    <AppLayout>
+      <Outlet />
+      <TanStackRouterDevtools />
+    </AppLayout>
+  )
+}
+
+export const Route = createRootRoute({ component: RootLayout })
diff --git a/web/frontend/src/routes/agent.tsx b/web/frontend/src/routes/agent.tsx
new file mode 100644
index 000000000..78104de5b
--- /dev/null
+++ b/web/frontend/src/routes/agent.tsx
@@ -0,0 +1,22 @@
+import {
+  Navigate,
+  Outlet,
+  createFileRoute,
+  useRouterState,
+} from "@tanstack/react-router"
+
+export const Route = createFileRoute("/agent")({
+  component: AgentLayout,
+})
+
+function AgentLayout() {
+  const pathname = useRouterState({
+    select: (state) => state.location.pathname,
+  })
+
+  if (pathname === "/agent") {
+    return <Navigate to="/agent/skills" />
+  }
+
+  return <Outlet />
+}
diff --git a/web/frontend/src/routes/agent/skills.tsx b/web/frontend/src/routes/agent/skills.tsx
new file mode 100644
index 000000000..bbe396bdb
--- /dev/null
+++ b/web/frontend/src/routes/agent/skills.tsx
@@ -0,0 +1,11 @@
+import { createFileRoute } from "@tanstack/react-router"
+
+import { SkillsPage } from "@/components/skills/skills-page"
+
+export const Route = createFileRoute("/agent/skills")({
+  component: AgentSkillsRoute,
+})
+
+function AgentSkillsRoute() {
+  return <SkillsPage />
+}
diff --git a/web/frontend/src/routes/agent/tools.tsx b/web/frontend/src/routes/agent/tools.tsx
new file mode 100644
index 000000000..ac8738a8f
--- /dev/null
+++ b/web/frontend/src/routes/agent/tools.tsx
@@ -0,0 +1,11 @@
+import { createFileRoute } from "@tanstack/react-router"
+
+import { ToolsPage } from "@/components/tools/tools-page"
+
+export const Route = createFileRoute("/agent/tools")({
+  component: AgentToolsRoute,
+})
+
+function AgentToolsRoute() {
+  return <ToolsPage />
+}
diff --git a/web/frontend/src/routes/channels/$name.tsx b/web/frontend/src/routes/channels/$name.tsx
new file mode 100644
index 000000000..e2e4941c1
--- /dev/null
+++ b/web/frontend/src/routes/channels/$name.tsx
@@ -0,0 +1,13 @@
+import { createFileRoute } from "@tanstack/react-router"
+
+import { ChannelConfigPage } from "@/components/channels/channel-config-page"
+
+export const Route = createFileRoute("/channels/$name")({
+  component: ChannelsByNameRoute,
+})
+
+function ChannelsByNameRoute() {
+  const { name } = Route.useParams()
+
+  return <ChannelConfigPage channelName={name} />
+}
diff --git a/web/frontend/src/routes/channels/route.tsx b/web/frontend/src/routes/channels/route.tsx
new file mode 100644
index 000000000..044ff20c1
--- /dev/null
+++ b/web/frontend/src/routes/channels/route.tsx
@@ -0,0 +1,22 @@
+import {
+  Navigate,
+  Outlet,
+  createFileRoute,
+  useRouterState,
+} from "@tanstack/react-router"
+
+export const Route = createFileRoute("/channels")({
+  component: ChannelsLayout,
+})
+
+function ChannelsLayout() {
+  const pathname = useRouterState({
+    select: (state) => state.location.pathname,
+  })
+
+  if (pathname === "/channels") {
+    return <Navigate to="/channels/$name" params={{ name: "pico" }} />
+  }
+
+  return <Outlet />
+}
diff --git a/web/frontend/src/routes/config.raw.tsx b/web/frontend/src/routes/config.raw.tsx
new file mode 100644
index 000000000..048a4379a
--- /dev/null
+++ b/web/frontend/src/routes/config.raw.tsx
@@ -0,0 +1,7 @@
+import { createFileRoute } from "@tanstack/react-router"
+
+import { RawConfigPage } from "@/components/config/raw-config-page"
+
+export const Route = createFileRoute("/config/raw")({
+  component: RawConfigPage,
+})
diff --git a/web/frontend/src/routes/config.tsx b/web/frontend/src/routes/config.tsx
new file mode 100644
index 000000000..853af521c
--- /dev/null
+++ b/web/frontend/src/routes/config.tsx
@@ -0,0 +1,19 @@
+import { Outlet, createFileRoute, useRouterState } from "@tanstack/react-router"
+
+import { ConfigPage } from "@/components/config/config-page"
+
+export const Route = createFileRoute("/config")({
+  component: ConfigRouteLayout,
+})
+
+function ConfigRouteLayout() {
+  const pathname = useRouterState({
+    select: (state) => state.location.pathname,
+  })
+
+  if (pathname === "/config") {
+    return <ConfigPage />
+  }
+
+  return <Outlet />
+}
diff --git a/web/frontend/src/routes/credentials.tsx b/web/frontend/src/routes/credentials.tsx
new file mode 100644
index 000000000..349a6b734
--- /dev/null
+++ b/web/frontend/src/routes/credentials.tsx
@@ -0,0 +1,7 @@
+import { createFileRoute } from "@tanstack/react-router"
+
+import { CredentialsPage } from "@/components/credentials/credentials-page"
+
+export const Route = createFileRoute("/credentials")({
+  component: CredentialsPage,
+})
diff --git a/web/frontend/src/routes/index.tsx b/web/frontend/src/routes/index.tsx
new file mode 100644
index 000000000..0006df485
--- /dev/null
+++ b/web/frontend/src/routes/index.tsx
@@ -0,0 +1,7 @@
+import { createFileRoute } from "@tanstack/react-router"
+
+import { ChatPage } from "@/components/chat/chat-page"
+
+export const Route = createFileRoute("/")({
+  component: ChatPage,
+})
diff --git a/web/frontend/src/routes/logs.tsx b/web/frontend/src/routes/logs.tsx
new file mode 100644
index 000000000..86cbf1210
--- /dev/null
+++ b/web/frontend/src/routes/logs.tsx
@@ -0,0 +1,7 @@
+import { createFileRoute } from "@tanstack/react-router"
+
+import { LogsPage } from "@/components/logs/logs-page"
+
+export const Route = createFileRoute("/logs")({
+  component: LogsPage,
+})
diff --git a/web/frontend/src/routes/models.tsx b/web/frontend/src/routes/models.tsx
new file mode 100644
index 000000000..71fd6fe47
--- /dev/null
+++ b/web/frontend/src/routes/models.tsx
@@ -0,0 +1,7 @@
+import { createFileRoute } from "@tanstack/react-router"
+
+import { ModelsPage } from "@/components/models/models-page"
+
+export const Route = createFileRoute("/models")({
+  component: ModelsPage,
+})
diff --git a/web/frontend/src/store/chat.ts b/web/frontend/src/store/chat.ts
new file mode 100644
index 000000000..da5fa6670
--- /dev/null
+++ b/web/frontend/src/store/chat.ts
@@ -0,0 +1,62 @@
+import { atom, getDefaultStore } from "jotai"
+
+import {
+  getInitialActiveSessionId,
+  writeStoredSessionId,
+} from "@/features/chat/state"
+
+export interface ChatMessage {
+  id: string
+  role: "user" | "assistant"
+  content: string
+  timestamp: number | string
+}
+
+export type ConnectionState =
+  | "disconnected"
+  | "connecting"
+  | "connected"
+  | "error"
+
+export interface ChatStoreState {
+  messages: ChatMessage[]
+  connectionState: ConnectionState
+  isTyping: boolean
+  activeSessionId: string
+  hasHydratedActiveSession: boolean
+}
+
+type ChatStorePatch = Partial<ChatStoreState>
+
+const DEFAULT_CHAT_STATE: ChatStoreState = {
+  messages: [],
+  connectionState: "disconnected",
+  isTyping: false,
+  activeSessionId: getInitialActiveSessionId(),
+  hasHydratedActiveSession: false,
+}
+
+export const chatAtom = atom<ChatStoreState>(DEFAULT_CHAT_STATE)
+
+const store = getDefaultStore()
+
+export function getChatState() {
+  return store.get(chatAtom)
+}
+
+export function updateChatStore(
+  patch:
+    | ChatStorePatch
+    | ((prev: ChatStoreState) => ChatStorePatch | ChatStoreState),
+) {
+  store.set(chatAtom, (prev) => {
+    const nextPatch = typeof patch === "function" ? patch(prev) : patch
+    const next = { ...prev, ...nextPatch }
+
+    if (next.activeSessionId !== prev.activeSessionId) {
+      writeStoredSessionId(next.activeSessionId)
+    }
+
+    return next
+  })
+}
diff --git a/web/frontend/src/store/gateway.ts b/web/frontend/src/store/gateway.ts
new file mode 100644
index 000000000..1bdec6220
--- /dev/null
+++ b/web/frontend/src/store/gateway.ts
@@ -0,0 +1,204 @@
+import { atom, getDefaultStore } from "jotai"
+
+import { type GatewayStatusResponse, getGatewayStatus } from "@/api/gateway"
+
+export type GatewayState =
+  | "running"
+  | "starting"
+  | "restarting"
+  | "stopping"
+  | "stopped"
+  | "error"
+  | "unknown"
+
+export interface GatewayStoreState {
+  status: GatewayState
+  canStart: boolean
+  restartRequired: boolean
+}
+
+type GatewayStorePatch = Partial<GatewayStoreState>
+
+const DEFAULT_GATEWAY_STATE: GatewayStoreState = {
+  status: "unknown",
+  canStart: true,
+  restartRequired: false,
+}
+
+const GATEWAY_POLL_INTERVAL_MS = 2000
+const GATEWAY_TRANSIENT_POLL_INTERVAL_MS = 1000
+const GATEWAY_STOPPING_TIMEOUT_MS = 5000
+
+interface RefreshGatewayStateOptions {
+  force?: boolean
+}
+
+// Global atom for gateway state
+export const gatewayAtom = atom<GatewayStoreState>(DEFAULT_GATEWAY_STATE)
+
+let gatewayPollingSubscribers = 0
+let gatewayPollingTimer: ReturnType<typeof setTimeout> | null = null
+let gatewayPollingRequest: Promise<void> | null = null
+let gatewayStoppingTimer: ReturnType<typeof setTimeout> | null = null
+
+function clearGatewayStoppingTimeout() {
+  if (gatewayStoppingTimer !== null) {
+    clearTimeout(gatewayStoppingTimer)
+    gatewayStoppingTimer = null
+  }
+}
+
+function normalizeGatewayStoreState(
+  prev: GatewayStoreState,
+  patch: GatewayStorePatch,
+) {
+  const next = { ...prev, ...patch }
+
+  if (
+    next.status === prev.status &&
+    next.canStart === prev.canStart &&
+    next.restartRequired === prev.restartRequired
+  ) {
+    return prev
+  }
+
+  return next
+}
+
+export function updateGatewayStore(
+  patch:
+    | GatewayStorePatch
+    | ((prev: GatewayStoreState) => GatewayStorePatch | GatewayStoreState),
+) {
+  const store = getDefaultStore()
+  store.set(gatewayAtom, (prev) => {
+    const nextPatch = typeof patch === "function" ? patch(prev) : patch
+    return normalizeGatewayStoreState(prev, nextPatch)
+  })
+  const nextState = store.get(gatewayAtom)
+  if (nextState?.status !== "stopping") {
+    clearGatewayStoppingTimeout()
+  }
+}
+
+export function beginGatewayStoppingTransition() {
+  clearGatewayStoppingTimeout()
+  updateGatewayStore({
+    status: "stopping",
+    canStart: false,
+    restartRequired: false,
+  })
+  gatewayStoppingTimer = setTimeout(() => {
+    gatewayStoppingTimer = null
+    updateGatewayStore((prev) =>
+      prev.status === "stopping" ? { status: "running" } : prev,
+    )
+    void refreshGatewayState({ force: true })
+  }, GATEWAY_STOPPING_TIMEOUT_MS)
+}
+
+export function cancelGatewayStoppingTransition() {
+  clearGatewayStoppingTimeout()
+  updateGatewayStore((prev) =>
+    prev.status === "stopping" ? { status: "running" } : prev,
+  )
+}
+
+export function applyGatewayStatusToStore(
+  data: Partial<
+    Pick<
+      GatewayStatusResponse,
+      "gateway_status" | "gateway_start_allowed" | "gateway_restart_required"
+    >
+  >,
+) {
+  updateGatewayStore((prev) => ({
+    status:
+      prev.status === "stopping" && data.gateway_status === "running"
+        ? "stopping"
+        : (data.gateway_status ?? prev.status),
+    canStart:
+      prev.status === "stopping" && data.gateway_status === "running"
+        ? false
+        : (data.gateway_start_allowed ?? prev.canStart),
+    restartRequired:
+      prev.status === "stopping" && data.gateway_status === "running"
+        ? false
+        : (data.gateway_restart_required ?? prev.restartRequired),
+  }))
+}
+
+function nextGatewayPollInterval() {
+  const status = getDefaultStore().get(gatewayAtom).status
+  if (
+    status === "starting" ||
+    status === "restarting" ||
+    status === "stopping"
+  ) {
+    return GATEWAY_TRANSIENT_POLL_INTERVAL_MS
+  }
+  return GATEWAY_POLL_INTERVAL_MS
+}
+
+function scheduleGatewayPoll(delay = nextGatewayPollInterval()) {
+  if (gatewayPollingSubscribers === 0) {
+    return
+  }
+
+  if (gatewayPollingTimer !== null) {
+    clearTimeout(gatewayPollingTimer)
+  }
+
+  gatewayPollingTimer = setTimeout(() => {
+    gatewayPollingTimer = null
+    void refreshGatewayState()
+  }, delay)
+}
+
+export async function refreshGatewayState(
+  options: RefreshGatewayStateOptions = {},
+) {
+  if (gatewayPollingRequest) {
+    await gatewayPollingRequest
+    if (options.force) {
+      return refreshGatewayState()
+    }
+    return
+  }
+
+  gatewayPollingRequest = (async () => {
+    try {
+      const status = await getGatewayStatus()
+      applyGatewayStatusToStore(status)
+    } catch {
+      // Preserve the last known state when a poll fails.
+    } finally {
+      gatewayPollingRequest = null
+      scheduleGatewayPoll()
+    }
+  })()
+
+  try {
+    await gatewayPollingRequest
+  } finally {
+    if (gatewayPollingSubscribers === 0 && gatewayPollingTimer !== null) {
+      clearTimeout(gatewayPollingTimer)
+      gatewayPollingTimer = null
+    }
+  }
+}
+
+export function subscribeGatewayPolling() {
+  gatewayPollingSubscribers += 1
+  if (gatewayPollingSubscribers === 1) {
+    void refreshGatewayState()
+  }
+
+  return () => {
+    gatewayPollingSubscribers = Math.max(0, gatewayPollingSubscribers - 1)
+    if (gatewayPollingSubscribers === 0 && gatewayPollingTimer !== null) {
+      clearTimeout(gatewayPollingTimer)
+      gatewayPollingTimer = null
+    }
+  }
+}
diff --git a/web/frontend/src/store/index.ts b/web/frontend/src/store/index.ts
new file mode 100644
index 000000000..d377cdace
--- /dev/null
+++ b/web/frontend/src/store/index.ts
@@ -0,0 +1,2 @@
+export * from "./gateway"
+export * from "./chat"
diff --git a/web/frontend/tsconfig.app.json b/web/frontend/tsconfig.app.json
new file mode 100644
index 000000000..a13231303
--- /dev/null
+++ b/web/frontend/tsconfig.app.json
@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"]
+}
diff --git a/web/frontend/tsconfig.json b/web/frontend/tsconfig.json
new file mode 100644
index 000000000..fec8c8e5c
--- /dev/null
+++ b/web/frontend/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ],
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
diff --git a/web/frontend/tsconfig.node.json b/web/frontend/tsconfig.node.json
new file mode 100644
index 000000000..8a67f62f4
--- /dev/null
+++ b/web/frontend/tsconfig.node.json
@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts"]
+}
diff --git a/web/frontend/vite.config.ts b/web/frontend/vite.config.ts
new file mode 100644
index 000000000..0ef4e1415
--- /dev/null
+++ b/web/frontend/vite.config.ts
@@ -0,0 +1,38 @@
+import path from "path"
+
+import tailwindcss from "@tailwindcss/vite"
+import { tanstackRouter } from "@tanstack/router-plugin/vite"
+import react from "@vitejs/plugin-react"
+import { defineConfig } from "vite"
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [
+    tanstackRouter({
+      target: "react",
+      autoCodeSplitting: true,
+    }),
+    react(),
+    tailwindcss(),
+  ],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+  build: {
+    chunkSizeWarningLimit: 2048,
+  },
+  server: {
+    proxy: {
+      "/api": {
+        target: "http://localhost:18800",
+        changeOrigin: true,
+      },
+      "/ws": {
+        target: "ws://localhost:18800",
+        ws: true,
+      },
+    },
+  },
+})
diff --git a/web/picoclaw-launcher.desktop b/web/picoclaw-launcher.desktop
new file mode 100644
index 000000000..7e1f7b4d0
--- /dev/null
+++ b/web/picoclaw-launcher.desktop
@@ -0,0 +1,9 @@
+[Desktop Entry]
+Name=PicoClaw Launcher
+Comment=Web-based configuration and management UI for PicoClaw
+Exec=picoclaw-launcher
+Icon=picoclaw-launcher
+Terminal=true
+Type=Application
+Categories=Utility;Network;
+Keywords=picoclaw;ai;agent;bot;
diff --git a/web/picoclaw-launcher.png b/web/picoclaw-launcher.png
new file mode 100644
index 000000000..e0b4aab9c
Binary files /dev/null and b/web/picoclaw-launcher.png differ
diff --git a/workspace/AGENT.md b/workspace/AGENT.md
new file mode 100644
index 000000000..08f55a1b7
--- /dev/null
+++ b/workspace/AGENT.md
@@ -0,0 +1,45 @@
+---
+name: pico
+description: >
+  The default general-purpose assistant for everyday conversation, problem
+  solving, and workspace help.
+---
+
+You are Pico, the default assistant for this workspace.
+Your name is PicoClaw 🦞.
+## Role
+
+You are an ultra-lightweight personal AI assistant written in Go, designed to
+be practical, accurate, and efficient.
+
+## Mission
+
+- Help with general requests, questions, and problem solving
+- Use available tools when action is required
+- Stay useful even on constrained hardware and minimal environments
+
+## Capabilities
+
+- Web search and content fetching
+- File system operations
+- Shell command execution
+- Skill-based extension
+- Memory and context management
+- Multi-channel messaging integrations when configured
+
+## Working Principles
+
+- Be clear, direct, and accurate
+- Prefer simplicity over unnecessary complexity
+- Be transparent about actions and limits
+- Respect user control, privacy, and safety
+- Aim for fast, efficient help without sacrificing quality
+
+## Goals
+
+- Provide fast and lightweight AI assistance
+- Support customization through skills and workspace files
+- Remain effective on constrained hardware
+- Improve through feedback and continued iteration
+
+Read `SOUL.md` as part of your identity and communication style.
diff --git a/workspace/AGENTS.md b/workspace/AGENTS.md
deleted file mode 100644
index 707717f6e..000000000
--- a/workspace/AGENTS.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Agent Instructions
-
-You are a helpful AI assistant. Be concise, accurate, and friendly.
-
-## Guidelines
-
-- Always explain what you're doing before taking actions
-- Ask for clarification when request is ambiguous
-- Use tools to help accomplish tasks
-- Remember important information in your memory files
-- Be proactive and helpful
-- Learn from user feedback
-
-## Docker Bootstrap
-
-If the user asks you to install a tool, add a library, or persist a capability in the Docker environment, edit the file at `{workspace}/bootstrap.sh`. This script runs on every container start. Use `apk add` for Alpine packages. Check if the tool is already installed before installing (use `command -v`).
-
-If you see a bootstrap error in your context (from `bootstrap.error.log`), it means the last bootstrap run failed and some capabilities may be missing. Read the error, fix `bootstrap.sh`, and inform the user they should restart the container to apply the fix.
\ No newline at end of file
diff --git a/workspace/IDENTITY.md b/workspace/IDENTITY.md
deleted file mode 100644
index dabb0e14b..000000000
--- a/workspace/IDENTITY.md
+++ /dev/null
@@ -1,56 +0,0 @@
-# Identity
-
-## Name
-PicoClaw 🦞
-
-## Description
-Ultra-lightweight personal AI assistant written in Go, inspired by nanobot.
-
-## Version
-0.1.0
-
-## Purpose
-- Provide intelligent AI assistance with minimal resource usage
-- Support multiple LLM providers (OpenAI, Anthropic, Zhipu, etc.)
-- Enable easy customization through skills system
-- Run on minimal hardware ($10 boards, <10MB RAM)
-
-## Capabilities
-
-- Web search and content fetching
-- File system operations (read, write, edit)
-- Shell command execution
-- Multi-channel messaging (Telegram, WhatsApp, Feishu)
-- Skill-based extensibility
-- Memory and context management
-
-## Philosophy
-
-- Simplicity over complexity
-- Performance over features
-- User control and privacy
-- Transparent operation
-- Community-driven development
-
-## Goals
-
-- Provide a fast, lightweight AI assistant
-- Support offline-first operation where possible
-- Enable easy customization and extension
-- Maintain high quality responses
-- Run efficiently on constrained hardware
-
-## License
-MIT License - Free and open source
-
-## Repository
-https://github.com/sipeed/picoclaw
-
-## Contact
-Issues: https://github.com/sipeed/picoclaw/issues
-Discussions: https://github.com/sipeed/picoclaw/discussions
-
----
-
-"Every bit helps, every bit matters."
-- Picoclaw
\ No newline at end of file
diff --git a/workspace/SOUL.md b/workspace/SOUL.md
index 0be8834f5..8a6371ff9 100644
--- a/workspace/SOUL.md
+++ b/workspace/SOUL.md
@@ -1,6 +1,6 @@
 # Soul
 
-I am picoclaw, a lightweight AI assistant powered by AI.
+I am PicoClaw: calm, helpful, and practical.
 
 ## Personality
 
@@ -8,10 +8,12 @@ I am picoclaw, a lightweight AI assistant powered by AI.
 - Concise and to the point
 - Curious and eager to learn
 - Honest and transparent
+- Calm under uncertainty
 
 ## Values
 
 - Accuracy over speed
 - User privacy and safety
 - Transparency in actions
-- Continuous improvement
\ No newline at end of file
+- Continuous improvement
+- Simplicity over unnecessary complexity
diff --git a/workspace/USER.md b/workspace/USER.md
index 91398a019..9a3419d87 100644
--- a/workspace/USER.md
+++ b/workspace/USER.md
@@ -1,6 +1,6 @@
 # User
 
-Information about user goes here.
+Information about the user goes here.
 
 ## Preferences
 
@@ -18,4 +18,4 @@ Information about user goes here.
 
 - What the user wants to learn from AI
 - Preferred interaction style
-- Areas of interest
\ No newline at end of file
+- Areas of interest
diff --git a/workspace/skills/agent-browser/SKILL.md b/workspace/skills/agent-browser/SKILL.md
new file mode 100644
index 000000000..43505996d
--- /dev/null
+++ b/workspace/skills/agent-browser/SKILL.md
@@ -0,0 +1,129 @@
+---
+name: agent-browser
+description: "Browser automation via agent-browser CLI. Use when the user needs to navigate websites, fill forms, click buttons, take screenshots, extract data, or test web apps."
+metadata: {"nanobot":{"emoji":"🌐","requires":{"bins":["agent-browser"]},"install":[{"id":"npm","kind":"npm","package":"agent-browser","global":true,"bins":["agent-browser"],"label":"Install agent-browser (npm)"}]}}
+---
+
+# Agent Browser
+
+CLI browser automation via Chrome/Chromium CDP. Install: `npm i -g agent-browser && agent-browser install`.
+
+**Before using this skill**, verify the tool is available by running `which agent-browser`. If the command is not found, tell the user that browser automation requires the `agent-browser` CLI and Chromium, which are only available in the heavy container image. Do not attempt to install it at runtime.
+
+## Core Workflow
+
+1. `agent-browser open <url>` — navigate
+2. `agent-browser snapshot -i` — get interactive elements with refs (`@e1`, `@e2`, ...)
+3. Interact using refs — `click @e1`, `fill @e2 "text"`
+4. Re-snapshot after any navigation or DOM change — refs are invalidated
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+# @e1 [input] "Email", @e2 [input] "Password", @e3 [button] "Submit"
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "secret"
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser snapshot -i
+```
+
+Chain commands with `&&` when you don't need intermediate output:
+```bash
+agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
+```
+
+## Commands
+
+```bash
+# Navigation
+agent-browser open <url>
+agent-browser close
+
+# Snapshot
+agent-browser snapshot -i                # Interactive elements with refs
+agent-browser snapshot -s "#selector"    # Scope to CSS selector
+
+# Interaction (use @refs from snapshot)
+agent-browser click @e1
+agent-browser fill @e2 "text"            # Clear + type
+agent-browser type @e2 "text"            # Type without clearing
+agent-browser select @e1 "option"
+agent-browser check @e1
+agent-browser press Enter
+agent-browser scroll down 500
+
+# Get info
+agent-browser get text @e1
+agent-browser get url
+agent-browser get title
+
+# Wait
+agent-browser wait @e1                   # Wait for element
+agent-browser wait --load networkidle    # Wait for network idle
+agent-browser wait --url "**/dashboard"  # Wait for URL pattern
+agent-browser wait --text "Welcome"      # Wait for text
+agent-browser wait 2000                  # Wait ms
+
+# Capture
+agent-browser screenshot                 # Screenshot to temp dir
+agent-browser screenshot --full          # Full page
+agent-browser screenshot --annotate      # With numbered element labels ([N] -> @eN)
+agent-browser pdf output.pdf
+
+# Semantic locators (when refs unavailable)
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find role button click --name "Submit"
+```
+
+## Authentication
+
+```bash
+# Option 1: Import from user's running Chrome
+agent-browser --auto-connect state save ./auth.json
+agent-browser --state ./auth.json open https://app.example.com
+
+# Option 2: Persistent profile
+agent-browser --profile ~/.myapp open https://app.example.com/login
+# ... login once, all future runs are authenticated
+
+# Option 3: Session name (auto-save/restore)
+agent-browser --session-name myapp open https://app.example.com/login
+# ... login, close, next run state is restored
+
+# Option 4: State file
+agent-browser state save auth.json
+agent-browser state load auth.json
+```
+
+## Iframes
+
+Iframe content is inlined in snapshots. Interact with iframe refs directly — no frame switch needed.
+
+## Parallel Sessions
+
+```bash
+agent-browser --session s1 open https://site-a.com
+agent-browser --session s2 open https://site-b.com
+agent-browser session list
+```
+
+## JavaScript Eval
+
+```bash
+agent-browser eval 'document.title'
+
+# Complex JS — use --stdin to avoid shell quoting issues
+agent-browser eval --stdin <<'EVALEOF'
+JSON.stringify(Array.from(document.querySelectorAll("a")).map(a => a.href))
+EVALEOF
+```
+
+## Cleanup
+
+Always close sessions when done:
+```bash
+agent-browser close
+agent-browser --session s1 close
+```
diff --git a/workspace/skills/summarize/SKILL.md b/workspace/skills/summarize/SKILL.md
index 766ab5d0b..ca7008e7a 100644
--- a/workspace/skills/summarize/SKILL.md
+++ b/workspace/skills/summarize/SKILL.md
@@ -59,7 +59,7 @@ Default model is `google/gemini-3-flash-preview` if none is set.
 Optional config file: `~/.summarize/config.json`
 
 ```json
-{ "model": "openai/gpt-5.2" }
+{ "model": "openai/gpt-5.4" }
 ```
 
 Optional services:
diff --git a/workspace/skills/weather/SKILL.md b/workspace/skills/weather/SKILL.md
index 8073de192..aa90a9b20 100644
--- a/workspace/skills/weather/SKILL.md
+++ b/workspace/skills/weather/SKILL.md
@@ -1,49 +1,59 @@
 ---
 name: weather
-description: Get current weather and forecasts (no API key required).
+description: Get current weather and forecasts with verified location matching (no API key required).
 homepage: https://wttr.in/:help
 metadata: {"nanobot":{"emoji":"🌤️","requires":{"bins":["curl"]}}}
 ---
 
 # Weather
 
-Two free services, no API keys needed.
+Use the most reliable location match first. For Chinese city names or other non-Latin input, prefer `wttr.in` with the original query because it resolves native names directly. Use Open-Meteo for structured current conditions and forecasts only after you have confirmed the exact city.
 
-## wttr.in (primary)
+## Accuracy Rules
 
-Quick one-liner:
+- Always restate the matched location, region/country, and observation time in the final answer.
+- Do not trust the first geocoding hit blindly. Check `country`, `admin1`, `admin2`, and `population`.
+- For Chinese city queries, do not send Hanzi directly to Open-Meteo geocoding unless the top result is obviously correct. Prefer `wttr.in` with the original Chinese name, or geocode the English/pinyin city name instead.
+- If multiple plausible matches remain, ask a follow-up question or state the assumption clearly.
+- Use `timezone=auto` when calling Open-Meteo so the reported time matches the location.
+
+## wttr.in (best for direct city-name queries)
+
+Quick current conditions:
 ```bash
-curl -s "wttr.in/London?format=3"
-# Output: London: ⛅️ +8°C
+curl -s "https://wttr.in/London?format=%l:+%c+%t+%h+%w"
 ```
 
-Compact format:
+Chinese city example:
 ```bash
-curl -s "wttr.in/London?format=%l:+%c+%t+%h+%w"
-# Output: London: ⛅️ +8°C 71% ↙5km/h
+curl -s "https://wttr.in/%E6%88%90%E9%83%BD?format=%l:+%c+%t+%h+%w"
+curl -s "https://wttr.in/%E4%B8%8A%E6%B5%B7?format=%l:+%c+%t+%h+%w"
 ```
 
-Full forecast:
+JSON output if you need more detail:
 ```bash
-curl -s "wttr.in/London?T"
+curl -s "https://wttr.in/Chengdu?format=j1"
 ```
 
-Format codes: `%c` condition · `%t` temp · `%h` humidity · `%w` wind · `%l` location · `%m` moon
-
 Tips:
-- URL-encode spaces: `wttr.in/New+York`
-- Airport codes: `wttr.in/JFK`
-- Units: `?m` (metric) `?u` (USCS)
-- Today only: `?1` · Current only: `?0`
-- PNG: `curl -s "wttr.in/Berlin.png" -o /tmp/weather.png`
+- URL-encode spaces: `New York` -> `New+York`
+- URL-encode non-ASCII text before sending the request
+- Use `?m` for metric units and `?u` for US units
 
-## Open-Meteo (fallback, JSON)
+## Open-Meteo (best for structured forecasts)
 
-Free, no key, good for programmatic use:
+1. Geocode the city and verify the returned location metadata:
 ```bash
-curl -s "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true"
+curl -s "https://geocoding-api.open-meteo.com/v1/search?name=Chengdu&count=3&language=en&format=json"
 ```
 
-Find coordinates for a city, then query. Returns JSON with temp, windspeed, weathercode.
+2. Query current weather and today's forecast with the verified coordinates:
+```bash
+curl -s "https://api.open-meteo.com/v1/forecast?latitude=30.66667&longitude=104.06667&current=temperature_2m,relative_humidity_2m,weather_code,wind_speed_10m&daily=weather_code,temperature_2m_max,temperature_2m_min&forecast_days=1&timezone=auto"
+```
+
+Important:
+- For Chinese inputs like `成都`, geocoding `name=%E6%88%90%E9%83%BD` may return smaller homonym locations first. Prefer `Chengdu` after verifying it matches Sichuan, China.
+- If geocoding looks suspicious, fall back to `wttr.in` for the original city name instead of presenting a likely wrong result.
 
 Docs: https://open-meteo.com/en/docs